voxflow 1.17.2 → 1.18.1

package/lib/core/ffmpeg.js

@@ -14,6 +14,43 @@ const fs = require('fs');
 
 let _resolvedFfmpegPath = null;
 
+/**
+ * Resolve the bundled `ffmpeg-static` binary path.
+ *
+ * Naively, `require('ffmpeg-static')` returns the path of its sibling `ffmpeg`
+ * binary. But ffmpeg-static's index.js uses `path.join(__dirname, ...)` to
+ * compute that path — and when we ncc-bundle this CLI into a single
+ * `dist/index.js`, `__dirname` inside the inlined ffmpeg-static module
+ * collapses to the *bundle*'s directory (`<install>/voxflow/dist/`), not its
+ * real `<install>/voxflow/node_modules/ffmpeg-static/` location. The returned
+ * string then points at a file that doesn't exist.
+ *
+ * Recovery: `require.resolve('ffmpeg-static/package.json')` honors Node's
+ * runtime module resolution (not the `__dirname` baked in at bundle time), so
+ * it finds the real package directory. The binary lives next to that
+ * package.json. This works in both source-mode (npm test) and ncc-bundled
+ * mode (the published CLI).
+ *
+ * Returns: a path string (may or may not exist; caller should fs.existsSync).
+ *          Or null when ffmpeg-static is not installed at all.
+ */
+function resolveFfmpegStaticBin() {
+  // 1. Naive path — works in source mode and any non-ncc context.
+  let direct = null;
+  try { direct = require('ffmpeg-static'); } catch { /* not installed */ }
+  if (direct && fs.existsSync(direct)) return direct;
+
+  // 2. ncc-safe recovery via package.json resolution.
+  try {
+    const pkgJson = require.resolve('ffmpeg-static/package.json');
+    const exe = process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg';
+    const recovered = path.join(path.dirname(pkgJson), exe);
+    if (fs.existsSync(recovered)) return recovered;
+  } catch { /* not installed */ }
+
+  return null;
+}
+
 /**
  * Resolve the ffmpeg binary path. Priority:
  *   1. System `ffmpeg` on PATH
@@ -30,13 +67,11 @@ function resolveFfmpegBin() {
   } catch { /* not on PATH */ }
 
   // Fall back to ffmpeg-static
-  try {
-    const staticPath = require('ffmpeg-static');
-    if (staticPath && fs.existsSync(staticPath)) {
-      _resolvedFfmpegPath = staticPath;
-      return _resolvedFfmpegPath;
-    }
-  } catch { /* not installed */ }
+  const staticPath = resolveFfmpegStaticBin();
+  if (staticPath) {
+    _resolvedFfmpegPath = staticPath;
+    return _resolvedFfmpegPath;
+  }
 
   // Nothing found — return 'ffmpeg' and let it fail with a helpful error
   _resolvedFfmpegPath = 'ffmpeg';
@@ -536,4 +571,6 @@ module.exports = {
   concatVideos,
   normalizeVideo,
   detectCjkFont,
+  // ffmpeg-static path resolution (used by card-subtitle's libass fallback)
+  resolveFfmpegStaticBin,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.17.2",
+  "version": "1.18.1",
   "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.2",
+  "version": "1.18.1",
   "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.