mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(cli): a subfolder of an imported project keeps its received-files record Publish, cloud render and feedback now read the received-files record at the nearest folder at or above the one they stage, so staging a subfolder of an imported project still leaves out the outside files its received files reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a received file counts under any spelling of the same file on disk The received-files lookup now also matches a project file that is the same file on disk as a listed path, so a name respelled in letter case on a case-insensitive disk keeps its received status. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): cloud render prepares only the GIFs staging kept The entry GIF prep before a cloud render upload now reads only the staged copies it is handed. An image whose source staging left out keeps its reference as written and is never read from disk. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): never hand a playlist named as media to ffmpeg A media file whose first bytes are an HLS playlist, an XML manifest or a concat script now stays out of ffprobe and ffmpeg: cloud render leaves it in the zip as authored, the media probe reports it as not media, and the proxy copy refuses it. Real media never starts with these bytes, so it probes and transcodes as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio-server): catch playlists with control bytes, and keep them from stills and audio probes A text playlist or concat script is detected whatever bytes follow its first line; only markup must be all text. A still frame and the audio probe behind waveforms, peaks and loudness now refuse a file the probe reads as not media, as the proxy copy already does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a parent folder's state the CLI cannot read never marks a project received The walk up for a received-files record now skips a parent whose record cannot be reached. Only a record file that is there but cannot be read or parsed counts every file as received. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): a drive that reports no file ids matches no received file by identity Some network and virtual drives report a file id of 0 for every file, so the same-file match now gives such a file no identity instead of matching it to every listed file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(studio-server): read a media file's first bytes with a read stream The playlist check reads the first 64 bytes through a bounded read stream instead of a raw file descriptor, and the audio-track probe's doc comment sits on its function again. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(studio-server): raise the packed size budget for the media playlist check Main packs @hyperframes/studio-server close to the 1% tolerance on the 168500 budget, and the playlist check adds about 320 bytes, which put the Build over. Set the budget to 172000. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): open media only through self-contained media demuxers Every ffprobe and ffmpeg input that cloud render offload, the publish proxy bake and Studio's media helpers open now carries a demuxer whitelist built from the supported media extensions: MP4/MOV/M4A/AVIF, Matroska/WebM, MXF, AVI, MPEG-PS/TS, FLV, ASF, Ogg, WAV, MP3, AAC, FLAC, AIFF and the still-image formats. Playlist, manifest and concat demuxers can no longer open, whatever a file's bytes say. The proxy's own concat step is left as it is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli,studio-server): keep media probe argv flat, and expect the demuxer list in loudness args Two probe argv literals built from nested spreads are flat again, so "--" stays the visible second-to-last entry the argv contract checks. The normalize-audio test expects the demuxer list before the input. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(cli): play and present answer only local host names and allowed hosts play and present listen on every interface. Each request now passes the same Host check preview uses: localhost, loopback addresses and this machine's own addresses and names are answered, and any other host name gets a 403 naming HYPERFRAMES_PREVIEW_ALLOWED_HOSTS until it is listed there. Phones and other machines on the network still open them by LAN address or .local name. * fix(cli): a local render of a received composition leaves out files outside the project When the composition a local render opens is listed in the project's received-files record, hyperframes render (full and range) no longer brings in files outside the project. It prints one line naming the references it leaves out and why. An unreadable record counts as received. A project whose entry is the person's own, or that has no record, renders exactly as before. * fix(cli): received-render scan reads safely and treats an unreadable record as unknown The scan behind the received-composition notice skips a file it cannot read, finds url() references with a linear forward scan, and reads at most 2 MB of each file. An unreadable received-files record no longer counts as everything received for local render: the render keeps outside files and names the record it could not read. Publish and cloud upload still treat it as received. The notice now says the render stops on a sub-composition outside the project rather than leaving it out. * fix(cli): the studio render of a received composition leaves out files outside the project The Studio render route applies the same rule as hyperframes render: when the composition it renders is listed in the received-files record, the job does not bring in files outside the project, and the server log names the references it refuses. * chore(cli): name the unreadable received-files record helper without a comment * fix(cli): local render refuses outside files when any composition it plays was received The received-file rule for local render (CLI and Studio) now checks every page and stylesheet the render pulls in, not only the entry, so an own index.html that plays a received scene also reads nothing outside the project, and the notice names the received file. An unreadable, truncated or empty received-files record refuses outside files too, as publish and cloud upload do, and the notice names the record it could not read. * fix(cli): decide a received render from the files the compiler reads Local render (CLI and Studio) now leaves outside-file handling as it is for a project with no received-files record or an empty one, without scanning anything. When the record lists files, the compiler's own read list for the composition decides: the bundler runs out of process with a deadline and reports every project file it reads, so stylesheet imports and files past any scan limit count. A received file in that list, a build that fails or runs past its deadline, or an unreadable record refuses outside files. The scan that names refused references in the notice is advisory only: it guards every file system call, tracks visited files by real path, and caps the files and bytes it reads. * fix(cli,producer): decide a received render with the render compiler's own composition traversal The producer exports renderCompositionFiles, which walks data-composition-src with the same resolution, normalization and private file rules the render's sub-composition pass uses; that pass now calls the same helper. The received-render decision adds those files to the bundler's read list, so leading-slash and percent-encoded references the render reads count. The advisory scan resolves compositions the same way and reads template contents. * fix(cli): refuse outside files in a local render whenever the project has received files A local render (CLI and Studio) reads nothing outside the project when the project's received-files record lists any file, or cannot be read. No static list matches what a render consumes: the page loads its stylesheets and scripts through the browser at capture time, and scripts can load more, so the decision no longer depends on one. The reference scan stays only to name what the notice says is left out. This drops the out-of-process bundler read list and the producer composition walk added for that decision. * fix(cli): refuse outside files only when a received file can load other files A local render (CLI and Studio) reads nothing outside the project when the received-files record cannot be read, or lists a received file that can reference others: an .html, .htm, .css, .js, .mjs, .cjs or .svg name, or content that reads as HTML, SVG or CSS. A project that only received images, video, audio or fonts keeps bringing in outside files as before. * fix(cli): keep outside files only when every received file is positively media, a font or an image A local render keeps bringing in outside files only when each file the received-files record lists has a known media, font or image extension and starts with that type's signature bytes. Any other received file, a listed file that is missing or unreadable, or a mismatch between name and content refuses outside files. An ancestor record's entries now match a subfolder whose name is spelled in another Unicode form; the entry keeps its own spelling on disk. * fix(producer,core): a sub-composition must be an .html file The render compiler and the runtime load a data-composition-src only when it names an .html or .htm file. Any other file, such as an image or video, is refused as a page: render stops naming it, and the runtime reports the load failure without fetching it. * fix(producer,cli): the render and static file servers forbid type sniffing Both servers send X-Content-Type-Options: nosniff with every response, so the browser loads a file only as the type its extension names: an image or video cannot run as a script or apply as a stylesheet. .cjs is served as JavaScript. * test(cli): a received media file in a composition slot is refused as a page * test(cli): an empty nested received-files record cannot hide an outer record's received page * fix(cli): a received media file reached under another name refuses outside files The received-render decision now compares file identities, not names. It walks the project once, bounded by entry count and time, and refuses outside files when a hardlink or a symlink with a name that is not media reaches a received file, or when the walk cannot finish. A received file with no identity matches nothing, as in the received files check. * fix(cli): compare received files by link target and keep outside files for an empty record A received media file and every other project name are now compared by the identity of the file they reach with links followed. A linked folder that leads outside the project, or a file whose identity cannot be read, counts as unchecked and refuses outside files. An empty received-files record keeps outside files without walking the project. * chore: raise the producer unpacked size budget for the composition file checks --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2202 lines
88 KiB
TypeScript
2202 lines
88 KiB
TypeScript
import type { ReferenceBackgroundResult } from "@hyperframes/producer";
|
||
import { captureArtifactRevision } from "../utils/artifactCapture.js";
|
||
import { recordRenderSuccess, registerRenderOutput } from "@hyperframes/studio-server/history";
|
||
import { resolveGsapVendorDir } from "../server/gsapVendor.js";
|
||
import { failCommand, requestCliExit, scheduleCliExit } from "../utils/commandResult.js";
|
||
import { defineCommand } from "../utils/defineCommand.js";
|
||
import type { Example } from "./_examples.js";
|
||
import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
|
||
import {
|
||
createRenderPlan,
|
||
resolveBrowserGpuForCli,
|
||
type RenderFormat,
|
||
type RenderRange,
|
||
} from "./render/plan.js";
|
||
import { seedProjectAuthoringSkill } from "../utils/projectConfig.js";
|
||
import { deliveryFlagArgs } from "../utils/deliveryFlags.js";
|
||
import type { CatalogUsage } from "../utils/catalogUsage.js";
|
||
import { presentRenderPlan } from "./render/present.js";
|
||
import { acquireRenderSlot } from "./render/renderSlot.js";
|
||
import { executeRenderPlan, renderLintContinuationHint, runRenderLint } from "./render/execute.js";
|
||
// Test-only seams retained at the command boundary for render behavior tests.
|
||
export { resolveBrowserGpuForCli, renderLintContinuationHint, runRenderLint };
|
||
|
||
export const examples: Example[] = [
|
||
["Render to MP4", "hyperframes render --output output.mp4"],
|
||
["Render a specific composition", "hyperframes render -c compositions/intro.html -o intro.mp4"],
|
||
[
|
||
"Upsample any composition to 4K (supersamples via Chrome DPR)",
|
||
"hyperframes render --resolution 4k --output 4k.mp4",
|
||
],
|
||
["Render transparent overlay (ProRes)", "hyperframes render --format mov --output overlay.mov"],
|
||
["Render transparent WebM overlay", "hyperframes render --format webm --output overlay.webm"],
|
||
[
|
||
"Render animated GIF for PRs/docs",
|
||
"hyperframes render --format gif --fps 15 --gif-loop 0 --output demo.gif",
|
||
],
|
||
[
|
||
"Render PNG sequence (RGBA frames for AE/Nuke/Fusion)",
|
||
"hyperframes render --format png-sequence --output frames/",
|
||
],
|
||
[
|
||
"Render HLS VOD (master playlist + MPEG-TS segments in a directory)",
|
||
"hyperframes render --format hls --output stream/",
|
||
],
|
||
["High quality at 60fps", "hyperframes render --fps 60 --quality high --output hd.mp4"],
|
||
["Deterministic render via Docker", "hyperframes render --docker --output deterministic.mp4"],
|
||
["Parallel rendering with 6 workers", "hyperframes render --workers 6 --output fast.mp4"],
|
||
["Opt out of browser GPU render", "hyperframes render --no-browser-gpu --output cpu.mp4"],
|
||
[
|
||
"Show full lint findings instead of the summary line",
|
||
"hyperframes render --lint-verbose --output out.mp4",
|
||
],
|
||
[
|
||
"Relocate frame cache off C: (Windows) or another small partition",
|
||
"hyperframes render --frames-cache-dir D:/hf-cache --output out.mp4",
|
||
],
|
||
["HDR output (auto-detected)", "hyperframes render --output hdr-output.mp4"],
|
||
[
|
||
"Override composition variables (parametrized render)",
|
||
'hyperframes render --variables \'{"title":"Q4 Report","theme":"dark"}\' --output q4.mp4',
|
||
],
|
||
[
|
||
"Variables from a JSON file",
|
||
"hyperframes render --variables-file ./vars.json --output out.mp4",
|
||
],
|
||
[
|
||
"Batch render one output per variables row",
|
||
'hyperframes render --batch rows.json --output "renders/{name}.mp4"',
|
||
],
|
||
];
|
||
import { freemem, tmpdir } from "node:os";
|
||
import { resolve, dirname, join, basename } from "node:path";
|
||
import { execFileSync, spawn } from "node:child_process";
|
||
import { loadProducer } from "../utils/producer.js";
|
||
import { outsideAssetsAllowed } from "../utils/receivedRender.js";
|
||
import { c } from "../ui/colors.js";
|
||
import { desktopHint } from "../utils/desktopApp.js";
|
||
import {
|
||
formatBytes,
|
||
formatRenderSummaryDetail,
|
||
formatRenderPipelineDetail,
|
||
formatScreenshotFallbackHint,
|
||
resolvePrintedCaptureMode,
|
||
errorBox,
|
||
} from "../ui/format.js";
|
||
import { warnIfWebmAlphaDropped } from "../utils/webmAlphaCheck.js";
|
||
import { renderFailureDiagnostic } from "../ui/renderDiagnostic.js";
|
||
import { missingPathKind } from "../telemetry/missingPathKind.js";
|
||
import { renderProgress, renderMachineProgress } from "../ui/progress.js";
|
||
import {
|
||
trackRenderComplete,
|
||
trackRenderError,
|
||
trackRenderObservation,
|
||
type RenderOutputShapeTelemetryPayload,
|
||
type RenderEnvironmentTelemetryPayload,
|
||
} from "../telemetry/events.js";
|
||
import { maybePromptRenderFeedback } from "../telemetry/feedback.js";
|
||
import { renderMotionBlurTelemetryPayload } from "../telemetry/renderMotionBlur.js";
|
||
import {
|
||
readConfigFresh,
|
||
releaseDeParallelRouterLatch,
|
||
type DeRouterBreaker,
|
||
type DeRouterRevert,
|
||
recordRecentRender,
|
||
writeConfig,
|
||
writeConfigWithResult,
|
||
type HyperframesConfig,
|
||
} from "../telemetry/config.js";
|
||
import { renderJobObservabilityTelemetryPayload } from "../telemetry/renderObservability.js";
|
||
import {
|
||
startRenderCpuSampler,
|
||
type RenderCpuSampler,
|
||
type RenderCpuTelemetryPayload,
|
||
} from "../telemetry/renderCpu.js";
|
||
import { bytesToMb } from "../telemetry/system.js";
|
||
import { VERSION } from "../version.js";
|
||
import {
|
||
afterCleanRender,
|
||
afterRevert,
|
||
forVersion,
|
||
isRouterOff,
|
||
} from "./render/deRouterBreaker.js";
|
||
import { isDevMode } from "../utils/env.js";
|
||
import { buildDockerRunArgs, resolveDockerPlatform } from "../utils/dockerRunArgs.js";
|
||
import { createStderrTail, DockerRenderExitError } from "../utils/dockerStderrTail.js";
|
||
import type { BrowserInstallFacts } from "../browser/installFacts.js";
|
||
import { normalizeErrorMessage } from "../utils/errorMessage.js";
|
||
import {
|
||
DOCKER_BUILD_TIMEOUT_MINUTES,
|
||
describeDockerBuildFailure,
|
||
} from "../utils/dockerBuildFailure.js";
|
||
import { runEnvironmentChecks } from "../browser/preflight.js";
|
||
import {
|
||
detectH264EncoderModeForRender,
|
||
FFMPEG_PATH_ENV,
|
||
getFFmpegInstallHint,
|
||
H264EncoderUnavailableError,
|
||
type H264EncoderMode,
|
||
} from "../browser/ffmpeg.js";
|
||
import { chromeLaunchRemediation } from "../browser/linuxDeps.js";
|
||
import { macosOldChromeCrashRemediation } from "../browser/macosOldChromeCrash.js";
|
||
import { windowsChromeCrashRemediation } from "../browser/windowsCrash.js";
|
||
import { killOrphanedProcessesForRender } from "../utils/orphanCleanup.js";
|
||
import { createRenderCancellationScope } from "../utils/renderCancellation.js";
|
||
import { audioLoweredWarning } from "../utils/audioLoweredWarning.js";
|
||
import {
|
||
markRenderSucceeded,
|
||
runPostRenderStep,
|
||
runPostRenderStepAsync,
|
||
} from "../utils/render-success-state.js";
|
||
import type { ProducerLogger, RenderJob, RenderPerfSummary } from "@hyperframes/producer";
|
||
import {
|
||
EXTRACT_CACHE_DIR_DISABLED_ALIASES,
|
||
sandboxDeniedRemediation,
|
||
type PageMotionBlurSummary,
|
||
type ProresProfile,
|
||
type VideoFrameFormat,
|
||
} from "@hyperframes/engine";
|
||
import {
|
||
checkOutputResolutionCompatibility,
|
||
suggestMatchingPreset,
|
||
fpsToNumber,
|
||
type CanvasResolution,
|
||
type OutputResolutionIssueKind,
|
||
type Fps,
|
||
} from "@hyperframes/core";
|
||
|
||
export default defineCommand({
|
||
meta: {
|
||
name: "render",
|
||
description: "Render a composition to MP4, WebM, MOV, GIF, HLS, or a PNG sequence",
|
||
},
|
||
args: {
|
||
dir: {
|
||
type: "positional",
|
||
description: "Project directory",
|
||
required: false,
|
||
},
|
||
composition: {
|
||
type: "string",
|
||
alias: "c",
|
||
description:
|
||
"Render a specific composition file instead of index.html (e.g. compositions/intro.html). " +
|
||
"Sub-compositions using <template> wrappers must be referenced from index.html via data-composition-src. " +
|
||
"Pass `.` (or omit the flag) to render the project's index.html.",
|
||
},
|
||
output: {
|
||
type: "string",
|
||
alias: "o",
|
||
description: "Output path (default: renders/<project>_<YYYY-MM-DD>_<HH-MM-SS>.<ext>)",
|
||
},
|
||
fps: {
|
||
type: "string",
|
||
alias: "f",
|
||
description:
|
||
"Frame rate. Accepts integer (24, 25, 30, 50, 60, 120, 240) or " +
|
||
"ffmpeg-style rational (30000/1001 for NTSC 29.97, 24000/1001 for " +
|
||
"23.976, 60000/1001 for 59.94). Range 1-240. " +
|
||
"Defaults to the composition's root data-fps, else 30.",
|
||
// No `default` here on purpose: citty would set args.fps="30" on
|
||
// omission, which would make explicitFps always non-null and short-
|
||
// circuit the data-fps resolution below (resolveDefaultFpsArg). The
|
||
// "30" fallback lives at the parseFps(fpsArg ?? "30") call instead.
|
||
},
|
||
quality: {
|
||
type: "string",
|
||
alias: "q",
|
||
description:
|
||
"Quality: draft, looks, delivery, or standard/high. looks is the default (CRF 16). delivery is high. MOV uses ProRes 4444 with alpha unless --prores-profile picks a 422 profile.",
|
||
default: "looks",
|
||
},
|
||
skill: {
|
||
type: "string",
|
||
description:
|
||
"Authoring skill that initiated this render (e.g. hyperframes). " +
|
||
"Recorded on render telemetry for per-skill usage breakdowns; ignored unless it is a slug.",
|
||
},
|
||
format: {
|
||
type: "string",
|
||
description:
|
||
"Output format: mp4, webm, mov, gif, png-sequence, hls " +
|
||
"(MOV/WebM render with transparency; png-sequence writes RGBA frames " +
|
||
"to a directory for AE/Nuke/Fusion ingest; gif is best at 15fps for PRs/docs; " +
|
||
"hls writes a VOD playlist directory — H.264/AAC, SDR only, no GPU encoding)",
|
||
default: "mp4",
|
||
},
|
||
"gif-loop": {
|
||
type: "string",
|
||
description: "GIF loop count, 0 = infinite. Range: 0-65535. Only used with --format gif.",
|
||
},
|
||
"hls-segment-seconds": {
|
||
type: "string",
|
||
description:
|
||
"HLS target segment length in whole seconds (default: 4). Range: 1-60. " +
|
||
"Also fixes the encoder GOP at segment x fps frames so every segment " +
|
||
"starts on a keyframe. Only used with --format hls.",
|
||
},
|
||
"video-frame-format": {
|
||
type: "string",
|
||
description:
|
||
"Source video frame extraction format: auto, jpg, png (default: auto). " +
|
||
"Use png for UI recordings, screen captures, and color-sensitive source videos; " +
|
||
"alpha-capable sources always extract as PNG.",
|
||
default: "auto",
|
||
},
|
||
"page-motion-blur": {
|
||
type: "string",
|
||
description:
|
||
"Set off to disable authored page motion blur. Omit to keep the composition's setting.",
|
||
},
|
||
workers: {
|
||
type: "string",
|
||
alias: "w",
|
||
description:
|
||
"Parallel render workers (number or 'auto'). Default: auto. " +
|
||
"Each worker launches a separate Chrome process (~256 MB RAM).",
|
||
},
|
||
docker: {
|
||
type: "boolean",
|
||
description: "Use Docker for deterministic render",
|
||
default: false,
|
||
},
|
||
hdr: {
|
||
type: "boolean",
|
||
description: "Force HDR output even if no HDR sources are detected",
|
||
default: false,
|
||
},
|
||
sdr: {
|
||
type: "boolean",
|
||
description: "Force SDR output even if HDR sources are detected",
|
||
default: false,
|
||
},
|
||
crf: {
|
||
type: "string",
|
||
description:
|
||
"Override MP4/WebM encoder CRF. Mutually exclusive with --video-bitrate; unsupported for MOV.",
|
||
},
|
||
start: {
|
||
type: "string",
|
||
description:
|
||
"Render from this second of the film (MP4). The clip starts at 0 and carries the audio of the span.",
|
||
},
|
||
end: {
|
||
type: "string",
|
||
description:
|
||
"Render up to this second of the film (default: the end). Needs MP4, a whole frame rate of 24, 25, 30 or 60, and SDR.",
|
||
},
|
||
"video-bitrate": {
|
||
type: "string",
|
||
description:
|
||
"Target MP4/WebM video bitrate such as 10M. Mutually exclusive with --crf; unsupported for MOV.",
|
||
},
|
||
...deliveryFlagArgs,
|
||
"vp9-cpu-used": {
|
||
type: "string",
|
||
description:
|
||
"libvpx-vp9 -cpu-used value for WebM encodes (-8 to 8). Higher is faster with a larger quality/size tradeoff. Env: PRODUCER_VP9_CPU_USED.",
|
||
},
|
||
"chroma-subsampling": {
|
||
type: "string",
|
||
description:
|
||
"MP4 chroma: 420 (default) or 444. 444 keeps full-resolution colour for thin coloured " +
|
||
"text and UI (yuv444p, lossless PNG capture, slower). Software encoder and SDR MP4 only; " +
|
||
"many players cannot decode 4:4:4.",
|
||
default: "420",
|
||
},
|
||
gpu: { type: "boolean", description: "Use GPU encoding", default: false },
|
||
"browser-gpu": {
|
||
type: "boolean",
|
||
description:
|
||
"Force host GPU acceleration for Chrome/WebGL capture. Default: auto (probe on first launch; fall back to software if no GPU). Use --no-browser-gpu to force software (SwiftShader).",
|
||
},
|
||
quiet: {
|
||
type: "boolean",
|
||
description: "Suppress verbose output",
|
||
default: false,
|
||
},
|
||
"lint-verbose": {
|
||
type: "boolean",
|
||
description: "Show full lint findings instead of the summary line",
|
||
default: false,
|
||
},
|
||
debug: {
|
||
type: "boolean",
|
||
description:
|
||
"Write full render diagnostics and keep intermediate artifacts under the producer .debug directory.",
|
||
default: false,
|
||
},
|
||
"best-effort": {
|
||
type: "boolean",
|
||
description:
|
||
"Allow output with structured capture-readiness warnings (default). Use --no-best-effort to fail on missing or unready media.",
|
||
default: true,
|
||
},
|
||
wait: {
|
||
type: "boolean",
|
||
description:
|
||
"Wait while another render of this user account runs, then start (default): renders side by " +
|
||
"side starve each other. Use --no-wait to fail at once instead. Env: HYPERFRAMES_RENDER_LOCK=off " +
|
||
"lets renders run side by side; HYPERFRAMES_CACHE_DIR set to a shared folder shares the slot " +
|
||
"across user accounts.",
|
||
default: true,
|
||
},
|
||
strict: {
|
||
type: "boolean",
|
||
description: "Fail render on lint errors",
|
||
default: false,
|
||
},
|
||
"strict-all": {
|
||
type: "boolean",
|
||
description: "Fail render on lint errors AND warnings",
|
||
default: false,
|
||
},
|
||
"max-concurrent-renders": {
|
||
type: "string",
|
||
description: "Max concurrent renders when using the producer server (1-10). Default: 2.",
|
||
},
|
||
variables: {
|
||
type: "string",
|
||
description:
|
||
'JSON object of variable values, merged over the composition\'s data-composition-variables defaults. Example: --variables \'{"title":"Hello"}\'. Also a JSON file path, or - for stdin. Read inside the composition via window.__hyperframes.getVariables().',
|
||
},
|
||
"variables-file": {
|
||
type: "string",
|
||
description:
|
||
"Path to a JSON file with variable values (alternative to --variables). The file must contain a single JSON object.",
|
||
},
|
||
"strict-variables": {
|
||
type: "boolean",
|
||
description:
|
||
"Fail render if any --variables key is undeclared or has a wrong type vs the composition's data-composition-variables. Without this flag, mismatches are warnings.",
|
||
default: false,
|
||
},
|
||
batch: {
|
||
type: "string",
|
||
description:
|
||
'Path to a JSON array of variable rows (or {"rows":[...]}). Renders one output per row.',
|
||
},
|
||
"batch-concurrency": {
|
||
type: "string",
|
||
description:
|
||
"Maximum number of batch rows to render at once. Default: 1, because each render already parallelizes across workers.",
|
||
},
|
||
"batch-fail-fast": {
|
||
type: "boolean",
|
||
description: "Stop launching new batch rows after the first row failure.",
|
||
default: false,
|
||
},
|
||
json: {
|
||
type: "boolean",
|
||
description:
|
||
"With --batch, emit exactly one final JSON result document. Without --batch, print no progress, and on failure print the JSON error envelope.",
|
||
default: false,
|
||
},
|
||
resolution: {
|
||
type: "string",
|
||
description:
|
||
"Output resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160), landscape-1440p (2560x1440), portrait-1440p (1440x2560), square-1440p (1440x1440). Aliases: 1080p, 4k, uhd, 1440p, qhd, 1080p-square, square-1080p, 4k-square, 1440p-portrait, 1440p-square. The composition is unchanged — Chrome renders at higher DPR (deviceScaleFactor) so the captured screenshot lands at the requested dimensions. Aspect ratio must match the composition; upscaling requires an integer multiple. Not yet supported with --hdr.",
|
||
},
|
||
"page-side-compositing": {
|
||
type: "boolean",
|
||
description:
|
||
"Run shader transitions on a page-side WebGL canvas inside Chrome " +
|
||
"instead of the Node-side layered blend. ~6× faster for SDR " +
|
||
"shader-transition renders. Used for mp4, hls and gif output without " +
|
||
"HDR content; for mp4 and hls it usually turns off under --experimental-fast-capture. " +
|
||
"webm and mov output take the layered path. --no-page-side-compositing forces " +
|
||
"the layered path for mp4 and hls; gif always uses the page-side canvas.",
|
||
default: true,
|
||
},
|
||
"browser-timeout": {
|
||
type: "string",
|
||
description:
|
||
"Puppeteer page-navigation timeout in SECONDS for the entry HTML. " +
|
||
"Increase when heavy compositions (many videos / fonts / asset " +
|
||
"requests) cannot reach domcontentloaded within the 60s default " +
|
||
"(see issue #1199). Accepts 0.001-86400 (24h cap). " +
|
||
"Note: this controls page.goto only — very heavy compositions may " +
|
||
"also need PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS / " +
|
||
"PRODUCER_PLAYER_READY_TIMEOUT_MS bumped (the post-goto window.__hf " +
|
||
"readiness poll has its own 45s budget). " +
|
||
"Env fallback: PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS (MILLISECONDS).",
|
||
},
|
||
"protocol-timeout": {
|
||
type: "string",
|
||
description:
|
||
"CDP protocol timeout in ms. Increase on slow/low-memory machines " +
|
||
"where Chrome operations time out. Default: 300000 (5 min). " +
|
||
"Env: PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS.",
|
||
},
|
||
"player-ready-timeout": {
|
||
type: "string",
|
||
description:
|
||
"Timeout in ms for the composition player to become ready. " +
|
||
"Increase for complex compositions on slow hardware. Default: 45000 (45 s). " +
|
||
"Env: PRODUCER_PLAYER_READY_TIMEOUT_MS.",
|
||
},
|
||
resume: {
|
||
type: "boolean",
|
||
description:
|
||
"Segmented capture only (HF_SEGMENTED_CAPTURE=true): reuse segments a " +
|
||
"previous run of the same composition and settings already finished, " +
|
||
"recorded in renders/.hf-segments/<hash>/segments.json. Each reused " +
|
||
"segment is re-validated before it is skipped.",
|
||
default: false,
|
||
},
|
||
"keep-segments": {
|
||
type: "boolean",
|
||
description:
|
||
"Segmented capture only: keep renders/.hf-segments/<hash> after a " +
|
||
"successful render instead of deleting it.",
|
||
default: false,
|
||
},
|
||
"low-memory-mode": {
|
||
type: "boolean",
|
||
description:
|
||
"Force the low-memory safe render profile on (--low-memory-mode) or " +
|
||
"off (--no-low-memory-mode). Safe mode pins to 1 worker, uses " +
|
||
"screenshot capture, and skips auto-worker calibration to avoid " +
|
||
"memory thrash on constrained machines. Default: auto-detected from " +
|
||
"total RAM (<= 8 GB). Env: PRODUCER_LOW_MEMORY_MODE.",
|
||
},
|
||
"experimental-fast-capture": {
|
||
type: "boolean",
|
||
description:
|
||
"Capture frames via Chrome's drawElementImage API instead of " +
|
||
"Page.captureScreenshot — reads DOM paint records directly, ~2x faster. " +
|
||
"Default: on where it can engage (macOS + hardware-GPU browser); " +
|
||
"incompatible compositions and self-verification failures fall back to " +
|
||
"screenshot capture automatically. Pass =false to disable. " +
|
||
"Env: PRODUCER_EXPERIMENTAL_FAST_CAPTURE.",
|
||
// No `default` — an omitted flag must stay `undefined` so the `!= null`
|
||
// guard below leaves PRODUCER_EXPERIMENTAL_FAST_CAPTURE untouched and the
|
||
// env fallback survives (matches the --low-memory-mode idiom).
|
||
},
|
||
"frames-cache-dir": {
|
||
type: "string",
|
||
description:
|
||
"Directory for the content-addressed extracted-frame cache. " +
|
||
"Use to relocate the cache off the system drive when the OS temp " +
|
||
"directory lives on a small partition (e.g. Windows C: exhaustion " +
|
||
`during long renders). Pass ${EXTRACT_CACHE_DIR_DISABLED_ALIASES.map((a) => `"${a}"`).join(" / ")} to ` +
|
||
"disable caching entirely (frames extract into the render's workDir " +
|
||
"and are cleaned up when the render ends). Default: " +
|
||
"<tmpdir>/hyperframes-extract-cache-<uid>. " +
|
||
"Env: HYPERFRAMES_EXTRACT_CACHE_DIR.",
|
||
},
|
||
},
|
||
// Keep the transport adapter thin: each phase has one ownership boundary.
|
||
async run({ args }) {
|
||
const plan = createRenderPlan(args);
|
||
const cancellation = plan.useDocker ? undefined : createRenderCancellationScope();
|
||
try {
|
||
// Teach the project its owning skill from an explicit --skill so every
|
||
// later flag-less render (re-render, `npm run render`, batch) inherits it.
|
||
seedProjectAuthoringSkill(plan.project.dir, args.skill);
|
||
await presentRenderPlan(plan);
|
||
await executeRenderPlan(
|
||
plan,
|
||
{
|
||
renderDocker,
|
||
renderLocal,
|
||
checkResolution: checkRenderResolutionPreflight,
|
||
acquireRenderSlot,
|
||
},
|
||
cancellation,
|
||
);
|
||
} catch (error) {
|
||
if (cancellation?.signal.aborted) {
|
||
const reason = cancellation.signal.reason;
|
||
const message = reason instanceof Error ? reason.message : String(reason);
|
||
process.stderr.write(`Render cancelled: ${message}\n`);
|
||
requestCliExit(1);
|
||
}
|
||
throw error;
|
||
} finally {
|
||
cancellation?.dispose();
|
||
}
|
||
},
|
||
});
|
||
|
||
export interface SingleRenderResult extends Partial<ReferenceBackgroundResult> {
|
||
motionBlur?: PageMotionBlurSummary;
|
||
durationMs?: number;
|
||
renderTimeMs: number;
|
||
outcome?: "completed" | "completed_with_warnings";
|
||
warnings?: Array<{ code: string; message: string }>;
|
||
}
|
||
|
||
export interface RenderOptions {
|
||
fps: Fps;
|
||
quality: "draft" | "standard" | "high";
|
||
/** Authoring workflow skill that drove this render (telemetry attribution). */
|
||
authoringSkill?: string;
|
||
/** Which step resolved authoringSkill: an explicit --skill flag, or the project's own config. */
|
||
authoringSkillSource?: "flag" | "project-config";
|
||
/** Raw --skill value when it failed normalizeSkillSlug (an unrecognized skill name was passed). */
|
||
authoringSkillInvalid?: string;
|
||
/** Names of HF_-/HYPERFRAMES_-prefixed env vars present at plan time (never values), capped at 20. */
|
||
hfEnvOverrides?: readonly string[];
|
||
/**
|
||
* Catalog items installed in this project and those the rendered composition
|
||
* reaches. Resolved once in the render plan; absent on programmatic callers
|
||
* that build options by hand, which simply omit the catalog properties.
|
||
*/
|
||
catalogUsage?: CatalogUsage;
|
||
format: RenderFormat;
|
||
gifLoop?: number;
|
||
/** True when `createRenderPlan` clamped a requested `--fps` above 30 to 30 for `--format gif`. */
|
||
gifFpsCapped?: boolean;
|
||
/** Major FFmpeg/Chrome version from local preflight (telemetry only); absent on Docker renders. */
|
||
ffmpegVersionMajor?: number;
|
||
browserVersionMajor?: number;
|
||
browserInstall?: BrowserInstallFacts;
|
||
/** HLS target segment length in seconds; ignored unless `format` is `"hls"`. */
|
||
hlsSegmentSeconds?: number;
|
||
workers?: number;
|
||
gpu: boolean;
|
||
/**
|
||
* Chrome WebGL backend mode. "auto" probes on first launch and falls back
|
||
* to "software" if no usable GPU. Defaults to "software" when omitted to
|
||
* stay backwards-compatible with callers that pre-date the tri-state.
|
||
*/
|
||
browserGpuMode?: "auto" | "hardware" | "software";
|
||
hdrMode: "auto" | "force-hdr" | "force-sdr";
|
||
crf?: number;
|
||
vp9CpuUsed?: number;
|
||
videoBitrate?: string;
|
||
keyframeIntervalSeconds?: number;
|
||
range?: RenderRange;
|
||
proresProfile?: ProresProfile;
|
||
maxBitrate?: string;
|
||
bufferSize?: string;
|
||
videoFrameFormat?: VideoFrameFormat;
|
||
/** "444" opts an SDR MP4 render into full-resolution chroma. Absent means 4:2:0. */
|
||
chromaSubsampling?: "420" | "444";
|
||
pageMotionBlur?: "off";
|
||
quiet: boolean;
|
||
debug?: boolean;
|
||
/** Segmented capture: reuse a prior run's validated segments. */
|
||
resumeSegments?: boolean;
|
||
/** Segmented capture: keep the segment directory after success. */
|
||
keepSegments?: boolean;
|
||
bestEffort?: boolean;
|
||
browserPath?: string;
|
||
variables?: Record<string, unknown>;
|
||
entryFile?: string;
|
||
exitAfterComplete?: boolean;
|
||
embedded?: boolean;
|
||
/** Output resolution preset; see `resolveDeviceScaleFactor` for constraints. */
|
||
outputResolution?: CanvasResolution;
|
||
/** Whether the resolution names a tier without fixing an orientation. */
|
||
outputResolutionAspectAgnostic?: boolean;
|
||
/** Raw resolution flag retained for the in-container CLI. */
|
||
outputResolutionRaw?: string;
|
||
pageSideCompositing?: boolean;
|
||
/** EXPERIMENTAL. drawElementImage frame capture (--experimental-fast-capture). */
|
||
experimentalFastCapture?: boolean;
|
||
/**
|
||
* Puppeteer `page.goto()` timeout for the entry HTML, in milliseconds.
|
||
* When omitted, the engine default (60s) applies. Surfaced as
|
||
* `--browser-timeout <seconds>` at the CLI and threaded through to the
|
||
* producer's EngineConfig override.
|
||
*/
|
||
pageNavigationTimeoutMs?: number;
|
||
/** CDP protocol timeout override (ms). */
|
||
protocolTimeout?: number;
|
||
/** Player-ready timeout override (ms). */
|
||
playerReadyTimeout?: number;
|
||
/** Throw render failures to the caller instead of printing and exiting. */
|
||
throwOnError?: boolean;
|
||
/** Skip the interactive feedback prompt after a successful render. */
|
||
skipFeedback?: boolean;
|
||
/** False for a batch row: one line about the desktop app per batch is noise, not a pointer. */
|
||
desktopHint?: boolean;
|
||
/**
|
||
* OPT IN to managing the DE parallel-router circuit breaker
|
||
* (`applyDeParallelRouterCircuitBreaker`) for this render. Default OFF —
|
||
* only the top-level CLI render command's own call sites should ever set
|
||
* this (review): the mechanism shares one process-wide env var and two
|
||
* module-level flags across every `renderLocal` call in the process,
|
||
* which is safe for SEQUENTIAL calls (single render, single-concurrency
|
||
* batch rows) but not for genuinely concurrent ones — racing invocations
|
||
* could tear down or misattribute each other's outcome. Programmatic
|
||
* consumers importing `renderLocal` (a future studio-server path, test
|
||
* harnesses, distributed runners) therefore do not manage the breaker
|
||
* unless they explicitly opt in AND guarantee sequential invocation. The
|
||
* CLI sets this for single renders and for `--batch` at concurrency 1; it
|
||
* leaves it unset for `--batch-concurrency N>=2`.
|
||
*
|
||
* NOTE the asymmetry: the ROUTER itself is default-on for every consumer
|
||
* (the producer decides that). This flag only governs whether we
|
||
* additionally enforce the per-install breaker, because that is the part
|
||
* with process-wide state.
|
||
*/
|
||
manageDeParallelRouterBreaker?: boolean;
|
||
}
|
||
|
||
/**
|
||
* Read a composition's dimensions from the SAME source the producer's compiler
|
||
* uses — `data-width` / `data-height` on the `[data-composition-id]` root (see
|
||
* htmlCompiler.ts). Returns `undefined` when they can't be determined (no root,
|
||
* missing/invalid attrs, unparseable HTML). Note the producer *defaults* a
|
||
* missing attr to 1080; this pre-flight deliberately defers instead (returns
|
||
* `undefined`) rather than guess a dimension the author didn't declare, so it
|
||
* never false-aborts — the producer's defense-in-depth still catches that case.
|
||
*
|
||
* Deriving dims any other way (e.g. `data-resolution` or a `#stage` heuristic)
|
||
* risks disagreeing with the actual render: most compositions (all registry
|
||
* blocks) carry `data-width/height` and no `data-resolution`, so a parallel
|
||
* heuristic could false-abort a valid render. `DOMParser` isn't shipped by
|
||
* Node — the CLI polyfills it via linkedom, imported lazily so the heavy DOM
|
||
* library stays out of `render.js`'s module-load graph (it cold-imports at
|
||
* >5 s already; a static linkedom import tips the render test suite's import
|
||
* hook over its timeout — see the note on `renderLocal browser GPU config`).
|
||
*/
|
||
async function readCompositionDimensions(
|
||
compositionHtml: string,
|
||
): Promise<{ width: number; height: number } | undefined> {
|
||
try {
|
||
const { ensureDOMParser } = await import("../utils/dom.js");
|
||
ensureDOMParser();
|
||
const doc = new DOMParser().parseFromString(compositionHtml, "text/html");
|
||
const rootEl = doc.querySelector("[data-composition-id]");
|
||
const width = parseInt(rootEl?.getAttribute("data-width") ?? "", 10);
|
||
const height = parseInt(rootEl?.getAttribute("data-height") ?? "", 10);
|
||
if (width > 0 && height > 0) return { width, height };
|
||
} catch {
|
||
// Unreadable / unparseable composition — fall through to `undefined`.
|
||
}
|
||
return undefined;
|
||
}
|
||
|
||
/**
|
||
* Render pre-flight: return an actionable message when the chosen
|
||
* `outputResolution` preset is incompatible with the composition's
|
||
* orientation/aspect ratio, or with the alpha/HDR mode — or `undefined` when
|
||
* the combination is fine (or can't be determined statically).
|
||
*
|
||
* Extracted (and exported) so the CLI wiring around `process.exit` stays a
|
||
* thin adapter and the branch logic is unit-testable. See render-reliability
|
||
* workstream P1-3.
|
||
*/
|
||
export async function checkRenderResolutionPreflight(
|
||
compositionHtml: string,
|
||
outputResolution: CanvasResolution | undefined,
|
||
modes: { alphaRequested: boolean; hdrRequested: boolean; aspectAgnostic?: boolean },
|
||
): Promise<{ message: string; kind: OutputResolutionIssueKind } | undefined> {
|
||
if (!outputResolution) return undefined;
|
||
const dims = await readCompositionDimensions(compositionHtml);
|
||
// Couldn't determine the composition's actual dimensions — defer to the
|
||
// pipeline's own defense-in-depth check rather than guess.
|
||
if (!dims) return undefined;
|
||
const effective =
|
||
modes.aspectAgnostic === true
|
||
? (suggestMatchingPreset(dims.width, dims.height, outputResolution) ?? outputResolution)
|
||
: outputResolution;
|
||
const compat = checkOutputResolutionCompatibility({
|
||
compositionWidth: dims.width,
|
||
compositionHeight: dims.height,
|
||
outputResolution: effective,
|
||
alphaRequested: modes.alphaRequested,
|
||
hdrRequested: modes.hdrRequested,
|
||
});
|
||
// Narrow to the incompatible case; `message`/`kind` are always set there.
|
||
if (compat.ok || !compat.message || !compat.kind) return undefined;
|
||
return { message: compat.message, kind: compat.kind };
|
||
}
|
||
|
||
const DOCKER_IMAGE_PREFIX = "hyperframes-renderer";
|
||
const BEGIN_FRAME_FIRST_FRAME_DEADLINE_MS = 20_000;
|
||
|
||
function dockerImageTag(version: string): string {
|
||
return `${DOCKER_IMAGE_PREFIX}:${version}`;
|
||
}
|
||
|
||
function resolveDockerfilePath(): string {
|
||
// Built CLI: dist/docker/Dockerfile.render
|
||
const builtPath = resolve(__dirname, "docker", "Dockerfile.render");
|
||
// Dev mode: src/docker/Dockerfile.render
|
||
const devPath = resolve(__dirname, "..", "src", "docker", "Dockerfile.render");
|
||
for (const p of [builtPath, devPath]) {
|
||
try {
|
||
statSync(p);
|
||
return p;
|
||
} catch {
|
||
continue;
|
||
}
|
||
}
|
||
throw new Error("Dockerfile.render not found — CLI package may be corrupted");
|
||
}
|
||
|
||
function dockerImageExists(tag: string): boolean {
|
||
try {
|
||
execFileSync("docker", ["image", "inspect", tag], { stdio: "pipe", timeout: 10_000 });
|
||
return true;
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
function dockerImageTagForPlatform(version: string, platform: string): string {
|
||
// Suffix the tag with the arch so amd64 and arm64 images of the same
|
||
// hyperframes version coexist in the local cache (a developer who flips
|
||
// between hosts shouldn't have to rebuild).
|
||
const archSuffix = platform === "linux/arm64" ? "-arm64" : "";
|
||
return `${dockerImageTag(version)}${archSuffix}`;
|
||
}
|
||
|
||
function ensureDockerImage(version: string, platform: string, quiet: boolean): string {
|
||
const tag = dockerImageTagForPlatform(version, platform);
|
||
|
||
if (dockerImageExists(tag)) {
|
||
if (!quiet) console.log(c.dim(` Docker image: ${tag} (cached)`));
|
||
return tag;
|
||
}
|
||
|
||
if (!quiet) console.log(c.dim(` Building Docker image: ${tag} (${platform})...`));
|
||
|
||
const dockerfilePath = resolveDockerfilePath();
|
||
|
||
// Copy Dockerfile to a temp build context so docker build has a clean context.
|
||
// mkdtempSync (not a `Date.now()`-derived name) so the path is unpredictable
|
||
// and created 0o700 by the kernel — a guessable temp dir in a world-writable
|
||
// tmpdir is pre-creatable by another local user, who could then swap in their
|
||
// own Dockerfile or symlink the path (CodeQL js/insecure-temporary-file).
|
||
const tmpDir = mkdtempSync(join(tmpdir(), "hyperframes-docker-"));
|
||
writeFileSync(join(tmpDir, "Dockerfile"), readFileSync(dockerfilePath));
|
||
|
||
// Platform is now derived from the host arch (see resolveDockerPlatform).
|
||
// Apple Silicon and other arm64 hosts get a native linux/arm64 build; the
|
||
// Dockerfile installs a pinned arm64 chrome-headless-shell from Playwright
|
||
// (chrome-for-testing publishes no linux-arm64 build).
|
||
//
|
||
// TARGETARCH is passed explicitly rather than relying on BuildKit's
|
||
// automatic platform args because the legacy builder (and some BuildKit
|
||
// configurations like colima 0.6.x) leaves it unset, which would defeat
|
||
// the arch conditional in the Dockerfile.
|
||
const targetArch = platform === "linux/arm64" ? "arm64" : "amd64";
|
||
try {
|
||
execFileSync(
|
||
"docker",
|
||
[
|
||
"build",
|
||
"--platform",
|
||
platform,
|
||
"--build-arg",
|
||
`HYPERFRAMES_VERSION=${version}`,
|
||
"--build-arg",
|
||
`TARGETARCH=${targetArch}`,
|
||
"-t",
|
||
tag,
|
||
tmpDir,
|
||
],
|
||
{ stdio: quiet ? "pipe" : "inherit", timeout: DOCKER_BUILD_TIMEOUT_MINUTES * 60_000 },
|
||
);
|
||
} catch (error: unknown) {
|
||
const message = normalizeErrorMessage(error);
|
||
throw new Error(`Failed to build Docker image: ${message}`, { cause: error });
|
||
} finally {
|
||
rmSync(tmpDir, { recursive: true, force: true });
|
||
}
|
||
|
||
if (!quiet) console.log(c.dim(` Docker image: ${tag} (built)`));
|
||
return tag;
|
||
}
|
||
|
||
/**
|
||
* Resolves the Docker `--platform` for this host and enforces the constraints
|
||
* that come with it — keeping that policy out of `renderDocker` so the
|
||
* orchestrator stays focused on build/run wiring. May terminate the process
|
||
* via errorBox on unrecoverable mismatches (e.g. --gpu on arm64).
|
||
*/
|
||
function resolveDockerHostPlatform(options: RenderOptions): string {
|
||
const platform = resolveDockerPlatform();
|
||
|
||
// Docker Desktop on Apple Silicon (and colima with VZ) doesn't implement
|
||
// the `--gpus` host-passthrough flag, so requesting `--gpu` on a linux/arm64
|
||
// container fails at `docker run` with an opaque device-driver error. Catch
|
||
// it early with actionable guidance.
|
||
if (options.gpu && platform === "linux/arm64") {
|
||
errorBox(
|
||
"--gpu is not supported with --docker on arm64 hosts",
|
||
"Docker Desktop/colima on Apple Silicon doesn't expose --gpus host passthrough to linux/arm64 containers.",
|
||
"Drop --gpu, or run a native (non-Docker) render on this host, or set HYPERFRAMES_DOCKER_PLATFORM=linux/amd64 if you need GPU encoding (slow under qemu but works).",
|
||
);
|
||
failCommand();
|
||
}
|
||
|
||
if (!options.quiet && platform === "linux/arm64") {
|
||
// The arm64 image uses Playwright's pinned linux-arm64 chrome-headless-shell
|
||
// (chrome-for-testing has no arm64 build). It's a different Chromium build
|
||
// than amd64's chrome-for-testing binary, so output isn't byte-identical to
|
||
// an amd64 golden baseline — fine for end-user output. Set
|
||
// HYPERFRAMES_DOCKER_PLATFORM=linux/amd64 to force parity (qemu-emulated,
|
||
// slower).
|
||
console.log(
|
||
c.dim(
|
||
" Host is arm64 — using linux/arm64 image with Playwright's " +
|
||
"chrome-headless-shell (output won't be byte-identical to amd64 " +
|
||
"renders; set HYPERFRAMES_DOCKER_PLATFORM=linux/amd64 to force parity).",
|
||
),
|
||
);
|
||
}
|
||
|
||
return platform;
|
||
}
|
||
|
||
async function registerRenderOutputOrWarn(projectDir: string, outputPath: string): Promise<void> {
|
||
await registerRenderOutput(projectDir, outputPath).catch((error: unknown) =>
|
||
console.warn(`Render output was not registered: ${normalizeErrorMessage(error)}`),
|
||
);
|
||
}
|
||
|
||
// Inherited minor finding (CRAP 37.1, cyclomatic 11). This PR only added
|
||
// `pageNavigationTimeoutMs` to the options forwarded to `buildDockerRunArgs`.
|
||
// fallow-ignore-next-line complexity
|
||
async function renderDocker(
|
||
projectDir: string,
|
||
outputPath: string,
|
||
options: RenderOptions,
|
||
): Promise<SingleRenderResult> {
|
||
await registerRenderOutputOrWarn(projectDir, outputPath);
|
||
const capture = await captureArtifactRevision(projectDir).catch(() => undefined);
|
||
const startTime = Date.now();
|
||
const cpu = startRenderCpuSampler();
|
||
|
||
// Dev mode (tsx/ts-node) uses "latest" since the local version isn't on npm
|
||
const dockerVersion = isDevMode() ? "latest" : VERSION;
|
||
if (!options.quiet && isDevMode()) {
|
||
console.log(c.dim(" Dev mode: using hyperframes@latest in Docker image"));
|
||
}
|
||
|
||
const platform = resolveDockerHostPlatform(options);
|
||
|
||
let imageTag: string;
|
||
try {
|
||
imageTag = ensureDockerImage(dockerVersion, platform, options.quiet);
|
||
} catch (error: unknown) {
|
||
cpu.stop();
|
||
const failure = describeDockerBuildFailure(error);
|
||
errorBox(failure.title, failure.message, failure.hint);
|
||
failCommand();
|
||
}
|
||
|
||
const outputDir = dirname(outputPath);
|
||
const outputFilename = basename(outputPath);
|
||
const dockerArgs = buildDockerRunArgs({
|
||
imageTag,
|
||
projectDir: resolve(projectDir),
|
||
outputDir: resolve(outputDir),
|
||
outputFilename,
|
||
platform,
|
||
hostStdoutIsTty: process.stdout.isTTY === true,
|
||
options: {
|
||
fps: options.fps,
|
||
quality: options.quality,
|
||
format: options.format,
|
||
gifLoop: options.gifLoop,
|
||
hlsSegmentSeconds: options.hlsSegmentSeconds,
|
||
workers: options.workers,
|
||
gpu: options.gpu,
|
||
browserGpu: options.browserGpuMode === "hardware",
|
||
hdrMode: options.hdrMode,
|
||
crf: options.crf,
|
||
vp9CpuUsed: options.vp9CpuUsed,
|
||
videoBitrate: options.videoBitrate,
|
||
keyframeIntervalSeconds: options.keyframeIntervalSeconds,
|
||
range: options.range,
|
||
proresProfile: options.proresProfile,
|
||
maxBitrate: options.maxBitrate,
|
||
bufferSize: options.bufferSize,
|
||
videoFrameFormat: options.videoFrameFormat,
|
||
chromaSubsampling: options.chromaSubsampling,
|
||
pageMotionBlur: options.pageMotionBlur,
|
||
quiet: options.quiet,
|
||
variables: options.variables,
|
||
entryFile: options.entryFile,
|
||
outputResolution: options.outputResolutionRaw ?? options.outputResolution,
|
||
pageSideCompositing: options.pageSideCompositing,
|
||
debug: options.debug,
|
||
bestEffort: options.bestEffort,
|
||
experimentalFastCapture: options.experimentalFastCapture,
|
||
pageNavigationTimeoutMs: options.pageNavigationTimeoutMs,
|
||
protocolTimeoutMs: options.protocolTimeout,
|
||
playerReadyTimeoutMs: options.playerReadyTimeout,
|
||
},
|
||
});
|
||
|
||
if (!options.quiet) {
|
||
console.log(c.dim(" Running render in Docker container..."));
|
||
console.log("");
|
||
}
|
||
|
||
try {
|
||
await new Promise<void>((resolvePromise, reject) => {
|
||
const stderrTail = createStderrTail();
|
||
// stderr is piped so the failure can name its cause; it is still echoed live.
|
||
const child = spawn("docker", dockerArgs, {
|
||
stdio: options.quiet ? ["pipe", "ignore", "pipe"] : ["inherit", "inherit", "pipe"],
|
||
});
|
||
child.stderr?.on("data", (chunk: Buffer) => {
|
||
process.stderr.write(chunk);
|
||
stderrTail.push(chunk.toString());
|
||
});
|
||
child.on("close", (code) => {
|
||
if (code === 0) resolvePromise();
|
||
else reject(new DockerRenderExitError(code, stderrTail.tail()));
|
||
});
|
||
child.on("error", (err) => reject(err));
|
||
});
|
||
} catch (error: unknown) {
|
||
handleRenderError(error, options, startTime, cpu, true, "Check Docker is running: docker info");
|
||
}
|
||
|
||
const elapsed = Date.now() - startTime;
|
||
const cpuUsage = cpu.stop();
|
||
|
||
// Docker child exited 0 → the containerized producer already validated
|
||
// AND committed the artifact. Mirror renderLocal's post-success guarantee
|
||
// so any late throw here (telemetry flush, feedback prompt) cannot flip
|
||
// the exit code.
|
||
if (!options.embedded) markRenderSucceeded();
|
||
await runPostRenderStepAsync("recordRenderSuccess", () =>
|
||
recordRenderSuccess(projectDir, outputPath, "completed", capture).then(() => {}),
|
||
);
|
||
|
||
// Track metrics (no job object available from Docker — use a minimal stub)
|
||
runPostRenderStep("trackRenderComplete", () =>
|
||
trackRenderComplete({
|
||
durationMs: elapsed,
|
||
fps: fpsToNumber(options.fps),
|
||
quality: options.quality,
|
||
workers: options.workers,
|
||
docker: true,
|
||
gpu: options.gpu,
|
||
authoringSkill: options.authoringSkill,
|
||
authoringSkillSource: options.authoringSkillSource,
|
||
authoringSkillInvalid: options.authoringSkillInvalid,
|
||
hfEnvOverrides: options.hfEnvOverrides,
|
||
catalogUsage: options.catalogUsage,
|
||
...renderOutputShapeTelemetryPayload(options),
|
||
...renderEnvironmentTelemetryPayload(options),
|
||
...getMemorySnapshot(),
|
||
...cpuUsage,
|
||
}),
|
||
);
|
||
|
||
// ponytail: Docker runs the producer in a child process, so no perfSummary is
|
||
// threaded back here; the summary shows render time only (never a wrong video
|
||
// length). Probe the output with ffprobe if a duration figure is wanted here.
|
||
runPostRenderStep("printRenderComplete", () =>
|
||
printRenderComplete({
|
||
outputPath,
|
||
projectDir,
|
||
desktopHint: wantsDesktopHint(options),
|
||
elapsedMs: elapsed,
|
||
quiet: options.quiet,
|
||
format: options.format,
|
||
}),
|
||
);
|
||
runPostRenderStep("warnIfWebmAlphaDropped", () =>
|
||
warnIfWebmAlphaDropped(outputPath, options.format, options.quiet),
|
||
);
|
||
if (options.exitAfterComplete && !options.embedded) scheduleCliExit();
|
||
return { renderTimeMs: elapsed };
|
||
}
|
||
|
||
export async function renderLocal(
|
||
projectDir: string,
|
||
outputPath: string,
|
||
options: RenderOptions,
|
||
commandCancellation?: ReturnType<typeof createRenderCancellationScope>,
|
||
): Promise<SingleRenderResult> {
|
||
const cancellation = commandCancellation ?? createRenderCancellationScope();
|
||
try {
|
||
return await executeLocalRender(projectDir, outputPath, options, cancellation);
|
||
} finally {
|
||
if (!commandCancellation) cancellation.dispose();
|
||
}
|
||
}
|
||
|
||
// fallow-ignore-next-line complexity
|
||
async function executeLocalRender(
|
||
projectDir: string,
|
||
outputPath: string,
|
||
options: RenderOptions,
|
||
cancellation: ReturnType<typeof createRenderCancellationScope>,
|
||
): Promise<SingleRenderResult> {
|
||
await registerRenderOutputOrWarn(projectDir, outputPath);
|
||
const capture = await captureArtifactRevision(projectDir).catch(() => undefined);
|
||
cancellation.checkAncestors();
|
||
cancellation.signal.throwIfAborted();
|
||
let recoveredOrphanTrees = 0;
|
||
try {
|
||
recoveredOrphanTrees = await killOrphanedProcessesForRender(cancellation.signal);
|
||
} catch {
|
||
if (cancellation.signal.aborted) cancellation.signal.throwIfAborted();
|
||
}
|
||
cancellation.checkAncestors();
|
||
cancellation.signal.throwIfAborted();
|
||
if (recoveredOrphanTrees > 0 && !options.quiet) {
|
||
console.warn(
|
||
c.warn(
|
||
` Recovered ${recoveredOrphanTrees} orphaned browser process ${recoveredOrphanTrees === 1 ? "tree" : "trees"} from an interrupted render.`,
|
||
),
|
||
);
|
||
}
|
||
|
||
const preflight = await runEnvironmentChecks({
|
||
projectDir,
|
||
diskPaths: [tmpdir(), dirname(outputPath)],
|
||
browserPath: options.browserPath,
|
||
includeBrowser: true,
|
||
includeDisk: true,
|
||
includeWindowsUnc: true,
|
||
signal: cancellation.signal,
|
||
});
|
||
options = {
|
||
...options,
|
||
ffmpegVersionMajor: preflight.ffmpegVersionMajor,
|
||
browserVersionMajor: preflight.browserVersionMajor,
|
||
browserInstall: preflight.browserInstall,
|
||
};
|
||
cancellation.checkAncestors();
|
||
cancellation.signal.throwIfAborted();
|
||
const failedChecks = preflight.outcomes.filter((outcome) => !outcome.ok);
|
||
if (failedChecks.length > 0) {
|
||
for (const check of failedChecks) {
|
||
errorBox(check.title ?? `${check.name} check failed`, check.detail, check.hint);
|
||
}
|
||
failCommand();
|
||
}
|
||
if (!options.quiet) {
|
||
for (const outcome of preflight.outcomes) {
|
||
if (outcome.level === "warn") {
|
||
console.warn(c.warn(` ${outcome.name}: ${outcome.detail}`));
|
||
if (outcome.hint) console.warn(c.dim(` ${outcome.hint}`));
|
||
}
|
||
}
|
||
}
|
||
|
||
if (preflight.ffmpegPath) process.env.HYPERFRAMES_FFMPEG_PATH = preflight.ffmpegPath;
|
||
if (preflight.ffprobePath) process.env.HYPERFRAMES_FFPROBE_PATH = preflight.ffprobePath;
|
||
if (preflight.browser?.executablePath && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
|
||
process.env.PRODUCER_HEADLESS_SHELL_PATH = preflight.browser.executablePath;
|
||
}
|
||
|
||
// HLS shares the H.264 encode path but cannot take the GPU fallback below:
|
||
// its fixed-length segments need the software encoder's forced-keyframe lock.
|
||
const isHls = options.format === "hls";
|
||
if ((options.format === "mp4" || isHls) && preflight.ffmpegPath) {
|
||
const gpuRequested = options.gpu && !isHls;
|
||
let encoderMode: H264EncoderMode = gpuRequested ? "gpu" : "software";
|
||
try {
|
||
encoderMode = await detectH264EncoderModeForRender(
|
||
preflight.ffmpegPath,
|
||
gpuRequested,
|
||
cancellation.signal,
|
||
);
|
||
} catch (error) {
|
||
if (cancellation.signal.aborted) cancellation.signal.throwIfAborted();
|
||
// HDR MP4 uses HEVC; auto mode cannot resolve the codec until sources are
|
||
// inspected. Forced SDR, HLS, or no libx265 either: nothing here can encode.
|
||
if (
|
||
error instanceof H264EncoderUnavailableError &&
|
||
(options.hdrMode === "force-sdr" || isHls || !error.hevcEncoderAvailable)
|
||
) {
|
||
errorBox(
|
||
`${isHls ? "HLS" : "MP4"} H.264 encoder unavailable`,
|
||
error.message,
|
||
`Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()}), or point ${FFMPEG_PATH_ENV} at one` +
|
||
(isHls
|
||
? "."
|
||
: ", or render WebM instead: hyperframes render --format webm --output output.webm"),
|
||
);
|
||
failCommand();
|
||
}
|
||
// Capability probing is advisory. Let the real encode surface the
|
||
// authoritative FFmpeg error instead of failing here with a bare stack.
|
||
if (!options.quiet) {
|
||
const detail = error instanceof Error ? error.message : String(error);
|
||
console.warn(c.warn(` Unable to probe H.264 encoder capabilities: ${detail}`));
|
||
}
|
||
}
|
||
if (encoderMode === "gpu" && isHls) {
|
||
errorBox(
|
||
"HLS H.264 encoder unavailable",
|
||
"FFmpeg does not include libx264, and HLS cannot fall back to VideoToolbox: fixed-length segments require the software encoder's forced-keyframe lock.",
|
||
`Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()}).`,
|
||
);
|
||
failCommand();
|
||
}
|
||
if (encoderMode === "gpu" && !gpuRequested) {
|
||
console.warn(
|
||
c.warn(" FFmpeg does not include libx264; falling back to GPU H.264 encoding."),
|
||
);
|
||
options = { ...options, gpu: true };
|
||
}
|
||
if (encoderMode === "software" && gpuRequested && !options.quiet) {
|
||
console.warn(c.warn(" No GPU encoder works on this machine; encoding with libx264."));
|
||
}
|
||
}
|
||
|
||
cancellation.checkAncestors();
|
||
cancellation.signal.throwIfAborted();
|
||
const gsapVendorDir = resolveGsapVendorDir();
|
||
if (gsapVendorDir && !process.env.HYPERFRAMES_GSAP_VENDOR_DIR) {
|
||
process.env.HYPERFRAMES_GSAP_VENDOR_DIR = gsapVendorDir;
|
||
}
|
||
const producer = await loadProducer();
|
||
const allowOutsideProjectAssets = outsideAssetsAllowed(projectDir, options.entryFile, (line) =>
|
||
console.warn(c.warn(` ${line}`)),
|
||
);
|
||
const deParallelRouterActive =
|
||
options.manageDeParallelRouterBreaker === true
|
||
? applyDeParallelRouterCircuitBreaker(options.quiet)
|
||
: // Not managing the breaker: the router still runs (producer default),
|
||
// we just don't enforce or record the per-install trip.
|
||
false;
|
||
|
||
const startTime = Date.now();
|
||
const cpu = startRenderCpuSampler();
|
||
const logger = createRenderTelemetryLogger(
|
||
producer.createConsoleLogger?.(options.debug ? "debug" : options.quiet ? "warn" : "info") ??
|
||
createNoopProducerLogger(),
|
||
);
|
||
|
||
const engineConfig = producer.resolveConfig({
|
||
browserGpuMode: options.browserGpuMode ?? "software",
|
||
// Local auto opts out of the software-GPU screenshot clamp, and a BeginFrame that draws no first frame
|
||
// retries by screenshot. Docker and --no-browser-gpu request software; --resolution supersamples via screenshot.
|
||
...(options.browserGpuMode === "auto" &&
|
||
options.outputResolution == null &&
|
||
process.env.PRODUCER_FORCE_SCREENSHOT !== "true"
|
||
? {
|
||
forceScreenshot: false,
|
||
beginFrameFirstFrameDeadlineMs: BEGIN_FRAME_FIRST_FRAME_DEADLINE_MS,
|
||
}
|
||
: {}),
|
||
...(options.pageNavigationTimeoutMs != null
|
||
? { pageNavigationTimeout: options.pageNavigationTimeoutMs }
|
||
: {}),
|
||
...(options.protocolTimeout != null && { protocolTimeout: options.protocolTimeout }),
|
||
...(options.playerReadyTimeout != null && { playerReadyTimeout: options.playerReadyTimeout }),
|
||
...(options.vp9CpuUsed != null ? { vp9CpuUsed: options.vp9CpuUsed } : {}),
|
||
});
|
||
const request = producer.createRenderRequest({
|
||
projectDir,
|
||
outputPath,
|
||
engineConfig,
|
||
options: {
|
||
fps: options.fps,
|
||
quality: options.quality,
|
||
format: options.format,
|
||
gifLoop: options.gifLoop,
|
||
hlsSegmentSeconds: options.hlsSegmentSeconds,
|
||
workers: options.workers,
|
||
useGpu: options.gpu,
|
||
hdrMode: options.hdrMode,
|
||
crf: options.crf,
|
||
videoBitrate: options.videoBitrate,
|
||
keyframeIntervalSeconds: options.keyframeIntervalSeconds,
|
||
proresProfile: options.proresProfile,
|
||
maxBitrate: options.maxBitrate,
|
||
bufferSize: options.bufferSize,
|
||
videoFrameFormat: options.videoFrameFormat,
|
||
chromaSubsampling: options.chromaSubsampling,
|
||
pageMotionBlur: options.pageMotionBlur,
|
||
variables: options.variables,
|
||
entryFile: options.entryFile,
|
||
outputResolution: options.outputResolution,
|
||
outputResolutionAspectAgnostic: options.outputResolutionAspectAgnostic,
|
||
debug: options.debug,
|
||
resumeSegments: options.resumeSegments,
|
||
keepSegments: options.keepSegments,
|
||
strictness: options.bestEffort === false ? "strict" : "best-effort",
|
||
// plan() takes the film's own size; these only satisfy the request shape.
|
||
distributed: options.range ? { width: 1920, height: 1080 } : undefined,
|
||
},
|
||
});
|
||
if (options.range) {
|
||
return renderRange({
|
||
producer,
|
||
request,
|
||
range: options.range,
|
||
projectDir,
|
||
outputPath,
|
||
options,
|
||
logger,
|
||
startTime,
|
||
cpu,
|
||
signal: cancellation.signal,
|
||
allowOutsideProjectAssets,
|
||
});
|
||
}
|
||
const job = producer.createRenderJob(
|
||
producer.renderConfigFromRequest(request, { logger, allowOutsideProjectAssets }),
|
||
);
|
||
|
||
const onProgress = options.quiet
|
||
? undefined
|
||
: (progressJob: Pick<RenderJob, "progress" | "stageProgress">, message: string) => {
|
||
renderProgress(progressJob.progress, message);
|
||
renderMachineProgress(progressJob.progress, progressJob.stageProgress);
|
||
};
|
||
|
||
try {
|
||
cancellation.checkAncestors();
|
||
await producer.executeRenderJob(
|
||
job,
|
||
projectDir,
|
||
outputPath,
|
||
onProgress,
|
||
cancellation.signal,
|
||
cancellation.checkAncestors,
|
||
);
|
||
} catch (error: unknown) {
|
||
maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet);
|
||
// The render container sets `ENV CONTAINER=true`; suggesting `--docker`
|
||
// from inside it is a misdirection (heygen-com/hyperframes#3370).
|
||
const inContainer = process.env.CONTAINER === "true";
|
||
handleRenderError(
|
||
error,
|
||
options,
|
||
startTime,
|
||
cpu,
|
||
false,
|
||
inContainer ? "" : "Try --docker for containerized rendering",
|
||
job.failedStage,
|
||
job,
|
||
);
|
||
}
|
||
|
||
// Render resolved without throwing → producer's `artifact validated`
|
||
// checkpoint fired AND the artifact was committed to disk. From this
|
||
// point on, ANY thrown teardown error must not be allowed to override
|
||
// the exit code. Field signal ts=1784169760 / ts=1784171150 / ts=1784172467
|
||
// (win32/x64, CLI 0.7.58): valid MP4 on disk, exited 1 with no error print.
|
||
if (!options.embedded) markRenderSucceeded();
|
||
await runPostRenderStepAsync("recordRenderSuccess", () =>
|
||
recordRenderSuccess(
|
||
projectDir,
|
||
outputPath,
|
||
job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed",
|
||
capture,
|
||
).then(() => {}),
|
||
);
|
||
|
||
maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet, true);
|
||
const elapsed = Date.now() - startTime;
|
||
const cpuUsage = cpu.stop();
|
||
if (job.outcome === "completed_with_warnings") {
|
||
for (const warning of job.warnings) {
|
||
console.warn(c.warn(` [${warning.code}] ${warning.message}`));
|
||
}
|
||
}
|
||
const audioLowered = audioLoweredWarning(job.audioLoweredDb);
|
||
if (audioLowered) console.warn(c.warn(` [${audioLowered.code}] ${audioLowered.message}`));
|
||
runPostRenderStep("trackRenderMetrics", () =>
|
||
trackRenderMetrics(job, elapsed, options, false, cpuUsage),
|
||
);
|
||
runPostRenderStep("printRenderComplete", () =>
|
||
printRenderComplete({
|
||
outputPath,
|
||
projectDir,
|
||
desktopHint: wantsDesktopHint(options),
|
||
elapsedMs: elapsed,
|
||
quiet: options.quiet,
|
||
format: options.format,
|
||
perf: job.perfSummary,
|
||
requestedGpuMode: options.browserGpuMode,
|
||
}),
|
||
);
|
||
runPostRenderStep("warnIfWebmAlphaDropped", () =>
|
||
warnIfWebmAlphaDropped(outputPath, options.format, options.quiet),
|
||
);
|
||
if (!options.skipFeedback) {
|
||
await runPostRenderStepAsync("maybePromptRenderFeedback", () =>
|
||
maybePromptRenderFeedback({
|
||
renderDurationMs: elapsed,
|
||
quiet: options.quiet,
|
||
}),
|
||
);
|
||
}
|
||
if (options.exitAfterComplete && !options.embedded) scheduleCliExit();
|
||
const durationMs = job.perfSummary
|
||
? Math.round(job.perfSummary.compositionDurationSeconds * 1000)
|
||
: undefined;
|
||
const outcome =
|
||
job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed";
|
||
return {
|
||
...producer.referenceBackgroundResult(job[producer.REFERENCE_BACKGROUND_FIELD]),
|
||
motionBlur: job.perfSummary?.motionBlur,
|
||
renderTimeMs: elapsed,
|
||
durationMs,
|
||
outcome,
|
||
warnings: [
|
||
...job.warnings.map((warning) => ({ code: warning.code, message: warning.message })),
|
||
...(audioLowered ? [audioLowered] : []),
|
||
],
|
||
};
|
||
}
|
||
|
||
async function renderRange(input: {
|
||
producer: Awaited<ReturnType<typeof loadProducer>>;
|
||
request: ReturnType<Awaited<ReturnType<typeof loadProducer>>["createRenderRequest"]>;
|
||
range: RenderRange;
|
||
projectDir: string;
|
||
outputPath: string;
|
||
options: RenderOptions;
|
||
logger: ProducerLogger;
|
||
startTime: number;
|
||
cpu: RenderCpuSampler;
|
||
signal: AbortSignal;
|
||
allowOutsideProjectAssets: boolean;
|
||
}): Promise<SingleRenderResult> {
|
||
const { producer, options } = input;
|
||
let framesEncoded = 0;
|
||
let reference = producer.referenceBackgroundResult(undefined);
|
||
try {
|
||
const config = producer.distributedConfigFromRequest(input.request, {
|
||
logger: input.logger,
|
||
abortSignal: input.signal,
|
||
});
|
||
const spanResult = await producer.renderSpan(
|
||
input.projectDir,
|
||
config,
|
||
input.range,
|
||
input.outputPath,
|
||
{ allowOutsideProjectAssets: input.allowOutsideProjectAssets },
|
||
);
|
||
framesEncoded = spanResult.framesEncoded;
|
||
reference = producer.referenceBackgroundResult(spanResult[producer.REFERENCE_BACKGROUND_FIELD]);
|
||
} catch (error: unknown) {
|
||
handleRenderError(error, options, input.startTime, input.cpu, false, "");
|
||
}
|
||
if (!options.embedded) markRenderSucceeded();
|
||
const elapsed = Date.now() - input.startTime;
|
||
input.cpu.stop();
|
||
printRenderComplete({
|
||
outputPath: input.outputPath,
|
||
projectDir: input.projectDir,
|
||
desktopHint: wantsDesktopHint(options),
|
||
elapsedMs: elapsed,
|
||
quiet: options.quiet,
|
||
format: options.format,
|
||
});
|
||
if (options.exitAfterComplete && !options.embedded) scheduleCliExit();
|
||
return {
|
||
renderTimeMs: elapsed,
|
||
...reference,
|
||
durationMs: Math.round((framesEncoded / fpsToNumber(options.fps)) * 1000),
|
||
outcome: "completed",
|
||
warnings: [],
|
||
};
|
||
}
|
||
|
||
function getMemorySnapshot() {
|
||
return {
|
||
peakMemoryMb: bytesToMb(process.memoryUsage.rss()),
|
||
memoryFreeMb: bytesToMb(freemem()),
|
||
};
|
||
}
|
||
|
||
/** Output-shape request facts, resolved before the pipeline starts (survives a pre-perfSummary render_error). */
|
||
function renderOutputShapeTelemetryPayload(
|
||
options: RenderOptions,
|
||
): RenderOutputShapeTelemetryPayload {
|
||
return {
|
||
outputResolutionPreset: options.outputResolution,
|
||
outputFormat: options.format,
|
||
hdrMode: options.hdrMode,
|
||
videoFrameFormat: options.videoFrameFormat,
|
||
gifFpsCapped: options.gifFpsCapped,
|
||
};
|
||
}
|
||
|
||
/** Toolchain facts from local preflight; undefined on Docker renders (the container runs its own). */
|
||
function renderEnvironmentTelemetryPayload(
|
||
options: RenderOptions,
|
||
): RenderEnvironmentTelemetryPayload {
|
||
return {
|
||
ffmpegVersionMajor: options.ffmpegVersionMajor,
|
||
browserVersionMajor: options.browserVersionMajor,
|
||
browserInstall: options.browserInstall,
|
||
};
|
||
}
|
||
|
||
function metaString(meta: Record<string, unknown> | undefined, key: string): string | undefined {
|
||
const value = meta?.[key];
|
||
return typeof value === "string" ? value : undefined;
|
||
}
|
||
|
||
function metaNumber(meta: Record<string, unknown> | undefined, key: string): number | undefined {
|
||
const value = meta?.[key];
|
||
return typeof value === "number" && Number.isFinite(value) ? value : undefined;
|
||
}
|
||
|
||
function metaBoolean(meta: Record<string, unknown> | undefined, key: string): boolean | undefined {
|
||
const value = meta?.[key];
|
||
return typeof value === "boolean" ? value : undefined;
|
||
}
|
||
|
||
function trackRenderTraceFromLog(message: string, meta: Record<string, unknown> | undefined): void {
|
||
if (message !== "[Render:trace]") return;
|
||
const status = metaString(meta, "status");
|
||
if (status !== "start" && status !== "end" && status !== "checkpoint" && status !== "error") {
|
||
return;
|
||
}
|
||
trackRenderObservation({
|
||
source: "cli",
|
||
renderJobId: metaString(meta, "renderJobId"),
|
||
phase: metaString(meta, "phase"),
|
||
status,
|
||
compositionHash: metaString(meta, "compositionHash"),
|
||
elapsedMs: metaNumber(meta, "elapsedMs"),
|
||
durationMs: metaNumber(meta, "durationMs"),
|
||
message: metaString(meta, "message"),
|
||
workerCount: metaNumber(meta, "workerCount"),
|
||
forceScreenshot: metaBoolean(meta, "forceScreenshot"),
|
||
useStreamingEncode: metaBoolean(meta, "useStreamingEncode"),
|
||
useLayeredComposite: metaBoolean(meta, "useLayeredComposite"),
|
||
usePageSideCompositing: metaBoolean(meta, "usePageSideCompositing"),
|
||
hasHdrContent: metaBoolean(meta, "hasHdrContent"),
|
||
captureMode: metaString(meta, "captureMode"),
|
||
captureOperation: metaString(meta, "captureOperation"),
|
||
framesCompleted: metaNumber(meta, "framesCompleted"),
|
||
totalFrames: metaNumber(meta, "totalFrames"),
|
||
heartbeatIndex: metaNumber(meta, "heartbeatIndex"),
|
||
stageElapsedMs: metaNumber(meta, "stageElapsedMs"),
|
||
videoCount: metaNumber(meta, "videoCount"),
|
||
extractedVideoCount: metaNumber(meta, "extractedVideoCount"),
|
||
totalFramesExtracted: metaNumber(meta, "totalFramesExtracted"),
|
||
maxFramesPerVideo: metaNumber(meta, "maxFramesPerVideo"),
|
||
avgFramesPerExtractedVideo: metaNumber(meta, "avgFramesPerExtractedVideo"),
|
||
vfrPreflightCount: metaNumber(meta, "vfrPreflightCount"),
|
||
vfrPreflightMs: metaNumber(meta, "vfrPreflightMs"),
|
||
cacheHits: metaNumber(meta, "cacheHits"),
|
||
cacheMisses: metaNumber(meta, "cacheMisses"),
|
||
});
|
||
}
|
||
|
||
function createRenderTelemetryLogger(base: ProducerLogger): ProducerLogger {
|
||
return {
|
||
error(message, meta) {
|
||
base.error(message, meta);
|
||
trackRenderTraceFromLog(message, meta);
|
||
},
|
||
warn(message, meta) {
|
||
base.warn(message, meta);
|
||
trackRenderTraceFromLog(message, meta);
|
||
},
|
||
info(message, meta) {
|
||
base.info(message, meta);
|
||
trackRenderTraceFromLog(message, meta);
|
||
},
|
||
debug(message, meta) {
|
||
base.debug(message, meta);
|
||
trackRenderTraceFromLog(message, meta);
|
||
},
|
||
isLevelEnabled(level) {
|
||
return base.isLevelEnabled?.(level) ?? true;
|
||
},
|
||
};
|
||
}
|
||
|
||
function createNoopProducerLogger(): ProducerLogger {
|
||
return {
|
||
error() {},
|
||
warn() {},
|
||
info() {},
|
||
debug() {},
|
||
isLevelEnabled() {
|
||
return true;
|
||
},
|
||
};
|
||
}
|
||
|
||
/**
|
||
* The 25-render exposure cap that bounded the old opt-in TRIAL is gone: the
|
||
* router is default-ON as of 2026-07-27, so "stop offering it after N
|
||
* renders" would mean switching a shipped default off behind the user's
|
||
* back. What survives is the half that was always safety rather than
|
||
* sampling — the per-install circuit breaker below, which latches the router
|
||
* off for good the first time a render has to fall back.
|
||
*/
|
||
|
||
/**
|
||
* The user set `HF_DE_PARALLEL_ROUTER` themselves (either polarity), latched
|
||
* once at first observation. Their choice wins over the circuit breaker in
|
||
* BOTH directions: we never overwrite an explicit opt-in with `"false"` on a
|
||
* fallback, and never overwrite an explicit opt-out either. Latched rather
|
||
* than re-read because the breaker itself writes the var — after the first
|
||
* write a live `process.env` read could no longer tell "the user set this"
|
||
* from "we set this" (the same distinction the old trial needed for
|
||
* `--batch` rows sharing one process).
|
||
*/
|
||
let deParallelRouterUserManaged = false;
|
||
let deParallelRouterUserManagedResolved = false;
|
||
|
||
/**
|
||
* In-process latch mirroring the persisted `deParallelRouterTrialFired`: set
|
||
* the moment the breaker trips, independent of whether persisting that to
|
||
* `~/.hyperframes/config.json` succeeds. `writeConfig` swallows all fs
|
||
* errors (by design — telemetry must never break the CLI), so on an
|
||
* unwritable config (root-owned file, disk full) the flag can never stick on
|
||
* disk; without this latch the router would re-enable and re-fail on every
|
||
* subsequent render in this process. Later processes re-arm — disk is the
|
||
* only cross-process channel — but each process now stops after at most one
|
||
* failure it couldn't record.
|
||
*/
|
||
let deParallelRouterBreakerTrippedThisProcess = false;
|
||
|
||
/**
|
||
* Test-only reset for the module-level trial state — a real CLI process
|
||
* only ever runs one `--batch` sequence, so this state never needs
|
||
* resetting outside a test process where many independent test cases share
|
||
* one imported module instance.
|
||
*/
|
||
export function __resetDeParallelRouterTrialStateForTests(): void {
|
||
deParallelRouterBreakerTrippedThisProcess = false;
|
||
deParallelRouterUserManaged = false;
|
||
deParallelRouterUserManagedResolved = false;
|
||
}
|
||
|
||
/**
|
||
* Put the router back: lift the latch from both stores, store `next` as the
|
||
* remaining breaker state, and undo the "false" this process wrote.
|
||
*/
|
||
function rearmDeParallelRouter(next: DeRouterBreaker | undefined): void {
|
||
releaseDeParallelRouterLatch();
|
||
const config = readConfigFresh();
|
||
config.deParallelRouterBreaker = next;
|
||
writeConfig(config);
|
||
deParallelRouterBreakerTrippedThisProcess = false;
|
||
if (!deParallelRouterUserManaged) delete process.env.HF_DE_PARALLEL_ROUTER;
|
||
}
|
||
|
||
/** Is the router held off for this render? A stale or record-less latch is lifted here. */
|
||
function routerHeldOff(config: HyperframesConfig): boolean {
|
||
if (deParallelRouterBreakerTrippedThisProcess) return true;
|
||
if (!config.deParallelRouterTrialFired) return false;
|
||
if (isRouterOff(config.deParallelRouterBreaker, VERSION)) return true;
|
||
rearmDeParallelRouter(forVersion(config.deParallelRouterBreaker, VERSION));
|
||
return false;
|
||
}
|
||
|
||
/** A render finished with the router held off: count it toward bringing the router back. */
|
||
function countCleanRenderWithRouterOff(): void {
|
||
if (!deParallelRouterBreakerTrippedThisProcess || deParallelRouterUserManaged) return;
|
||
const config = readConfigFresh();
|
||
// A trip that never reached disk (unwritable config) lasts for this process only.
|
||
if (config.deParallelRouterBreaker?.trip === undefined) return;
|
||
const next = afterCleanRender(config.deParallelRouterBreaker);
|
||
if (next?.trip === undefined) {
|
||
rearmDeParallelRouter(next);
|
||
return;
|
||
}
|
||
config.deParallelRouterBreaker = next;
|
||
writeConfig(config);
|
||
}
|
||
|
||
type DeFallback = Pick<
|
||
NonNullable<NonNullable<RenderJob["perfSummary"]>["drawElement"]>,
|
||
"fallbackReason" | "fallbackFrameIndex" | "fallbackFailedDb" | "fallbackThresholdDb"
|
||
>;
|
||
|
||
/** The rejected frame's detail: the perf summary on a finished render, the capture observability on a failed one. */
|
||
function fallbackOf(job: RenderJob): DeFallback {
|
||
const capture = job.errorDetails?.observability?.capture;
|
||
return (
|
||
job.perfSummary?.drawElement ?? {
|
||
fallbackReason: capture?.deFallbackReason,
|
||
fallbackFrameIndex: capture?.deFallbackFrameIndex,
|
||
fallbackFailedDb: capture?.deFallbackFailedDb,
|
||
fallbackThresholdDb: capture?.deFallbackThresholdDb,
|
||
}
|
||
);
|
||
}
|
||
|
||
function revertFrom(job: RenderJob, outcome: string, atRender: number): DeRouterRevert {
|
||
const fallback = fallbackOf(job);
|
||
return {
|
||
reason: fallback.fallbackReason ?? outcome,
|
||
frameIndex: fallback.fallbackFrameIndex,
|
||
failedDb: fallback.fallbackFailedDb,
|
||
thresholdDb: fallback.fallbackThresholdDb,
|
||
at: new Date().toISOString(),
|
||
version: VERSION,
|
||
atRender,
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Latch the router OFF for the rest of this process by writing an explicit
|
||
* `"false"`.
|
||
*
|
||
* Under the old default-OFF flag this deleted the var, because absent meant
|
||
* off. With the router default-ON, deleting means ON — the same call would
|
||
* silently RE-ENABLE the router on exactly the host that just failed
|
||
* (review finding). Writing the explicit value is what makes the breaker a
|
||
* breaker. No-op when the user set the var themselves: their choice wins in
|
||
* both directions.
|
||
*/
|
||
/**
|
||
* Mirror of the producer's `isDeParallelRouterEnabled`. Deliberately
|
||
* duplicated rather than imported: `@hyperframes/producer` is lazily loaded
|
||
* (`loadProducer()`) to keep CLI startup fast, and this runs on the startup
|
||
* path. Keep the two in sync — the producer copy is the source of truth.
|
||
*/
|
||
function userValueEnablesDeParallelRouter(): boolean {
|
||
const raw = process.env.HF_DE_PARALLEL_ROUTER?.trim().toLowerCase();
|
||
if (raw === undefined || raw === "") return true;
|
||
return !(raw === "false" || raw === "0" || raw === "off" || raw === "no");
|
||
}
|
||
|
||
function applyDeParallelRouterBreaker(): void {
|
||
if (deParallelRouterUserManaged) return;
|
||
process.env.HF_DE_PARALLEL_ROUTER = "false";
|
||
}
|
||
|
||
/**
|
||
* Apply this install's router circuit breaker before a render.
|
||
*
|
||
* The router is default-ON, so the normal path does NOTHING here — the
|
||
* producer's own default takes over. This exists for the one case that must
|
||
* survive a shipped default: an install that already had a render fall back
|
||
* stays off, permanently, across processes (the verdict is persisted to
|
||
* `~/.hyperframes/config.json`). See `maybeConsumeDeParallelRouterTrial` for
|
||
* what trips it.
|
||
*
|
||
* Returns whether the router is active for this render, so the caller knows
|
||
* to inspect the outcome afterward.
|
||
*/
|
||
function applyDeParallelRouterCircuitBreaker(quiet: boolean): boolean {
|
||
// Latch the user's own choice on first observation, BEFORE the breaker can
|
||
// write the var itself and make the two indistinguishable.
|
||
//
|
||
// Ownership uses the SAME normalization as the two parsers: a set-but-empty
|
||
// (or whitespace) value means "unset / default ON", so it is NOT a user
|
||
// choice and must stay breaker-managed. Treating any defined value as
|
||
// user-managed would let `HF_DE_PARALLEL_ROUTER=` route the render (empty
|
||
// parses as ON) while exempting that install from the breaker — it would
|
||
// keep retrying a failing router forever, losing exactly the first-fallback
|
||
// protection this PR exists to provide (review finding).
|
||
if (!deParallelRouterUserManagedResolved) {
|
||
deParallelRouterUserManaged = (process.env.HF_DE_PARALLEL_ROUTER ?? "").trim() !== "";
|
||
deParallelRouterUserManagedResolved = true;
|
||
}
|
||
if (deParallelRouterUserManaged) {
|
||
// Explicit choice, either polarity — report whether it enables the
|
||
// router so outcomes are still consumed, but never override it.
|
||
return userValueEnablesDeParallelRouter();
|
||
}
|
||
|
||
// The in-process latch decides once set — short-circuit before the disk
|
||
// read so post-trip batch rows don't pay a config read + parse per row for
|
||
// an answer module state already knows.
|
||
if (deParallelRouterBreakerTrippedThisProcess) {
|
||
applyDeParallelRouterBreaker();
|
||
return false;
|
||
}
|
||
// readConfigFresh, NOT readConfig: the cached read is process-lifetime, so
|
||
// another process persisting a trip mid-`--batch` would never be observed.
|
||
if (routerHeldOff(readConfigFresh())) {
|
||
deParallelRouterBreakerTrippedThisProcess = true;
|
||
applyDeParallelRouterBreaker();
|
||
if (!quiet) {
|
||
console.log(
|
||
c.dim(
|
||
" Parallel drawElement capture is off for this install after two failed frame " +
|
||
"checks; it returns with the next version or after 20 more renders. " +
|
||
"Re-enable now with HF_DE_PARALLEL_ROUTER=true.",
|
||
),
|
||
);
|
||
}
|
||
return false;
|
||
}
|
||
|
||
// Nothing left to gate: the router is a shipped default for every install,
|
||
// so leave the var unset and let the producer's default-ON apply. The
|
||
// breaker above is the only thing that turns it off, per install, and only
|
||
// after a real fallback. `HF_DE_PARALLEL_ROUTER=false` remains the user-
|
||
// facing kill switch.
|
||
//
|
||
// The `de-parallel-router` canary that used to sit here was removed with its
|
||
// registry entry (they had to go together — at >=100 the evaluator
|
||
// short-circuits ahead of the CI/seedless exclusions, so deleting only the
|
||
// entry would have flipped whatever still resolved false at deletion time).
|
||
//
|
||
// Two claims from the ramp's rationale were wrong, recorded so they are not
|
||
// reintroduced: "~17x jump in exposure onto <=4 CPUs / Docker" overstated
|
||
// the reach — Docker renders never use drawElement at all (0 of 4,281
|
||
// measured) and the router requires it, so no percentage ever exposed
|
||
// Docker. And "~11% of installs already route" was an OUTCOME (the share
|
||
// clearing eligibility and the old 25-render cap), not an exposure setting;
|
||
// read as a rollout knob it inverted the arithmetic, which is how gating at
|
||
// 5% came to CUT fleet exposure ~25x rather than ramp it.
|
||
return true;
|
||
}
|
||
|
||
/**
|
||
* The router outcome for this render, or undefined when the router never
|
||
* engaged. `perfSummary.drawElement.parallelRouter` is NEVER undefined on
|
||
* the success path — aggregateDrawElement (perfSummary.ts) defaults it to
|
||
* the string "none" for every render, whether or not drawElement/the router
|
||
* ever engaged. Normalizing "none" to undefined here is required, not
|
||
* optional: without it, ordinary renders below the router's own frame
|
||
* threshold (the common case) would tick the render-count backstop on every
|
||
* single render and trip DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS after 25
|
||
* completely unrelated renders that never touched the router (review
|
||
* finding).
|
||
*/
|
||
function resolveDeParallelRouterOutcome(job: RenderJob): string | undefined {
|
||
const outcome =
|
||
job.perfSummary?.drawElement?.parallelRouter ??
|
||
job.errorDetails?.observability?.capture.deParallelRouter;
|
||
return outcome === "none" ? undefined : outcome;
|
||
}
|
||
|
||
/**
|
||
* Persist `deParallelRouterTrialFired: true`, verifying against a fresh
|
||
* disk read that it actually stuck, and re-asserting if a concurrent
|
||
* writer's stale snapshot clobbered it. ONLY the fired flag is retried —
|
||
* re-asserting a boolean is idempotent, so retries can't corrupt anything,
|
||
* unlike the render counter (a re-applied increment double-counts the
|
||
* render when our write landed but a later concurrent write raced our
|
||
* verify read — review finding). Returns false as soon as `writeConfig`
|
||
* reports an fs failure (unwritable `~/.hyperframes` — retrying a failed
|
||
* write is pointless, so the retries are reserved for genuine concurrent
|
||
* clobbers, where the write landed but a racing writer's stale snapshot
|
||
* overwrote it — review finding).
|
||
*/
|
||
function persistDeParallelRouterTrialFired(): boolean {
|
||
const MAX_ATTEMPTS = 3;
|
||
let mirrored = false;
|
||
for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
|
||
const config = readConfigFresh();
|
||
// Both stores must carry the latch, not just config.json. Checking only
|
||
// the config let a run stop early after a failed mirror — and config.json
|
||
// is the copy a stale writer or a re-mint can erase, so the durable one
|
||
// is exactly the one that was missing. The read side merges install-state
|
||
// back in, so the two together are what make the trip survive.
|
||
if (config.deParallelRouterTrialFired && mirrored) return true;
|
||
config.deParallelRouterTrialFired = true;
|
||
const result = writeConfigWithResult(config);
|
||
if (!result.ok) return false;
|
||
mirrored = result.mirrored !== false;
|
||
if (mirrored) return true;
|
||
// Config landed but the mirror did not — retry rather than report success.
|
||
}
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Record how a router render went: a clean "routed" only counts it, any other
|
||
* outcome is a strike (see `deRouterBreaker.ts`), and a cancelled "routed" render is not one.
|
||
*/
|
||
function maybeConsumeDeParallelRouterTrial(
|
||
routerActive: boolean,
|
||
job: RenderJob,
|
||
quiet: boolean,
|
||
renderSucceeded = false,
|
||
): void {
|
||
if (!routerActive) {
|
||
if (renderSucceeded) countCleanRenderWithRouterOff();
|
||
return;
|
||
}
|
||
const outcome = resolveDeParallelRouterOutcome(job);
|
||
if (outcome === undefined) return;
|
||
|
||
const config = readConfigFresh();
|
||
const renderCount = (config.deParallelRouterTrialRenderCount ?? 0) + 1;
|
||
config.deParallelRouterTrialRenderCount = renderCount;
|
||
if (outcome === "routed") {
|
||
writeConfig(config);
|
||
return;
|
||
}
|
||
const breaker = afterRevert(
|
||
forVersion(config.deParallelRouterBreaker, VERSION),
|
||
revertFrom(job, outcome, renderCount),
|
||
);
|
||
config.deParallelRouterBreaker = breaker;
|
||
const fired = breaker.trip !== undefined;
|
||
if (fired) {
|
||
config.deParallelRouterTrialFired = true;
|
||
// Latch before persisting: the decision holds for this process even if the write never sticks.
|
||
deParallelRouterBreakerTrippedThisProcess = true;
|
||
applyDeParallelRouterBreaker();
|
||
}
|
||
writeConfig(config);
|
||
if (fired && !deParallelRouterUserManaged) reportDeParallelRouterBreakerTrip(quiet);
|
||
}
|
||
|
||
/**
|
||
* Tell the user the breaker tripped, and warn if the verdict couldn't be
|
||
* persisted. All output is `!quiet`-gated: quiet/batch-json renders must
|
||
* produce no unexpected terminal output — CI wrappers asserting empty stderr
|
||
* would misread a warning as a render failure (review finding). The
|
||
* in-process latch guarantees the safety behavior either way.
|
||
*/
|
||
function reportDeParallelRouterBreakerTrip(quiet: boolean): void {
|
||
const persisted = persistDeParallelRouterTrialFired();
|
||
if (quiet) return;
|
||
console.log(
|
||
c.dim(
|
||
" Frames failed verification twice, so parallel drawElement capture is off for this " +
|
||
"install until the next version or 20 more renders. Re-enable now: " +
|
||
"HF_DE_PARALLEL_ROUTER=true",
|
||
),
|
||
);
|
||
if (persisted) return;
|
||
console.warn(
|
||
c.warn(
|
||
" Could not persist the parallel drawElement circuit breaker to " +
|
||
"~/.hyperframes/config.json (unwritable?). It stays off for this process; " +
|
||
"future runs may retry it. Set HF_DE_PARALLEL_ROUTER=false to opt out for good.",
|
||
),
|
||
);
|
||
}
|
||
|
||
/**
|
||
* `job.currentStage`/`failedStage` are free-text progress labels
|
||
* (`updateJobStatus`'s callers each pass their own human sentence — "Compiling
|
||
* composition", "Extracting video frames", …), which makes an exact string
|
||
* property unbounded in a telemetry event. This maps the known set to a
|
||
* stable snake_case code, and slugifies anything unrecognized instead of
|
||
* bucketing it into a single opaque "unknown" — a future stage string still
|
||
* gets a distinct, readable code without needing this map updated first.
|
||
*/
|
||
const KNOWN_STAGE_CODES: Readonly<Record<string, string>> = {
|
||
Queued: "queued",
|
||
"Compiling composition": "compiling_composition",
|
||
"Extracting video frames": "extracting_video_frames",
|
||
"Processing audio tracks": "processing_audio_tracks",
|
||
"Starting frame capture": "starting_frame_capture",
|
||
"Render complete": "render_complete",
|
||
"Render cancelled": "render_cancelled",
|
||
pipeline: "pipeline",
|
||
"Starting browsers": "starting_browsers",
|
||
// Was "Encoding video" before encode reported frames; keeps the same bucket.
|
||
"Encoding frame": "encoding_video",
|
||
};
|
||
|
||
// Live counts in a progress label ("Capturing frame 120/600 (6 workers)") would make a code per render.
|
||
const STAGE_COUNTS = /\([^)]*\)|\d+\/\d+|\d+ of \d+/g;
|
||
|
||
export function normalizeStageCode(stage: string): string {
|
||
const base = stage.replace(STAGE_COUNTS, "").trim();
|
||
const known = KNOWN_STAGE_CODES[base];
|
||
if (known) return known;
|
||
const slug = base
|
||
.toLowerCase()
|
||
.replace(/[^a-z0-9]+/g, "_")
|
||
.replace(/^_+|_+$/g, "");
|
||
return slug || "unknown";
|
||
}
|
||
|
||
/**
|
||
* A Chrome launch failure is an environment problem, not a composition bug: the exact remediation for a Linux/WSL
|
||
* sandbox or shared-library failure, a macOS <13 dyld crash, or a Windows STATUS_STACK_BUFFER_OVERRUN, in that order.
|
||
*/
|
||
export function chromeLaunchFailure(
|
||
message: string,
|
||
): { title: string; remediation: string } | null {
|
||
const detectors = [
|
||
sandboxDeniedRemediation,
|
||
chromeLaunchRemediation,
|
||
macosOldChromeCrashRemediation,
|
||
];
|
||
const remediation = detectors.map((detect) => detect(message)).find(Boolean);
|
||
if (remediation) return { title: "Render failed — Chrome could not launch", remediation };
|
||
const windows = windowsChromeCrashRemediation(message);
|
||
return windows
|
||
? { title: "Render failed — chrome-headless-shell crashed at launch", remediation: windows }
|
||
: null;
|
||
}
|
||
|
||
function handleRenderError(
|
||
error: unknown,
|
||
options: RenderOptions,
|
||
startTime: number,
|
||
cpu: RenderCpuSampler,
|
||
docker: boolean,
|
||
hint: string,
|
||
failedStage?: string,
|
||
job?: RenderJob,
|
||
): never {
|
||
const message = normalizeErrorMessage(error);
|
||
renderFailureDiagnostic(job, error, options.quiet);
|
||
trackRenderError({
|
||
fps: fpsToNumber(options.fps),
|
||
quality: options.quality,
|
||
docker,
|
||
workers: options.workers,
|
||
gpu: options.gpu,
|
||
authoringSkill: options.authoringSkill,
|
||
authoringSkillSource: options.authoringSkillSource,
|
||
authoringSkillInvalid: options.authoringSkillInvalid,
|
||
hfEnvOverrides: options.hfEnvOverrides,
|
||
elapsedMs: Date.now() - startTime,
|
||
errorMessage: message,
|
||
failedStage,
|
||
...renderOutputShapeTelemetryPayload(options),
|
||
...renderEnvironmentTelemetryPayload(options),
|
||
// A bucketable failure taxonomy alongside the free-text error_message
|
||
// above: error.name is one of ~20 typed producer error classes
|
||
// (CaptureFailure, DrawElementCaptureError, SwiftShaderAssertionError, …);
|
||
// failed_stage_code is the same job.currentStage value normalized to a
|
||
// stable code. Error-conditional by nature — there is no equivalent on
|
||
// the render_complete success path, since nothing failed to name.
|
||
errorName: error instanceof Error ? error.name : "unknown",
|
||
failedStageCode: normalizeStageCode(failedStage || "pipeline"),
|
||
missingPathKind: missingPathKind(error),
|
||
...renderJobObservabilityTelemetryPayload(job),
|
||
...getMemorySnapshot(),
|
||
...cpu.stop(),
|
||
});
|
||
// Failed renders join the recent-renders ring too — a bug report filed via
|
||
// `hyperframes feedback` is MOST likely to be about a failed render.
|
||
if (job?.id) recordRecentRender(job.id, false);
|
||
if (options.throwOnError) {
|
||
throw new Error(message);
|
||
}
|
||
const launch = chromeLaunchFailure(message);
|
||
if (launch) {
|
||
errorBox(launch.title, message, launch.remediation);
|
||
failCommand();
|
||
}
|
||
errorBox("Render failed", message, hint);
|
||
failCommand();
|
||
}
|
||
|
||
/**
|
||
* Extract rich metrics from the completed render job and send to telemetry.
|
||
* speed_ratio = composition_duration / render_time — higher is better, >1 means faster than realtime.
|
||
*/
|
||
// Inherited CRITICAL (CRAP 148.4, cyclomatic 24): exhaustive nullish-fallback
|
||
// chain across 30+ telemetry fields. Not touched by this PR.
|
||
// fallow-ignore-next-line complexity
|
||
function trackRenderMetrics(
|
||
job: RenderJob,
|
||
elapsedMs: number,
|
||
options: RenderOptions,
|
||
docker: boolean,
|
||
cpuUsage: RenderCpuTelemetryPayload,
|
||
): void {
|
||
// Successful render → recent-renders ring, so a later `hyperframes
|
||
// feedback` can attach this render's telemetry id to the report.
|
||
recordRecentRender(job.id, true);
|
||
const perf = job.perfSummary;
|
||
const compositionDurationMs = perf
|
||
? Math.round(perf.compositionDurationSeconds * 1000)
|
||
: undefined;
|
||
const speedRatio =
|
||
compositionDurationMs && compositionDurationMs > 0 && elapsedMs > 0
|
||
? Math.round((compositionDurationMs / elapsedMs) * 100) / 100
|
||
: undefined;
|
||
|
||
const stages = perf?.stages ?? {};
|
||
const extract = perf?.videoExtractBreakdown;
|
||
|
||
trackRenderComplete({
|
||
durationMs: elapsedMs,
|
||
fps: fpsToNumber(options.fps),
|
||
quality: options.quality,
|
||
workers: options.workers ?? perf?.workers,
|
||
workersBoundBy: perf?.workerSizing?.boundBy,
|
||
workersCpuBased: perf?.workerSizing?.cpuBasedWorkers,
|
||
workersMemoryBased: perf?.workerSizing?.memoryBasedWorkers,
|
||
workersHeapBased: perf?.workerSizing?.heapBasedWorkers,
|
||
workersFrameBased: perf?.workerSizing?.frameBasedWorkers,
|
||
workersHeapLimitMb: perf?.workerSizing?.heapLimitMb,
|
||
workersExceedHeapAdvisory: perf?.workerSizing?.exceedsHeapAdvisory,
|
||
docker,
|
||
gpu: options.gpu,
|
||
authoringSkill: options.authoringSkill,
|
||
authoringSkillSource: options.authoringSkillSource,
|
||
authoringSkillInvalid: options.authoringSkillInvalid,
|
||
hfEnvOverrides: options.hfEnvOverrides,
|
||
catalogUsage: options.catalogUsage,
|
||
...renderOutputShapeTelemetryPayload(options),
|
||
...renderEnvironmentTelemetryPayload(options),
|
||
...renderMotionBlurTelemetryPayload(perf?.motionBlur),
|
||
chromeBrowserRssPeakMb: perf?.chromeMemory?.browserRssPeakMb,
|
||
chromeRendererRssPeakMb: perf?.chromeMemory?.rendererRssPeakMb,
|
||
chromeRssLastMb: perf?.chromeMemory?.rssLastMb,
|
||
chromeGpuProcessSeenLastSample: perf?.chromeMemory?.gpuProcessSeenLastSample,
|
||
chromeMemorySamples: perf?.chromeMemory?.samples,
|
||
staticDedupEnabled: perf?.staticDedup?.enabled,
|
||
staticDedupArmed: perf?.staticDedup?.armed,
|
||
staticDedupSkipReason: perf?.staticDedup?.skipReason,
|
||
staticDedupPredictedFrames: perf?.staticDedup?.predictedFrames,
|
||
staticDedupReusedFrames: perf?.staticDedup?.reusedFrames,
|
||
beginFrameNoDamageFrames: perf?.beginFrameReuse?.noDamageFrames,
|
||
beginFrameHasDamageFrames: perf?.beginFrameReuse?.hasDamageFrames,
|
||
deCaptureMode: perf?.drawElement?.mode,
|
||
vfxHostCount: perf?.drawElement?.vfxHostCount,
|
||
vfxCapture: perf?.drawElement?.vfxCapture,
|
||
vfxTypes: perf?.drawElement?.vfxTypes,
|
||
deCompileGate: perf?.drawElement?.compileGate,
|
||
deClampReason: perf?.drawElement?.clampReason,
|
||
deWorkerInversion: perf?.drawElement?.workerInversion,
|
||
dePreInversionWorkers: perf?.drawElement?.preInversionWorkers,
|
||
compositionElementCount: perf?.drawElement?.compositionElementCount,
|
||
compositionElementCountSource: perf?.drawElement?.compositionElementCountSource,
|
||
compositionElementTags: perf?.drawElement?.compositionElementTags,
|
||
arollVideoCount: perf?.drawElement?.arollVideoCount,
|
||
heygenVideoCount: perf?.drawElement?.heygenVideoCount,
|
||
adaptersUsed: perf?.drawElement?.adaptersUsed,
|
||
audioCount: perf?.drawElement?.audioCount,
|
||
imageCount: perf?.drawElement?.imageCount,
|
||
subCompositionCount: perf?.drawElement?.subCompositionCount,
|
||
audioGroupCount: perf?.drawElement?.audioGroupCount,
|
||
colorGradingCount: perf?.drawElement?.colorGradingCount,
|
||
hasLut: perf?.drawElement?.hasLut,
|
||
rootBodyMismatch: perf?.drawElement?.rootBodyMismatch,
|
||
rootBodyDeltaPxBucket: perf?.drawElement?.rootBodyDeltaPxBucket,
|
||
deShortBand: perf?.drawElement?.shortBand,
|
||
deParallelRouter: perf?.drawElement?.parallelRouter,
|
||
dePreRouterWorkers: perf?.drawElement?.preRouterWorkers,
|
||
deGateReason: perf?.drawElement?.gateReason,
|
||
gpuRenderer: perf?.drawElement?.gpuRenderer,
|
||
deWorkerEncode: perf?.drawElement?.workerEncode,
|
||
deVerifyArmed: perf?.drawElement?.verifyArmed,
|
||
deVerifyChecked: perf?.drawElement?.verifyChecked,
|
||
deVerifyMinDb: perf?.drawElement?.verifyMinDb,
|
||
deVerifyInitMs: perf?.drawElement?.verifyInitMs,
|
||
deSelfVerifyFallback: perf?.drawElement?.selfVerifyFallback,
|
||
deFallbackReason: perf?.drawElement?.fallbackReason,
|
||
deFallbackFailedDb: perf?.drawElement?.fallbackFailedDb,
|
||
deFallbackFrameIndex: perf?.drawElement?.fallbackFrameIndex,
|
||
deFallbackThresholdDb: perf?.drawElement?.fallbackThresholdDb,
|
||
deRouterBreakerOff: deParallelRouterBreakerTrippedThisProcess || undefined,
|
||
deBlankSuspects: perf?.drawElement?.blankSuspects,
|
||
deBlankDeterministicAccepts: perf?.drawElement?.blankDeterministicAccepts,
|
||
deBlankRecaptures: perf?.drawElement?.blankRecaptures,
|
||
deBoundaryFrames: perf?.drawElement?.boundaryFrames,
|
||
deRiskFrames: perf?.drawElement?.riskFrames,
|
||
deNcprFallbacks: perf?.drawElement?.ncprFallbacks,
|
||
deFrameTimeouts: perf?.drawElement?.frameTimeouts,
|
||
compositionDurationMs,
|
||
compositionWidth: perf?.resolution.width,
|
||
compositionHeight: perf?.resolution.height,
|
||
totalFrames: perf?.totalFrames,
|
||
speedRatio,
|
||
captureAvgMs: perf?.captureAvgMs,
|
||
captureP50Ms: perf?.captureP50Ms,
|
||
captureSeekAvgMs: perf?.captureSeekAvgMs,
|
||
captureBeforeCaptureAvgMs: perf?.captureBeforeCaptureAvgMs,
|
||
captureScreenshotAvgMs: perf?.captureScreenshotAvgMs,
|
||
encoderWaitAvgMs: perf?.encoderWaitAvgMs,
|
||
subTimelineWait: perf?.subTimelineWait,
|
||
videoCount: perf?.videoCount,
|
||
capturePeakMs: perf?.capturePeakMs,
|
||
tmpPeakBytes: perf?.tmpPeakBytes,
|
||
stageCompileMs: stages.compileMs,
|
||
stageVideoExtractMs: stages.videoExtractMs,
|
||
stageAudioProcessMs: stages.audioProcessMs,
|
||
stageCaptureMs: stages.captureMs,
|
||
stageCaptureSetupMs: stages.captureSetupMs,
|
||
stageCaptureFrameMs: stages.captureFrameMs,
|
||
stageEncodeMs: stages.encodeMs,
|
||
stageAssembleMs: stages.assembleMs,
|
||
extractResolveMs: extract?.resolveMs,
|
||
extractHdrProbeMs: extract?.hdrProbeMs,
|
||
extractHdrPreflightMs: extract?.hdrPreflightMs,
|
||
extractHdrPreflightCount: extract?.hdrPreflightCount,
|
||
extractVfrProbeMs: extract?.vfrProbeMs,
|
||
extractVfrPreflightMs: extract?.vfrPreflightMs,
|
||
extractVfrPreflightCount: extract?.vfrPreflightCount,
|
||
extractPhase3Ms: extract?.extractMs,
|
||
extractCacheHits: extract?.cacheHits,
|
||
extractCacheMisses: extract?.cacheMisses,
|
||
...renderJobObservabilityTelemetryPayload(job),
|
||
...getMemorySnapshot(),
|
||
...cpuUsage,
|
||
});
|
||
}
|
||
|
||
function readOutputFootprint(outputPath: string): { fileSize: string; isDirectory: boolean } {
|
||
try {
|
||
const stat = statSync(outputPath);
|
||
if (!stat.isDirectory()) return { fileSize: formatBytes(stat.size), isDirectory: false };
|
||
// png-sequence and hls write a directory; sum contained file sizes so the
|
||
// user sees the deliverable footprint, not the directory inode size.
|
||
let total = 0;
|
||
for (const entry of readdirSync(outputPath, { withFileTypes: true })) {
|
||
if (!entry.isFile()) continue;
|
||
try {
|
||
total += statSync(join(outputPath, entry.name)).size;
|
||
} catch {
|
||
// skip unreadable entries
|
||
}
|
||
}
|
||
return { fileSize: formatBytes(total), isDirectory: true };
|
||
} catch {
|
||
return { fileSize: "unknown", isDirectory: false };
|
||
}
|
||
}
|
||
|
||
/** A render points to the desktop app; a batch row does not. Drafts do too. */
|
||
export function wantsDesktopHint(options: Pick<RenderOptions, "desktopHint">): boolean {
|
||
return options.desktopHint !== false;
|
||
}
|
||
|
||
function printRenderComplete(input: {
|
||
outputPath: string;
|
||
projectDir: string;
|
||
/** Print the desktop-app line: a delivered render, never a draft or a batch row. */
|
||
desktopHint: boolean;
|
||
elapsedMs: number;
|
||
quiet: boolean;
|
||
format: RenderFormat;
|
||
perf?: RenderPerfSummary;
|
||
requestedGpuMode?: "auto" | "hardware" | "software";
|
||
}): void {
|
||
if (input.quiet) return;
|
||
const { outputPath, elapsedMs, perf } = input;
|
||
const { fileSize, isDirectory } = readOutputFootprint(outputPath);
|
||
const detail = formatRenderSummaryDetail({
|
||
elapsedMs,
|
||
outputDurationSeconds: perf?.compositionDurationSeconds,
|
||
isDirectory,
|
||
frameCount: perf?.totalFrames,
|
||
playlistDirectory: input.format === "hls",
|
||
});
|
||
console.log("");
|
||
console.log(c.success("\u25C7") + " " + c.accent(outputPath));
|
||
console.log(" " + c.bold(fileSize) + c.dim(" \u00B7 " + detail));
|
||
if (perf) printRenderPipeline(perf, input.requestedGpuMode);
|
||
const hint = input.desktopHint ? desktopHint(input.projectDir) : null;
|
||
if (hint) console.log(" " + c.dim(hint));
|
||
}
|
||
|
||
function printRenderPipeline(
|
||
perf: RenderPerfSummary,
|
||
requestedGpuMode?: "auto" | "hardware" | "software",
|
||
): void {
|
||
// aggregateDrawElement reports "unknown" when no session recorded a mode.
|
||
const capture = {
|
||
captureMode: resolvePrintedCaptureMode(
|
||
perf.drawElement?.mode,
|
||
perf.observability?.capture.captureMode,
|
||
),
|
||
browserGpuMode: perf.observability?.capture.browserGpuMode,
|
||
};
|
||
const pipeline = formatRenderPipelineDetail({
|
||
...capture,
|
||
streamingEncode: perf.observability?.capture.useStreamingEncode,
|
||
stages: perf.stages,
|
||
});
|
||
if (pipeline) console.log(" " + c.dim(pipeline));
|
||
const hint = formatScreenshotFallbackHint({
|
||
...capture,
|
||
requestedGpuMode,
|
||
platform: process.platform,
|
||
});
|
||
if (hint) console.log(" " + c.dim(hint));
|
||
}
|