> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-magi-device-auth-rfc8628.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/media-effects)                         |
| Dress        | Add an authored HUD, flash, light leak, or freeze-frame layer | [Media Overlays](/guides/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

<Tabs>
  <Tab title="Studio">
    Select a real `<img>` or `<video>` element to open Color Grading in the
    Design panel.

    <Steps>
      <Step title="Correct the source">
        Open **Scopes**, then adjust exposure, tonal balance, white balance, and
        saturation before applying a stronger look.
      </Step>

      <Step title="Shape the grade">
        Use tonal wheels, curves, or an HSL Color Selection only where the
        source needs more precise control.
      </Step>

      <Step title="Choose a look and verify">
        Preview a preset or load a 3D `.cube` LUT, compare with the source, and
        scrub representative frames before rendering.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Agent / CLI">
    Inspect the media, apply one validated payload, then verify representative
    frames:

    ```bash Terminal theme={null}
    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.
  </Tab>
</Tabs>

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](/guides/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:

```bash Terminal theme={null}
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`:

```html index.html theme={null}
<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:

```bash Terminal theme={null}
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:

```json data-color-grading theme={null}
{
  "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](/guides/hdr) to preserve the untreated HDR source.

For 4K output, follow [4K Rendering](/guides/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

<CardGroup cols={2}>
  <Card title="Media Effects" icon="wand-magic-sparkles" href="/guides/media-effects">
    Apply and animate shader-based optical, retro, print, and art treatments.
  </Card>

  <Card title="Media Overlays" icon="layer-group" href="/guides/media-overlays">
    Add editable HUD, flash, light-leak, and freeze-frame composition layers.
  </Card>

  <Card title="HDR Rendering" icon="sun" href="/guides/hdr">
    Render HDR10 outputs and understand the boundary with SDR grading.
  </Card>

  <Card title="4K Rendering" icon="up-right-and-down-left-from-center" href="/guides/4k-rendering">
    Render at 4K and understand source-versus-output resolution.
  </Card>
</CardGroup>