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

> Understand the EDL JSON format specification for video-use. Learn how to manually edit this manifest file to control clip assembly, color grades, overlays, and subtitles for your final video.

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

---

**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](https://github.com/browser-use/video-use) repository. According to the specification defined in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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.

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

```json
"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`](https://github.com/browser-use/video-use/blob/main/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.

```json
"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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/edl.json) in your project root or edit directory (e.g., [`my-project/edl.json`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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:

```bash
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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) to apply subtle corrections per segment.

## EDL JSON Code Examples

### Minimal EDL (Two Cuts, No Effects)

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

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

```json
{
  "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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) processes the file, it calls `auto_grade_for_clip` from [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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.