# What Is the Auto-Grade System and How Does It Apply Per-Clip ±8% Corrections?

> Discover `browser-use/video-use`s auto-grade system. Learn how this data-driven pipeline applies per-clip ±8% corrections to contrast, gamma, and saturation for clean footage.

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

---

**The auto-grade system is a data-driven color correction pipeline in `browser-use/video-use` that samples video frames, analyzes luma and saturation statistics, and applies conservative corrections bounded to ±8% (and specific sub-ranges) on contrast, gamma, and saturation axes to clean up footage without applying stylistic grades.**

The **auto-grade system** lives in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) and integrates into the render pipeline via [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py). When an EDL segment specifies `"grade": "auto"`, the system calculates unique per-clip corrections that are mathematically clamped to prevent perceptible over-processing.

## How the Auto-Grade Algorithm Works

The core logic resides in `auto_grade_for_clip()` inside [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py). This function samples approximately 10 frames across the clip duration, extracts statistical data using ffmpeg’s `signalstats` filter, and computes three bounded adjustment factors.

### Frame Sampling and Statistics Extraction

The pipeline calls `_sample_frame_stats()` to gather data from representative frames distributed across the clip range. For each sampled frame, the system extracts:

- **Y-luma mean** (`y_mean`) – the average brightness level
- **Y-luma range** – converted to a pseudo-standard-deviation (`y_std`)
- **Saturation mean** (`sat_mean`) – the average chroma intensity

These values are normalized to a 0–1 scale based on the video’s native bit-depth. The implementation details span [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) lines 84–112.

### Decision Rules for Color Corrections

Based on the sampled statistics, the system applies targeted correction strategies:

**Contrast adjustment** targets a range of approximately 0.72. If the sampled range falls below 0.65, the system boosts contrast up to 1.08; otherwise, it applies a subtle baseline of 1.03 (see [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) lines 166–174).

**Gamma (brightness) correction** targets a luma mean of approximately 0.48. Dark clips (`y_mean` < 0.42) receive a gamma lift up to 1.10, while over-exposed clips (`y_mean` > 0.60) are pulled back to 0.97 (lines 225–234).

**Saturation adjustment** targets a mean of approximately 0.25. Flat clips (`sat_mean` < 0.18) receive a boost to 1.04, while overly saturated clips (`sat_mean` > 0.38) are toned down to 0.96 (lines 235–244).

### Hard Caps and the ±8% Limitation

Every adjustment is clamped to strict boundaries defined in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) lines 46–49:

- **Contrast**: 0.94 – 1.08 (±8%)
- **Gamma**: 0.94 – 1.10 (up to +10%, down to -6%)
- **Saturation**: 0.94 – 1.06 (±6%)

These **hard caps** guarantee that the correction functions strictly as a technical cleanup rather than a creative color grade. Additionally, if all calculated adjustments fall below a 0.5% threshold, the system returns an empty filter string, causing the segment to be copied without re-encoding to preserve generation loss (lines 52–64).

## Integration in the Render Pipeline

The [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py) module resolves EDL grade fields during the segment extraction phase. When a segment’s grade value is `"auto"`, the code substitutes a `__AUTO__` sentinel that triggers per-segment analysis.

During `extract_all_segments`, the pipeline calls `auto_grade_for_clip()` for each time range, obtaining a clip-specific ffmpeg filter string (e.g., `eq=contrast=1.045:gamma=1.023:saturation=0.998`). This filter is injected into the ffmpeg `-vf` chain for that specific segment only, ensuring that adjacent clips with different lighting conditions receive independent corrections.

## Practical Implementation Examples

### Command-Line Auto-Grade

Process a single clip through the auto-grade pipeline:

```bash
python helpers/grade.py raw_clip.mp4 -o graded_clip.mp4

```

Analyze statistics without writing output:

```bash
python helpers/grade.py --analyze raw_clip.mp4

```

### Python API Usage

Integrate the auto-grade system into custom scripts:

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

src = Path("raw_clip.mp4")
out = Path("graded_clip.mp4")

# Analyze first 10 seconds only

filter_str, stats = auto_grade_for_clip(
    src, start=0.0, duration=10.0, verbose=True
)

# Apply filter or copy if filter_str is empty

apply_grade(src, out, filter_str)

```

### Render Pipeline Conditional Logic

The render module applies auto-grade conditionally per segment:

```python

# Inside helpers/render.py

if is_auto:  # EDL grade == "auto"

    seg_filter, _ = auto_grade_for_clip(
        src_path, start=start, duration=duration, verbose=False
    )
else:
    seg_filter = resolved  # preset or raw filter

extract_segment(
    src_path, start, duration,
    seg_filter, out_path,
    preview=preview, draft=draft
)

```

## Summary

- The **auto-grade system** resides in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) and applies data-driven color corrections via `auto_grade_for_clip()`.
- It samples approximately 10 frames per clip using ffmpeg’s `signalstats` filter to extract normalized luma and saturation statistics.
- Decision rules target specific ranges (contrast ~0.72, gamma ~0.48, saturation ~0.25) with hard caps preventing corrections beyond ±8% on most axes.
- When integrated via [`helpers/render.py`](https://github.com/browser-use/video-use/blob/main/helpers/render.py), each EDL segment receives individualized filters, ensuring consistent exposure across cuts without uniform global adjustments.
- Adjustments below 0.5% trigger pass-through copying to avoid unnecessary re-encoding.

## Frequently Asked Questions

### What is the auto-grade system in video-use?

The auto-grade system is an automated color correction feature that analyzes video clips using frame sampling and applies bounded adjustments to contrast, gamma, and saturation. It lives in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) and is designed to correct technical issues like under-exposure or flat color without applying stylistic looks.

### How does the ±8% correction limit work?

The system clamps all adjustments to specific ranges defined in [`helpers/grade.py`](https://github.com/browser-use/video-use/blob/main/helpers/grade.py) lines 46–49: contrast is limited to 0.94–1.08 (±8%), gamma to 0.94–1.10, and saturation to 0.94–1.06. These caps ensure corrections remain subtle and prevent the algorithm from over-processing footage into an artificial aesthetic.

### When does the auto-grade system skip processing a clip?

If the calculated adjustments for all three axes (contrast, gamma, saturation) fall below a 0.5% deviation from neutral (1.0), `auto_grade_for_clip()` returns an empty filter string. The render pipeline detects this and copies the source segment without re-encoding, preserving quality and reducing processing time.

### Can I apply auto-grade to specific time ranges rather than full clips?

Yes. The `auto_grade_for_clip()` function accepts `start` and `duration` parameters, allowing analysis of specific sub-clips. This is the primary mechanism used by the render pipeline to apply unique corrections to individual EDL segments within the same source file.