mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-04 07:19:52 +00:00
324 lines
12 KiB
Plaintext
324 lines
12 KiB
Plaintext
---
|
||
title: Color Grading
|
||
description: "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
|
||
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
|
||
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
|
||
<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
|
||
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
|
||
{
|
||
"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>
|