How the Video-Use Color Preset System Works: warm_cinematic, neutral_punch, and More

The Video-Use color preset system maps preset names like warm_cinematic and neutral_punch to pre-built ffmpeg filter chains, allowing one-step color grading via the CLI or Python API.

The repository browser-use/video-use ships with a lightweight color preset system that eliminates manual filter writing. Instead of constructing complex ffmpeg expressions, you apply predefined looks like warm_cinematic or neutral_punch to an entire clip in a single step.

What Is the Color Preset System?

The color preset system is a dictionary-based mapping in helpers/grade.py that connects human-readable preset names to complete ffmpeg filter strings. This abstraction layer lets you switch between subtle corrections and bold creative grades without touching raw ffmpeg syntax.

The system is designed as a plug-in-style component. You can use the built-in presets, supply custom filter strings, or fall back to automatic per-clip analysis—all through the same interface.

Available Presets and Their Filter Chains

The PRESETS dictionary defined at lines 38-63 in helpers/grade.py contains four distinct looks:

• subtle — Bare minimum cleanup with no color shift
• neutral_punch — Light contrast boost with an S-curve, keeping colors neutral
• warm_cinematic — Creative retro-cinematic look with higher contrast, warm shadows, and cool highlights
• none — No grading at all (empty filter string)

Each preset maps to a specific ffmpeg filter chain. The subtle preset uses eq=contrast=1.03:saturation=0.98. The neutral_punch preset combines an equalizer with an S-curve: eq=contrast=1.06:brightness=0.0:saturation=1.0,curves=master='0/0 0.25/0.23 0.75/0.77 1/1'.

The warm_cinematic preset is the most complex, layering contrast adjustments, color balance shifts, and curves: eq=contrast=1.12:brightness=-0.02:saturation=0.88,colorbalance=rs=0.02:gs=0.0:bs=-0.03:rm=0.04:gm=0.01:bm=-0.02:rh=0.08:gh=0.02:bh=-0.05,curves=master='0/0 0.25/0.22 0.75/0.78 1/1'.

How the Preset System Works Under the Hood

The core retrieval logic lives in the get_preset(name) function at lines 66-73 of helpers/grade.py. This function looks up the requested preset in the PRESETS dictionary and returns its filter string. If the name is unknown, it raises a clear error to prevent silent failures.

When the CLI or the render.py workflow needs a filter, it imports this logic via from grade import get_preset, auto_grade_for_clip. The chosen filter string is then injected directly into the ffmpeg command used for rendering. This architecture keeps the color preset system decoupled from the rendering pipeline, making it easy to extend with new presets or custom filter logic.

Using Presets via the Command Line

The grading CLI in helpers/grade.py exposes three ways to work with presets, parsed in the argparse block around lines 29-34:

1. Explicit preset — --preset warm_cinematic applies that filter chain verbatim
2. Print a preset — --print-preset neutral_punch outputs only the filter string without processing video
3. List all presets — --list-presets enumerates available names and their definitions

If neither --preset nor --filter is supplied, Video-Use falls back to auto-grade mode, which analyzes the clip and generates a subtle correction filter via auto_grade_for_clip.

# Apply the warm cinematic preset to a file

python helpers/grade.py input.mp4 -o output.mp4 --preset warm_cinematic

# Show the raw ffmpeg filter string for the neutral punch preset

python helpers/grade.py --print-preset neutral_punch

# List every preset the tool ships with

python helpers/grade.py --list-presets

Using Presets in Python Code

You can import the same logic into custom scripts for programmatic control:

from helpers.grade import get_preset, auto_grade_for_clip

# Use a preset in a custom ffmpeg command

preset_filter = get_preset('warm_cinematic')

# Returns: "eq=contrast=1.12:brightness=-0.02:saturation=0.88,colorbalance=..."

# Or compute an automatic filter for a specific clip segment

filter_str, stats = auto_grade_for_clip('clip.mp4', start=10, duration=5)

This allows you to build hybrid workflows—using get_preset for known creative looks while reserving auto_grade_for_clip for footage that needs data-driven correction.

Summary

• The color preset system in browser-use/video-use maps names like warm_cinematic and neutral_punch to complete ffmpeg filter chains in helpers/grade.py.
• Four built-in presets cover common needs: subtle corrections, neutral punch, warm cinematic looks, and no grading.
• The get_preset function retrieves filter strings by name and validates input at lines 66-73.
• CLI integration supports --preset, --print-preset, and --list-presets options for flexible workflow integration.
• Python API allows direct import of get_preset and auto_grade_for_clip for custom rendering pipelines.

Frequently Asked Questions

What video formats work with the color preset system?

The color preset system works with any format that ffmpeg supports, since the presets are simply ffmpeg filter strings. The tool processes the input through ffmpeg after applying the selected filter chain, so standard formats like MP4, MOV, and MKV are all compatible.

Can I create custom presets beyond warm_cinematic and neutral_punch?

Yes. You can modify the PRESETS dictionary in helpers/grade.py (lines 38-63) to add new entries, or you can bypass the preset system entirely by using the --filter CLI option to pass raw ffmpeg filter strings. The get_preset function will look up any key you add to the dictionary.

How does the auto-grade mode differ from using presets?

The auto-grade mode analyzes the specific clip using auto_grade_for_clip and generates a data-driven correction filter based on the footage's actual histogram. In contrast, presets like neutral_punch apply the same predetermined filter chain regardless of the input content. Use auto-grade for inconsistent footage and presets for stylistic consistency across multiple clips.

Where does the preset string get injected in the rendering pipeline?

In helpers/render.py, the code imports get_preset and injects the returned filter string directly into the ffmpeg command used for final rendering. This occurs after the import statement from grade import get_preset, auto_grade_for_clip and before the video encoding step.

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