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

> Learn how the EDL grade field supports preset names, raw filters, and auto mode in video-use. Resolve color grading commands with ease. Explore the render.py helper function.

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

---

**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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), which resolves the field value, and [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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.

```python
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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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:

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

```

In the EDL JSON:

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

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

```

Or in the EDL:

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

```

### Enabling Auto Mode

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

```json
{
  "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:

```python
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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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.