Understanding the EDL Format in Video-Use: How Cuts, Overlays, and Color Grades Work

The EDL format in video-use is a JSON-based Edit Decision List that defines cuts as timestamped ranges, color grades as preset strings or raw ffmpeg filters, and overlays as time-shifted video layers, all consumed by the render.py helper to automate the final composite.

The browser-use/video-use repository automates video editing through a deterministic JSON schema called the EDL format (Edit Decision List). Stored at edit/edl.json, this human-readable configuration encodes every editorial decision—including cuts, color grades, and overlay placements—that the rendering pipeline executes step-by-step without manual intervention.

What Is the EDL Format?

The EDL format is a JSON object that serves as the single source of truth for the video composition. According to the schema documented in SKILL.md (lines 268-289), the structure includes seven top-level keys that drive the render pipeline:

• version – Schema version (currently 1) for future-proofing.
• sources – Mapping of short IDs (e.g., C0103) to absolute source video paths, allowing the renderer to locate footage without hard-coding full paths in every range.
• ranges – Array of cut objects defining which segments to extract from source files.
• grade – Color-grade specification, either a preset name, raw ffmpeg filter string, or "auto".
• overlays – Array of overlay objects (animations, captions) with timing data.
• subtitles – Optional path to the master SRT file.
• total_duration_s – Expected total runtime for sanity checks after concatenation.

How the EDL Defines Cuts

The ranges Array Structure

Each entry in the ranges array represents a cut with the following properties:

• source – The short ID referencing the source video in the sources map.
• start / end – Timestamps in seconds marking segment boundaries, always snapped to word boundaries per the hard rules.
• beat, quote, reason – Optional metadata fields for LLM reasoning and documentation.

Lossless Per-Segment Extraction

In helpers/render.py, the renderer extracts each range using ffmpeg with stream copying to avoid generational loss:

ffmpeg -ss [start] -to [end] -c copy -avoid_negative_ts make_zero

These segments are concatenated only after all cuts are extracted and graded.

How Overlays Work in the EDL

The overlays array defines secondary video layers such as intro animations or captions. Each overlay object contains:

• file – Absolute or relative path to the rendered overlay clip (e.g., edit/animations/slot_1/render.mp4).
• start_in_output – When the overlay appears in the final timeline (seconds).
• duration – How long the overlay remains visible.

PTS Shifting for Timeline Alignment

To align overlays with the final composite timeline, the renderer applies ffmpeg’s setpts filter following hard rule 4:

setpts=PTS-STARTPTS+T/TB

This shifts the overlay’s presentation timestamp (PTS) so that the animation aligns precisely with the intended start_in_output window, regardless of when the overlay file begins internally.

Color Grading in the EDL

The grade field in the EDL accepts three distinct value types, processed by helpers/grade.py:

Presets vs Raw Filters

• Preset names (e.g., "warm_cinematic", "neutral_punch") map to predefined filter chains defined in the grader module.
• Raw ffmpeg filter strings (e.g., "curves=0.9:1.1:saturation=1.2") are passed directly to the video filter chain.
• "auto" triggers the grader to infer a suitable filter per segment based on content analysis.

Per-Segment Application

Following hard rule 5, color grading occurs during the per-segment extraction phase, not after concatenation. This avoids a second re-encode, preserving quality and reducing processing time. The grader applies the specified filter while extracting each range from the source.

Rendering the EDL

The helpers/render.py script reads edl.json and executes a four-stage pipeline:

1. Cut extraction with per-segment grading.
2. Concatenation of graded segments.
3. Overlay composition with PTS shifting.
4. Subtitle burn-in (if present), applied last per hard rule 1 to avoid being hidden by overlays.

Execute the render from the repository root:

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

Optional flags include --preview for fast 720p validation and --build-subtitles to regenerate the master SRT before compositing.

Example: Minimal EDL with Single Cut

{
  "version": 1,
  "sources": { "C0103": "/abs/path/C0103.MP4" },
  "ranges": [
    {
      "source": "C0103",
      "start": 2.42,
      "end": 6.85,
      "beat": "HOOK",
      "quote": "...",
      "reason": "Cleanest delivery"
    }
  ],
  "grade": "warm_cinematic",
  "overlays": [],
  "subtitles": null,
  "total_duration_s": 4.43
}

Example: Complex EDL with Custom Grade and Overlay

{
  "version": 1,
  "sources": {
    "C0103": "/abs/path/C0103.MP4",
    "C0108": "/abs/path/C0108.MP4"
  },
  "ranges": [
    {
      "source": "C0103",
      "start": 2.42,
      "end": 6.85,
      "beat": "HOOK",
      "reason": "Cleanest delivery, stops before slip at 38.46."
    },
    {
      "source": "C0108",
      "start": 14.30,
      "end": 28.90,
      "beat": "SOLUTION",
      "reason": "Only take without the false start."
    }
  ],
  "grade": "curves=0.9:1.1:saturation=1.2",
  "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
}

Summary

• The EDL format is a JSON configuration file at edit/edl.json that declaratively defines the entire video edit.
• Cuts are specified in the ranges array with source-relative timestamps and extracted losslessly via ffmpeg.
• Color grades support presets, raw ffmpeg filters, or automatic inference, applied during segment extraction to avoid re-encoding.
• Overlays are positioned using PTS shifting (setpts=PTS-STARTPTS+T/TB) to align with the final timeline.
• The helpers/render.py script consumes the EDL to automate extraction, grading, concatenation, and final compositing.

Frequently Asked Questions

What does EDL stand for in video-use?

EDL stands for Edit Decision List. In the browser-use/video-use codebase, it is a JSON file that encodes editorial decisions—what footage to use, how to color grade it, and where to place overlays—allowing the entire rendering process to be automated and version-controlled.

How do I add an overlay to the EDL?

Add an object to the overlays array with the file path, start_in_output time, and duration. The renderer automatically shifts the overlay’s PTS using setpts=PTS-STARTPTS+T/TB so it appears at the correct time in the final output, regardless of internal timing in the source file.

Can I use custom ffmpeg filters for color grading?

Yes. The grade field accepts raw ffmpeg filter strings (e.g., "curves=0.9:1.1:saturation=1.2") in addition to preset names like "warm_cinematic". Custom filters are passed directly to the ffmpeg command line during per-segment extraction in helpers/grade.py.

Where does the EDL file live in a video-use project?

The EDL file is generated and stored at edit/edl.json relative to the project root. This path is the default input for helpers/render.py, which reads the JSON to execute the render pipeline.

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