voxflow 1.15.3 → 1.15.5

package/lib/internal/deck-validator.js

@@ -128,6 +128,101 @@ 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
+// Optional per-card image registry. Each entry declares an AI-generation
+// recipe (prompt + aspect + quality) addressable by a stable `id` so the
+// content.html in V2 LayoutTree decks (and future themes that read by id)
+// can reference the resolved URL. Generation lives in stage's /api/imagine
+// endpoint, which content-hashes (prompt, aspect, quality) and caches
+// upstream-backed `data:image/...` payloads.
+const IMAGE_PROMPT_MAX = 1000;
+const IMAGE_ID_MAX = 64;
+const IMAGES_PER_CARD_MAX = 8;
+const IMAGE_VALID_ASPECTS = new Set(['portrait', 'landscape', 'square']);
+const IMAGE_VALID_QUALITIES = new Set(['fast', 'hd']);
+function validateCardImagesShape(images, cardIdx) {
+    if (images == null) return;
+    if (!Array.isArray(images)) {
+        throw new Error(`cards[${cardIdx}].images must be an array (or null)`);
+    }
+    if (images.length > IMAGES_PER_CARD_MAX) {
+        throw new Error(`cards[${cardIdx}].images too many (${images.length} > ${IMAGES_PER_CARD_MAX})`);
+    }
+    const seen = new Set();
+    images.forEach((img, j) => {
+        if (!img || typeof img !== 'object' || Array.isArray(img)) {
+            throw new Error(`cards[${cardIdx}].images[${j}] must be an object`);
+        }
+        if (typeof img.id !== 'string' || !img.id.trim()) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id required (non-empty string)`);
+        }
+        if (img.id.length > IMAGE_ID_MAX) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id too long (${img.id.length} > ${IMAGE_ID_MAX})`);
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(img.id)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id must match [a-zA-Z0-9_-]+`);
+        }
+        if (seen.has(img.id)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].id duplicate: ${img.id}`);
+        }
+        seen.add(img.id);
+        if (typeof img.prompt !== 'string' || !img.prompt.trim()) {
+            throw new Error(`cards[${cardIdx}].images[${j}].prompt required (non-empty string)`);
+        }
+        if (img.prompt.length > IMAGE_PROMPT_MAX) {
+            throw new Error(`cards[${cardIdx}].images[${j}].prompt too long (${img.prompt.length} > ${IMAGE_PROMPT_MAX})`);
+        }
+        if (img.aspect != null && !IMAGE_VALID_ASPECTS.has(img.aspect)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].aspect must be one of: ${[...IMAGE_VALID_ASPECTS].join(', ')}`);
+        }
+        if (img.quality != null && !IMAGE_VALID_QUALITIES.has(img.quality)) {
+            throw new Error(`cards[${cardIdx}].images[${j}].quality must be one of: ${[...IMAGE_VALID_QUALITIES].join(', ')}`);
+        }
+    });
+}
+
+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 +330,8 @@ function validatePaperSlideDeck(deck) {
                 throw new Error(`cards[${i}].voiceId too long (${card.voiceId.length} > 128)`);
             }
         }
+        validateVoiceoverShape(card.voiceover, i);
+        validateCardImagesShape(card.images, 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
@@ -290,10 +387,16 @@ function validatePaperSlideDeck(deck) {
 // / quote / stat / steps). Anything else is rejected so a renderer that
 // silently no-ops on unknown elements doesn't ship a broken video.
 
-const V2_ALLOWED_ELEMENTS = new Set(['heading', 'body', 'paper-figure', 'quote', 'stat', 'steps']);
+const V2_ALLOWED_ELEMENTS = new Set(['heading', 'body', 'paper-figure', 'quote', 'stat', 'steps', 'raw-html']);
 const V2_HEADING_MAX = 22;
 const V2_BODY_TEXT_MAX = 30;
 const V2_STAT_LABEL_MAX = 30;
+// raw-html is the open-ended escape hatch for themes / cards that want
+// arbitrary markup. The cap is generous enough for a styled inline figure
+// (a few paragraphs of HTML, maybe one inline data URI), but small enough
+// to keep deck.json human-editable and prevent an LLM run-on from blowing
+// past the watcher debounce.
+const V2_RAW_HTML_MAX = 4096;
 
 function validateV2Children(children, cardIdx, allowedElements, opts = {}) {
     if (!Array.isArray(children) || children.length === 0) {
@@ -375,6 +478,26 @@ function validateV2Children(children, cardIdx, allowedElements, opts = {}) {
                     );
                 }
             });
+        } else if (el.el === 'raw-html') {
+            // Schema-only support: validator accepts the element and the
+            // V2 normalizer (video-present/src/compositions/PaperSlide/
+            // layout-tree.ts) maps it to a `rawHtml` field on the V1
+            // normalized output. PaperSlide composition rendering of
+            // arbitrary HTML lands in a follow-up PR — for now the
+            // composition silently skips this element, so a deck with
+            // raw-html validates + saves + edits cleanly but renders blank
+            // until the JSX side is updated.
+            if (typeof el.html !== 'string') {
+                throw new Error(`cards[${cardIdx}].children[${j}].html must be string`);
+            }
+            if (!el.html.trim()) {
+                throw new Error(`cards[${cardIdx}].children[${j}].html empty`);
+            }
+            if (el.html.length > V2_RAW_HTML_MAX) {
+                throw new Error(
+                    `cards[${cardIdx}].children[${j}].html too long (${el.html.length} > ${V2_RAW_HTML_MAX})`
+                );
+            }
         }
     });
     return elements;
@@ -417,12 +540,22 @@ function validatePaperSlideDeckV2(deck) {
         if (!nonEmptyString(card.narration)) throw new Error(`cards[${i}].narration empty`);
 
         if (card.kind === 'title') {
-            const els = validateV2Children(card.children, i, new Set(['heading']), { maxChildren: 3 });
-            if (els.length === 0) throw new Error(`cards[${i}] title must have at least one heading`);
+            const els = validateV2Children(card.children, i, new Set(['heading', 'raw-html']), { maxChildren: 3 });
+            if (els.filter((e) => e.el === 'heading').length === 0) {
+                throw new Error(`cards[${i}] title must have at least one heading`);
+            }
         } else if (card.kind === 'body') {
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'paper-figure']), { maxChildren: 4 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'paper-figure', 'raw-html']), { maxChildren: 4 });
             const figs = els.filter((e) => e.el === 'paper-figure');
-            if (figs.length !== 1) throw new Error(`cards[${i}] body must contain exactly one paper-figure (got ${figs.length})`);
+            const rawEls = els.filter((e) => e.el === 'raw-html');
+            // A body card needs either a figure OR a raw-html block — raw
+            // HTML can stand in as the entire visual when the theme wants
+            // a custom panel instead of the canned figure renderer.
+            if (figs.length + rawEls.length !== 1) {
+                throw new Error(
+                    `cards[${i}] body must contain exactly one paper-figure OR one raw-html (got ${figs.length} figure + ${rawEls.length} raw-html)`
+                );
+            }
             const heads = els.filter((e) => e.el === 'heading');
             if (heads.length === 0) throw new Error(`cards[${i}] body must contain at least one heading`);
         } else if (card.kind === 'quote') {
@@ -431,21 +564,23 @@ function validatePaperSlideDeckV2(deck) {
             // stat / steps directly and ignores any non-discriminator elements
             // on these kinds). Discriminator element must still be present
             // exactly once. Cap at 3 children to keep output bounded.
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'quote']), { maxChildren: 3 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'quote', 'raw-html']), { maxChildren: 3 });
             const quoteEls = els.filter((e) => e.el === 'quote');
             if (quoteEls.length !== 1) throw new Error(`cards[${i}] quote card must contain exactly one quote element (got ${quoteEls.length})`);
             richCounts.quote += 1;
         } else if (card.kind === 'data') {
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'stat']), { maxChildren: 3 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'stat', 'raw-html']), { maxChildren: 3 });
             const statEls = els.filter((e) => e.el === 'stat');
             if (statEls.length !== 1) throw new Error(`cards[${i}] data card must contain exactly one stat element (got ${statEls.length})`);
             richCounts.data += 1;
         } else if (card.kind === 'list') {
-            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'steps']), { maxChildren: 3 });
+            const els = validateV2Children(card.children, i, new Set(['heading', 'body', 'steps', 'raw-html']), { maxChildren: 3 });
             const stepsEls = els.filter((e) => e.el === 'steps');
             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);
+        validateCardImagesShape(card.images, 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 +612,8 @@ module.exports = {
     validateQuotePayload,
     validateDataPayload,
     validateListPayload,
+    validateVoiceoverShape,
+    validateCardImagesShape,
     QUOTE_TEXT_MAX,
     QUOTE_ATTRIBUTION_MAX,
     DATA_VALUE_MAX,
@@ -485,4 +622,9 @@ module.exports = {
     LIST_ITEM_MAX_LEN,
     LIST_ITEM_MIN_COUNT,
     LIST_ITEM_MAX_COUNT,
+    VOICEOVER_TEXT_MAX,
+    IMAGE_PROMPT_MAX,
+    IMAGE_ID_MAX,
+    IMAGES_PER_CARD_MAX,
+    V2_RAW_HTML_MAX,
 };

package/lib/stage-core/image-gen.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * Stage → backend bridge for AI image generation (hunyuan-image).
+ *
+ * Mirror of tts-audition.js for the visual side: stage's per-card 🎨 button
+ * resolves `card.images[i] = { id, prompt, aspect?, quality? }`, hashes the
+ * generation recipe, and either returns a cached PNG/JPG or asks the backend
+ * to produce one. JWT lives on the server (same posture as cloud-render /
+ * audition).
+ *
+ * Public surface:
+ *   createImageGenClient({ apiBase?, tokenLoader?, cacheDir?, fetchImpl? })
+ *     → { imagine({ prompt, aspect, quality }), cacheDir }
+ *
+ * Cache layout: <cacheDir>/<sha256(prompt|aspect|quality)>.<ext>
+ * Default cacheDir: ~/.config/voxflow/stage-image-cache/ — global so a
+ * prompt repeated across decks resolves to one file on disk.
+ *
+ * Backend contract: POST /api/image/generate { prompt, ratio, quality }
+ *   → { code: 'success', image: 'data:image/png;base64,...', quota }
+ *   We parse the data URL, persist the raw bytes, and serve them with the
+ *   declared MIME so <img src> works in the browser without a base64 hop.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const http = require('http');
+const https = require('https');
+
+const { API_BASE } = require('../core/config');
+const { readCachedToken } = require('../core/auth');
+
+const DEFAULT_TIMEOUT_MS = 180_000;          // backend hunyuan-image takes 30-90s p95
+const DEFAULT_ASPECT = 'portrait';            // 9:16 matches Slice frame
+const DEFAULT_QUALITY = 'fast';               // 200-quota tier; 'hd' is 500
+// Catalog references — surfaced so the stage UI can show "🎨 costs N quota"
+// without an extra round-trip. Authoritative deduction is server-side.
+const IMAGE_GEN_COST_FAST = 200;
+const IMAGE_GEN_COST_HD = 500;
+
+function defaultCacheDir() {
+  return path.join(os.homedir(), '.config', 'voxflow', 'stage-image-cache');
+}
+
+function cacheKey({ prompt, aspect, quality }) {
+  // Stable content hash — every parameter that affects image output is
+  // included so the same (prompt, aspect, quality) maps to the same file.
+  const h = crypto.createHash('sha256');
+  h.update(prompt);
+  h.update(' ');
+  h.update(aspect);
+  h.update(' ');
+  h.update(quality);
+  return h.digest('hex');
+}
+
+function extensionFor(mime) {
+  // Backend hunyuan-image currently returns PNG; map other common MIMEs in
+  // case the provider swap underneath produces JPEG / WebP.
+  if (mime === 'image/png') return 'png';
+  if (mime === 'image/jpeg' || mime === 'image/jpg') return 'jpg';
+  if (mime === 'image/webp') return 'webp';
+  return 'bin';
+}
+
+function cachePath(dir, key, ext) {
+  return path.join(dir, `${key}.${ext}`);
+}
+
+function parseDataUrl(dataUrl) {
+  if (typeof dataUrl !== 'string') return null;
+  // RFC 2397 base64 form: data:<mime>;base64,<bytes>
+  const m = /^data:([^;,]+);base64,(.+)$/.exec(dataUrl);
+  if (!m) return null;
+  let buf;
+  try { buf = Buffer.from(m[2], 'base64'); }
+  catch { return null; }
+  if (!buf.length) return null;
+  return { mime: m[1].toLowerCase(), buf };
+}
+
+function requestJson(targetUrl, opts = {}, body = null, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(targetUrl);
+    const mod = u.protocol === 'https:' ? https : http;
+    const headers = Object.assign({}, opts.headers || {});
+    let payload = null;
+    if (body !== null && body !== undefined) {
+      payload = Buffer.from(JSON.stringify(body), 'utf8');
+      headers['Content-Type'] = 'application/json';
+      headers['Content-Length'] = payload.length;
+    }
+    const req = mod.request({
+      hostname: u.hostname,
+      port: u.port || (u.protocol === 'https:' ? 443 : 80),
+      path: u.pathname + u.search,
+      method: opts.method || 'GET',
+      headers,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed = null;
+        try { parsed = JSON.parse(raw); } catch { /* keep null */ }
+        resolve({ status: res.statusCode, data: parsed });
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => { req.destroy(new Error(`upstream timeout after ${timeoutMs}ms`)); });
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.apiBase=API_BASE]
+ * @param {() => ({access_token:string}|null)} [opts.tokenLoader]
+ * @param {string} [opts.cacheDir]
+ * @param {(args:object) => Promise<{status:number, data:object|null}>} [opts.fetchImpl]
+ *   Test injection point — receives `{ prompt, ratio, quality, headers }`.
+ * @returns {{ imagine: (params:object) => Promise<object>, cacheDir: string }}
+ */
+function createImageGenClient(opts = {}) {
+  const apiBase = (opts.apiBase || API_BASE).replace(/\/$/, '');
+  const tokenLoader = typeof opts.tokenLoader === 'function' ? opts.tokenLoader : readCachedToken;
+  const cacheDir = opts.cacheDir || defaultCacheDir();
+  const fetchImpl = typeof opts.fetchImpl === 'function' ? opts.fetchImpl : null;
+
+  try { fs.mkdirSync(cacheDir, { recursive: true }); } catch { /* best-effort */ }
+
+  function authHeaders() {
+    const cached = tokenLoader();
+    if (!cached || !cached.access_token) return null;
+    return { Authorization: 'Bearer ' + cached.access_token };
+  }
+
+  async function imagine({ prompt, aspect, quality } = {}) {
+    if (typeof prompt !== 'string' || !prompt.trim()) {
+      return { code: 'invalid_prompt', message: 'prompt required (non-empty string)' };
+    }
+    const asp = (aspect === 'portrait' || aspect === 'landscape' || aspect === 'square') ? aspect : DEFAULT_ASPECT;
+    const qual = (quality === 'fast' || quality === 'hd') ? quality : DEFAULT_QUALITY;
+    const key = cacheKey({ prompt, aspect: asp, quality: qual });
+
+    // Cache check — same recipe = same bytes. Walk known extensions so a
+    // stored PNG is found whether the cache layer tracks the MIME or not.
+    for (const ext of ['png', 'jpg', 'webp', 'bin']) {
+      const fp = cachePath(cacheDir, key, ext);
+      try {
+        const buf = fs.readFileSync(fp);
+        const mime = ({ png: 'image/png', jpg: 'image/jpeg', webp: 'image/webp', bin: 'application/octet-stream' })[ext];
+        return {
+          code: 'success',
+          buf,
+          contentType: mime,
+          fromCache: true,
+          cacheKey: key,
+          ext,
+        };
+      } catch { /* try next ext */ }
+    }
+
+    const headers = authHeaders();
+    if (!headers) {
+      return { code: 'not_logged_in', message: 'Run `voxflow login` first.' };
+    }
+
+    let r;
+    try {
+      if (fetchImpl) {
+        r = await fetchImpl({ prompt: prompt.trim(), ratio: asp, quality: qual, headers });
+      } else {
+        r = await requestJson(`${apiBase}/api/image/generate`, { method: 'POST', headers }, {
+          prompt: prompt.trim(),
+          ratio: asp,
+          quality: qual,
+        });
+      }
+    } catch (err) {
+      return { code: 'network_error', message: err.message || String(err) };
+    }
+
+    if (r.status === 401) return { code: 'not_logged_in', message: 'Token expired — run `voxflow login`.' };
+    if (r.status === 402 || r.status === 429) return { code: 'quota_exceeded', message: r.data?.message || 'Insufficient quota' };
+    if (r.status >= 400 || !r.data || r.data.code !== 'success') {
+      return {
+        code: r.data?.code || 'imagine_failed',
+        message: r.data?.message || `HTTP ${r.status}`,
+      };
+    }
+    const parsed = parseDataUrl(r.data.image);
+    if (!parsed) {
+      return { code: 'imagine_failed', message: 'response missing or malformed image data URL' };
+    }
+    const ext = extensionFor(parsed.mime);
+    const filePath = cachePath(cacheDir, key, ext);
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+      fs.writeFileSync(tmp, parsed.buf);
+      fs.renameSync(tmp, filePath);
+    } catch {
+      try { fs.unlinkSync(tmp); } catch { /* */ }
+    }
+    return {
+      code: 'success',
+      buf: parsed.buf,
+      contentType: parsed.mime,
+      fromCache: false,
+      cacheKey: key,
+      ext,
+    };
+  }
+
+  return { imagine, cacheDir };
+}
+
+module.exports = {
+  createImageGenClient,
+  cacheKey,
+  cachePath,
+  defaultCacheDir,
+  parseDataUrl,
+  extensionFor,
+  IMAGE_GEN_COST_FAST,
+  IMAGE_GEN_COST_HD,
+  DEFAULT_ASPECT,
+  DEFAULT_QUALITY,
+};

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

@@ -45,6 +45,9 @@ const {
   THEME_TO_DECK_ID,
   DEFAULT_THEME,
 } = require('../commands/slice-render');
+const { createTtsAuditionClient } = require('./tts-audition');
+const { createImageGenClient } = require('./image-gen');
+const { startVoiceoverServer, prepareVoiceovers, prepareImages } = 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
@@ -158,10 +161,92 @@ function startLocalRender(opts) {
 
 async function runRender({ job, deck, onProgress, onDone, onError }) {
   const { jobId, outputPath, deckId } = job;
+  let voiceoverServer = null;
   try {
     job.state = 'preparing';
+
+    // ─── Voiceover + Image prep (Phase 1 + Phase B) ─────────────────────
+    // Stage's Render button defaults to BOTH audio + AI image generation.
+    // Users in stage are iterating and expect a fully-rendered preview;
+    // hitting the cache makes re-renders effectively free for content they
+    // already auditioned / regenerated. Either pass can fail to silent
+    // fallback without aborting the render — failures land in
+    // job.voiceoverSkipped / job.imageSkipped so the UI can surface the
+    // reason post hoc.
+    let voiceoverByIdx = {};
+    let imageByIdx = {};
+    let voiceoverSkipped = [];
+    let imageSkipped = [];
+    try {
+      const audClient = createTtsAuditionClient();
+      const imgClient = createImageGenClient();
+      voiceoverServer = await startVoiceoverServer({
+        cacheDir: audClient.cacheDir,
+        imageCacheDir: imgClient.cacheDir,
+      });
+      const voPrep = 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 = voPrep.byIdx;
+      voiceoverSkipped = voPrep.skipped;
+
+      const imgPrep = await prepareImages({
+        deck,
+        imgClient,
+        baseUrl: voiceoverServer.url,
+        onProgress: (p) => {
+          if (typeof onProgress === 'function') {
+            try {
+              onProgress({
+                jobId,
+                progress: 0,
+                framesRendered: 0,
+                framesTotal: 0,
+                phase: 'image',
+                imageIndex: p.cardIdx + 1,
+                imageTotal: p.total,
+                imageFromCache: p.fromCache,
+              });
+            } catch { /* swallow */ }
+          }
+        },
+      });
+      imageByIdx = imgPrep.byIdx;
+      imageSkipped = imgPrep.skipped;
+    } catch (err) {
+      // Media prep failure is non-fatal — fall back to silent + no-AI
+      // images so a TTS / image outage still produces an mp4.
+      voiceoverSkipped = [{ cardIdx: -1, reason: 'media_prep_failed', message: err.message }];
+      if (voiceoverServer) {
+        try { await voiceoverServer.close(); } catch { /* */ }
+        voiceoverServer = null;
+      }
+    }
+    job.voiceoverCount = Object.keys(voiceoverByIdx).length;
+    job.voiceoverSkipped = voiceoverSkipped;
+    job.imageCount = Object.keys(imageByIdx).length;
+    job.imageSkipped = imageSkipped;
+
     const serveUrl = resolveServeUrl();
-    const inputProps = buildInputProps(deck);
+    const inputProps = buildInputProps(deck, { voiceoverByIdx, imageByIdx });
 
     const renderer = loadRenderer();
     job.coldStart = !chromeBinaryExists();
@@ -234,6 +319,12 @@ async function runRender({ job, deck, onProgress, onDone, onError }) {
     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 */ }
+    }
   }
 }