EDL JSON Format Specification and Manual Editing Guide for Video-Use

The EDL JSON format is a manifest file that tells video-use how to assemble source clips, apply color grades, composite overlays, and burn subtitles into a final video.

The EDL (Edit Decision List) JSON format serves as the central configuration schema in the browser-use/video-use repository. According to the specification defined in SKILL.md, this machine-readable structure provides fine-grained control over video editing workflows without requiring modifications to the underlying Python rendering pipeline.

EDL JSON Schema Overview

The specification lives in the repository’s SKILL.md file under the “## EDL format” heading. The format is a single JSON object containing top-level keys that define sources, temporal ranges, visual effects, and output parameters. The rendering pipeline in helpers/render.py parses this file to drive the end-to-end video generation process.

Required Fields in the EDL JSON Specification

version

The version key is a number that defines the schema version. Currently, this is always set to 1.

sources

The sources field is an object that maps short source IDs (e.g., "C0103") to absolute file paths on disk. These IDs are referenced later in the ranges array.

"sources": {
  "C0103": "/abs/path/C0103.MP4",
  "C0108": "/abs/path/C0108.MP4"
}

ranges

The ranges array contains an ordered list of clip segments to extract from the sources. Each entry is an object with the following properties:

• source – The source ID matching a key in the sources object.
• start / end – Timestamps in seconds (float) defining the in and out points.
• beat (optional) – A documentation label such as "HOOK" or "SOLUTION".
• quote (optional) – A short snippet of the original audio for reference.
• reason (optional) – Editorial note explaining why the segment was chosen.

"ranges": [
  {
    "source": "C0103",
    "start": 2.42,
    "end": 6.85,
    "beat": "HOOK",
    "quote": "...",
    "reason": "Cleanest delivery, stops before slip at 38.46."
  }
]

grade

The grade field accepts either a preset name (e.g., "warm_cinematic"), a raw ffmpeg filter string, or the string "auto". When set to "auto", the renderer calls auto_grade_for_clip from helpers/grade.py to compute per-segment color correction.

total_duration_s

This number specifies the expected total length of the final video in seconds. While the renderer computes the exact length independently, this field serves as a sanity check during validation.

Optional Fields for Advanced Workflows

overlays

The overlays array lists pre-rendered animation clips to composite on top of the base video. Each overlay object requires:

• file – Path to the rendered overlay video (relative to the EDL’s directory).
• start_in_output – Timestamp in seconds when the overlay appears in the final timeline.
• duration – How long the overlay remains visible.

"overlays": [
  {
    "file": "edit/animations/slot_1/render.mp4",
    "start_in_output": 0.0,
    "duration": 5.0
  }
]

subtitles

The subtitles field is a string containing the path to an SRT file. The renderer burns these subtitles after applying all overlays, as implemented in the build_master_srt function within helpers/render.py.

How to Manually Edit EDL JSON Files

Follow these steps to edit the EDL specification manually without touching the Python codebase:

1. Locate the file – Open edl.json in your project root or edit directory (e.g., my-project/edl.json).

2. Configure sources – Add entries for each raw clip using absolute paths or paths relative to the EDL file location.

3. Define ranges – For each segment:

   • Reference the source ID from your sources map.
   • Set precise start and end timestamps (obtain these via ffprobe or a video player).
   • Optionally add beat, quote, and reason for documentation.

4. Set the grade – Choose a preset from helpers/grade.py, write a custom ffmpeg filter string, or use "auto" for automatic per-segment grading.

5. Add overlays – Point file to rendered overlay videos and specify start_in_output to align them with your timeline.

6. Reference subtitles – Provide the path to an SRT file generated by transcription helpers like helpers/transcribe.py.

7. Update duration – Recalculate total_duration_s as the sum of all range durations plus overlay durations.

After editing, validate the file by running a dry-run of the renderer:

python helpers/render.py edl.json -o preview.mp4 --preview

If the JSON is malformed, the script aborts with an error message pointing to the specific line.

Rendering Pipeline Implementation

The helpers/render.py script implements the runtime interpretation of the EDL JSON specification. Key functions include:

• extract_all_segments – Reads the ranges array and extracts each clip from the specified sources.
• concat_segments – Concatenates extracted clips in the order defined by the ranges array.
• build_master_srt – Handles subtitle burning after overlay compositing.

When grade is set to "auto", the pipeline invokes auto_grade_for_clip from helpers/grade.py to apply subtle corrections per segment.

EDL JSON Code Examples

Minimal EDL (Two Cuts, No Effects)

{
  "version": 1,
  "sources": {
    "A": "videos/raw1.mp4",
    "B": "videos/raw2.mp4"
  },
  "ranges": [
    { "source": "A", "start": 0.0, "end": 5.0 },
    { "source": "B", "start": 10.0, "end": 15.0 }
  ],
  "grade": null,
  "total_duration_s": 10.0
}

Adding Overlay Animations

{
  "version": 1,
  "sources": {
    "C": "videos/interview.mp4"
  },
  "ranges": [
    { "source": "C", "start": 0.0, "end": 30.0 }
  ],
  "grade": "warm_cinematic",
  "overlays": [
    {
      "file": "edit/animations/slot_3/render.webm",
      "start_in_output": 2.5,
      "duration": 4.0
    }
  ],
  "subtitles": "edit/master.srt",
  "total_duration_s": 30.0
}

Using Automatic Color Grading

{
  "version": 1,
  "sources": {
    "D": "videos/raw.mp4"
  },
  "ranges": [
    { "source": "D", "start": 5.0, "end": 20.0 }
  ],
  "grade": "auto",
  "total_duration_s": 15.0
}

Summary

• The EDL JSON format specification is defined in SKILL.md (lines 70-86) and serves as the central manifest for video-use projects.
• Required fields include version, sources, ranges, grade, and total_duration_s.
• Optional fields overlays and subtitles enable complex compositing and captioning workflows.
• Manual editing requires updating JSON arrays and objects without modifying helpers/render.py.
• The rendering pipeline validates the schema and provides helpful error messages for malformed JSON.

Frequently Asked Questions

What is the EDL JSON format specification used for in video-use?

The EDL JSON format specification acts as a machine-readable edit decision list that drives the entire rendering pipeline. It tells helpers/render.py which source files to pull from, which time ranges to extract, how to color grade the footage, and where to composite overlays and subtitles.

How do I add overlay animations to an EDL JSON file?

Add an object to the overlays array containing the file path (relative to the EDL location), the start_in_output timestamp in seconds, and the duration. The renderer composites these on top of the base video after concatenating the source ranges.

Can I use automatic color grading in the EDL format?

Yes. Set the grade field to the string "auto". When helpers/render.py processes the file, it calls auto_grade_for_clip from helpers/grade.py for each segment, applying computed corrections individually rather than using a global preset or static filter.

Where is the EDL JSON schema officially defined?

The canonical schema definition resides in the SKILL.md file at the root of the browser-use/video-use repository, specifically under the "## EDL format" section (lines 70-86). This documentation specifies the exact key names, data types, and optional fields supported by the rendering engine.

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