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

> Learn the EDL format for video-use. Discover how it defines cuts, overlays, and color grades using timestamped ranges and filters, all automated by render.py. Optimize your video workflow today.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: deep-dive
- Published: 2026-07-08

---

**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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), the renderer extracts each range using ffmpeg with stream copying to avoid generational loss:

```bash
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:

```bash
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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) script reads [`edl.json`](https://github.com/browser-use/video-use/blob/main/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:

```bash
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

```json
{
  "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

```json
{
  "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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/edit/edl.json) relative to the project root. This path is the default input for [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), which reads the JSON to execute the render pipeline.