Skip to content

Commit a93c183

Browse files
vanceingallsclaude
andcommitted
feat(core): grade groups grade a whole lane from one hf-color-group
An inert <hf-color-group> holds a lane's data-color-grading; <video>, <img> and <canvas> join with data-color-group. A member's own grading overrides its group's. The runtime discovers members, regrades them when the group's grading or a member's data-color-group changes, and ungrades them when the group element or its grading goes, drawing only members on screen. Render keeps group-graded video at full size like directly graded video, and lint accepts (and still validates) grading on hf-color-group. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 67c7ec2 commit a93c183

14 files changed

Lines changed: 511 additions & 34 deletions

File tree

‎docs/reference/color-grading.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,43 @@ npx hyperframes media-treatment \
3333
Add `--dry-run --json` to inspect the change without writing it. Use `--clear`
3434
to remove the treatment.
3535

36+
## Grade a whole lane
37+
38+
A camera cut into hundreds of clips takes one grade, set once. Put the grade
39+
on an `<hf-color-group>` and point each clip at it with `data-color-group`:
40+
41+
```html
42+
<hf-color-group
43+
id="tamer-cam"
44+
data-label="Tamer"
45+
data-color-grading='{"preset":"skin-soft","intensity":0.7}'
46+
></hf-color-group>
47+
48+
<video id="tamer-01" data-color-group="tamer-cam" src="./assets/tamer.mp4" …></video>
49+
<video id="tamer-02" data-color-group="tamer-cam" src="./assets/tamer.mp4" …></video>
50+
<video
51+
id="tamer-03"
52+
data-color-group="tamer-cam"
53+
data-color-grading='{"adjust":{"exposure":0.3}}'
54+
src="./assets/tamer.mp4"
55+
…
56+
></video>
57+
```
58+
59+
- `data-color-grading` on the group takes the same JSON as on a clip. Editing it
60+
regrades every member, in preview and in render.
61+
- `data-color-group` goes on the `<video>`, `<img>` or `<canvas>`. Membership is
62+
held by the member, so a deleted clip simply leaves the group.
63+
- **A clip's own `data-color-grading` wins.** It replaces the group's grade for
64+
that clip, so `tamer-03` above gets only its exposure lift, not skin-soft.
65+
- `data-color-group=""` is no group, and a group id with no `<hf-color-group>`
66+
element leaves the clip ungraded. Removing the element, or its
67+
`data-color-grading`, ungrades its members.
68+
- Groups do not nest. Group ids share the element-id namespace.
69+
- The element is inert: the runtime injects
70+
`hf-color-group{display:contents!important}`. Close it with
71+
`</hf-color-group>`, since HTML ignores `/>` on a custom element.
72+
3673
## Animate a supported property
3774

3875
Nine grading properties expose CSS custom properties that a paused timeline

‎docs/reference/lint-rules.mdx‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -594,9 +594,10 @@ Source: `packages/lint/src/rules/media.ts`.
594594

595595
### `color_grading_non_media`
596596

597-
**Error.** `data-color-grading` is set on an element other than `<video>`, `<img>` or `<canvas>`, such as a
598-
wrapper or an element with a CSS background. The shader runtime only grades real `<video>`, `<img>` and
599-
`<canvas>` elements, so the attribute has no effect.
597+
**Error.** `data-color-grading` is set on an element other than `<video>`, `<img>`, `<canvas>` or
598+
`<hf-color-group>`, such as a wrapper or an element with a CSS background. The shader runtime only grades
599+
real `<video>`, `<img>` and `<canvas>` elements, plus the members of a
600+
[grade group](/reference/color-grading#grade-a-whole-lane), so the attribute has no effect.
600601

601602
**Fix:** Move the attribute to the `<video>`, `<img>` or `<canvas>` element itself.
602603

‎packages/cli/src/capture/colorGrading.chromium.test.ts‎

Lines changed: 108 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -76,32 +76,41 @@ async function renderPixel(page: Page, grading: HfColorGrading): Promise<number[
7676
}, grading);
7777
}
7878

