voxflow 1.15.2 → 1.15.4

package/lib/commands/slice-render.js

@@ -38,9 +38,14 @@ const DEFAULT_CARD_SEC = 4;
  * Phase 0 is silent — every card gets DEFAULT_CARD_SEC. Phase 1 will
  * splice per-card TTS in and replace this with audio-driven durations.
  */
-function buildInputProps(deck) {
+function buildInputProps(deck, opts = {}) {
+    // Map of cardIdx → audio URL produced by prepareVoiceovers (or empty when
+    // the renderer runs silent). Threads into PaperSlideDeckProps.cards[].slide
+    // .voiceoverSrc so the composition's <Audio> element fetches it during
+    // Remotion's headless render.
+    const voiceoverByIdx = opts.voiceoverByIdx || {};
     const numberBadge = null;
-    const cards = deck.cards.map((card) => {
+    const cards = deck.cards.map((card, i) => {
         const slide = {
             kind: card.kind,
             header: deck.header,
@@ -49,7 +54,7 @@ function buildInputProps(deck) {
             figureKeyword: card.figureKeyword ?? null,
             seriesTitle: deck.seriesTitle,
             seriesTagline: deck.seriesTagline,
-            voiceoverSrc: null,
+            voiceoverSrc: voiceoverByIdx[i] || null,
             numberBadge,
             imageUrl: card.imageUrl,
         };
@@ -181,8 +186,53 @@ async function render(opts) {
     const outputDir = path.dirname(outputPath);
     if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
 
+    // ─── Voiceover prep (Phase 1) ────────────────────────────────────────
+    // Synthesize per-card TTS up front so renderMedia's headless Chromium
+    // can fetch each clip as the composition plays. Reuses the audition
+    // cache so a card the user previewed in stage doesn't pay quota again.
+    // Skip the whole pass on --no-audio (back-compat with Phase 0 silent).
+    const includeAudio = opts.noAudio !== true;
+    let voiceoverByIdx = {};
+    let voiceoverServer = null;
+    let voiceoverSkipped = [];
+    if (includeAudio) {
+        const { createTtsAuditionClient } = require('../stage-core/tts-audition');
+        const { startVoiceoverServer, prepareVoiceovers } = require('../stage-core/voiceover-mux');
+        const audClient = createTtsAuditionClient();
+        voiceoverServer = await startVoiceoverServer({ cacheDir: audClient.cacheDir });
+        let synthCount = 0;
+        let cacheCount = 0;
+        const prep = await prepareVoiceovers({
+            deck,
+            auditionClient: audClient,
+            baseUrl: voiceoverServer.url,
+            onProgress: (p) => {
+                if (p.fromCache) cacheCount += 1; else synthCount += 1;
+                process.stdout.write(
+                    `\r[slice render] voiceover ${p.cardIdx + 1}/${p.total} ` +
+                    `(${p.fromCache ? 'cache' : 'synth'})           `
+                );
+            },
+        });
+        voiceoverByIdx = prep.byIdx;
+        voiceoverSkipped = prep.skipped;
+        if (synthCount > 0 || cacheCount > 0) process.stdout.write('\n');
+        if (Object.keys(voiceoverByIdx).length === 0) {
+            const fatal = voiceoverSkipped.find(
+                (s) => s.reason === 'not_logged_in' || s.reason === 'quota_exceeded'
+            );
+            if (fatal) {
+                console.warn(
+                    `[slice render] ⚠ audio skipped — ${fatal.reason}` +
+                    (fatal.message ? `: ${fatal.message}` : '') +
+                    ' (rendering silent video; pass --no-audio to suppress this notice)'
+                );
+            }
+        }
+    }
+
     const serveUrl = resolveServeUrl();
-    const inputProps = buildInputProps(deck);
+    const inputProps = buildInputProps(deck, { voiceoverByIdx });
 
     // Lazy require so users who never run `slice render` don't pay the
     // remotion install cost at CLI startup (renderer pulls in puppeteer-
@@ -246,24 +296,38 @@ async function render(opts) {
     const totalMs = Date.now() - t0;
     process.stdout.write('\n');
 
+    // Tear down the localhost audio file server after the render is fully
+    // committed to disk so a hanging Chromium fetch can't be interrupted.
+    if (voiceoverServer) {
+        try { await voiceoverServer.close(); } catch { /* best-effort */ }
+    }
+
     const stat = fs.statSync(outputPath);
     console.log(`[slice render] done in ${fmtSec(totalMs)} — ${humanSize(stat.size)}`);
     console.log(`[slice render] saved to ${outputPath}`);
-    return { outputPath, totalMs, frames: lastFrame, size: stat.size };
+    return {
+        outputPath,
+        totalMs,
+        frames: lastFrame,
+        size: stat.size,
+        voiceoverCount: Object.keys(voiceoverByIdx).length,
+        voiceoverSkipped,
+    };
 }
 
 async function handle(args) {
     const { parseFlag } = require('../core/args');
     const output = parseFlag(args, '--output', '-o');
+    const noAudio = args.includes('--no-audio');
     const positional = args.find(
         (a) => !a.startsWith('-') && !a.startsWith('--')
     );
     if (!positional) {
-        console.error('Usage: voxflow slice render <deck.json> [--output out.mp4]');
+        console.error('Usage: voxflow slice render <deck.json> [--output out.mp4] [--no-audio]');
         process.exit(1);
     }
     try {
-        await render({ deckPath: positional, output });
+        await render({ deckPath: positional, output, noAudio });
     } catch (err) {
         console.error(`\nslice render failed: ${err.message}`);
         if (process.env.VOXFLOW_DEBUG) console.error(err.stack);

package/lib/commands/slice-stage.js

@@ -19,8 +19,13 @@ const { watchDeckFile } = require('../stage-core/watcher');
 const { createEventBus } = require('../stage-core/event-bus');
 const { createSnapshotStore } = require('../stage-core/snapshot-store');
 const { createCloudRenderClient } = require('../stage-core/cloud-render');
+const { startLocalRender, getJobStatus } = require('../stage-core/local-render');
+const { createTtsAuditionClient } = require('../stage-core/tts-audition');
+const { validatePaperSlideDeck, isV2LayoutTreeDeck } = require('../internal/deck-validator');
 const { renderSliceStageHtml } = require('../stage-ui/slice/template');
 const { emit: emitTelemetry } = require('../core/telemetry');
+const { readCachedToken } = require('../core/auth');
+const { SYNTHESIZE_DEFAULTS } = require('../core/config');
 
 // Sourced from the canonical registry at repo root. Previously this list
 // silently fell out of sync (lagged at 6 themes while the rest of the repo
@@ -137,12 +142,104 @@ async function startSliceStage(opts) {
   // user logged into; the page never sees the JWT.
   const cloudRender = opts.cloudRender || createCloudRenderClient();
 
+  // ─── Local render bridge ───────────────────────────────────────────────
+  // Wires @remotion/renderer into stage so the page can produce mp4 without
+  // touching the cloud. The bridge captures the deck snapshot at submit
+  // time and proxies progress events through the existing SSE bus.
+  const localRenderBridge = opts.localRender || {
+    start({ output, onProgress, onDone, onError }) {
+      if (!snapshot.deck) {
+        const err = new Error('No deck loaded — fix the JSON parse error first.');
+        err.code = 'invalid_deck';
+        throw err;
+      }
+      return startLocalRender({
+        deck: snapshot.deck,
+        deckPath,
+        output,
+        onProgress,
+        onDone,
+        onError,
+      });
+    },
+    status: (jobId) => getJobStatus(jobId),
+  };
+
+  // ─── Inline deck save bridge (Task B) ──────────────────────────────────
+  // Validates the incoming deck against the same schema the cloud route
+  // uses, then writes atomically (tmp → rename). The watcher already
+  // broadcasts the resulting change to SSE — no extra fan-out needed.
+  const deckSaverBridge = opts.deckSaver || {
+    save(deck) {
+      if (isV2LayoutTreeDeck(deck)) {
+        return {
+          ok: false,
+          message: 'V2 LayoutTree decks are not supported for inline edit yet — edit deck.json directly.',
+        };
+      }
+      try {
+        validatePaperSlideDeck(deck);
+      } catch (err) {
+        return { ok: false, message: err.message, errors: [err.message] };
+      }
+      const tmp = `${deckPath}.tmp-${process.pid}-${Date.now()}`;
+      const out = JSON.stringify(deck, null, 2) + '\n';
+      fs.writeFileSync(tmp, out, 'utf8');
+      fs.renameSync(tmp, deckPath);
+      return { ok: true };
+    },
+  };
+
+  // ─── TTS audition bridge (per-card ▶ on stage UI) ──────────────────────
+  // Resolves `card.voiceover` / `card.voiceId` / `card.narration` against the
+  // live deck snapshot at request time so editing the deck → ▶ replays the
+  // new content immediately. Audio is cached by content hash so iterative
+  // re-listens cost zero quota after the first call.
+  const auditionBridge = opts.audition || (() => {
+    const tts = opts.ttsClient || createTtsAuditionClient(opts.ttsClientOpts || {});
+    return {
+      async play({ cardIndex, voiceOverride }) {
+        if (!snapshot.deck) return { code: 'no_deck', message: 'no deck loaded' };
+        const cards = Array.isArray(snapshot.deck.cards) ? snapshot.deck.cards : [];
+        const card = cards[cardIndex];
+        if (!card) return { code: 'card_not_found', message: `no card at index ${cardIndex}` };
+        const vo = card.voiceover || {};
+        if (vo.enabled === false) {
+          return { code: 'voiceover_disabled', message: 'card voiceover.enabled = false' };
+        }
+        const text = (typeof vo.text === 'string' && vo.text.trim()) ? vo.text : card.narration;
+        if (typeof text !== 'string' || !text.trim()) {
+          return { code: 'invalid_text', message: 'no text to synthesize (card.voiceover.text or card.narration)' };
+        }
+        const voiceId = (voiceOverride && String(voiceOverride).trim())
+          || vo.voiceId
+          || card.voiceId
+          || SYNTHESIZE_DEFAULTS.voice;
+        const speed = typeof vo.rate === 'number' ? vo.rate : 1.0;
+        return tts.audition({ voiceId, text, speed, format: 'mp3' });
+      },
+    };
+  })();
+
+  // Boot-time auth probe so the UI can emphasise local vs cloud render.
+  // We treat any cached, non-expired token as "logged in"; the actual
+  // request flow still revalidates on /api/quota-balance.
+  const tokenAvailable = (() => {
+    if (typeof opts.tokenAvailable === 'boolean') return opts.tokenAvailable;
+    try { return !!readCachedToken(); } catch { return false; }
+  })();
+
   const handle = await startStageServer({
     uiHtml: initialHtml,
     getDeckSnapshot: () => snapshot,
     subscribe: bus.subscribe,
     snapshots: snapshotsBridge,
     cloudRender,
+    localRender: localRenderBridge,
+    deckSaver: deckSaverBridge,
+    audition: auditionBridge,
+    publishEvent: bus.publish,
+    tokenAvailable,
     preferredPort,
     maxPortTries,
   });

package/lib/internal/deck-validator.js

@@ -128,6 +128,49 @@ function validateListPayload(list, i) {
     });
 }
 
+// Optional per-card voiceover override. Extends the legacy `card.voiceId`
+// (V1-only) with a nested object that carries audio behavior toggles — silent
+// card, custom TTS text override, speech rate — so stage's audition endpoint
+// and the local-render mux pass resolve a single source of truth per card.
+// All fields are optional inside an optional object: omitting `voiceover`
+// entirely keeps existing decks unchanged. Render-time resolution (highest
+// precedence first):
+//   voiceId = voiceover.voiceId ?? card.voiceId ?? job-level default
+//   text    = voiceover.text    ?? card.narration
+//   enabled = voiceover.enabled ?? true
+//   rate    = voiceover.rate    ?? 1.0
+const VOICEOVER_TEXT_MAX = 500;
+function validateVoiceoverShape(vo, cardIdx) {
+    if (vo == null) return;
+    if (typeof vo !== 'object' || Array.isArray(vo)) {
+        throw new Error(`cards[${cardIdx}].voiceover must be an object`);
+    }
+    if (vo.enabled != null && typeof vo.enabled !== 'boolean') {
+        throw new Error(`cards[${cardIdx}].voiceover.enabled must be boolean`);
+    }
+    if (vo.voiceId != null) {
+        if (typeof vo.voiceId !== 'string' || !vo.voiceId.trim()) {
+            throw new Error(`cards[${cardIdx}].voiceover.voiceId must be non-empty string when present`);
+        }
+        if (vo.voiceId.length > 128) {
+            throw new Error(`cards[${cardIdx}].voiceover.voiceId too long (${vo.voiceId.length} > 128)`);
+        }
+    }
+    if (vo.text != null) {
+        if (typeof vo.text !== 'string') {
+            throw new Error(`cards[${cardIdx}].voiceover.text must be string`);
+        }
+        if (vo.text.length > VOICEOVER_TEXT_MAX) {
+            throw new Error(`cards[${cardIdx}].voiceover.text too long (${vo.text.length} > ${VOICEOVER_TEXT_MAX})`);
+        }
+    }
+    if (vo.rate != null) {
+        if (typeof vo.rate !== 'number' || !Number.isFinite(vo.rate) || vo.rate < 0.5 || vo.rate > 2.0) {
+            throw new Error(`cards[${cardIdx}].voiceover.rate must be number in [0.5, 2.0]`);
+        }
+    }
+}
+
 function validatePaperSlideDeck(deck) {
     if (!deck || typeof deck !== 'object') throw new Error('deck missing');
     for (const f of ['header', 'seriesTitle', 'seriesTagline']) {
@@ -235,6 +278,7 @@ function validatePaperSlideDeck(deck) {
                 throw new Error(`cards[${i}].voiceId too long (${card.voiceId.length} > 128)`);
             }
         }
+        validateVoiceoverShape(card.voiceover, i);
         // Optional per-card image URL — photo-feature / atmospheric themes
         // composite it as a full-bleed background; other themes ignore it.
         // Shape-check only (string, length cap, http(s) prefix); reachability
@@ -446,6 +490,7 @@ function validatePaperSlideDeckV2(deck) {
             if (stepsEls.length !== 1) throw new Error(`cards[${i}] list card must contain exactly one steps element (got ${stepsEls.length})`);
             richCounts.list += 1;
         }
+        validateVoiceoverShape(card.voiceover, i);
     });
     // Cap on rich-kind variety — at most 1 of each (same as V1 prompt rule)
     for (const k of Object.keys(richCounts)) {
@@ -477,6 +522,7 @@ module.exports = {
     validateQuotePayload,
     validateDataPayload,
     validateListPayload,
+    validateVoiceoverShape,
     QUOTE_TEXT_MAX,
     QUOTE_ATTRIBUTION_MAX,
     DATA_VALUE_MAX,
@@ -485,4 +531,5 @@ module.exports = {
     LIST_ITEM_MAX_LEN,
     LIST_ITEM_MIN_COUNT,
     LIST_ITEM_MAX_COUNT,
+    VOICEOVER_TEXT_MAX,
 };

package/lib/stage-core/local-render.js

@@ -0,0 +1,324 @@
+'use strict';
+
+/**
+ * Stage → @remotion/renderer bridge for the *offline* Slice renderer.
+ *
+ * Why this exists: stage's existing "Render mp4" button proxies to the cloud
+ * backend (Fly render-worker), which requires `voxflow login` and burns 500
+ * quota per call. The Phase 0 promise was offline-first authoring — if a
+ * skill-driven user never logged in, the only render path on the stage page
+ * was broken. This module wires the same `@remotion/renderer` flow that
+ * `voxflow slice render` already uses (see `slice-render.js`) into stage,
+ * so the page can produce an mp4 against the pre-bundled Remotion serveUrl
+ * at `cli/dist/remotion-bundle/` with no network round-trip.
+ *
+ * Public surface:
+ *   startLocalRender({ deck, output, onProgress, onDone, onError })
+ *     → { jobId }                       — non-blocking, returns immediately
+ *   getJobStatus(jobId)                 → { state, progress, framesRendered,
+ *                                            framesTotal, outputPath, error }
+ *
+ * State machine per job:
+ *   pending  → preparing  → rendering  → completed
+ *                                     └→ failed
+ *
+ * Concurrency: jobs run sequentially on the stage server's event loop —
+ * `@remotion/renderer` spawns headless Chromium in subprocess workers and is
+ * CPU-bound, so parallel renders would thrash. The stage server is for
+ * single-author iteration; queueing is acceptable.
+ *
+ * Reuses helpers from slice-render.js (single source of truth):
+ *   - buildInputProps     — validator deck → PaperSlideDeckProps
+ *   - resolveServeUrl     — find dist/remotion-bundle in dev + ncc layouts
+ *   - chromeBinaryExists  — detect first-run cold start (so we can warn)
+ *   - THEME_TO_DECK_ID    — slice theme id → Remotion composition id
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const {
+  buildInputProps,
+  resolveServeUrl,
+  chromeBinaryExists,
+  THEME_TO_DECK_ID,
+  DEFAULT_THEME,
+} = require('../commands/slice-render');
+const { createTtsAuditionClient } = require('./tts-audition');
+const { startVoiceoverServer, prepareVoiceovers } = require('./voiceover-mux');
+
+// In-memory job table. We never persist jobs — a stage restart wipes history,
+// which is fine because the produced mp4 lives on disk under the user's deck
+// directory. The page only knows about jobs while it's open.
+const jobs = new Map();
+
+function makeJobId() {
+  // crypto.randomUUID is Node 19+; the cli's engines field requires 20+, so
+  // it's always available. Tests can stub the module to inject deterministic
+  // ids if needed (see local-render.test.js).
+  return crypto.randomUUID();
+}
+
+/**
+ * Default output path: sibling of the deck file, same basename, `.mp4` ext.
+ *   /tmp/.../my-deck.json  →  /tmp/.../my-deck.mp4
+ *
+ * Falls back to `out.mp4` if the deck wasn't loaded from disk (deck-in-memory
+ * is hypothetical at the moment; current stage always has a deckPath, but we
+ * future-proof for an MCP-piped variant).
+ */
+function defaultOutputPath(deckPath) {
+  if (deckPath && typeof deckPath === 'string') {
+    const dir = path.dirname(deckPath);
+    const base = path.basename(deckPath, path.extname(deckPath));
+    return path.join(dir, `${base}.mp4`);
+  }
+  return path.resolve(process.cwd(), 'out.mp4');
+}
+
+/**
+ * Lazy-load @remotion/renderer. Doing this at module load would force every
+ * stage boot to pay the ~30 MB resolver cost; we defer until the first job.
+ * The renderer is a peer of slice-render.js (same version) so the bundle
+ * deduplicates in node_modules.
+ */
+function loadRenderer() {
+  return require('@remotion/renderer');
+}
+
+/**
+ * Start an offline Remotion render against the pre-bundled serveUrl.
+ *
+ * @param {object} opts
+ * @param {object} opts.deck                 Validator-shaped deck (cards + theme).
+ * @param {string} [opts.deckPath]           For default output path inference.
+ * @param {string} [opts.output]             Optional explicit output path.
+ * @param {(p:object) => void} [opts.onProgress]
+ *   Called on every Remotion progress tick. Payload:
+ *     { jobId, progress (0..1), framesRendered, framesTotal }
+ * @param {(d:object) => void} [opts.onDone]
+ *   Called with { jobId, outputPath, totalMs, sizeBytes } when the mp4 is written.
+ * @param {(e:object) => void} [opts.onError]
+ *   Called with { jobId, message } on any failure (synchronous or async).
+ * @returns {{ jobId:string, outputPath:string }}
+ *   Returned synchronously so the HTTP route can respond immediately while
+ *   the render proceeds in the background.
+ */
+function startLocalRender(opts) {
+  const deck = opts && opts.deck;
+  if (!deck || !Array.isArray(deck.cards)) {
+    const err = new Error('startLocalRender: deck.cards required');
+    err.code = 'invalid_deck';
+    throw err;
+  }
+  const theme = deck.theme || DEFAULT_THEME;
+  const deckId = THEME_TO_DECK_ID[theme];
+  if (!deckId) {
+    const err = new Error(`Unknown theme "${theme}". Valid: ${Object.keys(THEME_TO_DECK_ID).join(', ')}`);
+    err.code = 'invalid_theme';
+    throw err;
+  }
+
+  const outputPath = path.resolve(
+    opts.output || defaultOutputPath(opts.deckPath)
+  );
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+
+  const jobId = makeJobId();
+  const job = {
+    jobId,
+    state: 'pending',
+    progress: 0,
+    framesRendered: 0,
+    framesTotal: 0,
+    outputPath,
+    theme,
+    deckId,
+    error: null,
+    startedAt: Date.now(),
+    finishedAt: null,
+    sizeBytes: null,
+  };
+  jobs.set(jobId, job);
+
+  // Kick off the actual work on the next tick so the caller's POST handler
+  // can flush the response with the jobId before any renderer init starts.
+  setImmediate(() => {
+    runRender({
+      job,
+      deck,
+      onProgress: opts.onProgress,
+      onDone: opts.onDone,
+      onError: opts.onError,
+    });
+  });
+
+  return { jobId, outputPath };
+}
+
+async function runRender({ job, deck, onProgress, onDone, onError }) {
+  const { jobId, outputPath, deckId } = job;
+  let voiceoverServer = null;
+  try {
+    job.state = 'preparing';
+
+    // ─── Voiceover prep (Phase 1) ──────────────────────────────────────
+    // Stage's Render button defaults to including audio — users in stage
+    // are iterating and expect a richer preview. The audition cache makes
+    // re-renders effectively free for cards they already previewed.
+    // Falls back to silent video on not_logged_in / quota_exceeded
+    // (recorded in job.voiceoverSkipped so the UI can surface the reason).
+    let voiceoverByIdx = {};
+    let voiceoverSkipped = [];
+    try {
+      const audClient = createTtsAuditionClient();
+      voiceoverServer = await startVoiceoverServer({ cacheDir: audClient.cacheDir });
+      const prep = await prepareVoiceovers({
+        deck,
+        auditionClient: audClient,
+        baseUrl: voiceoverServer.url,
+        onProgress: (p) => {
+          if (typeof onProgress === 'function') {
+            try {
+              onProgress({
+                jobId,
+                progress: 0,
+                framesRendered: 0,
+                framesTotal: 0,
+                phase: 'voiceover',
+                voiceoverIndex: p.cardIdx + 1,
+                voiceoverTotal: p.total,
+                voiceoverFromCache: p.fromCache,
+              });
+            } catch { /* swallow */ }
+          }
+        },
+      });
+      voiceoverByIdx = prep.byIdx;
+      voiceoverSkipped = prep.skipped;
+    } catch (err) {
+      // Voiceover prep failure is non-fatal — fall back to silent render
+      // so a TTS outage / first-run-without-login still produces an mp4.
+      voiceoverSkipped = [{ cardIdx: -1, reason: 'voiceover_prep_failed', message: err.message }];
+      if (voiceoverServer) {
+        try { await voiceoverServer.close(); } catch { /* */ }
+        voiceoverServer = null;
+      }
+    }
+    job.voiceoverCount = Object.keys(voiceoverByIdx).length;
+    job.voiceoverSkipped = voiceoverSkipped;
+
+    const serveUrl = resolveServeUrl();
+    const inputProps = buildInputProps(deck, { voiceoverByIdx });
+
+    const renderer = loadRenderer();
+    job.coldStart = !chromeBinaryExists();
+
+    const composition = await renderer.selectComposition({
+      serveUrl,
+      id: deckId,
+      inputProps,
+    });
+    job.framesTotal = composition.durationInFrames;
+    job.state = 'rendering';
+    if (typeof onProgress === 'function') {
+      try {
+        onProgress({
+          jobId,
+          progress: 0,
+          framesRendered: 0,
+          framesTotal: job.framesTotal,
+        });
+      } catch { /* swallow consumer errors */ }
+    }
+
+    await renderer.renderMedia({
+      composition,
+      serveUrl,
+      codec: 'h264',
+      outputLocation: outputPath,
+      inputProps,
+      imageFormat: 'jpeg',
+      jpegQuality: 85,
+      concurrency: 4,
+      x264Preset: 'ultrafast',
+      chromiumOptions: { gl: 'swiftshader' },
+      offthreadVideoCacheSizeInBytes: 512 * 1024 * 1024,
+      onProgress: ({ progress, renderedFrames }) => {
+        job.progress = progress;
+        job.framesRendered = renderedFrames;
+        if (typeof onProgress === 'function') {
+          try {
+            onProgress({
+              jobId,
+              progress,
+              framesRendered: renderedFrames,
+              framesTotal: job.framesTotal,
+            });
+          } catch { /* swallow */ }
+        }
+      },
+    });
+
+    const stat = fs.statSync(outputPath);
+    job.state = 'completed';
+    job.progress = 1;
+    job.sizeBytes = stat.size;
+    job.finishedAt = Date.now();
+    if (typeof onDone === 'function') {
+      try {
+        onDone({
+          jobId,
+          outputPath,
+          totalMs: job.finishedAt - job.startedAt,
+          sizeBytes: job.sizeBytes,
+        });
+      } catch { /* swallow */ }
+    }
+  } catch (err) {
+    job.state = 'failed';
+    job.error = err && err.message ? err.message : String(err);
+    job.finishedAt = Date.now();
+    if (typeof onError === 'function') {
+      try { onError({ jobId, message: job.error }); } catch { /* swallow */ }
+    }
+  } finally {
+    // Always tear down the audio file server, including on render failure,
+    // so a stale localhost listener doesn't leak across jobs.
+    if (voiceoverServer) {
+      try { await voiceoverServer.close(); } catch { /* best-effort */ }
+    }
+  }
+}
+
+function getJobStatus(jobId) {
+  const job = jobs.get(jobId);
+  if (!job) return null;
+  return {
+    jobId: job.jobId,
+    state: job.state,
+    progress: job.progress,
+    framesRendered: job.framesRendered,
+    framesTotal: job.framesTotal,
+    outputPath: job.outputPath,
+    error: job.error,
+    sizeBytes: job.sizeBytes,
+    startedAt: job.startedAt,
+    finishedAt: job.finishedAt,
+  };
+}
+
+/** Test-only: nuke the job table between cases. Not exposed in module exports
+ *  publicly to discourage callers from clearing state in production paths. */
+function _resetJobsForTests() {
+  jobs.clear();
+}
+
+module.exports = {
+  startLocalRender,
+  getJobStatus,
+  defaultOutputPath,
+  _resetJobsForTests,
+};