Skip to content

Commit 1828627

Browse files
committed
docs: refine media treatment guides
1 parent 1a2c30a commit 1828627

5 files changed

Lines changed: 309 additions & 279 deletions

File tree

‎docs/guides/color-grading.mdx‎

Lines changed: 103 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,11 @@ title: Color Grading
33
description: "Correct and creatively grade video or image media with presets, scopes, color wheels, curves, HSL selections, and custom LUTs."
44
---
55

6-
HyperFrames provides real-time, media-level color grading for project-local
7-
`<video>` and `<img>` elements.
6+
Use Color Grading to correct and creatively grade real `<video>` and `<img>`
7+
media in Studio or through an agent with the same validated SDR/Rec.709 shader
8+
contract in preview and render.
89

9-
Studio and AI agents use the same validated grading contract, and final
10-
rendering runs the same shader pipeline used by the preview.
11-
12-
The current pipeline is designed for SDR/Rec.709-oriented work. It provides
13-
professional primary and selective grading tools, but it is not an ACES, OCIO,
14-
or native HDR finishing pipeline.
15-
16-
## The Mental Model
10+
## Choose the Right Tool
1711

1812
| Stage | Purpose | HyperFrames tools |
1913
| --- | --- | --- |
@@ -25,67 +19,68 @@ or native HDR finishing pipeline.
2519
| Dress | Add an authored HUD, flash, light leak, or freeze-frame layer | [Media Overlays](/guides/media-overlays) |
2620

2721
All pixel-level stages are stored together on the selected media element. An
28-
overlay is different: it is an ordinary editable composition layer above the
29-
media.
30-
31-
## Studio Workflow
32-
33-
Select a real `<img>` or `<video>` element to open Color Grading in the Design
34-
panel.
35-
36-
<Steps>
37-
<Step title="Inspect the source">
38-
Open **Scopes** and choose Histogram, Waveform, RGB Parade, or Vectorscope.
39-
Scopes refresh from the selected media frame and help identify clipped
40-
highlights, crushed shadows, channel imbalance, and saturation before you
41-
make creative changes.
42-
</Step>
43-
<Step title="Make the primary correction">
44-
Use Exposure, Contrast, Highlights, Shadows, White Point, Black Point,
45-
Warmth, Tint, Vibrance, and Saturation. Correct obvious source problems
46-
before applying a stronger look.
47-
</Step>
48-
<Step title="Shape tonal color">
49-
Use the Shadows, Midtones, and Highlights wheels. Each wheel provides hue,
50-
color amount, and level, so color and brightness can be adjusted within the
51-
same tonal zone.
52-
</Step>
53-
<Step title="Refine with curves">
54-
Use the Master curve for overall luminance, Red/Green/Blue curves for
55-
channel shaping, and Hue vs Hue, Hue vs Saturation, or Hue vs Luma for
56-
hue-selective adjustments.
57-
</Step>
58-
<Step title="Isolate a color when needed">
59-
Add a Color Selection, capture the current frame, and use the eyedropper to
60-
initialize its HSL qualifier. Switch to **Selection matte** to inspect the
61-
selected pixels, refine hue/saturation/luma range and softness, then apply
62-
bounded hue, saturation, luma, temperature, or tint correction. Up to four
63-
ordered selections are supported.
64-
</Step>
65-
<Step title="Choose a look and finish">
66-
Preview a built-in preset on the selected media or load a project-local 3D
67-
`.cube` LUT. Use vignette and grain only when they support the visual
68-
direction.
69-
</Step>
70-
<Step title="Compare and render">
71-
Hold the compare control to see the ungraded source. Scrub representative
72-
frames, verify faces and highlights, then render. The final render redraws
73-
the grading shader after exact video-frame injection.
74-
</Step>
75-
</Steps>
76-
77-
To reuse the complete authored grade, use **Copy grade to** and choose
78-
**Current file media** or **All project media**, then click **Apply**. This
79-
copies the validated payload to other real media elements; it does not alter
80-
overlay, caption, or DOM layers.
81-
82-
<Note>
83-
Color Grading is media-only. It processes real `<video>` and `<img>` elements,
84-
not captions, text, SVG, or arbitrary DOM. Use first-class media elements for
85-
visual assets that should remain editable and gradeable.
86-
</Note>
87-
88-
## What Each Professional Tool Does
22+
overlay is different: it is an ordinary editable composition layer whose final
23+
paint order follows its authored track and CSS `z-index`.
24+
25+
## Quick Start
26+
27+
<Tabs>
28+
<Tab title="Studio">
29+
Select a real `<img>` or `<video>` element to open Color Grading in the
30+
Design panel.
31+
32+
<Steps>
33+
<Step title="Correct the source">
34+
Open **Scopes**, then adjust exposure, tonal balance, white balance, and
35+
saturation before applying a stronger look.
36+
</Step>
37+
<Step title="Shape the grade">
38+
Use tonal wheels, curves, or an HSL Color Selection only where the
39+
source needs more precise control.
40+
</Step>
41+
<Step title="Choose a look and verify">
42+
Preview a preset or load a 3D `.cube` LUT, compare with the source, and
43+
scrub representative frames before rendering.
44+
</Step>
45+
</Steps>
46+
</Tab>
47+
<Tab title="Agent / CLI">
48+
Inspect the media, apply one validated payload, then verify representative
49+
frames:
50+
51+
```bash Terminal
52+
npx hyperframes media-treatment \
53+
--project . \
54+
--file compositions/interview.html \
55+
--selector '#interview' \
56+
--analyze \
57+
--json
58+
59+
npx hyperframes media-treatment \
60+
--project . \
61+
--file compositions/interview.html \
62+
--selector '#interview' \
63+
--grading '{"adjust":{"highlights":-0.08,"shadows":0.06},"wheels":{"midtones":{"hue":32,"amount":0.05}}}' \
64+
--apply \
65+
--json
66+
```
67+
68+
Use `--dry-run` when target or scope is uncertain. Use `--clear` to remove
69+
the complete treatment.
70+
</Tab>
71+
</Tabs>
72+
73+
To reuse a grade in Studio, use **Copy grade to**, choose **Current file media**
74+
or **All project media**, then click **Apply**. Project-wide copy refuses
75+
project-relative LUT paths because the same path may resolve differently in
76+
another composition; use current-file copy or a project-root path/data URL. The
77+
copy changes only the treatment payload, not overlays, captions, or DOM layers.
78+
79+
Project-local media is the reliable path. Remote media requires compatible CORS
80+
headers. Color Grading does not process captions, text, SVG, arbitrary DOM, or
81+
CSS background images.
82+
83+
## Professional Controls
8984

