Skip to content

Commit c6b4619

Browse files
vanceingallsclaude
andcommitted
feat(hdr): shader transitions, --hdr flag, and SDR rendering fixes
- 15 GLSL→TypeScript shader transitions on rgb48le buffers - Dual-scene compositing with scene detection via window.__hf.transitions - --hdr flag gates ffprobe probing (zero overhead on SDR compositions) - Cross-transfer conversion (PQ↔HLG) via OOTF-corrected composite LUT - Buffer.from() copy in writeFrame() fixes streaming encoder race condition - SDR rendering fixes (three stacked bugs) - Object.assign fix for window.__hf preservation Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
1 parent 8b68cd7 commit c6b4619

8 files changed

Lines changed: 2176 additions & 225 deletions

File tree

‎packages/cli/src/commands/render.ts‎

Lines changed: 10 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,9 @@ export const examples: Example[] = [
77
["Render transparent overlay (ProRes)", "hyperframes render --format mov --output overlay.mov"],
88
["Render transparent WebM overlay", "hyperframes render --format webm --output overlay.webm"],
99
["High quality at 60fps", "hyperframes render --fps 60 --quality high --output hd.mp4"],
10-
["Custom CRF for maximum quality", "hyperframes render --crf 15 --output pristine.mp4"],
11-
["Target bitrate encoding", "hyperframes render --video-bitrate 10M --output hq.mp4"],
1210
["Deterministic render via Docker", "hyperframes render --docker --output deterministic.mp4"],
1311
["Parallel rendering with 6 workers", "hyperframes render --workers 6 --output fast.mp4"],
12+
["HDR output (H.265 10-bit)", "hyperframes render --hdr --output hdr-output.mp4"],
1413
];
1514
import { cpus, freemem, tmpdir } from "node:os";
1615
import { resolve, dirname, join, basename } from "node:path";
@@ -81,19 +80,10 @@ export default defineCommand({
8180
description: "Use Docker for deterministic render",
8281
default: false,
8382
},
84-
crf: {
85-
type: "string",
86-
description:
87-
"CRF (Constant Rate Factor) for the video encoder. " +
88-
"Lower = higher quality / larger file. Range: 0–51 for H.264. " +
89-
"Overrides the quality preset CRF. Cannot be used with --video-bitrate.",
90-
},
91-
"video-bitrate": {
92-
type: "string",
93-
description:
94-
"Target video bitrate (e.g. '10M', '5000k'). " +
95-
"Uses bitrate-based encoding instead of CRF. " +
96-
"Cannot be used with --crf.",
83+
hdr: {
84+
type: "boolean",
85+
description: "Enable HDR: probe sources for PQ/HLG, output H.265 10-bit BT.2020",
86+
default: false,
9787
},
9888
gpu: { type: "boolean", description: "Use GPU encoding", default: false },
9989
quiet: {
@@ -144,36 +134,6 @@ export default defineCommand({
144134
}
145135
const format = formatRaw as "mp4" | "webm" | "mov";
146136

147-
// ── Validate CRF / video-bitrate ────────────────────────────────────
148-
let crf: number | undefined;
149-
let videoBitrate: string | undefined;
150-
if (args.crf != null && args["video-bitrate"] != null) {
151-
errorBox(
152-
"Conflicting options",
153-
"--crf and --video-bitrate cannot be used together. Choose one.",
154-
);
155-
process.exit(1);
156-
}
157-
if (args.crf != null) {
158-
const parsed = parseInt(args.crf, 10);
159-
if (isNaN(parsed) || parsed < 0 || parsed > 51) {
160-
errorBox("Invalid CRF", `Got "${args.crf}". Must be a number between 0 and 51.`);
161-
process.exit(1);
162-
}
163-
crf = parsed;
164-
}
165-
if (args["video-bitrate"] != null) {
166-
const raw = args["video-bitrate"];
167-
if (!/^\d+(\.\d+)?[kKM]$/.test(raw)) {
168-
errorBox(
169-
"Invalid video bitrate",
170-
`Got "${raw}". Must be a number followed by k, K, or M (e.g. "10M", "5000k", "1.5M").`,
171-
);
172-
process.exit(1);
173-
}
174-
videoBitrate = raw;
175-
}
176-
177137
// ── Validate workers ──────────────────────────────────────────────────
178138
let workers: number | undefined;
179139
if (args.workers != null && args.workers !== "auto") {
@@ -231,12 +191,7 @@ export default defineCommand({
231191
c.accent(project.name) +
232192
c.dim(" \u2192 " + outputPath),
233193
);
234-
const encodeLabel = videoBitrate
235-
? `bitrate ${videoBitrate}`
236-
: crf != null
237-
? `crf ${crf}`
238-
: quality;
239-
console.log(c.dim(" " + fps + "fps \u00B7 " + encodeLabel + " \u00B7 " + workerLabel));
194+
console.log(c.dim(" " + fps + "fps \u00B7 " + quality + " \u00B7 " + workerLabel));
240195
console.log("");
241196
}
242197

@@ -316,9 +271,8 @@ export default defineCommand({
316271
format,
317272
workers: workerCount,
318273
gpu: useGpu,
274+
hdr: args.hdr ?? false,
319275
quiet,
320-
crf,
321-
videoBitrate,
322276
});
323277
} else {
324278
await renderLocal(project.dir, outputPath, {
@@ -327,10 +281,9 @@ export default defineCommand({
327281
format,
328282
workers: workerCount,
329283
gpu: useGpu,
284+
hdr: args.hdr ?? false,
330285
quiet,
331286
browserPath,
332-
crf,
333-
videoBitrate,
334287
});
335288
}
336289
},
@@ -342,10 +295,9 @@ interface RenderOptions {
342295
format: "mp4" | "webm" | "mov";
343296
workers: number;
344297
gpu: boolean;
298+
hdr: boolean;
345299
quiet: boolean;
346300
browserPath?: string;
347-
crf?: number;
348-
videoBitrate?: string;
349301
}
350302

351303
const DOCKER_IMAGE_PREFIX = "hyperframes-renderer";
@@ -480,8 +432,6 @@ async function renderDocker(
480432
String(options.workers),
481433
...(options.quiet ? ["--quiet"] : []),
482434
...(options.gpu ? ["--gpu"] : []),
483-
...(options.crf != null ? ["--crf", String(options.crf)] : []),
484-
...(options.videoBitrate ? ["--video-bitrate", options.videoBitrate] : []),
485435
];
486436

487437
if (!options.quiet) {
@@ -543,8 +493,7 @@ async function renderLocal(
543493
format: options.format,
544494
workers: options.workers,
545495
useGpu: options.gpu,
546-
crf: options.crf,
547-
videoBitrate: options.videoBitrate,
496+
hdr: options.hdr,
548497
});
549498

550499
const onProgress = options.quiet

‎packages/core/src/lint/rules/media.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
8282
const timedTagPositions: Array<{ name: string; start: number; id?: string }> = [];
8383
for (const tag of tags) {
8484
if (tag.name === "video" || tag.name === "audio") continue;
85+
// Skip the composition root — it uses data-start as a playback anchor, not as a clip timer
86+
if (readAttr(tag.raw, "data-composition-id")) continue;
8587
if (readAttr(tag.raw, "data-start")) {
8688
timedTagPositions.push({
8789
name: tag.name,

‎packages/engine/src/index.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434
export type {
3535
HfProtocol,
3636
HfMediaElement,
37+
HfTransitionMeta,
3738
CaptureOptions,
3839
CaptureResult,
3940
CaptureBufferResult,
@@ -155,6 +156,7 @@ export {
155156
} from "./utils/ffprobe.js";
156157

157158
export { downloadToTemp, isHttpUrl } from "./utils/urlDownloader.js";
159+
export { runFfmpeg, type RunFfmpegOptions, type RunFfmpegResult } from "./utils/runFfmpeg.js";
158160

159161
export {
160162
decodePng,
@@ -164,10 +166,22 @@ export {
164166
blitRgb48leAffine,
165167
parseTransformMatrix,
166168
getSrgbToHdrLut,
169+
roundedRectAlpha,
167170
} from "./utils/alphaBlit.js";
168171

169172
export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.js";
170173

174+
// ── Shader transitions ────────────────────────────────────────────────────────
175+
export {
176+
type TransitionFn,
177+
TRANSITIONS,
178+
crossfade,
179+
sampleRgb48le,
180+
hdrToLinear,
181+
linearToHdr,
182+
convertTransfer,
183+
} from "./utils/shaderTransitions.js";
184+
171185
export {
172186
initHdrReadback,
173187
uploadAndReadbackHdrFrame,

‎packages/engine/src/types.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,29 @@ export interface HfMediaElement {
3131
hasAudio?: boolean;
3232
}
3333

34+
/**
35+
* Metadata for a shader transition between two scenes.
36+
*
37+
* Compositions using @hyperframes/shader-transitions populate
38+
* `window.__hf.transitions` with one entry per transition so the
39+
* producer can pre-compute scene ranges, capture per-scene buffers,
40+
* and apply the transition in HDR-aware compositing.
41+
*/
42+
export interface HfTransitionMeta {
43+
/** Time the transition starts (seconds) */
44+
time: number;
45+
/** Transition duration (seconds) */
46+
duration: number;
47+
/** Shader identifier (e.g. "fade", "wipe") */
48+
shader: string;
49+
/** GSAP easing string (e.g. "power2.inOut") */
50+
ease: string;
51+
/** Scene id the transition starts from */
52+
fromScene: string;
53+
/** Scene id the transition ends on */
54+
toScene: string;
55+
}
56+
3457
/**
3558
* The seek protocol. The only contract between the engine and a page.
3659
*
@@ -49,6 +72,8 @@ export interface HfProtocol {
4972
seek(time: number): void;
5073
/** Optional: media elements the engine should handle */
5174
media?: HfMediaElement[];
75+
/** Optional: shader transition metadata for HDR-aware compositing */
76+
transitions?: HfTransitionMeta[];
5277
}
5378

5479
// ── Capture Types ──────────────────────────────────────────────────────────────

0 commit comments

Comments
 (0)