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

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, the load_edl() function implements this detection logic:

# 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:

# 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) 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 inside the project's edit/ folder. On subsequent runs, the CLI command automatically triggers the migration:

# 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 – Core rendering pipeline; parses, migrates, and applies the EDL. Contains version detection (load_edl) and the migration table (EDL_MIGRATIONS).
• 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 – 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 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 (set to "2.0"). This string is compared against the version field in loaded EDLs to determine which migration functions to apply.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}