voxflow 1.15.2 → 1.15.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.15.2",
+  "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