voxflow 1.15.2 → 1.15.4

package/lib/stage-core/server.js

@@ -32,8 +32,28 @@ const { findAvailablePort } = require('./port');
  *   and GET /api/quota-balance — all proxies to the upstream API. Shape:
  *   { submit(deck), status(jobId), quota() }. Lets users go from "deck I
  *   like" → mp4 without leaving stage; the proxy keeps the JWT off the page.
+ * @param {object} [opts.localRender] Optional local-render handle.
+ *   If provided, exposes POST /api/render-local and GET /api/render-local/:id/status.
+ *   Shape: { start({onProgress, onDone, onError, output}), status(jobId) }.
+ *   Used to render mp4 with `@remotion/renderer` *without* any cloud
+ *   round-trip — required for offline-first authoring (skill-driven users
+ *   may never have run `voxflow login`). Reuses the same SSE channel
+ *   `subscribe` feeds for progress fan-out.
+ * @param {object} [opts.deckSaver] Optional inline-edit handle.
+ *   If provided, exposes POST /api/deck → write new deck JSON to disk.
+ *   Shape: { save(deck) → { ok:true } | { ok:false, errors:[...] } }.
+ *   The file watcher picks up the resulting change and broadcasts deck SSE,
+ *   so no extra fan-out is needed here.
+ * @param {(event:object) => void} [opts.publishEvent]
+ *   Optional event-bus publisher — when provided, local-render progress
+ *   events are fanned out through the same `subscribe` channel as deck
+ *   events, so the page can listen on one EventSource for everything.
  * @param {number} [opts.preferredPort=5180]
  * @param {number} [opts.maxPortTries=10]
