Edit Decision List (EDL) Format in video‑use: Complete JSON Specification

The Edit Decision List (EDL) format in video‑use is a JSON file with three top‑level sections: clips (required ordered segments), overlays (optional per‑clip visual elements), and global (optional render‑wide defaults).

The browser-use/video-use repository provides a lightweight, FFmpeg‑based video pipeline that uses this EDL format to declaratively describe multi‑clip edits, colour grading, overlays, and subtitle integration. The format is intentionally minimal—omitted fields fall back to sensible defaults—making it suitable for both hand‑authored edits and programmatic generation.

---

Top‑Level Structure of the EDL JSON Format

The EDL file is a single JSON object containing up to three keys.

Key	Required	Purpose
clips	Yes	Ordered array of video segments to concatenate
overlays	No	Per‑clip visual/audio overlay specifications
global	No	Default settings applied to all clips

---

The clips Array: Core Timeline Segments

Each element in clips defines a contiguous segment pulled from a source video file. Clips are concatenated in array order to form the final output.

Required Fields per Clip

Field	Type	Description
source	string	Path to source video (relative to EDL file or absolute)
in	number	Start time in seconds within the source
out	number	End time in seconds within the source

Optional Clip Fields

Field	Type	Description
grade	string	Colour grade: "auto", preset name, or raw FFmpeg filter string
overlays	array	List of overlay objects (see below) applied to this clip

In helpers/render.py, the renderer iterates over edl["clips"] (lines 1‑20) and passes each clip's grade value to resolve_grade_filter() (lines 66‑84). This function handles three cases: preset names mapped through helpers/grade.py, raw FFmpeg filter strings passed through unchanged, or "auto" to trigger auto_grade_for_clip for per‑segment analysis.

---

Per‑Clip overlays: Images, Text, and Animations

The optional overlays field contains an array of objects specifying visual or audio elements composited on top of the clip.

Field	Type	Description
type	string	"image", "text", or "animation"
path	string	File path to overlay asset (image, video, etc.)
start	number	Seconds from clip start when overlay appears
duration	number	Seconds the overlay remains visible
position	string	Placement specification (e.g., "center", "top-right")

The final filter graph built in helpers/render.py (lines 600‑618) composites all overlays before applying subtitles.

---

The global Object: Render‑Wide Defaults

Settings in global apply when individual clips omit corresponding fields.

Field	Type	Description
grade	string	Default colour grade for clips without explicit grade
subtitle_path	string	Path to master SRT merged with per‑source transcripts
subtitle_style	string	Custom ASS style; default defined as SUB_FORCE_STYLE in render.py (lines 51‑56)

---

How the Renderer Processes the EDL

The helpers/render.py script executes a five‑stage pipeline:

1. Parse – json.load() reads the EDL; the script validates required fields and iterates edl["clips"]
2. Resolve grades – resolve_grade_filter() (lines 66‑84) determines the FFmpeg filter for each clip
3. Extract segments – extract_segment() (lines 52‑99) invokes FFmpeg to cut the source range, apply tonemapping if needed, scale output resolution, and bake in a 30 ms audio fade (lines 87‑90)
4. Composite overlays – Build FFmpeg filter graph with overlay positioning and subtitle rendering
5. Concatenate and output – Join all processed segments and write to the -o <output> path

---

Practical EDL Examples

Minimal Two‑Clip Edit

{
  "clips": [
    {
      "source": "src/intro.mp4",
      "in": 0,
      "out": 7.5,
      "grade": "auto"
    },
    {
      "source": "src/main-talk.mp4",
      "in": 12.3,
      "out": 45.9
    }
  ],
  "global": {
    "grade": "film-look",
    "subtitle_path": "subtitles/master.srt"
  }
}

The first clip triggers automatic grading via auto_grade_for_clip. The second inherits the global "film-look" preset.

Clip with Image Overlay

{
  "clips": [
    {
      "source": "src/interview.mp4",
      "in": 30,
      "out": 60,
      "grade": "auto",
      "overlays": [
        {
          "type": "image",
          "path": "assets/logo.png",
          "start": 5,
          "duration": 10,
          "position": "top-right"
        }
      ]
    }
  ]
}

The logo appears 5 seconds into the clip and displays for 10 seconds.

Full Render Command

python helpers/render.py edl.json -o final.mp4 --build-subtitles

---

Key Source Files Defining the EDL Format

File	Role
helpers/render.py	Core renderer: EDL parsing, grade resolution, segment extraction, concatenation, overlay compositing, subtitle baking
helpers/grade.py	Preset grade definitions and automatic grading logic
helpers/timeline_view.py	CLI visualization of EDL timeline for pre‑render review

---

Summary

• EDL format in video‑use is a JSON file with clips (required), overlays (optional per‑clip), and global (optional defaults)
• Clip segments specify source, in/out times, optional grade (preset/"auto"/raw filter), and overlays array
• Grade resolution happens in resolve_grade_filter() with three supported input types
• Rendering pipeline parses EDL, extracts graded segments with extract_segment(), composites overlays, and concatenates output
• Minimal syntax — omitted fields use defaults, enabling both manual authoring and programmatic generation

---

Frequently Asked Questions

What file format does video‑use use for edit decisions?

video‑use uses a JSON file as its Edit Decision List (EDL) format. The JSON structure contains an ordered clips array, optional per‑clip overlays, and an optional global defaults object. This JSON EDL is parsed directly by helpers/render.py using Python's standard json module.

How do I specify colour grading in an EDL file?

Set the grade field to one of three values: "auto" for automatic per‑segment analysis, a preset name defined in helpers/grade.py, or a raw FFmpeg filter string passed through unchanged. Clip‑level grades override the global.grade default. The resolve_grade_filter() function in helpers/render.py (lines 66‑84) handles all three cases.

Can I add logos or watermarks to specific clips?

Yes. Include an overlays array inside any clip object. Each overlay needs type (e.g., "image"), path to the asset, start time relative to clip beginning, duration, and position. The renderer composites these via FFmpeg filter graphs during the final concatenation stage.

What happens if I omit optional fields in the EDL?

Omitted fields fall back to defaults: clips without grade inherit from global.grade; overlays are only applied when explicitly declared; subtitle rendering is skipped without subtitle_path. This minimal design keeps EDL files concise and generator‑friendly.

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