# How video‑use Handles Color Grading with Presets and Auto Mode

> Discover how video-use handles color grading with presets and auto mode. Apply consistent looks or intelligent clip analysis for gentle corrections with this efficient pipeline.

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

---

**`video‑use` performs color grading through a lightweight pipeline in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py), supporting static presets for consistent looks and an intelligent auto mode that analyzes each clip to apply gentle, bounded corrections.**

The `browser-use/video-use` repository implements a flexible color grading system designed for automated video workflows. Whether you need a uniform aesthetic across your project or subtle per-clip corrections, the grading pipeline integrates seamlessly into the rendering process via ffmpeg filter strings.

## Understanding the Two Color Grading Modes

The grading system operates in two mutually exclusive modes, selectable through the EDL's `"grade"` field or programmatically via the Python API.

### Preset Mode: Named Looks for Consistent Aesthetics

Preset mode applies **static ffmpeg filter strings** that define specific visual styles. These are hardcoded in the `PRESETS` dictionary and retrieved via `get_preset()`.

Available presets in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) (lines 38–63):

| Preset | Description |
|--------|-------------|
| `subtle` | Minimal, nearly invisible correction |
| `neutral_punch` | Moderate contrast boost with neutral balance |
| `warm_cinematic` | Golden-hour warmth with lifted shadows |
| `none` | No grading applied (empty filter string) |

The `get_preset(name)` function (lines 66–73) validates the preset name and returns the corresponding filter string, raising `KeyError` for unknown names.

```python
from helpers.grade import get_preset

# Retrieve the warm cinematic look

filter_str = get_preset("warm_cinematic")

# Returns: "eq=contrast=1.1:saturation=0.9:gamma=1.05,curves=r='0/0 0.5/0.55 1/1':g='0/0 0.5/0.52 1/1':b='0/0 0.5/0.48 1/1'"

```

### Auto Mode: Per‑Clip Intelligent Analysis

**Auto mode** (the default behavior) analyzes each clip individually to calculate minimal corrective adjustments. The goal is a "clean, not graded" appearance—corrections stay within **±8% on any axis** to avoid heavy-handed processing.

The auto-grading workflow in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py):

1. **`_sample_frame_stats()`** (lines 78–115): Samples multiple frames using ffmpeg's `signalstats` filter to extract:
   - `YAVG` (mean brightness)
   - `YMIN`/`YMAX` (contrast range)
   - `SATAVG` (saturation levels)

2. **`auto_grade_for_clip()`** (lines 117–141): Computes adjustments based on deviations from ideal ranges, then builds an `eq=` filter string with `contrast_adj`, `gamma_adj`, and `sat_adj` values.

3. If no significant correction is needed, returns an empty string to skip grading entirely.

```python
from helpers.grade import auto_grade_for_clip, apply_grade
from pathlib import Path

src = Path("source.mp4")
out = Path("graded_auto.mp4")

# Analyze and grade the entire clip

filter_str, stats = auto_grade_for_clip(src, start=0, duration=None, verbose=True)
print(f"Applied adjustments: {stats}")

apply_grade(src, out, filter_str)

```

## How Grading Integrates with the Rendering Pipeline

The EDL-driven rendering workflow in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) orchestrates which grading mode applies to each segment.

### Resolving the Grade Field

`resolve_grade_filter()` (lines 66–84) interprets the EDL's `"grade"` value:

- **`"auto"`** → Returns the sentinel `"__AUTO__"` to trigger per-clip analysis
- **Preset name** → Calls `get_preset()` for the static filter
- **Raw ffmpeg filter string** → Passes through unchanged

### Per‑Segment Processing

During `extract_all_segments()` (lines 39–60), each segment's filter is determined:

```python

# Pseudo-code from render.py lines 49-58

if seg_grade == "__AUTO__":
    seg_filter, _ = auto_grade_for_clip(
        video_path, seg.start, seg.duration, verbose
    )
else:
    seg_filter = seg_grade  # Preset or raw filter, or "" for "none"

```

Both paths converge on `extract_segment()`, which inserts the filter into the ffmpeg `-vf` chain alongside scaling, tone-mapping, and audio fades.

## Key Implementation Files and Functions

