Color Grading

Correct and creatively grade video or image media with presets, scopes, color wheels, curves, HSL selections, and custom LUTs.

Use Color Grading to correct and creatively grade real <video> and <img> media in Studio or through an agent with the same validated SDR/Rec.709 shader contract in preview and render.

Choose the Right Tool

Stage	Purpose	HyperFrames tools
Correct	Fix exposure, contrast, tonal balance, and casts	Adjust controls and source analysis
Grade	Shape color and mood	Tonal wheels, RGB curves, hue curves, and HSL color selections
Apply a look	Start from a tested style or an existing external look	Presets and custom 3D .cube LUTs
Finish	Add restrained optical texture	Vignette and grain
Stylize	Transform the pixels beyond normal grading	Media Effects
Dress	Add an authored HUD, flash, light leak, or freeze-frame layer	Media Overlays

All pixel-level stages are stored together on the selected media element. An overlay is different: it is an ordinary editable composition layer whose final paint order follows its authored track and CSS z-index.

Quick Start

Studio

Select a real <img> or <video> element to open Color Grading in the Design panel.

1. Correct the source

   Open Scopes, then adjust exposure, tonal balance, white balance, and saturation before applying a stronger look.

2. Shape the grade

   Use tonal wheels, curves, or an HSL Color Selection only where the source needs more precise control.

3. Choose a look and verify

   Preview a preset or load a 3D .cube LUT, compare with the source, and scrub representative frames before rendering.

Agent / CLI

Inspect the media, apply one validated payload, then verify representative frames:

Terminal

npx hyperframes media-treatment \
  --project . \
  --file compositions/interview.html \
  --selector '#interview' \
  --analyze \
  --json

npx hyperframes media-treatment \
  --project . \
  --file compositions/interview.html \
  --selector '#interview' \
  --grading '{"adjust":{"highlights":-0.08,"shadows":0.06},"wheels":{"midtones":{"hue":32,"amount":0.05}}}' \
  --apply \
  --json

Use --dry-run when target or scope is uncertain. Use --clear to remove the complete treatment.

To reuse a grade in Studio, use Copy grade to, choose Current file media or All project media, then click Apply. Project-wide copy refuses project-relative LUT paths because the same path may resolve differently in another composition; use current-file copy or a project-root path/data URL. The copy changes only the treatment payload, not overlays, captions, or DOM layers.

Project-local media is the reliable path. Remote media requires compatible CORS headers. Color Grading does not process captions, text, SVG, arbitrary DOM, or CSS background images.

Professional Controls

Color Wheels

The three wheels target broad tonal zones:

• Shadows shapes dark regions.
• Midtones shapes most faces, products, and general scene color.
• Highlights shapes bright regions and specular areas.

Use small amounts first. The Level control changes the brightness of the same tonal zone, while hue and amount introduce color.

RGB Curves

• Master remaps overall luminance.
• Red, Green, and Blue remap individual channels.

Curve points are normalized [input, output] pairs. Resolved curves contain input endpoints 0 and 1; HyperFrames infers missing endpoints, and the 2–16-point limit includes those inferred points. An S-curve increases contrast; lifting the lower-left region raises shadows; channel curves can build split-tone or cast-removal adjustments.

Hue Curves

• Hue vs Hue moves a selected hue toward another hue.
• Hue vs Saturation changes saturation around a selected hue.
• Hue vs Luma changes brightness around a selected hue.

Hue curve points are [hueDegrees, delta] pairs and wrap around the color wheel. An authored hue curve requires 3–16 unique hue inputs from 0 up to, but not including, 360.

HSL Color Selections

A color selection qualifies pixels by hue, saturation, and luma, then applies a correction only inside that matte. This is useful for restrained tasks such as reducing an overly saturated shirt, cooling a background color, or protecting skin from a broad creative grade.

HyperFrames supports up to four ordered selections. These are static media-level qualifiers: they do not include object tracking, rotoscoping, facial recognition, or spatial masks.

Scopes

Scope	Use it for
Histogram	Overall distribution from dark to bright
Waveform	Brightness by horizontal image position
RGB Parade	Channel balance and clipped individual channels
Vectorscope	Hue direction and saturation

Studio scopes analyze a captured selected-media frame with the current treatment applied. They refresh as the grade changes, but are inspection tools and do not modify the grade.

Presets

HyperFrames ships tested shader-setting presets, not bundled LUT files:

Intent	Presets
Natural and corrective	Neutral, Warm Daylight, Clean Studio, Skin Soft, Food Pop, Night Lift
Editorial and tonal	Muted Editorial, Vintage Wash, Soft Boost, Bright Pop, Deep Contrast
Monochrome	Mono Clean, Mono Fade

Use these as starting points and tune them for the actual source. Presets that also activate a stylized shader treatment are documented under Media Effects.

Agent Guidance

Agents should use the CLI as the normal authoring surface. The data-color-grading attribute is the persistence contract, not the first thing an agent needs to memorize.

Users do not need to name a technical control. Requests such as “this interview feels too dark and cold” or “polish the footage without making it look filtered” route through the media-use skill, which inspects the source, discovers the relevant contract, applies a deterministic payload, and verifies the result.

Start with the concise capability overview, then query only the contract needed for the current intent:

Terminal

npx hyperframes media-treatment --capabilities --json
npx hyperframes media-treatment --capability grading --json
npx hyperframes media-treatment --capability curves --json

