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

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 and integrates into the render pipeline via 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. 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 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 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 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 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:

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

Analyze statistics without writing output:

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

Python API Usage

Integrate the auto-grade system into custom scripts:

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:

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

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