# EDL Format Explained: Required Fields for Video Editing in video-use

> Learn the EDL format for video editing. Understand required fields like version, sources, and ranges along with optional grading and overlays for efficient video production.

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

---

**The EDL (Edit Decision List) format in video-use is a JSON schema that defines how raw source clips are combined into a final edit through required fields including `version`, `sources`, `ranges`, and optional grading, overlays, and subtitle specifications.**

The **EDL format** provides the declarative backbone for the video-use rendering engine, allowing editors to specify precise cut points, color grading, and compositing instructions in machine-readable JSON. According to the specification in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) and the implementation in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), the EDL acts as a contract between editorial decisions and automated video generation.

## Required Top-Level Fields in the EDL Format

The video-use engine requires specific top-level keys to construct a valid edit timeline. These fields are validated by the rendering pipeline before any media processing begins.

### version

The `version` field is an integer specifying the EDL schema version. The current implementation requires version `1` as defined in [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) at line 268.

### sources

The `sources` object maps unique identifiers to video file paths. Each key represents a source ID referenced in the ranges array, while the value is an absolute or relative path resolved via [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) → `resolve_path`.

```json
{
  "sources": {
    "C0103": "/abs/path/C0103.MP4",
    "B0021": "/abs/path/B0021.MP4"
  }
}

```

### ranges

The `ranges` array contains the ordered sequence of cut segments. Each range object must include:

- `source`: ID matching a key in the `sources` object
- `start`: Float value in seconds
- `end`: Float value in seconds

Optional but recommended fields include `beat` for semantic labels like `HOOK`, `quote` for transcript excerpts, and `reason` for editorial justification. The rendering logic in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) extracts these segments and concatenates them sequentially.

```json
{
  "ranges": [
    {
      "source": "C0103",
      "start": 2.42,
      "end": 6.85,
      "beat": "HOOK",
      "quote": "Welcome to the future of video editing",
      "reason": "Cleanest delivery, stops before slip at 38.46"
    }
  ]
}

```

## Optional Fields for Advanced Editing

Beyond the minimum requirements, the EDL format supports professional grading, compositing, and subtitle workflows.

### grade

The `grade` field accepts a preset name (e.g., `warm_cinematic`), a raw ffmpeg filter string, or the value `auto` to trigger per-segment auto-grading. When set to `auto`, [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) expands this to a sentinel value and invokes `auto_grade_for_clip` for each segment.

```json
{
  "grade": "auto"
}

```

### overlays

The optional `overlays` array enables compositing of animation or video elements on top of the base edit. Each overlay object requires `file` (path relative to the edit directory), `start_in_output` (float in seconds), and `duration` (float in seconds). The implementation in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) (around line 640) shifts each overlay's PTS so frame 0 aligns with the specified start time.

```json
{
  "overlays": [
    {
      "file": "edit/animations/slot_1/render.mp4",
      "start_in_output": 0.0,
      "duration": 5.0
    }
  ]
}

```

### subtitles

The optional `subtitles` field specifies a path (relative to the edit directory) to a master SRT file. If provided, [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) burns these subtitles into the final output during the rendering phase.

```json
{
  "subtitles": "edit/master.srt"
}

```

### total_duration_s

While not strictly required for rendering, `total_duration_s` provides an expected duration in seconds for validation and reporting purposes, helping editors verify that the assembled timeline matches their target length.

## Complete EDL Format Example

Here is a minimal yet functional EDL that demonstrates the required structure alongside optional advanced features. This JSON is directly consumable by the video-use rendering pipeline.

```json
{
  "version": 1,
  "sources": {
    "C0103": "/abs/path/C0103.MP4",
    "B0021": "/abs/path/B0021.MP4"
  },
  "ranges": [
    {
      "source": "C0103",
      "start": 2.42,
      "end": 6.85,
      "beat": "HOOK",
      "quote": "Welcome to the future of video editing",
      "reason": "Cleanest delivery, stops before slip at 38.46"
    },
    {
      "source": "B0021",
      "start": 0.0,
      "end": 5.0,
      "beat": "INTRO"
    }
  ],
  "grade": "auto",
  "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 with video-use

Once your EDL JSON is complete, pass it to the rendering helper to generate the final video. The [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) script handles path resolution, segment extraction, grading application, concatenation, and overlay compositing.

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

```

This command invokes the rendering logic described in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) lines 15-19, processing the EDL through the full pipeline.

## How the Rendering Pipeline Validates EDL Fields

The [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) implementation enforces strict validation of the EDL structure. It first checks for the presence of `sources` and `ranges`, then resolves each source path through `resolve_path`, extracts the specified time ranges, applies the grading filters, and concatenates the segments in order. Overlays are processed separately with PTS adjustments to align with the output timeline, and subtitles are burned in if the field is present.

## Summary

- The **EDL format** in video-use is a JSON-based Edit Decision List that declaratively describes video edits.
- **Required fields** are `version` (integer), `sources` (object mapping IDs to paths), and `ranges` (array of cut segments with start/end times).
- **Optional fields** include `grade` (color grading presets or auto-grading), `overlays` (compositing instructions), `subtitles` (SRT path), and `total_duration_s` (validation metric).
- The rendering pipeline in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) validates, processes, and assembles the final video from the EDL specification.
- All paths in `sources` are resolved via `resolve_path`, while overlay timing is synchronized by shifting PTS values in the compositing stage.

## Frequently Asked Questions

### What is the EDL format used for in video-use?

The EDL format serves as a machine-readable instruction set that tells the video-use rendering engine how to assemble raw source clips into a final edited video. It specifies cut points, color grading, overlays, and subtitles in a structured JSON format interpreted by [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py).

### Is the grade field required in the EDL format?

No, the `grade` field is optional. If omitted, no grading is applied. You can specify a preset name like `warm_cinematic`, a raw ffmpeg filter string, or set it to `auto` to trigger per-segment auto-grading via the `auto_grade_for_clip` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py).

### How does video-use handle overlay timing in the EDL format?

Each overlay object in the `overlays` array includes `start_in_output` and `duration` fields. During rendering, [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) adjusts the overlay's presentation timestamp (PTS) so that frame 0 of the overlay aligns with the specified `start_in_output` time in the final timeline, typically around line 640 of the rendering script.

### Can I use relative paths in the EDL sources field?

Yes, the `sources` field accepts both absolute and relative paths. The rendering engine resolves all paths through the `resolve_path` function in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), allowing flexibility in how source files are referenced relative to the EDL file location.