Skip to content

refactor(producer): centralize frame filenames and consolidate timing #1420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
miguel-heygen wants to merge 3 commits into from
Closed

refactor(producer): centralize frame filenames and consolidate timing #1420

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9991661
refactor(producer): centralize frame filename construction
miguel-heygen Jun 13, 2026
9aabe77
perf(producer): hoist allElementIds out of compositing loop
miguel-heygen Jun 13, 2026
8205bb6
refactor(producer): consolidate HDR timing instrumentation
miguel-heygen Jun 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/producer/src/services/distributed/assemble.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ import { dirname, join } from "node:path";
import { applyFaststart, muxVideoWithAudio, runFfmpeg } from "@hyperframes/engine";
import { fpsToFfmpegArg } from "@hyperframes/core";
import { defaultLogger, type ProducerLogger } from "../../logger.js";
import { formatExportFrameName } from "../../utils/paths.js";
import { padOrTrimAudioToVideoFrameCount } from "../render/audioPadTrim.js";
import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
import type { DistributedFormat } from "./shared.js";
Expand Down Expand Up @@ -397,7 +398,7 @@ function mergePngFrameDirs(
throw new Error(`[assemble] png-sequence chunk has no frames: ${chunkDir}`);
}
for (const frame of frames) {
const dst = join(outputPath, `frame_${String(globalIdx + 1).padStart(6, "0")}.png`);
const dst = join(outputPath, formatExportFrameName(globalIdx, "png"));
cpSync(join(chunkDir, frame), dst);
globalIdx += 1;
}
Expand Down
219 changes: 105 additions & 114 deletions packages/producer/src/services/hdrCompositor.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ import {
import type { ProducerLogger } from "../logger.js";
import { type HdrImageTransferCache } from "./hdrImageTransferCache.js";
import { writeFileExclusiveSync } from "./render/shared.js";
import { type HdrPerfCollector, addHdrTiming } from "./render/hdrPerf.js";
import { type HdrPerfCollector, timeHdrPhase, timeHdrPhaseAsync } from "./render/hdrPerf.js";

// ─── Diagnostic helpers ────────────────────────────────────────────────────

Expand Down Expand Up @@ -169,25 +169,19 @@ export function blitHdrVideoLayer(

try {
if (hdrPerf) hdrPerf.hdrVideoLayerBlits += 1;
let timingStart = Date.now();
const bytesRead = readSync(
frameSource.fd,
frameSource.scratch,
0,
frameSource.frameSize,
frameOffset,
const bytesRead = timeHdrPhase(hdrPerf, "hdrVideoReadDecodeMs", () =>
readSync(frameSource.fd, frameSource.scratch, 0, frameSource.frameSize, frameOffset),
);
if (bytesRead !== frameSource.frameSize) return;
const hdrRgb = frameSource.scratch;
const srcW = frameSource.width;
const srcH = frameSource.height;
addHdrTiming(hdrPerf, "hdrVideoReadDecodeMs", timingStart);

// Convert between HDR transfer functions if source doesn't match output
if (sourceTransfer && targetTransfer && sourceTransfer !== targetTransfer) {
timingStart = Date.now();
convertTransfer(hdrRgb, sourceTransfer, targetTransfer);
addHdrTiming(hdrPerf, "hdrVideoTransferMs", timingStart);
timeHdrPhase(hdrPerf, "hdrVideoTransferMs", () =>
convertTransfer(hdrRgb, sourceTransfer, targetTransfer),
);
}

const viewportMatrix = parseTransformMatrix(el.transform);
Expand Down Expand Up @@ -241,54 +235,54 @@ export function blitHdrVideoLayer(
Math.abs(viewportMatrix[3]! - 1) < 0.001
);

timingStart = Date.now();
if (viewportMatrix && !isTranslationOnly) {
if (clipped && log) {
log.debug(
`HDR clip rect on affine-transformed element ${el.id} — clip not applied (affine scissor not yet supported)`,
timeHdrPhase(hdrPerf, "hdrVideoBlitMs", () => {
if (viewportMatrix && !isTranslationOnly) {
if (clipped && log) {
log.debug(
`HDR clip rect on affine-transformed element ${el.id} — clip not applied (affine scissor not yet supported)`,
);
}
blitRgb48leAffine(
canvas,
hdrRgb,
viewportMatrix,
srcW,
srcH,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
} else if (clipped) {
// Crop the source buffer to the clipped region before blitting
const croppedBuf = cropRgb48le(hdrRgb, srcW, srcH, blitSrcX, blitSrcY, blitW, blitH);
blitRgb48leRegion(
canvas,
croppedBuf,
blitX,
blitY,
blitW,
blitH,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
} else {
blitRgb48leRegion(
canvas,
hdrRgb,
el.x,
el.y,
srcW,
srcH,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
}
blitRgb48leAffine(
canvas,
hdrRgb,
viewportMatrix,
srcW,
srcH,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
} else if (clipped) {
// Crop the source buffer to the clipped region before blitting
const croppedBuf = cropRgb48le(hdrRgb, srcW, srcH, blitSrcX, blitSrcY, blitW, blitH);
blitRgb48leRegion(
canvas,
croppedBuf,
blitX,
blitY,
blitW,
blitH,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
} else {
blitRgb48leRegion(
canvas,
hdrRgb,
el.x,
el.y,
srcW,
srcH,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
}
addHdrTiming(hdrPerf, "hdrVideoBlitMs", timingStart);
});
} catch (err) {
if (log) {
log.debug(`HDR blit failed for ${el.id}`, {
Expand Down Expand Up @@ -343,47 +337,46 @@ export function blitHdrImageLayer(
// The cache returns `buf.data` unchanged when no conversion is needed,
// and otherwise returns a per-(imageId, targetTransfer) buffer that was
// converted exactly once and reused across every subsequent frame.
let timingStart = Date.now();
const hdrRgb =
const hdrRgb = timeHdrPhase(hdrPerf, "hdrImageTransferMs", () =>
sourceTransfer && targetTransfer
? hdrImageTransferCache.getConverted(el.id, sourceTransfer, targetTransfer, buf.data)
: buf.data;
addHdrTiming(hdrPerf, "hdrImageTransferMs", timingStart);
: buf.data,
);

const viewportMatrix = parseTransformMatrix(el.transform);

const br = el.borderRadius;
const hasBorderRadius = br[0] > 0 || br[1] > 0 || br[2] > 0 || br[3] > 0;
const borderRadiusParam = hasBorderRadius ? br : undefined;

timingStart = Date.now();
if (viewportMatrix) {
blitRgb48leAffine(
canvas,
hdrRgb,
viewportMatrix,
buf.width,
buf.height,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
} else {
blitRgb48leRegion(
canvas,
hdrRgb,
el.x,
el.y,
buf.width,
buf.height,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
}
addHdrTiming(hdrPerf, "hdrImageBlitMs", timingStart);
timeHdrPhase(hdrPerf, "hdrImageBlitMs", () => {
if (viewportMatrix) {
blitRgb48leAffine(
canvas,
hdrRgb,
viewportMatrix,
buf.width,
buf.height,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
} else {
blitRgb48leRegion(
canvas,
hdrRgb,
el.x,
el.y,
buf.width,
buf.height,
width,
height,
el.opacity < 0.999 ? el.opacity : undefined,
borderRadiusParam,
);
}
});
} catch (err) {
if (log) {
log.debug(`HDR image blit failed for ${el.id}`, {
Expand Down Expand Up @@ -505,6 +498,7 @@ export async function compositeHdrFrame(
// generation (their <img> replacements must be hidden from sibling
// screenshots). The actual blit is skipped in the compositing loop below.
const layers = groupIntoLayers(filteredStacking);
const allElementIds = fullStacking.map((e) => e.id);

const shouldLog = debugDumpEnabled && debugFrameIndex >= 0;
if (shouldLog) {
Expand Down Expand Up @@ -622,49 +616,46 @@ export async function compositeHdrFrame(
// (root background, sibling scenes' static content, the painted
// border/box-shadow of cards, etc.) and the resulting opaque
// pixels overwrite previously composited HDR content beneath.
const allElementIds = fullStacking.map((e) => e.id);
const layerIds = new Set(layer.elementIds);
const hideIds = allElementIds.filter((id) => !layerIds.has(id));
if (hdrPerf) hdrPerf.domLayerCaptures += 1;

// 1. Seek GSAP to restore all animated properties from clean state
let timingStart = Date.now();
await domSession.page.evaluate((t: number) => {
if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
}, time);
addHdrTiming(hdrPerf, "domLayerSeekMs", timingStart);
await timeHdrPhaseAsync(hdrPerf, "domLayerSeekMs", () =>
domSession.page.evaluate((t: number) => {
if (window.__hf && typeof window.__hf.seek === "function") window.__hf.seek(t);
}, time),
);

// 2. Run frame injector to set correct SDR video visibility
if (beforeCaptureHook) {
timingStart = Date.now();
await beforeCaptureHook(domSession.page, time);
addHdrTiming(hdrPerf, "domLayerInjectMs", timingStart);
await timeHdrPhaseAsync(hdrPerf, "domLayerInjectMs", () =>
beforeCaptureHook(domSession.page, time),
);
}

// 3. Install the mask (mass-hide stylesheet + inline-hide non-layer ids)
timingStart = Date.now();
await applyDomLayerMask(domSession.page, layer.elementIds, hideIds);
addHdrTiming(hdrPerf, "domMaskApplyMs", timingStart);
await timeHdrPhaseAsync(hdrPerf, "domMaskApplyMs", () =>
applyDomLayerMask(domSession.page, layer.elementIds, hideIds),
);

// 4. Screenshot
timingStart = Date.now();
const domPng = await captureAlphaPng(domSession.page, width, height);
addHdrTiming(hdrPerf, "domScreenshotMs", timingStart);
const domPng = await timeHdrPhaseAsync(hdrPerf, "domScreenshotMs", () =>
captureAlphaPng(domSession.page, width, height),
);

// 5. Tear down the mask
timingStart = Date.now();
await removeDomLayerMask(domSession.page, hideIds);
addHdrTiming(hdrPerf, "domMaskRemoveMs", timingStart);
await timeHdrPhaseAsync(hdrPerf, "domMaskRemoveMs", () =>
removeDomLayerMask(domSession.page, hideIds),
);

try {
timingStart = Date.now();
const { data: domRgba } = decodePng(domPng);
addHdrTiming(hdrPerf, "domPngDecodeMs", timingStart);
const { data: domRgba } = timeHdrPhase(hdrPerf, "domPngDecodeMs", () => decodePng(domPng));
const before = shouldLog ? countNonZeroRgb48(canvas) : 0;
const alphaPixels = shouldLog ? countNonZeroAlpha(domRgba) : 0;
timingStart = Date.now();
blitRgba8OverRgb48le(domRgba, canvas, width, height, compositeTransfer);
addHdrTiming(hdrPerf, "domBlitMs", timingStart);
timeHdrPhase(hdrPerf, "domBlitMs", () =>
blitRgba8OverRgb48le(domRgba, canvas, width, height, compositeTransfer),
);
if (shouldLog && debugDumpDir) {
const after = countNonZeroRgb48(canvas);
const dumpName = `frame_${String(debugFrameIndex).padStart(4, "0")}_layer_${String(layerIdx).padStart(2, "0")}_dom.png`;
Expand Down
24 changes: 24 additions & 0 deletions packages/producer/src/services/render/hdrPerf.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,30 @@ export function addHdrTiming(
perf.timings[key] += Date.now() - startMs;
}

export function timeHdrPhase<T>(
perf: HdrPerfCollector | undefined,
key: HdrPerfTimingKey,
fn: () => T,
): T {
if (!perf) return fn();
const start = Date.now();
const result = fn();
addHdrTiming(perf, key, start);
return result;
}

export async function timeHdrPhaseAsync<T>(
perf: HdrPerfCollector | undefined,
key: HdrPerfTimingKey,
fn: () => Promise<T>,
): Promise<T> {
if (!perf) return fn();
const start = Date.now();
const result = await fn();
addHdrTiming(perf, key, start);
return result;
}

function averageTiming(totalMs: number, count: number): number {
return count > 0 ? Math.round((totalMs / count) * 100) / 100 : 0;
}
Expand Down
Loading
Loading