How to Configure Custom ffmpeg Color Grade Presets in video-use's grade.py

Extend the PRESETS dictionary in helpers/grade.py with a new key-value pair where the value is a valid ffmpeg filter string, then reference the preset name via CLI --preset, EDL grade field, or raw --filter arguments.

The browser-use/video-use repository provides a flexible color grading pipeline centered around helpers/grade.py. Configuring custom ffmpeg color grade presets beyond the built-in options requires modifying the central PRESETS dictionary that maps short identifiers to complete ffmpeg filter chains.

Understanding the Color Grading Architecture

The video-use pipeline resolves color grades through two primary entry points in helpers/grade.py and helpers/render.py.

The PRESETS Dictionary

In helpers/grade.py (lines 38–63), the PRESETS dictionary stores all named color grade configurations. Each key represents a preset identifier, while the corresponding value is a complete ffmpeg -vf filter string. The helper function get_preset(name) retrieves these strings at runtime, making new entries immediately available across the entire application.

The resolve_grade_filter Function

When the render pipeline in helpers/render.py processes a video segment, it calls resolve_grade_filter to determine which filter chain to apply. This function implements a priority system:

1. Returns an empty string if the grade field is missing
2. Returns the sentinel value __AUTO__ for the literal string "auto"
3. Checks if the value matches the preset identifier regex, then calls get_preset to retrieve the stored chain
4. Treats all other values as raw ffmpeg filter strings

Because the dictionary is read at import time, modifications to PRESETS require no additional registration steps.

Adding a Custom ffmpeg Color Grade Preset

Follow these steps to extend the available color grading options:

1. Open helpers/grade.py in your text editor.

2. Locate the PRESETS definition between lines 38 and 63.

3. Insert a new key-value pair using a valid ffmpeg filter expression. For example:

"my_cool_preset": (
    "eq=contrast=1.15:brightness=0.05:saturation=1.2,"
    "curves=master='0/0 0.3/0.25 0.7/0.75 1/1'"
)

4. Add a descriptive comment above your entry documenting the intended look.

5. Save the file—the preset is immediately available to both the CLI tool and the rendering pipeline.

Using Custom Presets in the Pipeline

Once defined, custom presets integrate seamlessly into three workflow entry points.

Command Line Interface

Invoke your custom preset via the --preset flag:

python helpers/grade.py source.mp4 -o graded.mp4 --preset my_cool_preset

The apply_grade function retrieves the filter string using get_preset and executes ffmpeg with -vf <filter>.

EDL Configuration

Reference presets in Edit Decision List JSON files using the grade field:

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

When render.py processes this EDL, resolve_grade_filter detects the preset identifier and injects the corresponding filter into each segment extraction.

Raw Filter Strings

Bypass the preset lookup entirely by passing a literal ffmpeg expression:

python helpers/grade.py source.mp4 -o graded.mp4 --filter "eq=contrast=1.2:saturation=1.05"

This method skips get_preset and passes the exact string directly to ffmpeg's -vf argument.

Summary

• Modify helpers/grade.py to add entries to the PRESETS dictionary with valid ffmpeg filter syntax
• Changes take effect immediately because the dictionary is evaluated at import time
• Use --preset for CLI grading, the grade field for EDL-based rendering, or --filter for one-off raw expressions
• resolve_grade_filter in helpers/render.py handles the logic for distinguishing between preset names and raw filter strings

Frequently Asked Questions

Where is the PRESETS dictionary defined in video-use?

The PRESETS dictionary is defined in helpers/grade.py between lines 38 and 63. This centralized mapping stores all named color grade configurations as key-value pairs where keys are preset identifiers and values are complete ffmpeg filter chains.

Can I use custom presets when rendering via the EDL pipeline?

Yes. The render.py module calls resolve_grade_filter which recognizes custom preset names added to PRESETS in grade.py. Simply specify your custom preset name in the EDL's grade field, and the renderer will automatically resolve it via the get_preset function.

What is the difference between the --preset and --filter options?

The --preset option accepts a key name that exists in the PRESETS dictionary, while --filter accepts a raw ffmpeg filter string that bypasses the preset lookup entirely. Use --preset for reusable, named configurations; use --filter for ad-hoc adjustments or testing new filter combinations before formalizing them as presets.

Do I need to restart the application after adding a preset to grade.py?

No. Because Python evaluates the PRESETS dictionary at import time when the module loads, saving the file makes the new preset immediately available to both the command-line tool (helpers/grade.py) and the rendering pipeline (helpers/render.py). No application restart or additional registration steps are required.

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