voxflow 1.17.1 → 1.18.0

package/lib/commands/card.js

@@ -1,55 +1,76 @@
 /**
  * VoxFlow CLI — card command
  *
- * Dispatches `voxflow card render <dir>` to card-render.js.
+ * Dispatches:
+ *   - `voxflow card render <dir>`   → card-render.js  (deck → narrated MP4)
+ *   - `voxflow card subtitle <dir>` → card-subtitle.js (MP4 → +synced subs)
+ *
  * The card *generation* workflow lives in cli/skills/card/SKILL.md —
- * Claude Code calls render-cards.mjs directly. This command handles the
- * post-generation video render step which needs API auth (TTS quota).
+ * Claude Code calls render-cards.mjs directly. These commands handle the
+ * post-generation video render + subtitle steps which need API auth /
+ * ffmpeg-static fallback / timeline.json plumbing.
  */
 
 'use strict';
 
 async function handle(args) {
-  if (args.length > 0 && args[0] === 'render') {
-    const cardRender = require('./card-render');
-    return cardRender.handle(args.slice(1));
+  if (args.length > 0) {
+    if (args[0] === 'render') {
+      const cardRender = require('./card-render');
+      return cardRender.handle(args.slice(1));
+    }
+    if (args[0] === 'subtitle' || args[0] === 'subtitles' || args[0] === 'subs') {
+      const cardSubtitle = require('./card-subtitle');
+      return cardSubtitle.handle(args.slice(1));
+    }
   }
 
   // Default: usage
   console.log(`Usage:
-  voxflow card render <dir>   Render card directory → narrated MP4 video
+  voxflow card render <dir>     Render card directory → narrated MP4 video
+  voxflow card subtitle <dir>   Burn per-sentence synced subs into the rendered MP4
 
 Subcommands:
   render     Synthesize TTS narration + render Ken Burns video from card PNGs
+             (emits timeline.json next to deck.json — used by \`subtitle\`)
+  subtitle   Read deck.json + timeline.json, allocate per-sentence cues by
+             char count, and burn subtitles into the source mp4 in-place.
+             Original kept as <name>-no-subs.mp4. Aliases: subs / subtitles.
 
-See: voxflow card render --help`);
+See: voxflow card render --help
+     voxflow card subtitle --help`);
 }
 
 const meta = {
   card: {
-    usage: 'render <dir> [options]',
-    description: 'Card video export: narrated MP4 with subtitles, intro/outro, and BGM from a card-skill output directory',
+    usage: '<subcommand> <dir> [options]',
+    description: 'Card video pipeline: deck.json + PNGs → narrated MP4 (`render`) → synced sentence-level subtitles (`subtitle`).',
     options: [
       'render <dir>           Render deck.json + PNGs → narrated MP4 video',
-      '--voice <id>           TTS voice ID (default: female-kefu-xiaoyue)',
-      '--speed <n>            TTS speed, 0.5-2.0 (default: 1.0)',
-      '--no-audio             Silent video — skip TTS synthesis',
-      '--pause <sec>          Silence after narration (reading time, default: 2.5)',
-      '--hold <sec>           Card duration in --no-audio mode (default: 5)',
-      '--no-intro             Skip intro title card',
-      '--no-outro             Skip outro branding card',
-      '--intro-dur <sec>      Intro duration (default: 2.5)',
-      '--outro-dur <sec>      Outro duration (default: 2)',
-      '--no-subtitle          Disable subtitle overlay',
-      '--bgm <path>           Background music (loops at low volume)',
-      '--bgm-volume <n>       BGM volume, 0-1 (default: 0.08)',
-      '-o, --output <path>    Output MP4 path (default: <dir>/<title>.mp4)',
+      'subtitle <dir>         Burn per-sentence synced subs into the rendered MP4',
+      '--voice <id>           [render] TTS voice ID (default: v-female-R2s4N9qJ)',
+      '--speed <n>            [render] TTS speed, 0.5-2.0 (default: 1.0)',
+      '--no-audio             [render] Silent video — skip TTS synthesis',
+      '--pause <sec>          [render] Silence after narration (default: 2.5)',
+      '--hold <sec>           [render] Card duration in --no-audio mode (default: 5)',
+      '--no-intro             [render] Skip intro title card',
+      '--no-outro             [render] Skip outro branding card',
+      '--intro-dur <sec>      [render] Intro duration (default: 2.5)',
+      '--outro-dur <sec>      [render] Outro duration (default: 2)',
+      '--no-subtitle          [render] Disable in-render subtitle bar',
+      '--bgm <path>           [render] Background music (loops at low volume)',
+      '--bgm-volume <n>       [render] BGM volume, 0-1 (default: 0.08)',
+      '--input <path>         [subtitle] Override source mp4',
+      '--style <ass>          [subtitle] ASS force_style override (advanced)',
+      '--dry-run              [subtitle] Write subs.srt but skip ffmpeg burn-in',
+      '-o, --output <path>    Output MP4 path (default: <dir>/<title>.mp4 or in-place)',
     ],
     examples: [
       'voxflow card render cards/fermentation/',
-      'voxflow card render cards/fermentation/ --voice v-female-R2s4N9qJ -o out.mp4',
+      'voxflow card render cards/fermentation/ --no-intro --no-outro --no-subtitle',
+      'voxflow card subtitle cards/fermentation/',
+      'voxflow card subtitle cards/fermentation/ --dry-run',
       'voxflow card render cards/fermentation/ --bgm ~/music/ambient.mp3',
-      'voxflow card render cards/fermentation/ --no-audio --no-subtitle',
     ],
   },
 };

package/lib/commands/dub.js

@@ -527,7 +527,7 @@ const meta = {
       `--bgm <file>         Background music file to mix in`,
       `--ducking <n>        BGM volume ducking 0-1.0 (default: ${DUB_DEFAULTS.ducking})`,
       `--patch <id>         Re-synthesize a single caption by ID (patch mode)`,
-      `--output <path>      Output file path (default: ./dub-<timestamp>.wav)`,
+      `-o, --output <path>  Output file path (default: ./dub-<timestamp>.wav)`,
     ],
     examples: [
       'voxflow dub --srt subtitles.srt',

package/lib/commands/explain.js

@@ -476,7 +476,7 @@ async function handle(args) {
     topic: parseFlag(args, '--topic') || undefined,
     voice: parseFlag(args, '--voice') || undefined,
     style: style || undefined,
-    language: parseFlag(args, '--language') || undefined,
+    language: parseFlag(args, '--language', '--lang') || undefined,
     output, speed, scenes,
     audioOnly: parseBoolFlag(args, '--audio-only'),
     cloud: parseBoolFlag(args, '--cloud'),
@@ -492,13 +492,13 @@ const meta = {
     options: [
       `--topic <text>       Topic to explain (use "demo" for built-in demo)`,
       `--style <style>      Visual style: modern (default), playful, corporate, chalkboard`,
-      `--language <code>    Script language: en (default), zh, ja, ko, etc.`,
+      `--language <code>    Script language: en (default), zh, ja, ko, etc. (alias: --lang)`,
       `--voice <id>         TTS voice ID (default: ${EXPLAIN_DEFAULTS.voice})`,
       `--speed <n>          TTS speed 0.5-2.0 (default: ${EXPLAIN_DEFAULTS.speed})`,
       `--scenes <n>         Number of scenes, 3-12 (default: ${EXPLAIN_DEFAULTS.sceneCount})`,
       `--audio-only         Skip video render, output WAV narration only`,
       `--cloud              Render on cloud instead of local Remotion`,
-      `--output <path>      Output file path (default: ./explain-<timestamp>.mp4)`,
+      `-o, --output <path>  Output file path (default: ./explain-<timestamp>.mp4)`,
     ],
     examples: [
       'voxflow explain --topic "What is React?"',

package/lib/commands/narrate.js

@@ -612,7 +612,7 @@ const meta = {
       `--format <fmt>       Output format: pcm, wav, mp3 (default: pcm → WAV)`,
       `--speed <n>          TTS speed 0.5-2.0 (default: ${NARRATE_DEFAULTS.speed})`,
       `--silence <sec>      Silence between segments, 0-5.0 (default: ${NARRATE_DEFAULTS.silence})`,
-      `--output <path>      Output file path (default: matches input basename, e.g. design.md → design.wav)`,
+      `-o, --output <path>  Output file path (default: matches input basename, e.g. design.md → design.wav)`,
     ],
     examples: [
       'voxflow narrate --input article.txt --voice v-female-R2s4N9qJ',

package/lib/commands/picstory.js

@@ -487,7 +487,7 @@ async function handle(args) {
     outputDir: outputDir || undefined,
     style: style || undefined,
     ratio: ratio || undefined,
-    language: parseFlag(args, '--language') || undefined,
+    language: parseFlag(args, '--language', '--lang') || undefined,
     sceneCount: scenes,
     quality: quality || undefined,
     fadeSeconds: fadeSeconds !== undefined ? fadeSeconds : undefined,
@@ -511,7 +511,7 @@ const meta = {
       `--text <content>     Input text content to visualize`,
       `--style <name>       Visual style: sketchnote (default), neon_noir, minimal_3d, chalkboard, photo, manga_panel, vintage_newspaper`,
       `--ratio <name>       Aspect ratio: portrait (default, 9:16), landscape (16:9), square (1:1)`,
-      `--language <code>    Script language: zh (default), en, ja, etc.`,
+      `--language <code>    Script language: zh (default), en, ja, etc. (alias: --lang)`,
       `--scenes <n>         Number of scenes, 2-10 (default: ${PICSTORY_DEFAULTS.sceneCount})`,
       `--quality <tier>     Image quality: fast (default), hd, ultra (gpt-5.4-image-2, best quality, ~16× cost), hd-aiberm / fast-aiberm (Aiberm Gemini — strongest Chinese text rendering)`,
       `--voice <id>         TTS voice ID`,
@@ -522,7 +522,7 @@ const meta = {
       `--fade <n>           Scene fade-in/out duration in seconds (default: ${PICSTORY_DEFAULTS.fadeSeconds}, set 0 to disable)`,
       `--image-only         Save images+audio without rendering video`,
       `--output-dir <dir>   Directory for all output files (auto-created if needed)`,
-      `--output <path>      Output file path (overrides --output-dir)`,
+      `-o, --output <path>  Output file path (overrides --output-dir)`,
     ],
     examples: [
       'voxflow picstory --topic "AI Agent 入门" --style sketchnote',

package/lib/commands/podcast/index.js

@@ -534,7 +534,7 @@ const meta = {
       `--voice <id>         Override TTS voice for all speakers`,
       `--bgm <file>         Background music file to mix in`,
       `--ducking <n>        BGM volume ducking 0-1.0 (default: ${PODCAST_DEFAULTS.ducking})`,
-      `--output <path>      Output WAV path (default: ./podcast-<timestamp>.wav)`,
+      `-o, --output <path>  Output WAV path (default: ./podcast-<timestamp>.wav)`,
       `--speed <n>          TTS speed 0.5-2.0 (default: ${PODCAST_DEFAULTS.speed})`,
       `--silence <sec>      Uniform silence override between segments, 0-5.0 (legacy)`,
       `--pace <preset>      Pacing preset: tight | natural | relaxed (default: natural).`,

package/lib/commands/present.js

@@ -495,7 +495,7 @@ const meta = {
       `--speed <n>          TTS speed 0.5-2.0 (default: ${PRESENT_DEFAULTS.speed})`,
       `--no-audio           Skip TTS, render silent video only`,
       `--web-search         Search the web for up-to-date info on the topic`,
-      `--output <path>      Output file path (default: ./present-<timestamp>.mp4)`,
+      `-o, --output <path>  Output file path (default: ./present-<timestamp>.mp4)`,
     ],
     examples: [
       'voxflow present --text "Claude Code 是一个 AI 编程工具" --style aurora',

package/lib/commands/publish.js

@@ -395,7 +395,7 @@ const meta = {
       '--audio <file>       Mode C: merge existing audio into video',
       '--voice <id>         TTS voice for Mode A/B',
       '--voices <file>      Multi-speaker voice map for Mode A/B',
-      '--output <path>      Final MP4 output path',
+      '-o, --output <path>  Final MP4 output path',
       '--publish <target>   local (default) | webhook | none',
       '--publish-dir <dir>  Local publish directory (for --publish local)',
       '--publish-webhook <url> Webhook URL (for --publish webhook)',

package/lib/commands/slides/index.js

@@ -331,7 +331,7 @@ const meta = {
       `--template <name>    Template: product, report, tutorial, pitch, free (default: ${SLIDES_DEFAULTS.template})`,
       `--model <id>         Model: swift, balanced, pro, creative (default: ${SLIDES_DEFAULTS.model})`,
       `--no-audio           Skip TTS synthesis, generate slides only`,
-      `--output <path>      Output HTML file (default: ./slides-<timestamp>.html)`,
+      `-o, --output <path>  Output HTML file (default: ./slides-<timestamp>.html)`,
     ],
     examples: [
       'voxflow slides "AI in Healthcare"',

package/lib/commands/story.js

@@ -285,7 +285,7 @@ const meta = {
     options: [
       `--topic <text>       Story topic (default: children's story)`,
       `--voice <id>         TTS voice ID (default: ${STORY_DEFAULTS.voice})`,
-      `--output <path>      Output WAV path (default: ./story-<timestamp>.wav)`,
+      `-o, --output <path>  Output WAV path (default: ./story-<timestamp>.wav)`,
       `--paragraphs <n>     Paragraph count, 1-20 (default: ${STORY_DEFAULTS.paragraphs})`,
       `--speed <n>          TTS speed 0.5-2.0 (default: ${STORY_DEFAULTS.speed})`,
       `--silence <sec>      Silence between paragraphs, 0-5.0 (default: ${STORY_DEFAULTS.silence})`,

package/lib/commands/summarize.js

@@ -462,7 +462,7 @@ async function handle(args) {
   const voice = parseFlag(args, '--voice') || SUM_DEFS.voice;
   const speed = parseFloatFlag(args, '--speed') ?? SUM_DEFS.speed;
   const slideCount = parseIntFlag(args, '--slides') ?? SUM_DEFS.slides;
-  const language = parseFlag(args, '--lang') || SUM_DEFS.language;
+  const language = parseFlag(args, '--lang', '--language') || SUM_DEFS.language;
   const engine = parseFlag(args, '--engine') || SUM_DEFS.engine;
   const model = parseFlag(args, '--model');
   const tts = parseBoolFlag(args, '--tts');
@@ -509,7 +509,7 @@ const meta = {
       `--input <file>       Input video/audio file → ASR + summarize`,
       `--text <text>        Direct text input (skip ASR)`,
       `--slides <n>         Number of slides, 4-12 (default: ${SUMMARIZE_DEFAULTS.slides})`,
-      `--lang <code>        Output language: en, zh, ja, etc. (default: ${SUMMARIZE_DEFAULTS.language})`,
+      `--lang <code>        Output language: en, zh, ja, etc. (default: ${SUMMARIZE_DEFAULTS.language}) (alias: --language)`,
       `--engine <engine>    ASR engine: auto, local, cloud (default: ${SUMMARIZE_DEFAULTS.engine})`,
       `--model <model>      Whisper model for local ASR: tiny, base, small, medium, large`,
       `--tts                Generate TTS narration audio for each slide`,
@@ -517,7 +517,7 @@ const meta = {
       `--scheme <name>      Video visual scheme: noir, neon, editorial, aurora (default), brutalist`,
       `--voice <id>         TTS voice ID (default: ${SUMMARIZE_DEFAULTS.voice})`,
       `--speed <n>          TTS speed 0.5-2.0 (default: ${SUMMARIZE_DEFAULTS.speed})`,
-      `--output <path>      Output PPTX path (default: <input>-summary.pptx)`,
+      `-o, --output <path>  Output PPTX path (default: <input>-summary.pptx)`,
     ],
     examples: [
       'voxflow summarize --input lecture.mp4',

package/lib/commands/translate.js

@@ -566,7 +566,7 @@ const meta = {
       `--input <file>       Text file (.txt, .md) to translate`,
       `--from <lang>        Source language code (default: auto-detect)`,
       `--to <lang>          Target language code (required)`,
-      `--output <path>      Output file path (default: <input>-<lang>.<ext>)`,
+      `-o, --output <path>  Output file path (default: <input>-<lang>.<ext>)`,
       `--realign            Adjust subtitle timing for target language length`,
       `--batch-size <n>     Captions per LLM call, 1-20 (default: ${TRANSLATE_DEFAULTS.batchSize})`,
     ],

package/lib/commands/video-translate.js

@@ -559,7 +559,7 @@ const meta = {
       `--speed <n>          TTS speed 0.5-2.0 (default: ${require('../core/config').VIDEO_TRANSLATE_DEFAULTS.speed})`,
       `--batch-size <n>     Translation batch size, 1-20 (default: ${require('../core/config').VIDEO_TRANSLATE_DEFAULTS.batchSize})`,
       `--keep-intermediates Keep intermediate files (SRT, audio) for debugging`,
-      `--output <path>      Output MP4 path (default: <input>-<lang>.mp4)`,
+      `-o, --output <path>  Output MP4 path (default: <input>-<lang>.mp4)`,
       `--asr-mode <mode>    Override ASR mode: auto, sentence, flash, file`,
       `--asr-lang <engine>  Override ASR engine: 16k_zh, 16k_en, 16k_ja, 16k_ko, etc.`,
       `--engine <engine>    ASR engine: auto, local, cloud (default: auto)`,

package/lib/commands/voices.js

@@ -250,7 +250,7 @@ async function handle(args) {
     api,
     search: parseFlag(args, '--search'),
     gender: parseFlag(args, '--gender'),
-    language: parseFlag(args, '--language'),
+    language: parseFlag(args, '--language', '--lang'),
     useCase: parseFlag(args, '--use-case'),
     json: parseBoolFlag(args, '--json'),
     extended: parseBoolFlag(args, '--extended'),
@@ -275,7 +275,7 @@ const meta = {
       `--mine               List your cloned voices (requires login)`,
       `--search <query>     Search by name, tone, style, description`,
       `--gender <m|f>       Filter by gender: male/m or female/f`,
-      `--language <code>    Filter by language: zh, en, etc.`,
+      `--language <code>    Filter by language: zh, en, etc. (alias: --lang)`,
       `--use-case <tag>     Filter by editorial-curated use case (e.g. podcast)`,
       `--extended           Include extended voice library (380+ voices)`,
       `--json               Output raw JSON instead of table`,

package/package.json

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

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.17.1",
+  "version": "1.18.0",
   "description": "AI voice CLI bundled as 6 skills (hub, podcast, transcribe, video, slice, card). Synthesize speech in 200+ voices across 40+ languages, generate multi-speaker AI podcasts, transcribe audio/video with word-level timestamps, dub videos from SRT subtitles, run end-to-end video translation, turn long articles into vertical card video reels via Remotion, and turn text into polished shareable card images or narrated card videos. Backed by a hosted TTS/ASR/LLM/render service with per-user quota (free tier 10K/mo).",
   "author": {
     "name": "VoxFlow",

package/skills/card/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: card
-description: "Use when the user wants to turn text content into a set of polished, shareable visual CARD IMAGES or narrated card VIDEOS — knowledge cards, quote cards, 小红书图文, carousel cards, poster cards — rendered as HTML/CSS and exported via Playwright at ratios like 1:1 / 3:4 / 9:16; optionally produces a narrated MP4 video from those cards via `voxflow card render` (per-card TTS + FFmpeg static-image clips with optional subtitle bar / intro+outro cards / BGM mix). Triggers: card / 卡片 / 知识卡 / 文字卡片 / 金句卡 / 图文卡片 / 卡片生成 / make cards / card video / 卡片视频. For article → Slice-themed card VIDEO use voxflow:slice; for short videos / AI clips use voxflow:video; for podcasts use voxflow:podcast."
+description: "Use when the user wants to turn text content into a set of polished, shareable visual CARD IMAGES or narrated card VIDEOS — knowledge cards, quote cards, 小红书图文, carousel cards, poster cards — rendered as HTML/CSS and exported via Playwright at ratios like 1:1 / 3:4 / 9:16; optionally produces a narrated MP4 video from those cards via `voxflow card render` (per-card TTS + FFmpeg static-image clips with optional subtitle bar / intro+outro cards / BGM mix), and burns per-sentence synced captions for short-form video via `voxflow card subtitle` (timeline.json-driven, char-ratio time allocation, manual CJK line-wrapping). Triggers: card / 卡片 / 知识卡 / 文字卡片 / 金句卡 / 图文卡片 / 卡片生成 / make cards / card video / 卡片视频. For article → Slice-themed card VIDEO use voxflow:slice; for short videos / AI clips use voxflow:video; for podcasts use voxflow:podcast."
 ---
 
 # VoxFlow Skill — Card
@@ -409,6 +409,7 @@ Use `references/design-languages.md` to define the card set's visual grammar ind
       ├── card-01.html … card-N.html   (source HTML)
       ├── deck.json                     (narration + metadata)
       ├── exports/card-01.png …         (PNG exports)
+      ├── timeline.json                 (per-card start/end ms — used by `card subtitle`)
       ├── sources.md                    (attribution)
       └── my-topic.mp4                  (final video — slug derived from deck.meta.title)
       ```
@@ -439,6 +440,28 @@ Use `references/design-languages.md` to define the card set's visual grammar ind
     - **Quota**: ~50 per card narrated (`tts-synthesize`); zero with `--no-audio`. A 5-card deck costs ~250 quota total.
     - For article-to-card VIDEO with Slice themes (paper-slide, editorial-mag, etc.), prefer `voxflow:slice` instead.
 
+11. Burn per-sentence synced subtitles (optional — when the user wants a captioned reel for 小红书 / 抖音 / TikTok).
+
+    The `--no-subtitle` baseline is recommended for cards-as-cover short videos because the in-render subtitle bar shows the entire narration of a card for the full clip — fine for desktop preview, ineffective for short-form video. The dedicated `card subtitle` subcommand instead splits each card's narration into sentences and gives each its own time slice:
+
+    ```bash
+    # 1. Render without the in-render subtitle bar and without intro/outro chrome
+    voxflow card render <output-dir>/ --no-intro --no-outro --no-subtitle
+
+    # 2. Burn synced sentence-level captions
+    voxflow card subtitle <output-dir>/
+    ```
+
+    - The `render` step emits `timeline.json` next to `deck.json` with each card's exact `[start, end]` ms in the output mp4. `subtitle` reads it directly — no `silencedetect` guesswork.
+    - Sentences split on `[。！？!?.…—]`. Each sentence gets a time slice proportional to its character count; the last sentence absorbs any remainder so cues land exactly on the card boundary.
+    - CJK text is manually wrapped at ≤ 16 chars per visual line (with a soft preference for breaking after `[，,、；;：:—]` when within the last 4 chars of a line). ffmpeg's `subtitles=` filter does not auto-wrap CJK, so this manual wrap is required.
+    - The original mp4 is preserved as `<name>-no-subs.mp4` so iteration is non-destructive.
+    - `--dry-run` writes `subs.srt` but skips the ffmpeg burn-in. Use it to inspect and hand-edit cues before committing.
+    - `--input <path>` / `-o, --output <path>` — operate on / write to a different mp4 (otherwise: replace in place).
+    - **Quota**: 0 — pure FFmpeg pipeline.
+
+    Note: `card subtitle` also has a `silencedetect` fallback for old mp4s that pre-date the `timeline.json` emission (introduced in CLI 1.18). Prefer the timeline path; it is exact rather than heuristic.
+
 ## Asset and Source Discipline
 
 - Keep generated files contained in the requested output folder.