@@ -3,17 +3,11 @@ title: Color Grading
33description : " 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
2721All 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
117112Hue 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
145142HyperFrames 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
154151also activate a stylized shader treatment are documented under
155152[ Media Effects] ( /guides/media-effects ) .
156153
157- ## Agent Workflow
154+ ## Agent Guidance
158155
159156Agents 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,
166163discovers the relevant contract, applies a deterministic payload, and verifies
167164the 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
220183The 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
267230instructions:
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
274237Use ` --all ` only for exhaustive tooling or contract inspection.
@@ -277,7 +240,7 @@ Use `--all` only for exhaustive tooling or contract inspection.
277240
278241HyperFrames 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,
323286HyperFrames injects exact video frames and waits for the grading runtime to
324287redraw 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+
326296For 4K output, follow [ 4K Rendering] ( /guides/4k-rendering ) . A 1080p source does
327297not 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
334304CORS headers and should use ` crossorigin="anonymous" ` when pixel access is
335305required.
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