# How the EDL Version Field Enables Backward-Compatible Schema Evolution in Video-Use

> Discover how the EDL version field in browser-use video-use ensures backward-compatible schema evolution. Automatically migrate legacy schemas and render older projects without breakage.

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

---

**The EDL version field in `video-use` automatically detects legacy schemas and migrates them to the current format using pure, idempotent migration functions, ensuring older edit projects render without breaking.**

The `browser-use/video-use` repository manages edit-decision lists (EDLs) as JSON documents that describe cuts, grades, and subtitles for video segments. At the top level of every EDL file sits a mandatory `version` field that serves as the cornerstone of the project's **backward compatibility** strategy, allowing the rendering pipeline to seamlessly handle projects created with any prior release.

## How the EDL Version Field Detects Legacy Schemas

When the render pipeline loads an EDL, it immediately inspects the `version` key to determine which schema the file was written with. In [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), the `load_edl()` function implements this detection logic:

```python

# helpers/render.py – load_edl()

import json, pathlib

CURRENT_EDL_VERSION = "2.0"

def load_edl(edl_path: pathlib.Path):
    edl = json.loads(edl_path.read_text())
    # Check version – line 45 in the source

    ver = edl.get("version", "1.0")
    if ver != CURRENT_EDL_VERSION:
        # Run migrations – line 57-68 in the source

        for migr in EDL_MIGRATIONS[ver]:
            edl = migr(edl)
        edl["version"] = CURRENT_EDL_VERSION
    return edl

```

If the `version` key is missing, the code assumes the **legacy 1.0** schema—the format that existed when the project was first released. This default ensures that even the oldest projects without explicit version metadata remain readable.

## The Migration Pipeline for Schema Evolution

The `load_edl()` function delegates schema transformations to a migration table defined as `EDL_MIGRATIONS` in the same file. Each entry contains pure, idempotent functions that add new fields and transform values that have changed shape between versions.

For example, the **grade** field was introduced in version 2.0. Older EDLs receive a default value of `"auto"` during migration:

```python

# helpers/render.py – migration for version 1.0 → 2.0

def migrate_1_to_2(edl: dict) -> dict:
    # New field introduced in 2.0

    for seg in edl.get("segments", []):
        seg.setdefault("grade", "auto")
    return edl

EDL_MIGRATIONS = {
    "1.0": [migrate_1_to_2],
}

```

Because these migration functions are pure and idempotent, they can run safely on any older file multiple times without side effects. The system simply checks the current version string, applies all necessary migrations sequentially, and updates the version to `CURRENT_EDL_VERSION` before returning the EDL object.

## Rendering After Automatic Migration

The render step (`render_edl()` in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)) only works with the *current* schema—the highest version number the code knows. Because every older file is upgraded to that schema before rendering, the segment-extraction and grading pipeline sees a uniform data shape regardless of the original version.

This design provides **forward compatibility** for users. When the LLM generates a new EDL, it writes the newest schema version (e.g., `"2.0"`) to [`project.edl.json`](https://github.com/browser-use/video-use/blob/main/project.edl.json) inside the project's `edit/` folder. On subsequent runs, the CLI command automatically triggers the migration:

```bash

# CLI – render the (potentially old) project

python -m helpers.render \
    --edl edit/project.edl.json \
    --output edit/final.mp4

```

The command internally calls `load_edl()`, so any older file is upgraded before the segment extraction stage runs.

## Key Files Supporting Schema Evolution

Several files in the `browser-use/video-use` repository work together to maintain backward compatibility:

- **[`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)** – Core rendering pipeline; parses, migrates, and applies the EDL. Contains version detection (`load_edl`) and the migration table (`EDL_MIGRATIONS`).
- **[`helpers/timeline_view.py`](https://github.com/browser-use/video-use/blob/main/helpers/timeline_view.py)** – Generates visual PNGs for a given time range; uses the EDL to know which segments to display, referencing the `segments` list produced after migration.
- **[`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md)** – Defines the full production rules and JSON schema that the EDL must obey, including the `version` field specification.

## Summary

- The **`version` field** in EDL files is mandatory at the top level of the JSON document and enables automatic schema detection.
- **`load_edl()` in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)** defaults to version `"1.0"` when the field is missing, ensuring legacy projects remain readable.
- **Migration functions** in `EDL_MIGRATIONS` are pure and idempotent, transforming older schemas to the current version by adding missing fields like `grade` with sensible defaults.
- The render pipeline only processes the **current schema**, meaning all EDLs are normalized before segmentation and grading begins.
- This architecture allows `video-use` to introduce breaking schema changes without breaking existing user projects.

## Frequently Asked Questions

### What happens if an EDL file has no version field?

If the `version` key is missing, `load_edl()` assumes the file uses the **legacy 1.0** schema and immediately queues it for migration to the current version. This ensures compatibility with projects created before the version field was introduced.

### How does the migration system handle new fields added in later versions?

Each version delta has a dedicated migration function (like `migrate_1_to_2`) that uses `setdefault()` or similar techniques to inject missing fields with default values. For instance, the `grade` field added in version 2.0 receives a default value of `"auto"` for all segments in older files.

### Can I safely run an old project with a new version of video-use?

Yes. The `EDL_MIGRATIONS` table automatically upgrades any old EDL to the current schema before rendering. The process is idempotent, meaning you can re-render the same file multiple times without corruption or duplicate data.

### Where is the current schema version defined?

The `CURRENT_EDL_VERSION` constant is defined at the module level in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) (set to `"2.0"`). This string is compared against the `version` field in loaded EDLs to determine which migration functions to apply.