| File | Key Component | Purpose |
|------|---------------|---------|
| [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) | `PRESETS` dict (lines 38–63) | Static filter definitions |
| [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) | `get_preset()` (lines 66–73) | Preset retrieval with validation |
| [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) | `_sample_frame_stats()` (lines 78–115) | FFmpeg signalstats analysis |
| [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) | `auto_grade_for_clip()` (lines 117–141) | Bounded adjustment calculation |
| [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) | `apply_grade()` | FFmpeg execution with filter |
| [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) | `resolve_grade_filter()` (lines 66–84) | EDL grade field interpretation |
| [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) | `extract_all_segments()` (lines 39–60) | Per-segment grade resolution |

## Complete Workflow Examples

### Applying a Preset to a Single Clip

```python
from helpers.grade import get_preset, apply_grade
from pathlib import Path

input_file = Path("interview_footage.mp4")
output_file = Path("interview_warm.mp4")

# Get and apply the warm cinematic preset

preset_filter = get_preset("warm_cinematic")
apply_grade(input_file, output_file, preset_filter)

```

### Rendering an EDL with Auto‑Grade Per Segment

```json
{
  "grade": "auto",
  "ranges": [
    { "source": "clip_a", "start": 0, "end": 12.5 },
    { "source": "clip_b", "start": 5, "end": 20 }
  ],
  "sources": {
    "clip_a": "footage/clip_a.mp4",
    "clip_b": "footage/clip_b.mp4"
  }
}

```

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

```

Each segment receives independent analysis and gentle correction based on its actual content.

### Programmatic Grade Selection

```python
from helpers.grade import auto_grade_for_clip, get_preset, apply_grade

def grade_clip_intelligently(video_path, prefer_preset=None):
    """
    Use preset if specified, otherwise fall back to auto-grade.
    """
    if prefer_preset:
        try:
            filter_str = get_preset(prefer_preset)
        except KeyError:
            # Unknown preset: fall back to auto

            filter_str, stats = auto_grade_for_clip(video_path)
    else:
        filter_str, stats = auto_grade_for_clip(video_path)
    
    output = video_path.with_suffix(".graded.mp4")
    apply_grade(video_path, output, filter_str)
    return output

```

## Summary

- **`video‑use` color grading** operates through [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) with two complementary modes: static presets and adaptive auto-grading.
- **Preset mode** delivers consistent, named looks via pre-defined ffmpeg filter strings stored in the `PRESETS` dictionary.
- **Auto mode** analyzes clip statistics with `signalstats`, calculating bounded corrections (±8%) for clean, invisible correction.
- **Pipeline integration** occurs in [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), where `resolve_grade_filter()` and `extract_all_segments()` delegate to the appropriate grading logic per segment.
- **Both modes converge** on the same `extract_segment()` call, ensuring unified handling of scaling, tone-mapping, and audio processing regardless of grading source.

## Frequently Asked Questions

### What happens if I specify an unknown preset name?

The `get_preset()` function raises a `KeyError` with the invalid name. In the rendering pipeline, this propagates up and halts processing, so EDL files should only use the four supported preset names: `subtle`, `neutral_punch`, `warm_cinematic`, or `none`.

### Why does auto mode limit adjustments to ±8%?

The ±8% bound is deliberately conservative to maintain a "clean, not graded" aesthetic. According to the [`SKILL.md`](https://github.com/browser-use/video-use/blob/main/SKILL.md) design documentation and the implementation in `auto_grade_for_clip()`, this prevents aggressive corrections that would look obviously processed while still fixing exposure and saturation issues common in automated footage.

### Can I combine preset and auto mode in the same render?

Yes, at the segment level. While a single EDL entry has one `"grade"` field, you can structure your project with multiple EDL entries or manually construct filter strings. For hybrid workflows, extract `auto_grade_for_clip()` results and save them as custom presets, or pass raw ffmpeg filters through the EDL's grade field.

### How does the auto mode sampling work?

`_sample_frame_stats()` uses ffmpeg's `signalstats` filter across **N sampled frames** distributed throughout the clip duration. It normalizes the raw `YAVG`, `YMIN`, `YMAX`, and `SATAVG` values to 0–1 ranges, then `auto_grade_for_clip()` maps these to contrast, gamma, and saturation adjustments targeting neutral midtones with healthy contrast and saturation levels.