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

> Learn to configure custom ffmpeg color grade presets beyond built-in options in video-use grade.py. Extend presets and apply them with ease via CLI or EDL.

- Repository: [Browser Use/video-use](https://github.com/browser-use/video-use)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Extend the `PRESETS` dictionary in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) and [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py).

### The PRESETS Dictionary

In [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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:

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

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

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

```

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

```bash
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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/render.py) module calls `resolve_grade_filter` which recognizes custom preset names added to `PRESETS` in [`grade.py`](https://github.com/browser-use/video-use/blob/main/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`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py)) and the rendering pipeline ([`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py)). No application restart or additional registration steps are required.