9085
### Color Wheels
9186

@@ -103,10 +98,10 @@ same tonal zone, while hue and amount introduce color.
10398
- **Master** remaps overall luminance.
10499
- **Red**, **Green**, and **Blue** remap individual channels.
105100

106-
Curve points are normalized `[input, output]` pairs. Endpoints are implicit,
107-
and each curve supports up to 16 points. An S-curve increases contrast; lifting
108-
the lower-left region raises shadows; channel curves can build split-tone or
109-
cast-removal adjustments.
101+
Curve points are normalized `[input, output]` pairs. Every RGB curve must include
102+
input endpoints `0` and `1` and contain 2–16 points. An S-curve increases
103+
contrast; lifting the lower-left region raises shadows; channel curves can
104+
build split-tone or cast-removal adjustments.
110105

111106
### Hue Curves
112107

@@ -115,7 +110,8 @@ cast-removal adjustments.
115110
- **Hue vs Luma** changes brightness around a selected hue.
116111

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

120116
### HSL Color Selections
121117

@@ -137,10 +133,11 @@ facial recognition, or spatial masks.
137133
| RGB Parade | Channel balance and clipped individual channels |
138134
| Vectorscope | Hue direction and saturation |
139135

140-
Studio scopes analyze a captured selected-media frame. They are inspection
141-
tools and do not change the grade.
136+
Studio scopes analyze a captured selected-media frame with the current
137+
treatment applied. They refresh as the grade changes, but are inspection tools
138+
and do not modify the grade.
142139

143-
## Built-In Looks
140+
## Presets
144141

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

@@ -154,7 +151,7 @@ Use these as starting points and tune them for the actual source. Presets that
154151
also activate a stylized shader treatment are documented under
155152
[Media Effects](/guides/media-effects).
156153

157-
## Agent Workflow
154+
## Agent Guidance
158155

159156
Agents should use the CLI as the normal authoring surface. The
160157
`data-color-grading` attribute is the persistence contract, not the first thing
@@ -166,56 +163,22 @@ look filtered"_ route through the `media-use` skill, which inspects the source,
166163
discovers the relevant contract, applies a deterministic payload, and verifies
167164
the result.
168165

169-
<Steps>
170-
<Step title="Discover the relevant surface">
171-
```bash Terminal
172-
hyperframes media-treatment --capabilities --json
173-
hyperframes media-treatment --capability grading --json
174-
```
175-
176-
The overview stays concise. Focused queries such as `wheels`, `curves`,
177-
`hue-curves`, `secondary`, `scopes`, or `lut` return exact controls, bounds,
178-
and examples.
179-
</Step>
180-
<Step title="Analyze the selected source">
181-
```bash Terminal
182-
hyperframes media-treatment \
183-
--project . \
184-
--file compositions/interview.html \
185-
--selector '#interview' \
186-
--analyze \
187-
--json
188-
```
189-
190-
Analysis measures a local media source and returns metadata, warnings,
191-
diagnosis, and a bounded suggested primary-correction patch. It does not
192-
replace visual judgment or automatically invent a creative grade.
193-
</Step>
194-
<Step title="Apply a validated grade">
195-
```bash Terminal
196-
hyperframes media-treatment \
197-
--project . \
198-
--file compositions/interview.html \
199-
--selector '#interview' \
200-
--grading '{"adjust":{"highlights":-0.08,"shadows":0.06},"wheels":{"midtones":{"hue":32,"amount":0.05}}}' \
201-
--apply \
202-
--json
203-
```
166+
Start with the concise capability overview, then query only the contract needed
167+
for the current intent:
204168