79+
function gradingProbeScript(): string {
80+
const bundle = buildSync({
81+
entryPoints: [resolve("../core/src/runtime/colorGrading.ts")],
82+
bundle: true,
83+
platform: "browser",
84+
format: "iife",
85+
globalName: "__gradingProbe",
86+
write: false,
87+
});
88+
const script = bundle.outputFiles[0]?.text;
89+
if (!script) throw new Error("missing grading runtime");
90+
return script;
91+
}
92+
93+
function launchSwiftShader(): Promise<Browser> {
94+
return puppeteer.launch({
95+
headless: true,
96+
executablePath,
97+
args: [
98+
"--no-sandbox",
99+
"--enable-unsafe-swiftshader",
100+
"--use-gl=angle",
101+
"--use-angle=swiftshader",
102+
],
103+
});
104+
}
105+
79106
describe.skipIf(!runsChromium)("color grading curves in Chromium", () => {
80107
let browser: Browser;
81108
let page: Page;
82109
const browserErrors: string[] = [];
83110

84111
beforeAll(async () => {
85-
const bundle = buildSync({
86-
entryPoints: [resolve("../core/src/runtime/colorGrading.ts")],
87-
bundle: true,
88-
platform: "browser",
89-
format: "iife",
90-
globalName: "__gradingProbe",
91-
write: false,
92-
});
93-
const script = bundle.outputFiles[0]?.text;
94-
if (!script) throw new Error("missing grading runtime");
95-
browser = await puppeteer.launch({
96-
headless: true,
97-
executablePath,
98-
args: [
99-
"--no-sandbox",
100-
"--enable-unsafe-swiftshader",
101-
"--use-gl=angle",
102-
"--use-angle=swiftshader",
103-
],
104-
});
112+
const script = gradingProbeScript();
113+
browser = await launchSwiftShader();
105114
page = await browser.newPage();
106115
page.on("pageerror", (error) => browserErrors.push(String(error)));
107116
await page.setViewport({ width: 64, height: 32 });
@@ -187,3 +196,82 @@ describe.skipIf(!runsChromium)("color grading curves in Chromium", () => {
187196
expect(browserErrors).toEqual([]);
188197
});
189198
});
199+
200+
describe.skipIf(!runsChromium)("a grade group in Chromium", () => {
201+
const MEMBERS = 50;
202+
let browser: Browser;
203+
let page: Page;
204+
const browserErrors: string[] = [];
205+
206+
// The centre pixel of every member's grading canvas, in member order.
207+
const memberPixels = (): Promise<number[][]> =>
208+
page.evaluate((count) => {
209+
const output = document.createElement("canvas");
210+
const context = output.getContext("2d", { willReadFrequently: true });
211+
if (!context) throw new Error("missing output context");
212+
return Array.from({ length: count }, (_, i) => {
213+
const canvas = document.getElementById(`__hf_color_grading_m${i}`);
214+
if (!(canvas instanceof HTMLCanvasElement)) throw new Error(`member ${i} is not graded`);
215+
output.width = canvas.width;
216+
output.height = canvas.height;
217+
context.drawImage(canvas, 0, 0);
218+
const centre = context.getImageData(canvas.width >> 1, canvas.height >> 1, 1, 1).data;
219+
return [...centre];
220+
});
221+
}, MEMBERS);
222+
223+
beforeAll(async () => {
224+
const script = gradingProbeScript();
225+
browser = await launchSwiftShader();
226+
page = await browser.newPage();
227+
page.on("pageerror", (error) => browserErrors.push(String(error)));
228+
await page.setViewport({ width: 400, height: 200 });
229+
const members = Array.from(
230+
{ length: MEMBERS },
231+
(_, i) => `<img id="m${i}" data-color-group="lane" style="width:40px;height:40px">`,
232+
).join("");
233+
await page.setContent(
234+
`<body style="margin:0"><hf-color-group id="lane" data-color-grading='{"adjust":{"exposure":1}}'></hf-color-group>` +
235+
`<div style="display:flex;flex-wrap:wrap;width:400px">${members}</div></body>`,
236+
);
237+
await page.evaluate("self.__name = self.__name || ((fn) => fn);");
238+
await page.addScriptTag({ content: script });
239+
await page.evaluate(async () => {
240+
const source = document.createElement("canvas");
241+
source.width = source.height = 8;
242+
const context = source.getContext("2d");
243+
if (!context) throw new Error("missing source context");
244+
context.fillStyle = "rgb(96,96,96)";
245+
context.fillRect(0, 0, 8, 8);
246+
const src = source.toDataURL();
247+
await Promise.all(
248+
Array.from(document.querySelectorAll("img"), (img) => {
249+
img.src = src;
250+
return img.decode();
251+
}),
252+
);
253+
window.__gradingTestRuntime = window.__gradingProbe.createColorGradingRuntime();
254+
});
255+
}, 120_000);
256+
257+
afterAll(async () => {
258+
await browser?.close();
259+
});
260+
261+
it("repaints every member when the group's grading is edited once", async () => {
262+
const before = await memberPixels();
263+
expect(before).toHaveLength(MEMBERS);
264+
for (const [red] of before) expect(red).toBeGreaterThan(150);
265+
266+
await page.evaluate(async () => {
267+
document
268+
.getElementById("lane")
269+
?.setAttribute("data-color-grading", '{"adjust":{"exposure":-1}}');
270+
await new Promise((resolve) => setTimeout(resolve, 0));
271+
});
272+
273+
const after = await memberPixels();
274+
for (const [red] of after) expect(red).toBeLessThan(70);
275+
expect(browserErrors).toEqual([]);
276+
});
277+
});
Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
import { beforeEach, describe, expect, it } from "vitest";
2+
import { HF_COLOR_GRADING_ATTR } from "./colorGrading";
3+
import {
4+
colorGroupOf,
5+
effectiveColorGrading,
6+
ensureColorGroupInertStyle,
7+
HF_COLOR_GROUP_ATTR,
8+
HF_COLOR_GROUP_TAG,
9+
resolveColorGroupElement,
10+
} from "./colorGroups";
11+
12+
const LANE_GRADE = '{"adjust":{"exposure":0.4}}';
13+
const OWN_GRADE = '{"adjust":{"exposure":-0.2}}';
14+
15+
beforeEach(() => {
16+
document.head.innerHTML = "";
17+
document.body.innerHTML = "";
18+
});
19+
20+
describe("colorGroupOf", () => {
21+
it("reads membership off the member", () => {
22+
document.body.innerHTML = `
23+
<hf-color-group id="tamer" data-color-grading='${LANE_GRADE}'></hf-color-group>
24+
<video id="a" data-color-group="tamer"></video>
25+
<img id="b" data-color-group="tamer">
26+
<canvas id="c" data-color-group="tamer"></canvas>
27+
`;
28+
for (const id of ["a", "b", "c"]) {
29+
expect(colorGroupOf(document.getElementById(id)!)).toBe("tamer");
30+
}
31+
});
32+
33+
it('treats data-color-group="" as no group', () => {
34+
document.body.innerHTML = `<video id="a" data-color-group=""></video>`;
35+
expect(colorGroupOf(document.getElementById("a")!)).toBeNull();
36+
});
37+
38+
it("ignores the attribute on an element the grader cannot draw", () => {
39+
document.body.innerHTML = `<div id="a" data-color-group="tamer"></div>`;
40+
expect(colorGroupOf(document.getElementById("a")!)).toBeNull();
41+
});
42+
});
43+
44+
describe("resolveColorGroupElement", () => {
45+
it("finds the group element by id", () => {
46+
document.body.innerHTML = `<hf-color-group id="tamer"></hf-color-group>`;
47+
expect(resolveColorGroupElement(document, "tamer")?.tagName.toLowerCase()).toBe(
48+
HF_COLOR_GROUP_TAG,
49+
);
50+
});
51+
52+
it("does not read an unrelated element that shares the id as a group", () => {
53+
document.body.innerHTML = `<div id="tamer" data-color-grading='${LANE_GRADE}'></div>`;
54+
expect(resolveColorGroupElement(document, "tamer")).toBeNull();
55+
});
56+
});
57+
58+
describe("effectiveColorGrading", () => {
59+
it("grades a member through its group element", () => {
60+
document.body.innerHTML = `
61+
<hf-color-group id="tamer" data-color-grading='${LANE_GRADE}'></hf-color-group>
62+
<video id="a" data-color-group="tamer"></video>
63+
`;
64+
expect(effectiveColorGrading(document.getElementById("a")!, document)).toBe(LANE_GRADE);
65+
});
66+
67+
it("is null when the group has no element", () => {
68+
document.body.innerHTML = `<video id="a" data-color-group="tamer"></video>`;
69+
expect(effectiveColorGrading(document.getElementById("a")!, document)).toBeNull();
70+
});
71+
72+
it("is null when the group element carries no grading", () => {
73+
document.body.innerHTML = `
74+
<hf-color-group id="tamer"></hf-color-group>
75+
<video id="a" data-color-group="tamer"></video>
76+
`;
77+
expect(effectiveColorGrading(document.getElementById("a")!, document)).toBeNull();
78+
});
79+
80+
it("lets a member's own grading win over its group's", () => {
81+
document.body.innerHTML = `
82+
<hf-color-group id="tamer" data-color-grading='${LANE_GRADE}'></hf-color-group>
83+
<video id="a" data-color-group="tamer" data-color-grading='${OWN_GRADE}'></video>
84+
`;
85+
expect(effectiveColorGrading(document.getElementById("a")!, document)).toBe(OWN_GRADE);
86+
});
87+
88+
it("is the element's own grading when it has no group", () => {
89+
document.body.innerHTML = `<img id="a" ${HF_COLOR_GRADING_ATTR}='${OWN_GRADE}'>`;
90+
expect(effectiveColorGrading(document.getElementById("a")!, document)).toBe(OWN_GRADE);
91+
});
92+
93+
it('is null for data-color-group="" with no grading of its own', () => {
94+
document.body.innerHTML = `
95+
<hf-color-group id="" data-color-grading='${LANE_GRADE}'></hf-color-group>
96+
<video id="a" ${HF_COLOR_GROUP_ATTR}=""></video>
97+
`;
98+
expect(effectiveColorGrading(document.getElementById("a")!, document)).toBeNull();
99+
});
100+
});
101+
102+
describe("ensureColorGroupInertStyle", () => {
103+
it("takes the group element out of layout, against an author rule", () => {
104+
document.head.insertAdjacentHTML("beforeend", `<style>#tamer{display:flex}</style>`);
105+
document.body.innerHTML = `<hf-color-group id="tamer"></hf-color-group>`;
106+
ensureColorGroupInertStyle(document);
107+
expect(getComputedStyle(document.getElementById("tamer")!).display).toBe("contents");
108+
});
109+
110+
it("injects its style once", () => {
111+
ensureColorGroupInertStyle(document);
112+
ensureColorGroupInertStyle(document);
113+
expect(document.head.querySelectorAll("style")).toHaveLength(1);
114+
});
115+
});

‎packages/core/src/colorGroups.ts‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
/**
2+
* Grade groups: one colour grade for a whole lane. An inert `<hf-color-group>`
3+
* holds the grade in `data-color-grading`; each `<video>`, `<img>` or `<canvas>`
4+
* joins with `data-color-group` naming the group's id. Membership is held by the
5+
* member, as with audio groups, so a camera cut into hundreds of clips is graded
6+
* by editing one attribute.
7+
*/
8+
9+
import { COLOR_GROUP_ATTR, COLOR_GROUP_TAG } from "@hyperframes/parsers/color-grading-contract";
10+
import { HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_SOURCE_TAGS } from "./colorGrading";
11+
12+
export const HF_COLOR_GROUP_TAG = COLOR_GROUP_TAG;
13+
export const HF_COLOR_GROUP_ATTR = COLOR_GROUP_ATTR;
14+
15+
type GroupLookupRoot = Pick<Document, "getElementById"> | null | undefined;
16+
17+
/**
18+
* The group a gradable element belongs to, or null. `data-color-group=""` is no
19+
* group. Tolerant of partial `Element` doubles, as `audioGroupOf` is.
20+
*/
21+
export function colorGroupOf(el: Element): string | null {
22+
if (typeof el.tagName !== "string" || typeof el.getAttribute !== "function") return null;
23+
if (!(HF_COLOR_GRADING_SOURCE_TAGS as readonly string[]).includes(el.tagName.toLowerCase())) {
24+
return null;
25+
}
26+
return el.getAttribute(HF_COLOR_GROUP_ATTR) || null;
27+
}
28+
29+
/**
30+
* The `<hf-color-group>` for an id, or null. Tag-checked so an unrelated
31+
* element sharing the id is never read as a lane's grade.
32+
*/
33+
export function resolveColorGroupElement(root: GroupLookupRoot, groupId: string): Element | null {
34+
const el = root?.getElementById(groupId) ?? null;
35+
return el?.tagName.toLowerCase() === HF_COLOR_GROUP_TAG ? el : null;
36+
}
37+
38+
/**
39+
* The grade that applies to `el`: its own `data-color-grading` when present,
40+
* else its group element's, else null. A group id with no element is ungrouped.
41+
*/
42+
export function effectiveColorGrading(el: Element, root: GroupLookupRoot): string | null {
43+
const own = el.getAttribute(HF_COLOR_GRADING_ATTR);
44+
if (own !== null) return own;
45+
const groupId = colorGroupOf(el);
46+
if (!groupId) return null;
47+
return resolveColorGroupElement(root, groupId)?.getAttribute(HF_COLOR_GRADING_ATTR) ?? null;
48+
}
49+
50+
/**
51+
* Make `<hf-color-group>` inert, once per document: an unknown custom element
52+
* still makes a box, and a grade must not shift authored layout. `contents`, so
53+
* anything nested inside one still renders; `!important` because an author rule
54+
* can outrank a bare type selector.
55+
*/
56+
export function ensureColorGroupInertStyle(doc: Document): void {
57+
const styleId = "__hf-color-group-inert";
58+
if (!doc?.head || doc.getElementById(styleId)) return;
59+
const style = doc.createElement("style");
60+
style.id = styleId;
61+
style.textContent = `${HF_COLOR_GROUP_TAG}{display:contents!important}`;
62+
doc.head.appendChild(style);
63+
}

‎packages/core/src/index.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,14 @@ export {
262262
type NormalizedHfColorGradingWheels,
263263
type ResolvedHfColorGrading,
264264
} from "./colorGrading";
265+
export {
266+
colorGroupOf,
267+
effectiveColorGrading,
268+
ensureColorGroupInertStyle,
269+
HF_COLOR_GROUP_ATTR,
270+
HF_COLOR_GROUP_TAG,
271+
resolveColorGroupElement,
272+
} from "./colorGroups";
265273
export { parseCubeLut, CubeLutParseError, type ParseCubeLutOptions } from "./colorLuts";
266274
export {
267275
firstFrameColourArgs,

0 commit comments

Comments
 (0)