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

video‑use performs color grading through a lightweight pipeline in 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 (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.

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:

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.

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

# 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	PRESETS dict (lines 38–63)	Static filter definitions
helpers/grade.py	get_preset() (lines 66–73)	Preset retrieval with validation
helpers/grade.py	_sample_frame_stats() (lines 78–115)	FFmpeg signalstats analysis
helpers/grade.py	auto_grade_for_clip() (lines 117–141)	Bounded adjustment calculation
helpers/grade.py	apply_grade()	FFmpeg execution with filter
helpers/render.py	resolve_grade_filter() (lines 66–84)	EDL grade field interpretation
helpers/render.py	extract_all_segments() (lines 39–60)	Per-segment grade resolution

Complete Workflow Examples

Applying a Preset to a Single Clip

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

{
  "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"
  }
}

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

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 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, 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 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.

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