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

> Understand the Edit Decision List EDL format in video-use. Explore its JSON structure with clips, overlays, and global sections for efficient video editing.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: api-reference
- Published: 2026-08-06

---

**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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/render.py) (lines 51‑56) |

---

## How the Renderer Processes the EDL

The [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/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

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

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

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

```

---

## Key Source Files Defining the EDL Format

| File | Role |
|------|------|
| [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) | Core renderer: EDL parsing, grade resolution, segment extraction, concatenation, overlay compositing, subtitle baking |
| [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) | Preset grade definitions and automatic grading logic |
| [`helpers/timeline_view.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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.