Skip to content

Commit 819ed63

Browse files
vanceingallsclaude
andcommitted
docs(prompting): add colour grading and film effects chapter
Ten A/B demos, each with the plain-language prompt that produced it and the payload it compiled to. Slots into Level 4 — Substance. The chapter teaches technique and leaves the key/bound reference to the Colour Grading guide rather than duplicating it. Also adds two sections to docs/guides/color-grading.mdx: - Animating a Grade — the nine CSS custom properties, plus driving the payload from the timeline for effects that have none. Documents that --hf-color-grading-intensity does not scale a grade at render time, and that payload-rewrite animation is effect-dependent: verified working for halftone and twoInkPrint, verified not working for crtCurvature, scanlines, chromaBleed and chromaticAberration. - Limiting a Grade to Part of the Frame — grading qualifies by value, never by screen position, so a region has to become its own layer. Includes the three layer recipes and a worked face-redaction example. Previously the support matrix said "not supported" with nowhere to go. Renders are served from the CDN; docs/images/ is gitignored. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 3a6b7f0 commit 819ed63

3 files changed

Lines changed: 325 additions & 2 deletions

File tree

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@
111111
"prompting/overlays-and-lower-thirds",
112112
"prompting/captions-catalog",
113113
"prompting/generated-artwork",
114+
"prompting/color-grading",
114115
"prompting/vfx-and-liquid-glass",
115116
"prompting/runtimes-and-3d"
116117
]

‎docs/guides/color-grading.mdx‎

Lines changed: 165 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,9 @@ skin from a broad creative grade.
123123