Focused queries such as wheels, hue-curves, secondary, scopes, or lut return exact controls, bounds, and examples. Start from source analysis or a tested preset, then add small, explainable adjustments. Avoid inventing many unrelated curve and secondary values: they are difficult to review and easy to overcook.

Low-Level HTML Contract

The CLI and Studio persist the resolved grade in data-color-grading:

index.html

<video
  id="interview"
  src="assets/interview.mp4"
  data-start="0"
  data-duration="6"
  muted
  playsinline
  data-color-grading='{
    "preset":"clean-studio",
    "intensity":0.85,
    "adjust":{
      "exposure":0.04,
      "highlights":-0.08,
      "shadows":0.06,
      "temperature":0.03
    },
    "wheels":{
      "shadows":{"hue":218,"amount":0.04,"level":-0.01},
      "midtones":{"hue":32,"amount":0.05,"level":0.01},
      "highlights":{"hue":42,"amount":0.03,"level":0}
    },
    "curves":{
      "master":[[0,0],[0.28,0.25],[0.72,0.76],[1,1]]
    },
    "hueCurves":{
      "hueVsSaturation":[[0,0],[28,-0.05],[52,0]]
    },
    "secondaries":[{
      "enabled":true,
      "key":{
        "hue":{"center":28,"range":18,"softness":12},
        "saturation":{"min":0.15,"max":0.9,"softness":0.08},
        "luma":{"min":0.12,"max":0.95,"softness":0.08}
      },
      "correction":{"saturation":-0.04,"temperature":0.03}
    }],
    "details":{"vignette":0.05,"grain":0.03},
    "colorSpace":"rec709"
  }'
></video>

The contract rejects unknown keys and clamps numeric values to Core-owned bounds. Query the current contract instead of copying bounds into agent instructions:

Terminal

npx hyperframes media-treatment --capability secondary --json
npx hyperframes media-treatment --all --json

Use --all only for exhaustive tooling or contract inspection.

Custom LUTs

HyperFrames supports project-local 3D .cube LUTs:

data-color-grading

{
  "lut": {
    "src": "assets/luts/product-look.cube",
    "intensity": 0.7
  }
}

• 3D .cube LUTs up to LUT_3D_SIZE 64 are supported.
• 1D and mixed 1D+3D .cube files are not supported.
• Common DOMAIN_MIN, DOMAIN_MAX, and DaVinci/IRIDAS-style LUT_3D_INPUT_RANGE headers are supported.
• HyperFrames does not bundle third-party LUT packs.
• A LUT is only correct when its expected input color space matches the source.
• Rec.709 creative LUTs are the safest current workflow.
• Camera LOG conversion LUTs can be loaded, but HyperFrames does not identify camera profiles or apply ACES/OCIO input transforms automatically.

Never paste a .cube body into an agent prompt. LUT files commonly contain tens of thousands of numeric rows. Keep the file local and use metadata, validation, and rendered comparisons to evaluate it.

Support Matrix

Source or workflow	Status	What to expect
1080p SDR video	Supported	Recommended default path
4K SDR video or image	Supported	Higher preview/render cost; output resolution still follows the composition
iPhone SDR video	Supported	Treated as normal browser-decoded SDR media
iPhone HDR, HLG, or Dolby Vision-style upload	Partial	Studio can show an SDR shader preview, but native HDR delivery bypasses the SDR treatment for native HDR source pixels
HDR delivery render	Separate workflow	The native HDR compositor preserves HDR source pixels and does not apply this SDR grading/effects pipeline to native HDR layers
LOG camera footage	Partial	Requires a known matching transform/LUT; no automatic camera profile management
Full-scene grade including DOM/text	Not supported	Current grading targets individual media elements
Face or region tracking	Not supported	Use a separate isolated media layer or external tracking/masking workflow
Remote media	Partial	Requires compatible CORS headers; project-local assets are reliable
ACES/OCIO finishing	Not supported	Outside the current browser shader pipeline

Render and Performance

The runtime creates a sibling WebGL canvas, uploads the current image/video frame as a texture, applies the same grading contract used by Studio, and hides the native source after a shader frame is ready. During final rendering, HyperFrames injects exact video frames and waits for the grading runtime to redraw before capture.

That render-parity statement applies to SDR output. In the native HDR render path, HyperFrames keeps HDR source pixels out of the SDR DOM capture and composites them separately at higher bit depth. The current SDR grading canvas is therefore not applied to native HDR layers. Convert or tone-map the source to SDR first when these grading controls must appear in the result, or use HDR Rendering to preserve the untreated HDR source.

For 4K output, follow 4K Rendering. A 1080p source does not gain new detail merely because the composition is rendered at 4K.

When animating a graded media layer’s opacity, animate a wrapper rather than the <video> itself. The visible pixels are drawn by the sibling grading canvas, so wrapper opacity keeps the media and canvas together.

Project-local media is the safest path. Remote media must provide compatible CORS headers and should use crossorigin="anonymous" when pixel access is required.

Next Steps

Media Effects

Apply and animate shader-based optical, retro, print, and art treatments.

Media Overlays

Add editable HUD, flash, light-leak, and freeze-frame composition layers.

HDR Rendering

Render HDR10 outputs and understand the boundary with SDR grading.

4K Rendering

Render at 4K and understand source-versus-output resolution.