voxflow 1.15.3 → 1.15.4

package/lib/stage-ui/slice/template.js

@@ -547,6 +547,49 @@ function renderSliceStageHtml({ sourcePath, port }) {
     .deck-toolbar button.copied {
       color: var(--good); border-color: var(--good);
     }
+    /* ─── Audition (▶) — voice picker + per-card play + status ────────────── */
+    .toolbar-divider {
+      width: 1px; align-self: stretch;
+      background: var(--border); margin: 2px 4px;
+    }
+    .voice-picker {
+      display: inline-flex; align-items: center; gap: 6px;
+      border: 1px solid var(--border); border-radius: 8px;
+      padding: 0 8px; font-size: 12px;
+    }
+    .voice-picker:focus-within { border-color: var(--accent); }
+    .voice-picker-icon { color: var(--muted); font-size: 12px; }
+    #voice-picker-input {
+      appearance: none; border: 0; background: transparent;
+      font: inherit; color: var(--text); font-size: 12px;
+      padding: 6px 0; width: 180px; outline: none;
+    }
+    .stage-card .card-actions button[data-action="audition"] .audition-icon {
+      display: inline-block; margin-right: 4px; font-size: 9px;
+    }
+    .stage-card .card-actions button[data-action="audition"].playing {
+      background: rgba(88,81,184,0.92); color: #fff;
+    }
+    .stage-card .card-actions button[data-action="audition"].loading {
+      background: rgba(0,0,0,0.45); color: #fff; cursor: progress;
+    }
+    .stage-card .card-actions button[data-action="audition"].error {
+      background: rgba(239,68,68,0.92); color: #fff;
+    }
+    .audition-status {
+      display: inline-flex; align-items: center;
+      font-size: 11px; color: var(--muted);
+      padding: 4px 10px; border-radius: 6px;
+      max-width: 320px;
+      overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    }
+    .audition-status[data-state="loading"] { color: var(--accent); }
+    .audition-status[data-state="cache"] {
+      color: var(--good); background: rgba(34,197,94,0.08);
+    }
+    .audition-status[data-state="error"] {
+      color: #b91c1c; background: rgba(239,68,68,0.08);
+    }
 
     .selection-fab {
       position: fixed; z-index: 50;
@@ -765,7 +808,14 @@ function renderSliceStageHtml({ sourcePath, port }) {
         <button id="copy-json-btn" type="button" disabled title="Copy raw deck.json to clipboard">Copy JSON</button>
         <button id="download-json-btn" type="button" disabled title="Save deck.json to disk">Download .json</button>
         <button id="copy-md-btn" type="button" disabled title="Copy as Markdown — paste into Notion / blog / 飞书">Copy as Markdown</button>
+        <span class="toolbar-divider" aria-hidden="true"></span>
+        <label class="voice-picker" title="Voice ID override (empty = let card.voiceover.voiceId or default win)">
+          <span class="voice-picker-icon" aria-hidden="true">♪</span>
+          <input id="voice-picker-input" type="text" placeholder="Voice (default)" spellcheck="false" autocomplete="off" aria-label="Voice override for audition" />
+        </label>
+        <span class="audition-status" id="audition-status" hidden aria-live="polite"></span>
       </div>
+      <audio id="audition-audio" preload="none"></audio>
       <div id="cards-pane" class="empty">Waiting for deck…</div>
     </section>
     <section>
@@ -1018,6 +1068,123 @@ function renderSliceStageHtml({ sourcePath, port }) {
         copyTextToClipboard(formatCardAsText(card), btn);
       });
 
+      // ─── Per-card Audition (▶) — fetch /api/audition, play in <audio>. ────
+      // Voice override comes from the toolbar voice-picker input; empty input
+      // means let the server bridge resolve via the documented precedence
+      // (card.voiceover.voiceId → card.voiceId → SYNTHESIZE_DEFAULTS.voice).
+      // Status bar surfaces loading / cache HIT / upstream error so the user
+      // can spot quota or auth issues without opening browser devtools.
+      var auditionAudio = document.getElementById('audition-audio');
+      var auditionStatus = document.getElementById('audition-status');
+      var voicePickerInput = document.getElementById('voice-picker-input');
+      var currentAuditionBtn = null;
+
+      function setAuditionStatus(state, message) {
+        if (!auditionStatus) return;
+        if (!state) {
+          auditionStatus.hidden = true;
+          auditionStatus.removeAttribute('data-state');
+          auditionStatus.textContent = '';
+          return;
+        }
+        auditionStatus.hidden = false;
+        auditionStatus.dataset.state = state;
+        auditionStatus.textContent = message || '';
+      }
+
+      function resetAuditionBtn(btn) {
+        if (!btn) return;
+        btn.classList.remove('playing', 'loading', 'error');
+        var icon = btn.querySelector('.audition-icon');
+        if (icon) icon.textContent = '▶';
+      }
+
+      cardsPane.addEventListener('click', function (ev) {
+        var btn = ev.target.closest && ev.target.closest('[data-action="audition"]');
+        if (!btn || !currentDeck) return;
+        var idx = parseInt(btn.getAttribute('data-card-index'), 10);
+        if (!Number.isFinite(idx)) return;
+
+        // Click on the currently playing button = stop + reset.
+        if (currentAuditionBtn === btn && !auditionAudio.paused) {
+          auditionAudio.pause();
+          auditionAudio.currentTime = 0;
+          resetAuditionBtn(btn);
+          currentAuditionBtn = null;
+          setAuditionStatus(null);
+          return;
+        }
+        // Reset a previously playing button (if any) when starting a new one.
+        if (currentAuditionBtn && currentAuditionBtn !== btn) {
+          resetAuditionBtn(currentAuditionBtn);
+        }
+
+        currentAuditionBtn = btn;
+        btn.classList.remove('error');
+        btn.classList.add('loading');
+        var icon = btn.querySelector('.audition-icon');
+        if (icon) icon.textContent = '⟳';
+        setAuditionStatus('loading', 'Synthesizing card ' + (idx + 1) + '…');
+
+        var voiceOverride = (voicePickerInput && voicePickerInput.value.trim()) || '';
+        var url = '/api/audition?card=' + encodeURIComponent(idx)
+          + (voiceOverride ? '&voice=' + encodeURIComponent(voiceOverride) : '');
+
+        fetch(url, { method: 'GET', credentials: 'same-origin' })
+          .then(function (res) {
+            var cache = res.headers.get('X-Audition-Cache') || '';
+            if (!res.ok) {
+              return res.json().then(function (j) {
+                throw new Error((j && j.message) || ('HTTP ' + res.status));
+              }, function () {
+                throw new Error('HTTP ' + res.status);
+              });
+            }
+            return res.blob().then(function (blob) { return { blob: blob, cache: cache }; });
+          })
+          .then(function (out) {
+            var objectUrl = URL.createObjectURL(out.blob);
+            auditionAudio.src = objectUrl;
+            return auditionAudio.play().then(function () {
+              btn.classList.remove('loading');
+              btn.classList.add('playing');
+              if (icon) icon.textContent = '❚❚';
+              setAuditionStatus(
+                out.cache === 'HIT' ? 'cache' : 'loading',
+                out.cache === 'HIT' ? 'Cache hit — no quota used.' : 'Playing card ' + (idx + 1) + '.'
+              );
+            });
+          })
+          .catch(function (err) {
+            btn.classList.remove('loading', 'playing');
+            btn.classList.add('error');
+            if (icon) icon.textContent = '!';
+            setAuditionStatus('error', String(err && err.message || err));
+            setTimeout(function () {
+              if (currentAuditionBtn === btn) currentAuditionBtn = null;
+              resetAuditionBtn(btn);
+            }, 3000);
+          });
+      });
+
+      auditionAudio.addEventListener('ended', function () {
+        if (currentAuditionBtn) {
+          resetAuditionBtn(currentAuditionBtn);
+          currentAuditionBtn = null;
+        }
+        setAuditionStatus(null);
+      });
+      auditionAudio.addEventListener('error', function () {
+        if (currentAuditionBtn) {
+          currentAuditionBtn.classList.remove('loading', 'playing');
+          currentAuditionBtn.classList.add('error');
+          var ic = currentAuditionBtn.querySelector('.audition-icon');
+          if (ic) ic.textContent = '!';
+          currentAuditionBtn = null;
+        }
+        setAuditionStatus('error', 'Audio playback failed.');
+      });
+
       // For highlighting cards that just changed on hot-reload, we keep a
       // hash of each card's stringified JSON. On the next deck event we
       // diff per-index and add the just-changed CSS class to whichever
@@ -1117,6 +1284,10 @@ function renderSliceStageHtml({ sourcePath, port }) {
           + '<div class="body">' + titleHtml + '</div>'
           + '<div class="accent-bar"></div>'
           + '<div class="card-actions">'
+              + '<button type="button" data-action="audition" data-card-index="' + i + '"'
+              + ' aria-label="Audition card ' + (i + 1) + ' voiceover" title="Play TTS preview — uses card.voiceover or card.narration, costs 100 quota first time then cached">'
+              + '<span class="audition-icon" aria-hidden="true">▶</span>Audition'
+              + '</button>'
               + '<button type="button" data-action="copy-card" data-card-index="' + i + '"'
               + ' aria-label="Copy card ' + (i + 1) + ' as text">Copy text</button>'
           + '</div>'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.15.3",
+  "version": "1.15.4",
   "description": "AI audio content creation CLI — stories, podcasts, narration, dubbing, transcription, translation, and video translation with TTS",
   "bin": {
     "voxflow": "./dist/index.js"

package/skills/voxflow-slice/SKILL.md

@@ -145,6 +145,31 @@ All cards require a non-empty `narration` string (TTS reads this; 30–60 zh cha
 }
 ```
 
+### Optional per-card `voiceover` override
+
+Any card kind may carry a nested `voiceover` object to tune its audio
+track. All four sub-fields are optional inside an optional object —
+absent ⇒ the renderer uses the job-level default voice with
+`card.narration` at 1× speed (back-compat with Phase 0 silent decks).
+
+```jsonc
+{
+  "kind": "body",
+  "caption": "短字幕",
+  "narration": "默认是 TTS 朗读的文本",
+  "voiceover": {
+    "enabled": true,             // false → this card is silent in the mp4
+    "voiceId": "v-female-R2s4N9qJ", // overrides the job-level default voice
+    "text": "口播稿可以跟字幕不一样",  // overrides narration for TTS only (visible caption unaffected)
+    "rate": 1.1                  // [0.5, 2.0], default 1.0
+  }
+}
+```
+
+Validator caps: `voiceover.text` ≤ 500 chars; `rate ∈ [0.5, 2.0]`.
+Render-time resolution precedence:
+`voiceover.voiceId → card.voiceId → job-level default`.
+
 > **Source of truth**: `backend/services/paper-slide/deck-validator.js` — caps live at lines 39–46 (QUOTE_TEXT_MAX, DATA_VALUE_MAX, LIST_ITEM_MAX_LEN, etc.). Read it if anything below seems ambiguous.
 
 ### Controlled `figureKeyword` list
@@ -232,12 +257,59 @@ After writing `deck.json`, tell the user:
 ```
 Wrote deck.json (<N> cards, theme: <theme-id>). Next:
 
-  voxflow slice render deck.json --output out.mp4    # render mp4 locally (~30s)
-  voxflow slice stage  deck.json                     # live preview in browser
+  voxflow slice preview deck.json                    # browser preview + per-card audition + render button
+  voxflow slice render deck.json --output out.mp4    # one-shot mp4 from the terminal
 ```
 
 Do not run either command yourself unless the user asks.
 
+Both commands work fully offline for the visual side. **Audio (per-card
+TTS audition + render audio track) requires `voxflow login`** — 100 quota
+per unique `(voice, text)` clip, then cached at
+`~/.config/voxflow/stage-tts-cache/`. With no login, both commands fall
+back silently to a Phase-0-style silent video; pass `--no-audio` to
+`render` to suppress the audio pass entirely.
+
+## Multi-turn editing loop (Claude Code / Cursor / native `Edit`)
+
+When the user is iterating — "shorten card 2", "swap order", "different
+voice for card 3", "hear card 1 again" — they are **NOT** asking for a
+regen. Stay in this loop:
+
+```bash
+# Run once at the start of the session; auto-opens http://127.0.0.1:5180.
+# The page hot-reloads on every save of deck.json (~50 ms fs watcher).
+voxflow slice preview deck.json &
+```
+
+Then for every follow-up:
+
+| User intent | Your move | Cost |
+|---|---|---|
+| "card N is too long" | `Edit` `cards[N-1].caption` / `.narration` — page hot-reloads | 0 |
+| "swap card 2 and 3" | `Edit` the `cards` array order | 0 |
+| "different voice for card 3" | `Edit` `cards[2].voiceover.voiceId` — or tell user to paste a voiceId in the toolbar voice picker | 0 (Edit) |
+| "make card 4 silent" | `Edit` `cards[3].voiceover = { "enabled": false }` | 0 |
+| "口播说点不一样的" | `Edit` `cards[i].voiceover.text` so TTS reads override while caption stays | 0 |
+| "I want to hear card 3" | Tell user to click ▶ on card 3 in the browser; the toolbar shows cache hit / quota cost / error | 100 (first time per clip), 0 (cached) |
+| "render mp4" | Tell user: click **Render mp4 (local)** in the browser, OR `voxflow slice render deck.json` | TTS pass (cached if auditioned) + render |
+
+### Loop rules
+
+1. **Edit only the fields the user asked about.** Other cards must stay
+   byte-identical — the stage UI's diff highlight is the user's "what
+   changed" indicator. Touching extra fields breaks that signal.
+2. **Never re-run `voxflow slice <article>` during iteration** — that
+   costs 200 quota AND overwrites every user edit with a fresh LLM draft.
+3. **Re-validate after every save** by re-reading the file. If the user
+   says "page shows old content" or "red banner appeared", the JSON has a
+   syntax error (trailing comma, unbalanced quote) — open, fix, save.
+4. **Don't restart the preview server.** One process handles the whole
+   session; restarting wipes snapshot history.
+5. **Don't call `/api/audition` yourself.** It's user-driven via the ▶
+   button. Editing `cards[i].voiceover.voiceId` is enough — the next ▶
+   click picks up the new voice.
+
 ## Self-review checklist
 
 Before declaring the slice done:
@@ -254,6 +326,7 @@ Before declaring the slice done:
 - [ ] If the theme is `photo-feature` or `atmospheric` and the user provided per-card images, `imageUrl` starts with `https://`
 - [ ] No outro card unless the user explicitly asked for one
 - [ ] No React, TSX, or CSS files were created
+- [ ] If any card has a `voiceover` object, every key inside it (`enabled` / `voiceId` / `text` / `rate`) matches the schema (boolean / non-empty string ≤128 / string ≤500 / number in [0.5, 2.0])
 
 ## Anti-patterns