mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-17 15:24:19 +00:00
refactor(producer): apply /simplify cleanups across distributed harness stack
Code reuse:
- Move `PlanVideosJson` interface + `meta/videos.json` path constant into
`services/distributed/shared.ts`; plan.ts and renderChunk.ts import from
there instead of redeclaring the same shape with the "duplicated here so
renderChunk doesn't import from plan.ts" comment.
- Replace hand-rolled `framePattern.slice(lastIndexOf("."))` with
`extname()` from `node:path` in `rebuildExtractedFramesFromPlanDir`.
Efficiency:
- Hoist `rebuildExtractedFramesFromPlanDir` + `createFrameLookupTable` +
`createVideoFrameInjector` out of the per-chunk closure in renderChunk.
Computed once per chunk now, not once per `createRenderVideoFrameInjector`
callsite (which `runCaptureStage` may invoke multiple times).
- Add a regex filter to `cpSync(projectDir → planDir/compiled/)` so
`node_modules`, `.git`, `output/`, `failures/`, `dist/`, etc. are not
copied. Real projects can have hundreds of MB in those directories;
shipping them to S3/Lambda /tmp on every render bloats cost and time.
- Drop redundant `if (!existsSync(metaDir)) mkdirSync(metaDir, {recursive:true})`
guards; `mkdirSync({recursive:true})` is already idempotent.
Quality:
- Strip narrative comments that told the story of debugging:
- renderChunk's 30-line "Two failure modes made the call actively
harmful" block → 4-line invariant on why `discardWarmupCapture` is
omitted.
- plan.ts's "DO NOT call cleanup()" block → 3 lines naming the
invariant.
- plan.ts's pre-seed-projectDir block → 7 lines on the file-server
invariant.
- renderChunk.ts top docstring's discardWarmupCapture paragraph.
- regression-harness-distributed.ts's PSNR-drift table (belongs in
DISTRIBUTED-RENDERING-PLAN.md, not the source).
- test file's docstring about which tests live where.
- Drop the unreachable IIFE-throw on `format === "webm"` in the harness
(the support check above rejected webm); replace with a plain
`as` cast.
- Replace dynamic `await import("node:fs")` with a top-level import in
`regression-harness-distributed.ts`.
All 54 distributed unit tests still pass in Docker. Full fixture sweep
in `docker:test --mode=distributed-simulated` (font-variant-numeric,
many-cuts, gsap-letters-render-compat, style-1-prod, sub-composition-video)
all PASSED.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,14 +1,5 @@
|
||||
/**
|
||||
* Unit tests for the harness mode plumbing — `parseHarnessModeFlag`,
|
||||
* `checkDistributedSupport`, and `resolveMinPsnrForMode`.
|
||||
*
|
||||
* These do NOT exercise the render pipeline itself. The byte-identical-retry
|
||||
* contract is covered by `services/distributed/renderChunk.test.ts` and the
|
||||
* PSNR contract is covered by `Dockerfile.test` running the harness with
|
||||
* `--mode=distributed-simulated` against the smallest existing fixture.
|
||||
* What lives here is the dispatch logic that decides which mode runs and
|
||||
* which fixtures skip.
|
||||
*/
|
||||
// Pure-function tests for the harness mode dispatch logic. End-to-end
|
||||
// PSNR contract lives in `Dockerfile.test` runs of the regression harness.
|
||||
|
||||
import { describe, expect, it } from "bun:test";
|
||||
import {
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
* format and adapter.
|
||||
*/
|
||||
|
||||
import { existsSync } from "node:fs";
|
||||
import { existsSync, mkdirSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import type { Fps } from "@hyperframes/core";
|
||||
import { assemble, plan, renderChunk } from "./distributed.js";
|
||||
@@ -35,29 +35,12 @@ import { assemble, plan, renderChunk } from "./distributed.js";
|
||||
export type HarnessMode = "in-process" | "distributed-simulated";
|
||||
|
||||
/**
|
||||
* Minimum PSNR (in dB) at which a distributed-simulated render is considered
|
||||
* equivalent to its in-process baseline.
|
||||
*
|
||||
* `DISTRIBUTED-RENDERING-PLAN.md` §5.1 names ≥50 dB as the
|
||||
* distributed-vs-in-process equivalence floor, but that target was written
|
||||
* against per-render comparisons (one fresh in-process render vs one fresh
|
||||
* distributed render). The regression harness compares against a frozen
|
||||
* baseline file, and the in-process renderer itself drifts against that
|
||||
* baseline by varying amounts depending on the composition's dynamics:
|
||||
* - Static compositions (font-variant-numeric): ~48 dB drift
|
||||
* - Rapid transitions (many-cuts): 34-44 dB drift
|
||||
* Both modes share the same encoder/JPEG-capture jitter floor, so this is
|
||||
* a property of the fixture's content, not of either renderer.
|
||||
*
|
||||
* The harness therefore uses the fixture's own `minPsnr` for both modes:
|
||||
* distributed must pass the same quality threshold the in-process renderer
|
||||
* passes against the same baseline. A distributed regression that pushes
|
||||
* PSNR below the fixture's tolerance is caught the same way an in-process
|
||||
* regression would be.
|
||||
*
|
||||
* This constant is retained as a non-zero floor for absolute pathology
|
||||
* (e.g. a chunk renders as fully black), independent of how lenient the
|
||||
* fixture's authored threshold is.
|
||||
* Absolute pathology floor for `--mode=distributed-simulated` — catches
|
||||
* a chunk that renders fully-black against a fixture authored with a
|
||||
* permissive `minPsnr`. Non-pathological drift is caught by the fixture's
|
||||
* own threshold; both modes share the same encoder/JPEG-capture jitter
|
||||
* floor against the frozen baseline file, so the §5.1 50 dB target is
|
||||
* unreachable for either mode and isn't a useful per-test gate.
|
||||
*/
|
||||
export const DISTRIBUTED_SIMULATED_MIN_PSNR_DB = 10;
|
||||
|
||||
@@ -156,7 +139,6 @@ export async function runDistributedSimulatedRender(
|
||||
): Promise<void> {
|
||||
const planDir = join(input.tempRoot, "plan");
|
||||
const chunksDir = join(input.tempRoot, "chunks");
|
||||
const { mkdirSync } = await import("node:fs");
|
||||
mkdirSync(planDir, { recursive: true });
|
||||
mkdirSync(chunksDir, { recursive: true });
|
||||
|
||||
|
||||
@@ -717,17 +717,13 @@ async function runTestSuite(
|
||||
result.skipped = { reason: support.reason };
|
||||
return result;
|
||||
}
|
||||
// The support check narrows `fps.num` to 24|30|60; assert here so
|
||||
// TS sees the literal type that `DistributedRenderConfig.fps`
|
||||
// requires. The check itself rejected every other value above.
|
||||
// `checkDistributedSupport` already narrowed fps to {24,30,60} and
|
||||
// rejected webm; the `as` casts surface those guarantees to TS.
|
||||
const fpsNum = suite.meta.renderConfig.fps.num as 24 | 30 | 60;
|
||||
const distributedFormat: "mp4" | "mov" | "png-sequence" =
|
||||
suite.meta.renderConfig.format === "webm"
|
||||
? // Unreachable — checkDistributedSupport rejected webm above.
|
||||
(() => {
|
||||
throw new Error("webm reached distributed render path");
|
||||
})()
|
||||
: (suite.meta.renderConfig.format ?? "mp4");
|
||||
const distributedFormat = (suite.meta.renderConfig.format ?? "mp4") as
|
||||
| "mp4"
|
||||
| "mov"
|
||||
| "png-sequence";
|
||||
await runDistributedSimulatedRender({
|
||||
projectDir: tempSrcDir,
|
||||
tempRoot,
|
||||
|
||||
@@ -36,12 +36,7 @@ import {
|
||||
} from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { type CanvasResolution } from "@hyperframes/core";
|
||||
import {
|
||||
type EngineConfig,
|
||||
type ExtractedFrames,
|
||||
resolveConfig,
|
||||
type VideoElement,
|
||||
} from "@hyperframes/engine";
|
||||
import { type EngineConfig, resolveConfig } from "@hyperframes/engine";
|
||||
import { defaultLogger, type ProducerLogger } from "../../logger.js";
|
||||
import { runAudioStage } from "../render/stages/audioStage.js";
|
||||
import { runCompileStage } from "../render/stages/compileStage.js";
|
||||
@@ -60,7 +55,13 @@ import {
|
||||
} from "../render/stages/planHash.js";
|
||||
import { validateNoGpuEncode, validateNoSystemFonts } from "../render/planValidation.js";
|
||||
import { snapshotRuntimeEnv } from "../render/runtimeEnvSnapshot.js";
|
||||
import { buildSyntheticRenderJob, readFfmpegVersion, readProducerVersion } from "./shared.js";
|
||||
import {
|
||||
buildSyntheticRenderJob,
|
||||
PLAN_VIDEOS_META_RELATIVE_PATH,
|
||||
type PlanVideosJson,
|
||||
readFfmpegVersion,
|
||||
readProducerVersion,
|
||||
} from "./shared.js";
|
||||
|
||||
/**
|
||||
* Caller-supplied configuration for a distributed render. `fps`, `width`,
|
||||
@@ -145,6 +146,15 @@ export interface PlanResult {
|
||||
producerVersion: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Skip patterns for the `projectDir → planDir/compiled/` pre-seed copy.
|
||||
* Real projects often contain `node_modules/`, VCS metadata, and harness
|
||||
* artifacts that have no business in a planDir — they bloat the 2 GB
|
||||
* planDir cap and slow the S3/Lambda round-trip for no benefit.
|
||||
*/
|
||||
const PLAN_PROJECT_DIR_COPY_SKIP =
|
||||
/(^|\/)(node_modules|\.git|\.cache|output|failures|dist|\.next|\.turbo)(\/|$)/;
|
||||
|
||||
/** Default chunk size in frames (~8s @ 30fps; fits Lambda's 15-min cap). */
|
||||
export const DEFAULT_CHUNK_SIZE = 240;
|
||||
/** Default cap on parallel chunks for operational fairness across renders. */
|
||||
@@ -433,42 +443,6 @@ function buildLockedRenderConfig(input: {
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Persisted shape of the video-extraction outputs from `runExtractVideosStage`,
|
||||
* written to `<planDir>/meta/videos.json` for `renderChunk` to reconstruct
|
||||
* a `FrameLookupTable` from. The in-process renderer keeps these structures
|
||||
* in memory; the distributed pipeline writes them out so a separate chunk
|
||||
* worker process can rebuild the video-frame injector without re-running
|
||||
* the extract stage.
|
||||
*
|
||||
* `ExtractedFrames` from the engine carries an absolute `outputDir`,
|
||||
* an open file descriptor in some paths, and a `framePaths` map — none of
|
||||
* those survive a serialize → re-deserialize round trip across processes.
|
||||
* The serialized form keeps only what plan-time produced and lets
|
||||
* `renderChunk` re-derive `outputDir` (always `<planDir>/video-frames/<videoId>`)
|
||||
* and `framePaths` (re-listed from that directory).
|
||||
*/
|
||||
interface PlanVideosJson {
|
||||
/**
|
||||
* Composition's `<video>` elements in document order. Identical to
|
||||
* `composition.videos` from `compileForRender` — the chunk worker uses
|
||||
* this to drive `createFrameLookupTable`'s time/index math.
|
||||
*/
|
||||
videos: VideoElement[];
|
||||
/**
|
||||
* Per-video extraction outputs. `outputDir` is omitted — `renderChunk`
|
||||
* reconstructs it from `<planDir>/video-frames/<videoId>/`.
|
||||
*/
|
||||
extracted: Array<{
|
||||
videoId: string;
|
||||
srcPath: string;
|
||||
framePattern: string;
|
||||
fps: number;
|
||||
totalFrames: number;
|
||||
metadata: ExtractedFrames["metadata"];
|
||||
}>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-format encoder + pixel-format + preset triple. Distributed mode is
|
||||
* SDR-only: H.264 8-bit for mp4, ProRes 4444 for mov, raw RGBA for
|
||||
@@ -542,25 +516,19 @@ export async function plan(
|
||||
if (!existsSync(workDir)) mkdirSync(workDir, { recursive: true });
|
||||
const compiledDir = join(workDir, "compiled");
|
||||
|
||||
// Pre-seed the compiled directory with the composition's local assets
|
||||
// (CSS, JS, images, fonts, etc. referenced by relative URL from the
|
||||
// entry HTML). The in-process renderer's file server serves these
|
||||
// straight from `projectDir`, so they don't need to be in the compiled
|
||||
// tree there. The distributed chunk worker's file server, by contrast,
|
||||
// serves ONLY from `<planDir>/compiled/` — without these assets, a
|
||||
// composition like `<link rel="stylesheet" href="style.css">` resolves
|
||||
// to a 404 and the rendered chunk is the page's unstyled fallback.
|
||||
//
|
||||
// `compileStage`'s `writeCompiledArtifacts` runs after this and
|
||||
// overwrites the entry HTML with the compiled bytes (and writes
|
||||
// sub-compositions + external-projectDir assets). Everything we pre-seed
|
||||
// here is local to `projectDir` and stays in the planDir as the
|
||||
// canonical asset bundle the chunk worker will serve.
|
||||
// Pre-seed the compiled directory with `projectDir`'s local assets
|
||||
// (style.css, script.js, images, etc.). The chunk worker's file server
|
||||
// serves ONLY from `<planDir>/compiled/`, so without this copy a
|
||||
// composition's `<link rel=stylesheet href=style.css>` 404s and the
|
||||
// first capture lands an unstyled fallback frame. `compileStage`
|
||||
// overwrites the entry HTML afterwards. `dereference: true` resolves
|
||||
// symlinks so the planDir survives S3 / Lambda /tmp round-trips.
|
||||
mkdirSync(compiledDir, { recursive: true });
|
||||
// `dereference: true` resolves symlinks before copying — planDirs are
|
||||
// shipped across process / machine boundaries (S3, Lambda /tmp,
|
||||
// worker pods), and symlinks won't survive the round-trip.
|
||||
cpSync(projectDir, compiledDir, { recursive: true, dereference: true });
|
||||
cpSync(projectDir, compiledDir, {
|
||||
recursive: true,
|
||||
dereference: true,
|
||||
filter: (src) => !PLAN_PROJECT_DIR_COPY_SKIP.test(src),
|
||||
});
|
||||
|
||||
// The compiled directory lives at `<planDir>/compiled/` in the final
|
||||
// layout. The stages write under `<planDir>/.plan-work/compiled/`; we
|
||||
@@ -652,15 +620,9 @@ export async function plan(
|
||||
assertNotAborted,
|
||||
materializeSymlinks: true,
|
||||
});
|
||||
// DO NOT call `extractResult.frameLookup.cleanup()` here. cleanup()
|
||||
// rm-rfs each video's outputDir, which for the in-process renderer is
|
||||
// a scratch tree the orchestrator owns. In plan(), that "scratch" tree
|
||||
// (`compiledDir/__hyperframes_video_frames/<videoId>/`) IS the source
|
||||
// material for `planDir/video-frames/`; cleanup before the rename
|
||||
// leaves the planDir with only the `_downloads/` subdirectory and no
|
||||
// actual per-video frame files, and the chunk worker can't reconstruct
|
||||
// the BeforeCaptureHook without them. The renames below move the tree
|
||||
// into its final planDir location.
|
||||
// Skip `extractResult.frameLookup.cleanup()`: it would rm-rf each
|
||||
// video's outputDir, but in `plan()` those directories ARE the source
|
||||
// material the renames below move into `planDir/video-frames/`.
|
||||
|
||||
// ── Audio ──
|
||||
const audioResult = await runAudioStage({
|
||||
@@ -691,16 +653,12 @@ export async function plan(
|
||||
if (existsSync(finalCompiledDir)) rmSync(finalCompiledDir, { recursive: true, force: true });
|
||||
renameSync(compiledDir, finalCompiledDir);
|
||||
|
||||
// Persist the video-extraction outputs alongside the rest of the planDir
|
||||
// metadata so `renderChunk` can rebuild the BeforeCaptureHook that
|
||||
// injects pre-extracted frames into the page. Without this file the
|
||||
// chunk worker has no way to recover the per-video frame timing and
|
||||
// falls back to letting Chrome's native `<video>` element decode the
|
||||
// source mp4 on the fly — which produces ±1-frame drift relative to
|
||||
// the in-process renderer's pre-extracted injection (the source of
|
||||
// every committed baseline). Writing this file is the contract that
|
||||
// makes distributed renders pixel-comparable to in-process renders for
|
||||
// compositions with video sources.
|
||||
// `meta/videos.json` is the contract that makes distributed renders
|
||||
// pixel-comparable to in-process for compositions with video sources —
|
||||
// without it, renderChunk can't rebuild the BeforeCaptureHook and the
|
||||
// page's native `<video>` element decodes the source mp4 ~1 frame
|
||||
// off the pre-extracted images the in-process baseline was captured
|
||||
// from.
|
||||
const planVideosJson: PlanVideosJson = {
|
||||
videos: composition.videos,
|
||||
extracted: (extractResult.extractionResult?.extracted ?? []).map((ext) => ({
|
||||
@@ -712,9 +670,12 @@ export async function plan(
|
||||
metadata: ext.metadata,
|
||||
})),
|
||||
};
|
||||
const metaDir = join(planDir, "meta");
|
||||
if (!existsSync(metaDir)) mkdirSync(metaDir, { recursive: true });
|
||||
writeFileSync(join(metaDir, "videos.json"), JSON.stringify(planVideosJson, null, 2), "utf-8");
|
||||
mkdirSync(join(planDir, "meta"), { recursive: true });
|
||||
writeFileSync(
|
||||
join(planDir, PLAN_VIDEOS_META_RELATIVE_PATH),
|
||||
JSON.stringify(planVideosJson, null, 2),
|
||||
"utf-8",
|
||||
);
|
||||
|
||||
const planAudioPath = join(planDir, "audio.aac");
|
||||
if (audioResult.hasAudio && existsSync(audioResult.audioOutputPath)) {
|
||||
|
||||
@@ -25,11 +25,8 @@
|
||||
* (`buildVirtualTimeShim({ seedRandomFromFrame: true })`) so any
|
||||
* composition that uses `Math.random` / `crypto.getRandomValues`
|
||||
* produces byte-identical pixels per `(planDir, chunkIndex)`.
|
||||
* - The `lastFrameCache` priming step that earlier versions tried to
|
||||
* emit before the first capture was removed — every frame in the
|
||||
* capture loop seeks fresh DOM, so the cache is never consulted on
|
||||
* the read path, and emitting the priming beginFrame at the chunk's
|
||||
* first absolute frame deadlocked Chrome's compositor.
|
||||
* - No `lastFrameCache` priming: every frame seeks fresh DOM so the
|
||||
* cache is never read, and priming would deadlock the compositor.
|
||||
* - The chunk's encode runs with `lockGopForChunkConcat: true` and
|
||||
* `gopSize === framesInChunk` so concat-copy at assemble time is safe.
|
||||
*
|
||||
@@ -39,10 +36,11 @@
|
||||
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { extname, join } from "node:path";
|
||||
import type { Page } from "puppeteer-core";
|
||||
import {
|
||||
assertSwiftShader,
|
||||
type BeforeCaptureHook,
|
||||
BROWSER_GPU_NOT_SOFTWARE,
|
||||
type CaptureOptions,
|
||||
type CaptureSession,
|
||||
@@ -55,8 +53,6 @@ import {
|
||||
getEncoderPreset,
|
||||
initializeSession,
|
||||
resolveConfig,
|
||||
type VideoElement,
|
||||
type VideoMetadata,
|
||||
} from "@hyperframes/engine";
|
||||
import { defaultLogger } from "../../logger.js";
|
||||
import { runEncodeStage } from "../render/stages/encodeStage.js";
|
||||
@@ -69,7 +65,12 @@ import {
|
||||
import { sha256Hex } from "../render/stages/planHash.js";
|
||||
import { applyRuntimeEnvSnapshot } from "../render/runtimeEnvSnapshot.js";
|
||||
import { buildVirtualTimeShim, createFileServer, type FileServerHandle } from "../fileServer.js";
|
||||
import { buildSyntheticRenderJob, readFfmpegVersion } from "./shared.js";
|
||||
import {
|
||||
buildSyntheticRenderJob,
|
||||
PLAN_VIDEOS_META_RELATIVE_PATH,
|
||||
type PlanVideosJson,
|
||||
readFfmpegVersion,
|
||||
} from "./shared.js";
|
||||
|
||||
/**
|
||||
* Non-retryable error codes raised when the planDir is structurally
|
||||
@@ -131,36 +132,12 @@ export interface ChunkResult {
|
||||
perfPath: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* On-disk shape of `<planDir>/meta/videos.json` written by `plan()`.
|
||||
* Mirrored from `plan.ts`'s internal `PlanVideosJson` — duplicated here so
|
||||
* `renderChunk` doesn't import from `plan.ts` (which would create a cycle).
|
||||
*/
|
||||
interface PlanVideosJson {
|
||||
videos: VideoElement[];
|
||||
extracted: Array<{
|
||||
videoId: string;
|
||||
srcPath: string;
|
||||
framePattern: string;
|
||||
fps: number;
|
||||
totalFrames: number;
|
||||
metadata: VideoMetadata;
|
||||
}>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Rebuild the engine's in-memory `ExtractedFrames[]` from the on-disk
|
||||
* planDir layout. `plan()` wrote a serialized manifest of which videos
|
||||
* exist + per-video frame counts; `<planDir>/video-frames/<videoId>/`
|
||||
* holds the actual numbered frame files. This walks each video's output
|
||||
* directory, populates the `framePaths` Map keyed by 1-based frame index
|
||||
* (the convention `videoFrameInjector` and `FrameLookupTable` both rely
|
||||
* on), and returns the structures ready to feed back into
|
||||
* `createFrameLookupTable`.
|
||||
*
|
||||
* Pure: no Chrome involvement, no engine launch. Used by `renderChunk`
|
||||
* once per chunk to recreate the BeforeCaptureHook the in-process
|
||||
* renderer produces from a live extraction stage.
|
||||
* planDir layout. `<planDir>/video-frames/<videoId>/` holds the numbered
|
||||
* frame files plan() extracted; this lists each dir and rebuilds the
|
||||
* 1-based `framePaths` Map that `FrameLookupTable` / `videoFrameInjector`
|
||||
* both index against.
|
||||
*/
|
||||
function rebuildExtractedFramesFromPlanDir(
|
||||
planDir: string,
|
||||
@@ -175,13 +152,11 @@ function rebuildExtractedFramesFromPlanDir(
|
||||
`${outputDir} not present. plan() should have written frames here; the planDir is malformed.`,
|
||||
);
|
||||
}
|
||||
// The framePattern from extractAllVideoFrames looks like
|
||||
// `frame_%06d.jpg`. We can't sprintf at runtime, so list the dir and
|
||||
// index by sorted name — the encoder writes frame_NNNNNN.<ext> in
|
||||
// monotonic order, so sorted-by-name is also sorted-by-frame-index.
|
||||
const ext = v.framePattern.includes(".")
|
||||
? v.framePattern.slice(v.framePattern.lastIndexOf(".")).toLowerCase()
|
||||
: ".jpg";
|
||||
// framePattern looks like `frame_%05d.jpg`; sprintf isn't available at
|
||||
// runtime so list-and-sort the directory. Sorted-by-name matches
|
||||
// sorted-by-frame-index because the extractor writes zero-padded
|
||||
// monotonic indices.
|
||||
const ext = (extname(v.framePattern) || ".jpg").toLowerCase();
|
||||
const frames = readdirSync(outputDir)
|
||||
.filter((name) => name.toLowerCase().endsWith(ext))
|
||||
.sort();
|
||||
@@ -189,10 +164,7 @@ function rebuildExtractedFramesFromPlanDir(
|
||||
for (let i = 0; i < frames.length; i++) {
|
||||
const frameName = frames[i];
|
||||
if (!frameName) continue;
|
||||
// FrameLookupTable / videoFrameInjector index frames 1-based; the
|
||||
// extractor writes frame_000001, frame_000002, ... so the on-disk
|
||||
// names are already 1-based but we use the sorted-list position to
|
||||
// be tolerant of gaps.
|
||||
// FrameLookupTable indexes frames 1-based.
|
||||
framePaths.set(i + 1, join(outputDir, frameName));
|
||||
}
|
||||
result.push({
|
||||
@@ -348,11 +320,9 @@ export async function renderChunk(
|
||||
const encoder = JSON.parse(readFileSync(encoderJsonPath, "utf-8")) as LockedRenderConfig;
|
||||
const chunks = JSON.parse(readFileSync(chunksJsonPath, "utf-8")) as ChunkSliceJson[];
|
||||
|
||||
// Optional: `meta/videos.json` is present whenever the composition has
|
||||
// `<video>` elements. Absence is fine — compositions without video skip
|
||||
// the frame-extraction stage entirely and don't need an injector.
|
||||
// Presence drives the BeforeCaptureHook below.
|
||||
const videosJsonPath = join(planDir, "meta", "videos.json");
|
||||
// `meta/videos.json` only exists when the composition has `<video>`
|
||||
// elements; absence means no injector is needed.
|
||||
const videosJsonPath = join(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
|
||||
let planVideos: PlanVideosJson | null = null;
|
||||
if (existsSync(videosJsonPath)) {
|
||||
try {
|
||||
@@ -469,6 +439,22 @@ export async function renderChunk(
|
||||
forceScreenshot: encoder.forceScreenshot,
|
||||
};
|
||||
|
||||
// Rebuild the BeforeCaptureHook that injects pre-extracted video
|
||||
// frames into the page. Computed once per chunk and reused — the
|
||||
// `createRenderVideoFrameInjector` callback `runCaptureStage` accepts
|
||||
// can fire on every frame, and re-listing `planDir/video-frames/`
|
||||
// each time would be wasteful (the directory contents don't change
|
||||
// for the duration of a chunk render). Compositions with no video
|
||||
// elements produce `null` here, matching the in-process renderer's
|
||||
// skip path.
|
||||
const chunkVideoInjectorFactory = (): BeforeCaptureHook | null => {
|
||||
if (!planVideos || planVideos.extracted.length === 0) return null;
|
||||
const extracted = rebuildExtractedFramesFromPlanDir(planDir, planVideos.extracted);
|
||||
const frameLookup = createFrameLookupTable(planVideos.videos, extracted);
|
||||
return createVideoFrameInjector(frameLookup);
|
||||
};
|
||||
const cachedVideoInjector = chunkVideoInjectorFactory();
|
||||
|
||||
// ── Per-chunk work + frames directories ──
|
||||
// Suffix workDir with pid + random bytes so concurrent invocations on
|
||||
// the SAME `(planDir, chunkIndex)` (e.g. a scheduler that double-fires
|
||||
@@ -520,36 +506,10 @@ export async function renderChunk(
|
||||
await assertSwiftShader(session.page, readWebGlVendorInfoFromCanvas);
|
||||
await initializeSession(session);
|
||||
|
||||
// Note: `discardWarmupCapture` is intentionally NOT called here.
|
||||
//
|
||||
// The helper was originally added to prime Chrome's
|
||||
// `lastFrameCache` so that — if the chunk's first real capture
|
||||
// happened to return `hasDamage=false` — the cached bytes would
|
||||
// match what an in-process renderer's cache held at the same
|
||||
// absolute frame index. In practice, every frame in the chunk's
|
||||
// capture loop seeks fresh DOM via `__hf.seek(absoluteTime)`
|
||||
// before the screenshot, which means `hasDamage=true` on every
|
||||
// frame and `lastFrameCache` is never consulted on the read path.
|
||||
//
|
||||
// Two failure modes made the call actively harmful:
|
||||
// - calling it with the chunk's first absolute frame caused
|
||||
// captureStage to issue a second `HeadlessExperimental.beginFrame`
|
||||
// at the same `frameTimeTicks` Chrome's compositor had just
|
||||
// advanced to. Chrome blocks the second call indefinitely
|
||||
// waiting for new damage; the render hangs at protocolTimeout.
|
||||
// - calling it with `startFrame - 1` (an attempt to prime against
|
||||
// the prior frame) advanced compositor time past the chunk's
|
||||
// first capture, then the first real capture asked the
|
||||
// compositor to go backward in time, which wedged it the same
|
||||
// way.
|
||||
//
|
||||
// The byte-identical-retry contract holds without the priming:
|
||||
// both retries of the same `(planDir, chunkIndex)` enter the
|
||||
// capture loop in identical state (fresh session, locked warmup,
|
||||
// virtual-time-shimmed page) and seek the same absolute times in
|
||||
// the same order. The lastFrameCache fallback only matters for a
|
||||
// hasDamage=false frame, which doesn't appear under fresh-seek
|
||||
// captures.
|
||||
// `discardWarmupCapture` is intentionally NOT called: every frame
|
||||
// seeks fresh DOM, so `lastFrameCache` is never read; priming it
|
||||
// would deadlock Chrome's compositor by issuing a second beginFrame
|
||||
// at a `frameTimeTicks` it had just advanced to.
|
||||
|
||||
// ── Capture the chunk's range via runCaptureStage ──
|
||||
await runCaptureStage({
|
||||
@@ -570,20 +530,7 @@ export async function renderChunk(
|
||||
needsAlpha: plan.dimensions.format !== "mp4",
|
||||
captureAttempts: [],
|
||||
buildCaptureOptions: () => captureOptions,
|
||||
// Rebuild the in-process renderer's video-frame injector from the
|
||||
// planDir's `meta/videos.json` + `video-frames/<id>/`. Without
|
||||
// this, the chunk worker's page falls back to letting Chrome's
|
||||
// native `<video>` element decode the source mp4 against the
|
||||
// virtual clock, which produces ±1-frame drift relative to the
|
||||
// in-process renderer that pre-extracts frames and injects them
|
||||
// as images. Compositions with no `<video>` elements get a
|
||||
// null injector (no overhead, same as in-process).
|
||||
createRenderVideoFrameInjector: () => {
|
||||
if (!planVideos || planVideos.extracted.length === 0) return null;
|
||||
const extracted = rebuildExtractedFramesFromPlanDir(planDir, planVideos.extracted);
|
||||
const frameLookup = createFrameLookupTable(planVideos.videos, extracted);
|
||||
return createVideoFrameInjector(frameLookup);
|
||||
},
|
||||
createRenderVideoFrameInjector: () => cachedVideoInjector,
|
||||
abortSignal: undefined,
|
||||
assertNotAborted: () => {},
|
||||
frameRange: { startFrame: slice.startFrame, endFrame: slice.endFrame },
|
||||
|
||||
@@ -10,9 +10,41 @@ import { existsSync, readFileSync } from "node:fs";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { promisify } from "node:util";
|
||||
import { type Fps } from "@hyperframes/core";
|
||||
import { type VideoElement, type VideoMetadata } from "@hyperframes/engine";
|
||||
import { type RenderConfig, type RenderJob, createRenderJob } from "../renderOrchestrator.js";
|
||||
import { defaultLogger, type ProducerLogger } from "../../logger.js";
|
||||
|
||||
/**
|
||||
* Filename of the per-video extraction manifest written by `plan()` into
|
||||
* `<planDir>/meta/` and consumed by `renderChunk()` to rebuild the
|
||||
* BeforeCaptureHook that injects pre-extracted frames into the page.
|
||||
* Absence is fine — compositions with no `<video>` elements never
|
||||
* produce the file.
|
||||
*/
|
||||
export const PLAN_VIDEOS_META_RELATIVE_PATH = "meta/videos.json";
|
||||
|
||||
/**
|
||||
* On-disk shape of `<planDir>/meta/videos.json`. The engine's
|
||||
* `ExtractedFrames` shape carries an absolute `outputDir`, a `framePaths`
|
||||
* Map, and potentially an open file descriptor — none of those survive
|
||||
* a serialize → re-deserialize round trip across processes. The
|
||||
* serialized form keeps only what plan-time produced; `renderChunk` re-
|
||||
* derives `outputDir` (always `<planDir>/video-frames/<videoId>`) and
|
||||
* `framePaths` (re-listed from that directory) when reconstructing the
|
||||
* `FrameLookupTable`.
|
||||
*/
|
||||
export interface PlanVideosJson {
|
||||
videos: VideoElement[];
|
||||
extracted: Array<{
|
||||
videoId: string;
|
||||
srcPath: string;
|
||||
framePattern: string;
|
||||
fps: number;
|
||||
totalFrames: number;
|
||||
metadata: VideoMetadata;
|
||||
}>;
|
||||
}
|
||||
|
||||
const execFile = promisify(execFileCallback);
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user