EDL JSON Schema for video-use: How to Create and Edit EDL Files

The EDL (Edit Decision List) is a JSON document that drives the entire video-editing pipeline in the browser-use/video-use repository, specifying source videos, cut ranges, color grades, and overlays that helpers/render.py processes to produce the final output video.

The video-use project uses a lightweight, human-readable JSON schema to orchestrate video editing without a GUI. This Edit Decision List format allows you to version-control your editorial decisions and programmatically generate complex video cuts by declaring the edit structure in a single file.

What is the EDL JSON Schema?

The EDL JSON schema is defined in the repository’s SKILL.md file (lines 268-286) and serves as the single source of truth for the rendering pipeline. When you execute python helpers/render.py <edl>.json, the tool parses this file to extract video ranges, apply color grades via FFmpeg, stitch segments together, composite animation overlays, and burn subtitles.

The schema consists of seven top-level keys that declare the entire edit structure.

Schema Structure

Key	Type	Description
version	number	Schema version (currently always 1).
sources	object	Maps short identifiers (e.g., "C0103") to absolute or relative file paths.
ranges	array	Cut segments with timestamps, labels, and editorial notes.
grade	string	Color grade preset, FFmpeg filter string, or "auto".
overlays	array (optional)	Animation clips to composite on the final timeline.
subtitles	string (optional)	Path to an SRT file for hard-burning into the output.
total_duration_s	number (optional)	Expected output length for validation.

The Ranges Object

Each entry in the ranges array specifies a clip to extract from a source video:

• source: Identifier matching a key in sources
• start / end: Timestamps in seconds (float values)
• beat: Optional editorial label (e.g., "HOOK", "SOLUTION")
• quote: Optional transcript excerpt for reference
• reason: Free-form justification for auditability

How to Create an EDL File Manually

Follow these steps to author an EDL from scratch:

1. Gather source files – Copy or symlink raw footage into your working directory.

2. Identify cut points – Use helpers/timeline_view.py or any video player to note the exact start and end seconds you want to keep.

3. Write the JSON – Start with the template below, mapping sources to file paths and filling in the ranges you identified.

4. Select a grade – Choose a preset defined in helpers/grade.py, provide a raw FFmpeg filter string, or use "auto" for per-segment auto-grading.

5. Add overlays – Include only if you have pre-rendered animation clips ready to composite.

6. Specify subtitles – Provide a path to an SRT file if you want captions hard-burned into the final video.

7. Save – Use any filename ending in .json (e.g., my-edit.edl.json).

How to Edit an Existing EDL File

To modify an existing edit:

• Open the JSON file in any text editor.
• Update timestamps, add or remove range objects, change the grade value, insert new overlay entries, or adjust the subtitles path.
• Maintain valid JSON syntax (commas between objects, matching braces and quotes).
• Re-run helpers/render.py to generate the updated video.

Example EDL File

Below is a complete, valid EDL JSON document following the video-use schema:

{
  "version": 1,
  "sources": {
    "C0103": "/abs/path/C0103.MP4",
    "C0108": "/abs/path/C0108.MP4"
  },
  "ranges": [
    {
      "source": "C0103",
      "start": 2.42,
      "end": 6.85,
      "beat": "HOOK",
      "quote": "...",
      "reason": "Cleanest delivery, stops before slip at 38.46."
    },
    {
      "source": "C0108",
      "start": 14.30,
      "end": 28.90,
      "beat": "SOLUTION",
      "quote": "...",
      "reason": "Only take without the false start."
    }
  ],
  "grade": "warm_cinematic",
  "overlays": [
    {
      "file": "edit/animations/slot_1/render.mp4",
      "start_in_output": 0.0,
      "duration": 5.0
    }
  ],
  "subtitles": "edit/master.srt",
  "total_duration_s": 87.4
}

Rendering the EDL

Execute the render pipeline using the command below. The render.py script reads your EDL, resolves the grade filters, and assembles the final video.

python helpers/render.py my-edit.edl.json -o final.mp4

Additional flags:

• --build-subtitles: Generates a master SRT from source transcripts before burning.
• --no-subtitles: Skips subtitle burning entirely.

Automatic Color Grading

Setting "grade": "auto" in your EDL triggers per-segment auto-grading via the resolve_grade_filter function in helpers/render.py (lines 66-85). This automatically applies corrections such as:

def auto_grade_for_clip(video, start=0.0, duration=None, verbose=False):
    return "eq=contrast=1.03:saturation=0.98", {}

You can also reference presets defined in helpers/grade.py or provide raw FFmpeg filter strings directly in the grade field for custom color correction.

Summary

• The EDL JSON schema in video-use is a minimal, versionable format that controls the entire rendering pipeline without a GUI.
• Key components include sources (file mappings), ranges (cut lists with timestamps and metadata), and grade (color correction directives).
• The file is pure JSON—editable in any text editor or generated programmatically.
• Execute python helpers/render.py <edl>.json to process the EDL and output the final video.

Frequently Asked Questions

What file extension should I use for EDL files?

While any .json extension works, the convention is to name your files with the .edl.json suffix (e.g., project.edl.json) to distinguish them from configuration or data JSONs in your repository.

Can I use relative paths in the sources object?

Yes. The sources object accepts both absolute and relative paths. Relative paths are resolved from the directory where you execute helpers/render.py, making it easy to share projects across different machines.

How does the "auto" grade value work?

When "grade": "auto" is set, render.py calls auto_grade_for_clip for each range individually during the resolve_grade_filter phase (lines 66-85), applying algorithmic corrections based on the source footage's characteristics rather than a static filter.

Where are the color grade presets defined?

Preset grade strings like "warm_cinematic" are defined in helpers/grade.py. You can reference these presets by name in the grade field, or provide a raw FFmpeg filter string (e.g., "eq=contrast=1.1:brightness=0.05") for custom color correction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}