124124
HyperFrames supports up to four ordered selections. These are static
125125
media-level qualifiers: they do not include object tracking, rotoscoping,
126-
facial recognition, or spatial masks.
126+
facial recognition, or spatial masks. To confine a grade to a region of the
127+
frame rather than a range of colors, see
128+
[Limiting a Grade to Part of the Frame](#limiting-a-grade-to-part-of-the-frame).
127129

128130
### Scopes
129131

@@ -237,6 +239,167 @@ npx hyperframes media-treatment --all --json
237239

238240
Use `--all` only for exhaustive tooling or contract inspection.
239241

242+
## Animating a Grade
243+
244+
Nine grading properties are exposed as CSS custom properties and can be tweened
245+
directly:
246+
247+
```text
248+
--hf-color-grading-ascii --hf-color-grading-bloom --hf-color-grading-blur
249+
--hf-color-grading-dither --hf-color-grading-exposure --hf-color-grading-intensity
250+
--hf-color-grading-kuwahara --hf-color-grading-lut --hf-color-grading-pixelate
251+
```
252+
253+
```js
254+
tl.to("#plate", { "--hf-color-grading-pixelate": 0.5, duration: 3, ease: "power2.inOut" }, 0.3);
255+
```
256+
257+
Start the value at identity in the payload and in an inline `style`, so frame 0
258+
is the ungraded reference and every intermediate value is rendered rather than
259+
just the endpoints.
260+
261+
Two things this list does **not** give you:
262+
263+
- **`--hf-color-grading-intensity` does not scale a grade at render time.**
264+
Setting it to `0.5` renders the same as `0`, and animating `0 → 1` produces no
265+
change. Do not reach for it as a generic "ramp the whole look" dial.
266+
- **Every other property — `halftone`, `twoInkPrint`, `tapeDamage`, hue curves,
267+
secondaries — has no custom property**, so it cannot be tweened this way.
268+
269+
For some of those, you can drive the payload itself from the timeline.
270+
Rewriting `data-color-grading` re-applies the grade:
271+
272+
```js
273+
const plate = document.getElementById("plate");
274+
const v = { halftone: 0, bloom: 0 };
275+
276+
tl.to(v, {
277+
halftone: 0.72,
278+
bloom: 0.7,
279+
duration: 3.4,
280+
ease: "power2.inOut",
281+
onUpdate: () => {
282+
plate.setAttribute("data-color-grading", JSON.stringify({
283+
intensity: 1,
284+
effects: {
285+
halftone: v.halftone, halftoneSize: 0.38,
286+
bloom: v.bloom, bloomRadius: 18,
287+
},
288+
}));
289+
},
290+
}, 0.3);
291+
```
292+
293+
This stays deterministic: the value is derived from timeline position, never
294+
from wall-clock time, so seeking to a frame always produces the same result.
295+
It costs a payload parse per tick, so prefer a custom property when one exists.
296+
297+
<Warning>
298+
**This does not work for every effect.** It is verified working for `halftone`
299+
and `twoInkPrint`. It is verified *not* working for `crtCurvature`,
300+
`scanlines`, `chromaBleed`, and `chromaticAberration` — the identical payload
301+
applied statically renders correctly, but the same values driven through
302+
`setAttribute` produce no visible change, and seeding them non-zero at init
303+
does not help. Measure the effect you intend to animate before committing to
304+
it, and fall back to a static treatment if the ramp does not move.
305+
</Warning>
306+
307+
## Limiting a Grade to Part of the Frame
308+
309+
Grading qualifies pixels **by value, never by position**. Selections key on hue,
310+
saturation, and luma; the one spatially-varying control, `vignette`, is locked
311+
to the frame centre and cannot be moved or reshaped into a power window. There
312+
are no masks, shapes, or tracked regions in the contract.
313+
314+
A grade also applies to a whole media element. So to treat part of the frame,
315+
split that part into its own layer and grade the layer:
316+
317+
| You want | Build |
318+
| --- | --- |
319+
| Subject graded, background clean | Matted cutout on top, graded; original clip underneath, clean |
320+
| Background graded, subject clean | Original clip underneath, graded; matted cutout on top, clean |
321+
| One region of the subject graded | Two copies of the cutout — clean underneath, graded copy on top clipped to the region |
322+
323+
Two rules that are easy to get wrong:
324+
325+
- **Use the original clip as the background plate, not a subject-removed
326+
plate.** A subject-removed plate is a hole where the subject was, and a
327+
feathered cutout composited over it produces a dark rim.
328+
- **If your cutout ships premultiplied alpha**, the browser composites it as
329+
straight and edge pixels get multiplied twice, giving a black outline. Rebuild
330+
it from the original plus its matte:
331+
`ffmpeg -i clip.mp4 -i matte.mp4 -filter_complex "[1:v]format=gray[m];[0:v][m]alphamerge" -c:v libvpx-vp9 out.webm`
332+
333+
### Worked Example: Redacting a Face
334+
335+
Only the face is pixelated. The rest of the subject and the entire room are
336+
untouched. Three layers, and the region comes from `clip-path` on the third:
337+
338+
```html index.html
339+
<div class="band">
340+
<!-- 1. the room, clean -->
341+
<video src="media/room.mp4" muted
342+
data-start="0" data-duration="4" data-track-index="2"></video>
343+
344+
<!-- 2. the subject, clean -->
345+
<video src="media/subject.webm" muted class="fg"
346+
data-start="0" data-duration="4" data-track-index="3"></video>
347+
348+
<!-- 3. the same subject, graded, clipped to the head -->
349+
<video src="media/subject.webm" muted class="fx"
350+
data-start="0" data-duration="4" data-track-index="4"
351+
style="clip-path: ellipse(9.8% 15.5% at 50.7% 14.5%)"
352+
data-color-grading='{"intensity":1,"effects":{"pixelate":0.5}}'></video>
353+
</div>
354+
```
355+
356+
```css
357+
.band .fg { z-index: 2; }
358+
.band .fx { z-index: 3; }
359+
```
360+
361+
Everything outside the clip falls through to the clean copy beneath. Because the
362+
graded layer *is* the cutout, the ellipse can overshoot the head without
363+
touching the room — there is nothing outside the silhouette to paint — so size
364+
it generously rather than tightly around the features.
365+
366+
Pixelate preserves alpha, so the block grid clips to the silhouette instead of
367+
filling a rectangle.
368+
369+
<Warning>
370+
A fixed `clip-path` is only valid for footage where the subject barely moves.
371+
Measure before relying on it. Anything with real subject movement needs a
372+
tracked matte produced outside HyperFrames — there is no tracking in the
373+
grading pipeline.
374+
</Warning>
375+
376+
The prompt that produces the composition above:
377+
378+
```text
379+
Take room.mp4 and its matted cutout subject.webm and build a 4-second
380+
1920x1080 composition that redacts only the subject's face.
381+
382+
Three stacked layers inside one band, all playing the same 4 seconds:
383+
1. room.mp4, no grading at all
384+
2. subject.webm, no grading at all
385+
3. subject.webm again, on top, carrying the grade
386+
387+
Layer 3 is the only graded element: pixelate at 0.5, held constant for the
388+
whole shot — no ramp and no fade-up. A redaction that animates on reads as an
389+
effect; one that is simply on reads as policy. Mid strength should leave a
390+
recognisable human shape without a readable face.
391+
392+
Limit layer 3 to the head with a CSS clip-path ellipse. Do not try to do this
393+
with the grading payload — it has no spatial masking. Size the ellipse
394+
generously so it takes in the hairline, ears, and jaw rather than sitting tight
395+
on the features; it can overshoot the head safely, because outside the
396+
silhouette the cutout is transparent and there is nothing to paint.
397+
398+
Use the original room clip as the background plate rather than a
399+
subject-removed plate, and if the cutout has premultiplied alpha, rebuild it
400+
with ffmpeg alphamerge first so the edges do not come out with a black rim.
401+
```
402+
240403
## Custom LUTs
241404

242405
HyperFrames supports project-local 3D `.cube` LUTs:
@@ -275,7 +438,7 @@ validation, and rendered comparisons to evaluate it.
275438
| 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 |
276439
| LOG camera footage | Partial | Requires a known matching transform/LUT; no automatic camera profile management |
277440
| Full-scene grade including DOM/text | Not supported | Current grading targets individual media elements |
278-
| Face or region tracking | Not supported | Use a separate isolated media layer or external tracking/masking workflow |
441+
| Face or region tracking | Not supported | No masks or tracking in the contract. Isolate the region as its own layer — see [Limiting a Grade to Part of the Frame](#limiting-a-grade-to-part-of-the-frame) |
279442
| Remote media | Partial | Requires compatible CORS headers; project-local assets are reliable |
280443
| ACES/OCIO finishing | Not supported | Outside the current browser shader pipeline |
281444

0 commit comments

Comments
 (0)