+ * @param {boolean} [opts.tokenAvailable]
+ *   Optional flag baked into the boot snapshot returned by GET /api/auth-state.
+ *   The page reads this once on load to decide whether to emphasise the
+ *   "local" or "cloud" render button. Cheap; no JWT ever leaves the server.
  * @returns {Promise<{server:http.Server, port:number, url:string, close:() => Promise<void>}>}
  */
 async function startStageServer(opts) {
@@ -43,6 +63,11 @@ async function startStageServer(opts) {
     subscribe,
     snapshots = null,
     cloudRender = null,
+    localRender = null,
+    deckSaver = null,
+    audition = null,
+    publishEvent = null,
+    tokenAvailable = false,
     preferredPort = 5180,
     maxPortTries = 10,
   } = opts;
@@ -219,8 +244,19 @@ async function startStageServer(opts) {
     function statusForCode(code) {
       if (code === 'not_logged_in') return 401;
       if (code === 'quota_exceeded') return 402;
-      if (code === 'invalid_deck' || code === 'invalid_id') return 400;
-      if (code === 'job_not_found') return 404;
+      if (
+        code === 'invalid_deck' ||
+        code === 'invalid_id' ||
+        code === 'invalid_card_index' ||
+        code === 'invalid_voice' ||
+        code === 'invalid_text'
+      ) return 400;
+      if (
+        code === 'job_not_found' ||
+        code === 'no_deck' ||
+        code === 'card_not_found'
+      ) return 404;
+      if (code === 'voiceover_disabled') return 409;
       if (code === 'success') return 200;
       return 502; // upstream error
     }
@@ -273,6 +309,196 @@ async function startStageServer(opts) {
       return;
     }
 
+    // ─── Auth-state probe ───────────────────────────────────────────────────
+    // Single GET so the page can decide local-vs-cloud render emphasis on
+    // load. No JWT or refresh-token bytes ever leave the server.
+    if (req.method === 'GET' && req.url === '/api/auth-state') {
+      sendJson(200, { code: 'success', tokenAvailable: !!tokenAvailable });
+      return;
+    }
+
+    // ─── Local render (offline, @remotion/renderer) ─────────────────────────
+    // POST /api/render-local              → start a job, return { jobId }
+    // GET  /api/render-local/:id/status   → poll status
+    //
+    // Progress + done events are pushed onto the deck SSE channel via
+    // publishEvent so the page listens on a single EventSource.
+    if (localRender && req.method === 'POST' && req.url === '/api/render-local') {
+      const chunks = [];
+      let total = 0;
+      const MAX = 64 * 1024;
+      req.on('data', (c) => {
+        total += c.length;
+        if (total > MAX) { req.destroy(); return; }
+        chunks.push(c);
+      });
+      req.on('end', () => {
+        let body = {};
+        const raw = Buffer.concat(chunks).toString('utf8');
+        if (raw) {
+          try { body = JSON.parse(raw); }
+          catch { return sendJson(400, { code: 'bad_json', message: 'render-local body must be JSON' }); }
+        }
+        const output = typeof body.output === 'string' && body.output.trim()
+          ? body.output.trim() : null;
+
+        let started;
+        try {
+          started = localRender.start({
+            output,
+            onProgress(p) {
+              if (typeof publishEvent === 'function') {
+                publishEvent({
+                  type: 'render-local-progress',
+                  jobId: p.jobId,
+                  progress: p.progress,
+                  framesRendered: p.framesRendered,
+                  framesTotal: p.framesTotal,
+                  ts: Date.now(),
+                });
+              }
+            },
+            onDone(d) {
+              if (typeof publishEvent === 'function') {
+                publishEvent({
+                  type: 'render-local-done',
+                  jobId: d.jobId,
+                  outputPath: d.outputPath,
+                  totalMs: d.totalMs,
+                  sizeBytes: d.sizeBytes,
+                  ts: Date.now(),
+                });
+              }
+            },
+            onError(e) {
+              if (typeof publishEvent === 'function') {
+                publishEvent({
+                  type: 'render-local-error',
+                  jobId: e.jobId,
+                  message: e.message,
+                  ts: Date.now(),
+                });
+              }
+            },
+          });
+        } catch (err) {
+          return sendJson(400, {
+            code: err.code || 'render_local_failed',
+            message: err.message || 'could not start local render',
+          });
+        }
+        return sendJson(200, {
+          code: 'success',
+          jobId: started.jobId,
+          outputPath: started.outputPath,
+        });
+      });
+      return;
+    }
+
+    if (localRender && req.method === 'GET' && req.url.startsWith('/api/render-local/')) {
+      // expected: /api/render-local/:id/status
+      const rest = req.url.slice('/api/render-local/'.length);
+      const slashIdx = rest.indexOf('/');
+      const id = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
+      const tail = slashIdx === -1 ? '' : rest.slice(slashIdx + 1);
+      if (!id || tail !== 'status') {
+        sendJson(404, { code: 'not_found', message: `No route: ${req.method} ${req.url}` });
+        return;
+      }
+      const status = localRender.status(decodeURIComponent(id));
+      if (!status) {
+        sendJson(404, { code: 'job_not_found', message: `No local-render job: ${id}` });
+        return;
+      }
+      sendJson(200, { code: 'success', ...status });
+      return;
+    }
+
+    // ─── TTS audition (per-card ▶) ──────────────────────────────────────────
+    // GET /api/audition?card=<int>[&voice=<id>]
+    //   Resolves card.voiceover/voiceId/narration → calls /api/tts/synthesize
+    //   via the audition bridge → streams audio bytes (default mp3). Content
+    //   hash caches identical (voice, text, speed, format) so iteration is
+    //   free after the first call. The page never sees the JWT.
+    if (audition && req.method === 'GET' && req.url.startsWith('/api/audition')) {
+      let parsed;
+      try { parsed = new URL(req.url, `http://127.0.0.1:${port}`); }
+      catch {
+        return sendJson(400, { code: 'bad_request', message: 'invalid /api/audition url' });
+      }
+      const cardIndexStr = parsed.searchParams.get('card');
+      const cardIndex = Number.parseInt(cardIndexStr, 10);
+      if (!Number.isInteger(cardIndex) || cardIndex < 0) {
+        return sendJson(400, {
+          code: 'invalid_card_index',
+          message: '?card= must be a non-negative integer',
+        });
+      }
+      const voiceOverride = parsed.searchParams.get('voice') || undefined;
+      (async () => {
+        let result;
+        try {
+          result = await audition.play({ cardIndex, voiceOverride });
+        } catch (err) {
+          return sendJson(502, { code: 'upstream_error', message: err.message });
+        }
+        if (result.code !== 'success') {
+          return sendJson(statusForCode(result.code), result);
+        }
+        res.writeHead(200, {
+          'Content-Type': result.contentType || 'audio/mpeg',
+          'Content-Length': result.buf.length,
+          'Cache-Control': 'no-store',
+          'X-Audition-Cache': result.fromCache ? 'HIT' : 'MISS',
+          'X-Audition-Key': result.cacheKey || '',
+        });
+        res.end(result.buf);
+      })();
+      return;
+    }
+
+    // ─── Inline deck save (Task B) ──────────────────────────────────────────
+    // POST /api/deck  body: full deck JSON  → validates + writes to disk.
+    // The file watcher picks up the write and broadcasts the deck event, so
+    // the page hot-reloads via the same path as an external editor save.
+    if (deckSaver && req.method === 'POST' && req.url === '/api/deck') {
+      const chunks = [];
+      let total = 0;
+      // Decks are small (5-8 cards, ~5 KB). 256 KB cap is plenty headroom
+      // even with V2 layout-tree decks while still defending against pasted
+      // monsters.
+      const MAX = 256 * 1024;
+      req.on('data', (c) => {
+        total += c.length;
+        if (total > MAX) { req.destroy(); return; }
+        chunks.push(c);
+      });
+      req.on('end', () => {
+        let body;
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); }
+        catch { return sendJson(400, { code: 'bad_json', message: 'deck body must be JSON' }); }
+        const deck = body && body.deck;
+        if (!deck || typeof deck !== 'object') {
+          return sendJson(400, { code: 'invalid_deck', message: 'body.deck (object) required' });
+        }
+        let result;
+        try { result = deckSaver.save(deck); }
+        catch (err) {
+          return sendJson(500, { code: 'deck_save_failed', message: err.message || 'save error' });
+        }
+        if (!result || result.ok !== true) {
+          return sendJson(400, {
+            code: 'invalid_deck',
+            message: (result && result.message) || 'deck failed validation',
+            errors: (result && result.errors) || undefined,
+          });
+        }
+        return sendJson(200, { code: 'success' });
+      });
+      return;
+    }
+
     if (req.method === 'GET' && req.url === '/events') {
       res.writeHead(200, {
         'Content-Type': 'text/event-stream; charset=utf-8',

package/lib/stage-core/voiceover-mux.js

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Per-card voiceover audio prep for local Remotion render.
+ *
+ * Reuses the audition cache (~/.config/voxflow/stage-tts-cache/) so a card
+ * the user just listened to via stage's ▶ button doesn't get re-synthesized
+ * at render time. Spins up a tiny localhost HTTP server (auto-picked port)
+ * that serves audio files to the headless Chromium Remotion launches; the
+ * Remotion composition fetches voiceoverSrc URLs from this server while
+ * rendering. Tear the server down after renderMedia() resolves.
+ *
+ *   const aud = createTtsAuditionClient();
+ *   const server = await startVoiceoverServer({ cacheDir: aud.cacheDir });
+ *   const { byIdx, skipped } = await prepareVoiceovers({
+ *     deck, auditionClient: aud, baseUrl: server.url, onProgress,
+ *   });
+ *   // buildInputProps reads byIdx and threads URLs into card.slide.voiceoverSrc
+ *   await renderMedia({ inputProps: buildInputProps(deck, { voiceoverByIdx: byIdx }), ... });
+ *   await server.close();
+ *
+ * When auth is unavailable (no token in CLI cache), prepareVoiceovers
+ * returns an empty map quietly — the resulting mp4 is the Phase 0 silent
+ * video. Callers branch on the empty map to surface a hint to the user.
+ */
+
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+
+const { contentTypeFor } = require('./tts-audition');
+const { SYNTHESIZE_DEFAULTS } = require('../core/config');
+
+/**
+ * Tiny localhost HTTP server serving the audition cache directory.
+ * Only responds to GET /audio/<filename>; everything else is 404. Path
+ * traversal (.. or nested directories) is rejected up front since the
+ * cache layout is intentionally flat.
+ *
+ * @param {object} opts
+ * @param {string} opts.cacheDir         Directory containing <hash>.mp3 files.
+ * @param {number} [opts.preferredPort=0]  0 lets the OS pick a free port.
+ * @returns {Promise<{server, port, url, close}>}
+ */
+async function startVoiceoverServer({ cacheDir, preferredPort = 0 }) {
+  if (typeof cacheDir !== 'string' || !cacheDir) {
+    throw new Error('startVoiceoverServer: cacheDir required');
+  }
+  const server = http.createServer((req, res) => {
+    if (req.method !== 'GET' || !req.url.startsWith('/audio/')) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('not found');
+      return;
+    }
+    const fname = req.url.slice('/audio/'.length).split('?')[0];
+    // Defense in depth — reject path traversal even on a localhost-only
+    // server. The audition cache is a flat dir of <sha256>.<ext> filenames.
+    if (fname === '' || fname.includes('/') || fname.includes('\\') || fname.includes('..')) {
+      res.writeHead(400, { 'Content-Type': 'text/plain' });
+      res.end('bad filename');
+      return;
+    }
+    const filePath = path.join(cacheDir, fname);
+    fs.stat(filePath, (statErr, st) => {
+      if (statErr || !st.isFile()) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('not found');
+        return;
+      }
+      const ext = path.extname(fname).slice(1);
+      const ctype = contentTypeFor(ext);
+      res.writeHead(200, {
+        'Content-Type': ctype,
+        'Content-Length': st.size,
+        'Cache-Control': 'no-store',
+      });
+      fs.createReadStream(filePath).pipe(res);
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(preferredPort, '127.0.0.1', () => {
+      server.removeListener('error', reject);
+      resolve();
+    });
+  });
+  const port = server.address().port;
+  return {
+    server,
+    port,
+    url: `http://127.0.0.1:${port}`,
+    async close() {
+      await new Promise((resolve) => server.close(() => resolve()));
+    },
+  };
+}
+
+/**
+ * Resolve + synthesize (or cache-hit) one mp3 per card, return a map of
+ * { cardIdx: audio URL } that buildInputProps threads into voiceoverSrc.
+ *
+ * @param {object} opts
+ * @param {object} opts.deck                       Validator-shaped deck.
+ * @param {{audition: Function}} opts.auditionClient
+ *   Same client stage's /api/audition uses. Shares the on-disk cache so a
+ *   card the user previewed in the browser doesn't burn quota again at
+ *   render time.
+ * @param {string} opts.baseUrl                    e.g. http://127.0.0.1:54321
+ * @param {(p:object) => void} [opts.onProgress]
+ *   Called once per resolved card: { cardIdx, total, fromCache, voiceId, textLen }.
+ *   Use this to print a one-line "voiceover N/M (cache hit)" log so the
+ *   user knows TTS is happening before the renderer takes over.
+ * @returns {Promise<{ byIdx: Record<number,string>, skipped: Array<{cardIdx, reason, message?}> }>}
+ *   skipped reasons: missing-card | voiceover-disabled | no-text |
+ *   not_logged_in | quota_exceeded | tts_failed | network_error | invalid_voice
+ */
+async function prepareVoiceovers({ deck, auditionClient, baseUrl, onProgress }) {
+  const byIdx = {};
+  const skipped = [];
+  if (!deck || !Array.isArray(deck.cards)) return { byIdx, skipped };
+  if (!auditionClient || typeof auditionClient.audition !== 'function') {
+    throw new Error('prepareVoiceovers: auditionClient.audition is required');
+  }
+  if (typeof baseUrl !== 'string' || !baseUrl) {
+    throw new Error('prepareVoiceovers: baseUrl is required');
+  }
+  const cards = deck.cards;
+
+  for (let i = 0; i < cards.length; i++) {
+    const card = cards[i];
+    if (!card) { skipped.push({ cardIdx: i, reason: 'missing-card' }); continue; }
+    const vo = card.voiceover || {};
+    if (vo.enabled === false) {
+      skipped.push({ cardIdx: i, reason: 'voiceover-disabled' });
+      continue;
+    }
+    const text = (typeof vo.text === 'string' && vo.text.trim())
+      ? vo.text
+      : card.narration;
+    if (typeof text !== 'string' || !text.trim()) {
+      skipped.push({ cardIdx: i, reason: 'no-text' });
+      continue;
+    }
+    const voiceId = vo.voiceId || card.voiceId || SYNTHESIZE_DEFAULTS.voice;
+    const speed = typeof vo.rate === 'number' ? vo.rate : 1.0;
+    const format = 'mp3';
+
+    let r;
+    try {
+      r = await auditionClient.audition({ voiceId, text, speed, format });
+    } catch (err) {
+      skipped.push({ cardIdx: i, reason: 'network_error', message: err.message || String(err) });
+      continue;
+    }
+    if (r.code !== 'success') {
+      skipped.push({ cardIdx: i, reason: r.code, message: r.message });
+      // not_logged_in / quota_exceeded → bail early so the user sees one
+      // clear message rather than N copies of the same root cause.
+      if (r.code === 'not_logged_in' || r.code === 'quota_exceeded') break;
+      continue;
+    }
+    const fname = `${r.cacheKey}.${format}`;
+    byIdx[i] = `${baseUrl.replace(/\/$/, '')}/audio/${fname}`;
+    if (typeof onProgress === 'function') {
+      try {
+        onProgress({
+          cardIdx: i,
+          total: cards.length,
+          fromCache: !!r.fromCache,
+          voiceId,
+          textLen: text.length,
+        });
+      } catch { /* swallow consumer errors */ }
+    }
+  }
+
+  return { byIdx, skipped };
+}
+
+module.exports = {
+  startVoiceoverServer,
+  prepareVoiceovers,
+};