voxflow 1.18.1 → 1.18.3

package/lib/core/ffmpeg.js

@@ -17,37 +17,27 @@ 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.
+ * ffmpeg-static is marked external in our ncc build (see package.json
+ * `build` script: `-e ffmpeg-static`), so at runtime `require('ffmpeg-static')`
+ * goes through Node's actual module resolution algorithm rather than the
+ * bundled-module map. That matters because ffmpeg-static's index.js computes
+ * its binary path with `path.join(__dirname, ...)` — and only when the module
+ * is loaded by the real Node loader does `__dirname` resolve to the actual
+ * package directory (e.g. `<install>/voxflow/node_modules/ffmpeg-static/`).
  *
- * 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).
+ * If we let ncc inline ffmpeg-static, `__dirname` collapses to the bundle's
+ * own directory and the returned path points at a file that does not exist.
+ * Worse, `require.resolve(...)` inside an ncc bundle is rewritten to return
+ * a numeric module ID, so it cannot be used to recover the real package
+ * directory. The only robust fix is keeping ffmpeg-static external.
  *
- * Returns: a path string (may or may not exist; caller should fs.existsSync).
- *          Or null when ffmpeg-static is not installed at all.
+ * Returns: a binary path that exists, 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 */ }
-
+  let p = null;
+  try { p = require('ffmpeg-static'); } catch { /* not installed */ }
+  if (p && fs.existsSync(p)) return p;
   return null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.18.1",
+  "version": "1.18.3",
   "description": "AI audio content creation CLI — stories, podcasts, narration, dubbing, transcription, translation, and video translation with TTS",
   "bin": {
     "voxflow": "./dist/index.js"
@@ -44,7 +44,7 @@
     "voxflow"
   ],
   "scripts": {
-    "build": "ncc build bin/voxflow.js -o dist --minify -e @remotion/renderer && rm -rf dist/cli && node scripts/check-no-asset-rewrite.js",
+    "build": "ncc build bin/voxflow.js -o dist --minify -e @remotion/renderer -e ffmpeg-static && rm -rf dist/cli && node scripts/check-no-asset-rewrite.js",
     "build:bundle": "node scripts/build-bundle.mjs",
     "prepublishOnly": "npm run build:bundle && npm run build",
     "lint": "eslint lib/ bin/ tests/",

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

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

@@ -460,6 +460,28 @@ Use `references/design-languages.md` to define the card set's visual grammar ind
     - `--input <path>` / `-o, --output <path>` — operate on / write to a different mp4 (otherwise: replace in place).
     - **Quota**: 0 — pure FFmpeg pipeline.
 
+    **Card-design constraint when planning to burn subtitles** (applies during Workflow steps 4–6, *before* writing the HTML):
+
+    The default subtitle style sits at ASS `MarginV=14` with `BorderStyle=3` (opaque box) — roughly the bottom **12–18% of the canvas height** on a 1080×1920 card. Anything the card itself places in that band will be overlapped by the captions. Verified during 1.18 dogfooding: page-number footers, citation chrome, italic closing pull-quotes, and "endcap" lines at the bottom edge all got partially covered.
+
+    Rules of thumb:
+    - **Reserve the bottom 15% of every card as a captioning-safe zone**: no body copy, no citation footer, no closing pull-quote there. Move card-level chrome (page number, citation, kicker) to the *top* band, or shrink the live area so it ends at ~85% of canvas height.
+    - The editorial chrome (top kicker / series indicator) is always safe — captions live at the bottom only.
+    - **Visual anchors that span full height** (oversized type, edge-cropped illustrations, photo-led covers) are fine: subtitles sit on top of the artwork, which is the intended layering. Only legibility-critical text needs to clear the band.
+    - When a card legitimately needs a bottom-edge element (e.g. a stamp, big page number, full-bleed image), skip captions for that card by leaving its `narration` empty in `deck.json` — `card subtitle` will silently absorb the empty card into adjacent windows.
+    - If you forget and discover the collision in QA: run `card subtitle --dry-run` to inspect `subs.srt` first, then either redesign the offending card's bottom band or pass `--style 'MarginV=24,...'` to push captions higher (cards with a wider safe zone trade some readability — captions get smaller relative to the canvas).
+
+    **Card-design constraint when planning to burn subtitles** (applies during Workflow steps 4–6, *before* writing the HTML):
+
+    The default subtitle style sits at ASS `MarginV=14` with `BorderStyle=3` (opaque box) — roughly the bottom **12–18% of the canvas height** on a 1080×1920 card. Anything the card itself places in that band will be overlapped by the captions. Verified during 1.18 dogfooding: page-number footers, citation chrome, italic closing pull-quotes, and "endcap" lines at the bottom edge all got partially covered.
+
+    Rules of thumb:
+    - **Reserve the bottom 15% of every card as a captioning-safe zone**: no body copy, no citation footer, no closing pull-quote there. Move card-level chrome (page number, citation, kicker) to the *top* band, or shrink the live area so it ends at ~85% of canvas height.
+    - The editorial chrome (top kicker / series indicator) is always safe — captions live at the bottom only.
+    - **Visual anchors that span full height** (oversized type, edge-cropped illustrations, photo-led covers) are fine: subtitles sit on top of the artwork, which is the intended layering. Only legibility-critical text needs to clear the band.
+    - When a card legitimately needs a bottom-edge element (e.g. a stamp, big page number, full-bleed image), skip captions for that card by leaving its `narration` empty in `deck.json` — `card subtitle` will silently absorb the empty card into adjacent windows.
+    - If you forget and discover the collision in QA: run `card subtitle --dry-run` to inspect `subs.srt` first, then either redesign the offending card's bottom band or pass `--style 'MarginV=24,...'` to push captions higher (cards with a wider safe zone trade some readability — captions get smaller relative to the canvas).
+
     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