# EDL JSON Schema for video-use: How to Create and Edit EDL Files

> Learn the EDL JSON schema to create and edit EDL files. Drive your video-editing pipeline with this essential guide for browser-use video-use.

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

---

**The EDL (Edit Decision List) is a JSON document that drives the entire video-editing pipeline in the browser-use/video-use repository, specifying source videos, cut ranges, color grades, and overlays that [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) processes to produce the final output video.**

The video-use project uses a lightweight, human-readable JSON schema to orchestrate video editing without a GUI. This Edit Decision List format allows you to version-control your editorial decisions and programmatically generate complex video cuts by declaring the edit structure in a single file.

## What is the EDL JSON Schema?

The EDL JSON schema is defined in the repository’s [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) file (lines 268-286) and serves as the single source of truth for the rendering pipeline. When you execute `python helpers/render.py <edl>.json`, the tool parses this file to extract video ranges, apply color grades via FFmpeg, stitch segments together, composite animation overlays, and burn subtitles.

The schema consists of seven top-level keys that declare the entire edit structure.

### Schema Structure

| Key | Type | Description |
|-----|------|-------------|
| `version` | number | Schema version (currently always `1`). |
| `sources` | object | Maps short identifiers (e.g., `"C0103"`) to absolute or relative file paths. |
| `ranges` | array | Cut segments with timestamps, labels, and editorial notes. |
| `grade` | string | Color grade preset, FFmpeg filter string, or `"auto"`. |
| `overlays` | array (optional) | Animation clips to composite on the final timeline. |
| `subtitles` | string (optional) | Path to an SRT file for hard-burning into the output. |
| `total_duration_s` | number (optional) | Expected output length for validation. |

### The Ranges Object

Each entry in the `ranges` array specifies a clip to extract from a source video:

- `source`: Identifier matching a key in `sources`
- `start` / `end`: Timestamps in **seconds** (float values)
- `beat`: Optional editorial label (e.g., `"HOOK"`, `"SOLUTION"`)
- `quote`: Optional transcript excerpt for reference
- `reason`: Free-form justification for auditability

## How to Create an EDL File Manually

Follow these steps to author an EDL from scratch:

1. **Gather source files** – Copy or symlink raw footage into your working directory.

2. **Identify cut points** – Use [`helpers/timeline_view.py`](https://github.com/browser-use/video-use/blob/main/helpers/timeline_view.py) or any video player to note the exact start and end seconds you want to keep.

3. **Write the JSON** – Start with the template below, mapping `sources` to file paths and filling in the `ranges` you identified.

4. **Select a grade** – Choose a preset defined in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py), provide a raw FFmpeg filter string, or use `"auto"` for per-segment auto-grading.

5. **Add overlays** – Include only if you have pre-rendered animation clips ready to composite.

6. **Specify subtitles** – Provide a path to an SRT file if you want captions hard-burned into the final video.

7. **Save** – Use any filename ending in `.json` (e.g., [`my-edit.edl.json`](https://github.com/browser-use/video-use/blob/main/my-edit.edl.json)).

## How to Edit an Existing EDL File

To modify an existing edit:

- Open the JSON file in any text editor.
- Update timestamps, add or remove range objects, change the `grade` value, insert new overlay entries, or adjust the `subtitles` path.
- Maintain valid JSON syntax (commas between objects, matching braces and quotes).
- Re-run [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) to generate the updated video.

## Example EDL File

Below is a complete, valid EDL JSON document following the video-use schema:

```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",
      "quote": "...",
      "reason": "Cleanest delivery, stops before slip at 38.46."
    },
    {
      "source": "C0108",
      "start": 14.30,
      "end": 28.90,
      "beat": "SOLUTION",
      "quote": "...",
      "reason": "Only take without the false start."
    }
  ],
  "grade": "warm_cinematic",
  "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
}

```

## Rendering the EDL

Execute the render pipeline using the command below. The [`render.py`](https://github.com/browser-use/video-use/blob/main/render.py) script reads your EDL, resolves the grade filters, and assembles the final video.

```bash
python helpers/render.py my-edit.edl.json -o final.mp4

```

Additional flags:

- `--build-subtitles`: Generates a master SRT from source transcripts before burning.
- `--no-subtitles`: Skips subtitle burning entirely.

## Automatic Color Grading

Setting `"grade": "auto"` in your EDL triggers per-segment auto-grading via the `resolve_grade_filter` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) (lines 66-85). This automatically applies corrections such as:

```python
def auto_grade_for_clip(video, start=0.0, duration=None, verbose=False):
    return "eq=contrast=1.03:saturation=0.98", {}

```

You can also reference presets defined in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) or provide raw FFmpeg filter strings directly in the `grade` field for custom color correction.

## Summary

- The **EDL JSON schema** in video-use is a minimal, versionable format that controls the entire rendering pipeline without a GUI.
- Key components include `sources` (file mappings), `ranges` (cut lists with timestamps and metadata), and `grade` (color correction directives).
- The file is **pure JSON**—editable in any text editor or generated programmatically.
- Execute `python helpers/render.py <edl>.json` to process the EDL and output the final video.

## Frequently Asked Questions

### What file extension should I use for EDL files?

While any `.json` extension works, the convention is to name your files with the [`.edl.json`](https://github.com/browser-use/video-use/blob/main/.edl.json) suffix (e.g., [`project.edl.json`](https://github.com/browser-use/video-use/blob/main/project.edl.json)) to distinguish them from configuration or data JSONs in your repository.

### Can I use relative paths in the sources object?

Yes. The `sources` object accepts both absolute and relative paths. Relative paths are resolved from the directory where you execute [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), making it easy to share projects across different machines.

### How does the "auto" grade value work?

When `"grade": "auto"` is set, [`render.py`](https://github.com/browser-use/video-use/blob/main/render.py) calls `auto_grade_for_clip` for each range individually during the `resolve_grade_filter` phase (lines 66-85), applying algorithmic corrections based on the source footage's characteristics rather than a static filter.

### Where are the color grade presets defined?

Preset grade strings like `"warm_cinematic"` are defined in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py). You can reference these presets by name in the `grade` field, or provide a raw FFmpeg filter string (e.g., `"eq=contrast=1.1:brightness=0.05"`) for custom color correction.