205-
Use `--dry-run` when target or scope is uncertain. Use `--clear` to remove
206-
the complete treatment from the target.
207-
</Step>
208-
<Step title="Verify representative frames">
209-
Inspect more than one frame for video, compare before and after, and render
210-
a short draft when the grade is important to the final result.
211-
</Step>
212-
</Steps>
169+
```bash Terminal
170+
npx hyperframes media-treatment --capabilities --json
171+
npx hyperframes media-treatment --capability grading --json
172+
npx hyperframes media-treatment --capability curves --json
173+
```
213174

214-
Agents should normally start from source analysis or a tested preset, then add
215-
small, explainable adjustments. Directly inventing many unrelated curve and
216-
secondary values is difficult to review and easy to overcook.
175+
Focused queries such as `wheels`, `hue-curves`, `secondary`, `scopes`, or `lut`
176+
return exact controls, bounds, and examples. Start from source analysis or a
177+
tested preset, then add small, explainable adjustments. Avoid inventing many
178+
unrelated curve and secondary values: they are difficult to review and easy to
179+
overcook.
217180

218-
## Advanced Data Shape
181+
## Low-Level HTML Contract
219182

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

@@ -267,8 +230,8 @@ bounds. Query the current contract instead of copying bounds into agent
267230
instructions:
268231

269232
```bash Terminal
270-
hyperframes media-treatment --capability secondary --json
271-
hyperframes media-treatment --all --json
233+
npx hyperframes media-treatment --capability secondary --json
234+
npx hyperframes media-treatment --all --json
272235
```
273236

274237
Use `--all` only for exhaustive tooling or contract inspection.
@@ -277,7 +240,7 @@ Use `--all` only for exhaustive tooling or contract inspection.
277240

278241
HyperFrames supports project-local 3D `.cube` LUTs:
279242

280-
```json
243+
```json data-color-grading
281244
{
282245
"lut": {
283246
"src": "assets/luts/product-look.cube",
@@ -307,8 +270,8 @@ validation, and rendered comparisons to evaluate it.
307270
| 1080p SDR video | Supported | Recommended default path |
308271
| 4K SDR video or image | Supported | Higher preview/render cost; output resolution still follows the composition |
309272
| iPhone SDR video | Supported | Treated as normal browser-decoded SDR media |
310-
| iPhone HDR, HLG, or Dolby Vision-style upload | Partial | HDR metadata is detected and warned; the grading shader remains SDR |
311-
| HDR delivery render | Separate workflow | Use [HDR Rendering](/guides/hdr); grading controls are not HDR-aware |
273+
| 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 |
274+
| 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 |
312275
| LOG camera footage | Partial | Requires a known matching transform/LUT; no automatic camera profile management |
313276
| Full-scene grade including DOM/text | Not supported | Current grading targets individual media elements |
314277
| Face or region tracking | Not supported | Use a separate isolated media layer or external tracking/masking workflow |
@@ -323,6 +286,13 @@ the native source after a shader frame is ready. During final rendering,
323286
HyperFrames injects exact video frames and waits for the grading runtime to
324287
redraw before capture.
325288

289+
That render-parity statement applies to SDR output. In the native HDR render
290+
path, HyperFrames keeps HDR source pixels out of the SDR DOM capture and
291+
composites them separately at higher bit depth. The current SDR grading canvas
292+
is therefore not applied to native HDR layers. Convert or tone-map the source to
293+
SDR first when these grading controls must appear in the result, or use
294+
[HDR Rendering](/guides/hdr) to preserve the untreated HDR source.
295+
326296
For 4K output, follow [4K Rendering](/guides/4k-rendering). A 1080p source does
327297
not gain new detail merely because the composition is rendered at 4K.
328298

@@ -334,7 +304,7 @@ Project-local media is the safest path. Remote media must provide compatible
334304
CORS headers and should use `crossorigin="anonymous"` when pixel access is
335305
required.
336306

337-
## Related Guides
307+
## Next Steps
338308

339309
<CardGroup cols={2}>
340310
<Card title="Media Effects" icon="wand-magic-sparkles" href="/guides/media-effects">

0 commit comments

Comments
 (0)