From 46954b7f571f15ab4cbebce84ae393a08de508f6 Mon Sep 17 00:00:00 2001 From: James Date: Tue, 12 May 2026 02:01:41 +0000 Subject: [PATCH] refactor(producer): document executeRenderJob as a thin sequencer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Final polish PR of the Phase 1 stack. Comment-only — zero code change. After PRs #725, #726, #730, #731, #733, #734, the `executeRenderJob` function now composes eight stage modules instead of inlining the pipeline. Updates the file-level JSDoc to point at each stage module and explains the orchestrator's residual responsibilities: shared resource lifetime, perf counters, error diagnostics, and the `try/finally` cleanup. Adds JSDoc on `executeRenderJob` itself summarising what it returns and when it throws. The function body is unchanged. The line count dropped from ~2,200 (pre-Phase-1) to ~880; the remainder is in-sequencer setup that doesn't naturally compose into a stage (calibration, worker resolution, HDR auto-detection, preset selection, final perf-summary assembly) plus the orchestrator's `try/finally` resource ownership. Verified inside `Dockerfile.test`: font-variant-numeric (1.000), many-cuts (0.994), variables-prod (0.975), hdr-regression (1.000) — 4/4 PASS with audio correlations identical to every prior PR in the Phase 1 stack. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../src/services/renderOrchestrator.ts | 45 +++++++++++++++---- 1 file changed, 36 insertions(+), 9 deletions(-) diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index ccdffa7656..a3863a7ba1 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -1,16 +1,33 @@ /** * Render Orchestrator Service * - * Coordinates the entire video rendering pipeline: - * 1. Parse composition metadata - * 2. Pre-extract video frames - * 3. Pre-process audio tracks - * 4. Parallel frame capture - * 5. Video encoding - * 6. Final assembly (audio mux + faststart) + * `executeRenderJob` is the in-process entry point that composes the + * pipeline's six stages. Each stage lives in its own module under + * `./render/stages/` so the pure-function primitives can be reused by + * the distributed render path without dragging the orchestrator's + * cleanup and observability scaffolding with them. * - * Heavy observability: every stage logs timing, errors include - * full context, and failures produce a diagnostic summary. + * Stage 1 compile → services/render/stages/compileStage.ts + * Stage 1b probe → services/render/stages/probeStage.ts + * (browser-driven duration discovery + media reconciliation; + * grouped with Stage 1 in the perf summary) + * Stage 2 extract videos → services/render/stages/extractVideosStage.ts + * Stage 3 audio → services/render/stages/audioStage.ts + * Stage 4 capture → services/render/stages/captureStage.ts + * services/render/stages/captureStreamingStage.ts + * services/render/stages/captureHdrStage.ts + * Stage 5 encode → services/render/stages/encodeStage.ts + * Stage 6 assemble → services/render/stages/assembleStage.ts + * + * Resources spawned by stages (file server, capture sessions, streaming + * encoders, raw HDR frame files) are tracked in the orchestrator's + * `try/finally` so a stage throwing mid-pipeline doesn't leak Chrome + * processes or ffmpeg subprocesses. + * + * Heavy observability: every stage records timing into `perfStages`, + * errors carry full context, and failures produce a diagnostic summary + * (browser console tail, memory peaks, capture attempts, HDR + * diagnostics). */ import { @@ -1812,6 +1829,16 @@ export function extractStandaloneEntryFromIndex( return document.toString(); } +/** + * Render a `RenderJob` end-to-end: compile → probe → extract videos → + * audio → capture → encode → assemble. The function body is a thin + * sequencer over the eight stage modules in `./render/stages/`; the + * orchestrator owns shared resources (work dir, file server, probe + * session, browser console buffer, perf counters, peak-memory sampler) + * and the `try/finally` cleanup. Returns once the final output exists at + * `outputPath`; throws on cancellation, encoder failure, or a stage + * error (with a diagnostic summary written to `perf-summary.json`). + */ export async function executeRenderJob( job: RenderJob, projectDir: string,