Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* HDR / SDR mode resolution at the sequencer boundary.
*
* Folds three signals — `RenderConfig.hdrMode`, the probed video color
* spaces, and the probed image color spaces — into a single
* `effectiveHdr` decision, then emits the matching diagnostic log lines.
* The format gate (HDR + alpha is unsupported, so non-mp4 output forces
* SDR) lives here too so the sequencer doesn't need to know which
* formats can carry an HDR signal.
*/
import {
analyzeCompositionHdr,
formatHdrAutoPromotionWarning,
HDR_AUTO_PROMOTION_PIPELINE,
isHdrColorSpace,
sanitizeHdrAutoPromotionAsset,
} from "@hyperframes/engine";
import type { ExtractionResult, HdrTransfer, VideoColorSpace } from "@hyperframes/engine";
import type { ProducerLogger } from "../../logger.js";
import type { RenderConfig } from "../renderOrchestrator.js";
type EffectiveHdr = { transfer: HdrTransfer } | undefined;
type HdrModeInput = {
hdrMode: RenderConfig["hdrMode"];
outputFormat: NonNullable<RenderConfig["format"]>;
extractionResult: ExtractionResult | null | undefined;
imageColorSpaces: (VideoColorSpace | null)[];
autoPromotionTrigger?: string;
log: ProducerLogger;
};
/**
* The "format can't carry HDR, falling back to SDR" warning.
*
* `hls` is the one non-mp4 format refused for a reason other than alpha: HDR10
* would need HEVC in fMP4 segments, and v1 packages H.264 into MPEG-TS.
* `force-hdr` + `hls` is rejected outright before the render starts (see
* `validateHlsRenderConfig`), so only auto-detected HDR reaches this path.
*/
function formatDowngradeWarning(
outputFormat: NonNullable<RenderConfig["format"]>,
forcedHdrWithoutSources: boolean,
): string {
const hdrSourceReason = forcedHdrWithoutSources
? "HDR was forced without detected HDR sources"
: "HDR source detected";
const formatReason =
outputFormat === "hls"
? "HLS output is SDR-only (H.264 in MPEG-TS)"
: "HDR + alpha is not supported";
return (
`[Render] ${hdrSourceReason}, but format is "${outputFormat}", so falling back to SDR. ` +
`${formatReason}. Use --format mp4 for HDR10 output.`
);
}
export function findRenderHdrAutoPromotionTrigger(input: {
extractionResult: ExtractionResult | null | undefined;
videos: readonly { id: string; src: string }[];
images: readonly { id: string; src: string }[];
nativeHdrImageIds: ReadonlySet<string>;
}): string | undefined {
for (const extracted of input.extractionResult?.extracted ?? []) {
if (!isHdrColorSpace(extracted.metadata.colorSpace)) continue;
const source = input.videos.find(({ id }) => id === extracted.videoId)?.src;
if (source) return source;
}
return input.images.find(({ id }) => input.nativeHdrImageIds.has(id))?.src;
}
function logHdrResolution(
input: HdrModeInput,
hdrMode: NonNullable<RenderConfig["hdrMode"]>,
effectiveHdr: EffectiveHdr,
forcedHdrWithoutSources: boolean,
): void {
if (forcedHdrWithoutSources) {
input.log.warn(
"[Render] HDR forced by --hdr flag, but no HDR sources were detected, defaulting to HLG. SDR-only compositions may look perceptually wrong on HDR displays.",
);
}
if (!effectiveHdr) {
input.log.info(
hdrMode === "force-sdr"
? "[Render] SDR forced by --sdr flag"
: "[Render] No HDR sources detected, rendering SDR",
);
return;
}
if (hdrMode === "auto") {
input.log.warn(
formatHdrAutoPromotionWarning({
triggeringAsset: sanitizeHdrAutoPromotionAsset(
input.autoPromotionTrigger ?? "an HDR-tagged asset",
),
output: HDR_AUTO_PROMOTION_PIPELINE,
}),
);
return;
}
const reason = forcedHdrWithoutSources
? "forced by --hdr flag (no HDR sources detected, defaulting to HLG)"
: "forced by --hdr flag";
input.log.info(
`[Render] HDR ${reason}, output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`,
);
}
export function resolveEffectiveHdrMode(input: HdrModeInput): EffectiveHdr {
const hdrMode = input.hdrMode ?? "auto";
const videoColorSpaces = (input.extractionResult?.extracted ?? []).map(
(ext) => ext.metadata.colorSpace,
);
const allColorSpaces = [...videoColorSpaces, ...input.imageColorSpaces];
const info = allColorSpaces.length > 0 ? analyzeCompositionHdr(allColorSpaces) : null;
let effectiveHdr: EffectiveHdr;
let forcedHdrWithoutSources = false;
if (hdrMode === "force-sdr") {
effectiveHdr = undefined;
} else if (hdrMode === "force-hdr") {
if (info?.hasHdr && info.dominantTransfer) {
effectiveHdr = { transfer: info.dominantTransfer };
} else {
effectiveHdr = { transfer: "hlg" };
forcedHdrWithoutSources = true;
}
} else if (info?.hasHdr && info.dominantTransfer) {
effectiveHdr = { transfer: info.dominantTransfer };
}
if (effectiveHdr && input.outputFormat !== "mp4") {
input.log.warn(formatDowngradeWarning(input.outputFormat, forcedHdrWithoutSources));
effectiveHdr = undefined;
}
logHdrResolution(input, hdrMode, effectiveHdr, forcedHdrWithoutSources);
return effectiveHdr;
}