How the EDL Grade Field Supports Preset Names, Raw Filters, and Auto Mode in video-use

The EDL grade field accepts preset color-grade names, raw FFmpeg filter strings, or the literal "auto" mode, which the resolve_grade_filter function in helpers/render.py resolves into per-segment color grading commands.

The browser-use/video-use repository provides flexible color grading through the Edit Decision List (EDL) grade field. This single field supports three distinct input types—named presets, raw filter syntax, and automatic analysis—allowing editors to apply uniform corrections or per-clip adaptive adjustments without modifying the extraction pipeline.

Understanding the EDL Grade Field Implementation

The implementation spans two core modules: helpers/render.py, which resolves the field value, and helpers/grade.py, which provides the preset catalog and auto-grade algorithm.

The Resolver Function in helpers/render.py

The entry point is resolve_grade_filter (lines 66–84 in helpers/render.py). This function inspects the grade string and returns either an empty string (no grading), a concrete FFmpeg filter, or the sentinel "__AUTO__" for deferred per-segment processing.

def resolve_grade_filter(grade_field: str | None) -> str:
    """The EDL's 'grade' field can be a preset name, a raw ffmpeg filter, or 'auto'.

    Returns the filter string to embed into the per-segment -vf chain.
    For 'auto', returns the sentinel "__AUTO__" which is resolved per-segment.
    """
    if not grade_field:
        return ""
    if grade_field == "auto":
        return "__AUTO__"
    # Preset names are short identifiers, filter strings contain '=' or ','.

    if re.fullmatch(r"[a-zA-Z0-9_\-]+", grade_field):
        try:
            return get_preset(grade_field)
        except KeyError:
            print(f"warning: unknown preset '{grade_field}', using as raw filter")
            return grade_field
    return grade_field

The logic branches as follows:

• Empty or null: Returns "", indicating no color-grade filter should be applied.
• Literal "auto": Returns "__AUTO__", triggering per-segment analysis later in the pipeline.
• Alphanumeric identifiers: Matches the regex [a-zA-Z0-9_\-]+ and attempts a preset lookup via get_preset. If the name is unknown, it falls back to treating the string as a raw filter with a warning.
• Complex strings: Any value containing = or , bypasses preset lookup and returns verbatim as a raw FFmpeg filter.

Preset Catalog and Auto Logic in helpers/grade.py

The helpers/grade.py module defines the PRESETS dictionary (lines 38–62) mapping names like "subtle" or "warm_cinematic" to complete FFmpeg filter strings. The get_preset(name) function retrieves these values, raising KeyError for unrecognized names.

For auto mode, the module provides auto_grade_for_clip (lines 84–132). When resolve_grade_filter returns "__AUTO__", the extract_all_segments loop in helpers/render.py (lines 27–52) invokes this function for each individual segment. It analyzes a short sample of frames, computes brightness, contrast, and saturation metrics, and generates a bounded eq=... filter string tailored to that specific clip.

How Input Types Are Resolved

The grade field's flexibility allows four distinct behaviors based on the input value:

• Omitted or null: The resolver returns an empty string, and the video stream passes through unchanged without color grading.
• Preset name: Valid identifiers like "subtle" resolve to predefined FFmpeg filters applied uniformly to every segment.
• Raw filter: Strings containing = or , (e.g., "eq=contrast=1.1:saturation=0.95") are inserted directly into the -vf chain, bypassing the preset catalog.
• Auto mode: The literal "auto" triggers per-segment analysis, where auto_grade_for_clip generates unique eq=... filters for each clip based on its actual content.

Code Examples

Using a Preset Name

Apply the same color grade to every segment by referencing a named preset in your EDL or command line:

python helpers/render.py project.edl -o final.mp4 --preset warm_cinematic

In the EDL JSON:

{
  "grade": "warm_cinematic",
  "ranges": [...],
  "sources": {...}
}

Using a Raw FFmpeg Filter

Pass a custom filter string directly when you need precise control over FFmpeg parameters:

python helpers/render.py project.edl -o final.mp4 \
    --filter "eq=contrast=1.12:saturation=0.90"

Or in the EDL:

{
  "grade": "eq=contrast=1.12:saturation=0.90"
}

Enabling Auto Mode

Set the grade to "auto" to enable per-segment adaptive grading:

{
  "grade": "auto",
  "ranges": [...],
  "sources": {...}
}

When rendered, auto_grade_for_clip analyzes each clip individually and injects appropriate eq=brightness=...:contrast=... filters.

Programmatic Access

Access the same logic from Python for custom pipelines:

from helpers.grade import get_preset, auto_grade_for_clip
from pathlib import Path

# Retrieve a preset filter

filter_str = get_preset("neutral_punch")  # Returns "eq=contrast=1.06:..."

# Generate adaptive filter for a specific range

filter_str, stats = auto_grade_for_clip(
    Path("src/video.mp4"),
    start=12.3,
    duration=4.5,
    verbose=True
)

Summary

• The grade field in the video-use EDL supports preset names, raw FFmpeg filters, and auto mode through a single resolver function.
• resolve_grade_filter in helpers/render.py (lines 66–84) distinguishes input types using regex patterns and delegates to get_preset or returns the "__AUTO__" sentinel.
• Presets are stored in helpers/grade.py (lines 38–62) and retrieved via get_preset, while auto mode uses auto_grade_for_clip (lines 84–132) to generate per-segment corrections.
• Raw filters bypass preset lookup entirely when they contain = or , characters.
• Auto mode analyzes clip content at runtime to produce adaptive brightness and contrast adjustments.

Frequently Asked Questions

What happens if I specify an unknown preset name?

If the input matches the preset name pattern ([a-zA-Z0-9_\-]+) but is not found in the PRESETS dictionary, resolve_grade_filter catches the KeyError, prints a warning, and treats the string as a raw filter. This prevents pipeline failures while alerting you to the typo.

How does the auto mode determine the filter values?

The auto_grade_for_clip function samples frames from the specified clip segment, calculates aggregate brightness, contrast, and saturation statistics, then constructs an eq=... filter with bounded adjustments. The defaults and caps are documented in the module header of helpers/grade.py (lines 4–16).

Can I combine presets with additional raw filters?

No, the resolver treats inputs as mutually exclusive categories. However, you can achieve equivalent results by defining a custom preset in helpers/grade.py that includes your desired combination of filters, or by preprocessing the EDL to inject composite filter strings directly into the grade field.

Where is the grade filter applied in the FFmpeg pipeline?

The resolved filter string is embedded into the per-segment -vf (video filter) chain during the extract_segment call within helpers/render.py. For auto mode, this occurs inside the extract_all_segments loop (lines 27–52), where each segment receives its individually computed filter before the final compositing stage.

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