voxflow 1.15.0 → 1.15.2

package/lib/commands/narrate.js

@@ -0,0 +1,639 @@
+/**
+ * VoxFlow CLI — Narrate command
+ *
+ * Convert file, text, or script to multi-segment TTS audio.
+ * Three input modes:
+ *   1. Plain text: --text "..." or stdin pipe
+ *   2. File: --input file.txt / file.md
+ *   3. Script: --script script.json (per-segment voice/speed control)
+ *
+ * Supports output formats: WAV (default), MP3.
+ * Pipeline: read input → split segments → TTS each → concatenate → output
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { NARRATE_DEFAULTS } = require('../core/config');
+const { ApiError } = require('../core/http');
+const { parseParagraphs, buildWav, concatAudioBuffers, getFileExtension } = require('../core/audio');
+const { synthesizeTTS } = require('../core/tts-synthesizer');
+
+// ─── Script Parsing ──────────────────────────────────────────────────────────
+
+/**
+ * Parse and validate a script JSON file.
+ * @param {string} filePath - Path to script.json
+ * @returns {{ segments: Array<{text: string, voiceId?: string, speed?: number, volume?: number, pitch?: number}>, silence: number, output?: string }}
+ */
+function parseScript(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Script file not found: ${filePath}`);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Invalid JSON in script file: ${err.message}`);
+  }
+
+  if (!raw.segments || !Array.isArray(raw.segments) || raw.segments.length === 0) {
+    throw new Error('Script must have a non-empty "segments" array');
+  }
+
+  for (let i = 0; i < raw.segments.length; i++) {
+    const seg = raw.segments[i];
+    if (!seg.text || typeof seg.text !== 'string' || seg.text.trim().length === 0) {
+      throw new Error(`Segment ${i + 1} must have a non-empty "text" field`);
+    }
+  }
+
+  return {
+    segments: raw.segments.map((s) => ({
+      text: s.text.trim(),
+      voiceId: s.voiceId || undefined,
+      speed: s.speed != null ? Number(s.speed) : undefined,
+      volume: s.volume != null ? Number(s.volume) : undefined,
+      pitch: s.pitch != null ? Number(s.pitch) : undefined,
+    })),
+    silence: raw.silence != null ? Number(raw.silence) : NARRATE_DEFAULTS.silence,
+    output: raw.output || undefined,
+  };
+}
+
+// ─── Markdown Stripping ──────────────────────────────────────────────────────
+
+/**
+ * Strip basic markdown syntax for cleaner TTS input.
+ * Removes: headings (#), bold (**), italic (*), links [text](url), images, code blocks.
+ */
+function stripMarkdown(text) {
+  return text
+    // Remove code blocks (``` ... ```)
+    .replace(/```[\s\S]*?```/g, '')
+    // Remove inline code (`...`)
+    .replace(/`([^`]+)`/g, '$1')
+    // Remove images ![alt](url)
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    // Convert links [text](url) → text
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    // Remove headings (# ... )
+    .replace(/^#{1,6}\s+/gm, '')
+    // Remove bold/italic markers
+    .replace(/\*{1,3}([^*]+)\*{1,3}/g, '$1')
+    .replace(/_{1,3}([^_]+)_{1,3}/g, '$1')
+    // Remove horizontal rules
+    .replace(/^[-*_]{3,}\s*$/gm, '')
+    // Remove blockquote markers
+    .replace(/^>\s?/gm, '')
+    // Clean up extra blank lines
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+// ─── Stdin Reading ───────────────────────────────────────────────────────────
+
+/**
+ * Read all data from stdin (for pipe mode).
+ * @returns {Promise<string>}
+ */
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+// ─── TTS Synthesis ───────────────────────────────────────────────────────────
+
+async function synthesizeSegment(apiBase, token, text, voiceId, speed, volume, pitch, format, index, total) {
+  const result = await synthesizeTTS({
+    apiBase, token, text, voiceId,
+    speed: speed ?? 1.0,
+    volume: volume ?? 1.0,
+    pitch,
+    format: format || 'pcm',
+    index, total,
+  });
+
+  const formatLabel = format === 'mp3' ? 'MP3' : format === 'wav' ? 'WAV' : 'PCM';
+  console.log(` OK (${(result.audio.length / 1024).toFixed(0)} KB ${formatLabel})`);
+  return result;
+}
+
+// ─── Risk scanner (pre-flight) ───────────────────────────────────────────────
+
+/**
+ * Heuristic check for segments likely to trigger TTS provider edge cases.
+ * Most prominent: Issue #2901 — Chinese TTS voices return tts_failed on
+ * isolated short Latin fragments (single brand names, short English headings).
+ *
+ * Returns an array of { index, severity, message, text }. Empty array when
+ * no risks are detected. Does NOT block — purely informational.
+ */
+function scanSegmentRisks(segments) {
+  const risks = [];
+  for (let i = 0; i < segments.length; i++) {
+    const text = (segments[i].text || '').trim();
+    const isShort = text.length > 0 && text.length < 30;
+    const isLatinOnly = /^[A-Za-z0-9 .,_\-:;'"!?@#$%&*()/]+$/.test(text);
+    const hasLatinWord = /[A-Za-z]{2,}/.test(text);
+
+    if (isShort && isLatinOnly) {
+      risks.push({
+        index: i + 1,
+        severity: 'high',
+        text,
+        message: `pure-Latin short line (${text.length} chars) — Chinese TTS often returns tts_failed (Issue #2901). Try padding with Chinese context.`,
+      });
+    } else if (text.length < 25 && hasLatinWord) {
+      // Mixed CJK + Latin short text. Empirically the threshold below which
+      // a Chinese voice on a Chinese-mode call still fails on the embedded
+      // Latin words — saw 17-char "测试 VoxFlow 的 narrate 命令" trigger it.
+      risks.push({
+        index: i + 1,
+        severity: 'medium',
+        text,
+        message: `short line (${text.length} chars) with Latin word(s) — may fail; CLI will auto-retry with Chinese context wrap.`,
+      });
+    }
+  }
+  return risks;
+}
+
+/**
+ * Determine whether a segment is a candidate for the #2901 auto-wrap retry.
+ * We only retry when the failure is plausibly a Chinese-TTS-vs-Latin issue
+ * AND the text is short enough that wrapping with Chinese context is sane.
+ */
+function shouldAutoWrap(text) {
+  const t = (text || '').trim();
+  if (!t || t.length > 60) return false;
+  // Latin-only OR latin-heavy short text where adding Chinese context
+  // empirically rescues the synthesis.
+  const isLatinOnly = /^[A-Za-z0-9 .,_\-:;'"!?@#$%&*()/]+$/.test(t);
+  const latinChars = (t.match(/[A-Za-z]/g) || []).length;
+  return isLatinOnly || (latinChars / t.length > 0.4 && t.length < 30);
+}
+
+/**
+ * Wrap pseudonym: prefix with a short Chinese phrase that gives the TTS
+ * model enough Chinese context to switch into Mandarin mode for the trailing
+ * Latin tokens. Empirically, "如下：" works well; ending with "。" caps the
+ * sentence so prosody settles.
+ */
+function chineseContextWrap(text) {
+  return `如下：${text}。`;
+}
+
+/**
+ * Detect a TTS-provider rejection from an ApiError. The CLI's `throwApiError`
+ * wraps any 5xx into `code='server_error'` and embeds the backend's own code
+ * (e.g. `tts_failed`) into the message in the `[tts_failed]` form. We pattern
+ * match on that marker to distinguish #2901-style provider rejections from
+ * real server faults (which we shouldn't auto-retry — that just amplifies
+ * load on a struggling backend).
+ */
+function isTtsProviderRejection(err) {
+  if (!(err instanceof ApiError)) return false;
+  if (err.code === 'tts_failed') return true; // future-proof: if propagated cleanly
+  return /\[tts_failed\]/.test(err.message || '');
+}
+
+/**
+ * Synthesize one segment with one auto-retry on `tts_failed` using a
+ * Chinese-context wrap. Returns the API result on success; the audio belongs
+ * to the wrapped text, but the user-visible transcript still shows the
+ * original — that's intentional, the wrap is silent compensation.
+ *
+ * Throws every other error class (token_expired, quota_exceeded, network)
+ * unchanged so the outer loop can fast-fail.
+ */
+async function synthesizeWithRetry(opts, attempts = { wrap: 0 }) {
+  try {
+    return await synthesizeSegment(
+      opts.apiBase, opts.token, opts.text, opts.voiceId,
+      opts.speed, opts.volume, opts.pitch, opts.format,
+      opts.index, opts.total,
+    );
+  } catch (err) {
+    if (isTtsProviderRejection(err) && attempts.wrap === 0 && shouldAutoWrap(opts.text)) {
+      const wrapped = chineseContextWrap(opts.text);
+      process.stdout.write(`\n    ↻ retrying with Chinese context wrap: ${JSON.stringify(wrapped)}\n    TTS [${opts.index + 1}/${opts.total}]...`);
+      return await synthesizeWithRetry({ ...opts, text: wrapped }, { wrap: 1 });
+    }
+    throw err;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Narrate text, file, or script to a WAV file.
+ *
+ * @param {object} opts
+ * @param {string} opts.token       - JWT token
+ * @param {string} opts.api         - API base URL
+ * @param {string} [opts.text]      - Inline text to narrate
+ * @param {string} [opts.input]     - Path to .txt or .md file
+ * @param {string} [opts.script]    - Path to .json script file
+ * @param {string} [opts.voice]     - Default TTS voice ID
+ * @param {number} [opts.speed]     - Default TTS speed
+ * @param {string} [opts.format]     - Output format: pcm, wav, mp3 (default: pcm → WAV)
+ * @param {number} [opts.silence]   - Silence gap between segments (seconds)
+ * @param {string} [opts.output]    - Output WAV path
+ * @returns {Promise<{outputPath: string, textPath: string, duration: number, quotaUsed: number, segmentCount: number, format: string}>}
+ */
+async function narrate(opts) {
+  let isExiting = false;
+
+  const sigintHandler = () => {
+    if (isExiting) return;
+    isExiting = true;
+    console.log('\n\nNarration cancelled.');
+    process.exit(130);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  try {
+    return await _narrate(opts);
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+  }
+}
+
+async function _narrate(opts) {
+  const defaultVoice = opts.voice || NARRATE_DEFAULTS.voice;
+  const defaultSpeed = opts.speed ?? NARRATE_DEFAULTS.speed;
+  const format = opts.format || 'pcm'; // API format: pcm | wav | mp3
+  const api = opts.api;
+  const token = opts.token;
+
+  let segments;    // Array of { text, voiceId?, speed?, volume?, pitch? }
+  let silence;
+  let outputPath;
+  let inputLabel;
+
+  // ─── Determine input source ────────────────────────────────────────────
+
+  if (opts.script) {
+    // Script mode: JSON with per-segment control
+    const script = parseScript(opts.script);
+    segments = script.segments;
+    silence = opts.silence ?? script.silence;
+    outputPath = opts.output || script.output;
+    inputLabel = `script: ${opts.script} (${segments.length} segments)`;
+
+  } else if (opts.input) {
+    // File mode: read .txt or .md
+    const filePath = path.resolve(opts.input);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Input file not found: ${filePath}`);
+    }
+
+    let content = fs.readFileSync(filePath, 'utf8');
+
+    // Strip markdown for .md files
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.md' || ext === '.markdown') {
+      content = stripMarkdown(content);
+    }
+
+    const paragraphs = parseParagraphs(content);
+    if (paragraphs.length === 0) {
+      throw new Error('No text content found in input file');
+    }
+
+    segments = paragraphs.map((text) => ({ text }));
+    silence = opts.silence ?? NARRATE_DEFAULTS.silence;
+    outputPath = opts.output;
+    inputLabel = `file: ${opts.input} (${segments.length} paragraphs)`;
+
+  } else if (opts.text) {
+    // Plain text mode
+    const paragraphs = parseParagraphs(opts.text);
+    if (paragraphs.length === 0) {
+      throw new Error('No text content provided');
+    }
+
+    segments = paragraphs.map((text) => ({ text }));
+    silence = opts.silence ?? NARRATE_DEFAULTS.silence;
+    outputPath = opts.output;
+    inputLabel = `text: ${opts.text.length} chars (${segments.length} paragraphs)`;
+
+  } else if (!process.stdin.isTTY) {
+    // Stdin pipe mode
+    const stdinText = await readStdin();
+    if (!stdinText || stdinText.trim().length === 0) {
+      throw new Error('No input provided via stdin');
+    }
+
+    const paragraphs = parseParagraphs(stdinText);
+    if (paragraphs.length === 0) {
+      throw new Error('No text content found in stdin input');
+    }
+
+    segments = paragraphs.map((text) => ({ text }));
+    silence = opts.silence ?? NARRATE_DEFAULTS.silence;
+    inputLabel = `stdin (${segments.length} paragraphs)`;
+
+  } else {
+    throw new Error(
+      'No input provided. Use one of:\n' +
+      '  --input <file.txt>    Read a text or markdown file\n' +
+      '  --text "text"         Provide inline text\n' +
+      '  --script <file.json>  Use a script with per-segment control\n' +
+      '  echo "text" | voxflow narrate   Pipe from stdin'
+    );
+  }
+
+  // Default output path. Prefer the input file's basename — matches the
+  // user's mental model: `voxflow narrate --input design.md` → `design.wav`.
+  // Falls back to a timestamped name only when there's no input file
+  // (--text mode, --script JSON without explicit output, stdin pipe).
+  //
+  // Use path.join(process.cwd(), ...) explicitly. path.resolve() should
+  // do the same, but in the ncc-bundled dist/index.js it occasionally
+  // resolved against the bundle's runtime dir during 1.10.9 verify —
+  // output ended up at node_modules/voxflow/dist/cli/<file>. Joining
+  // process.cwd() explicitly side-steps that.
+  // CRITICAL: ncc's static asset analyzer rewrites
+  //   path.join(<dynamic>, `${expr}${ext}`)
+  // into __webpack_require__.ab + 'cli/' + expr + ext when the template
+  // starts with a non-literal — output ended up at dist/cli/<file> in
+  // 1.10.10/.11. Build the filename string FIRST so path.join sees two
+  // opaque arguments and the analyzer leaves it alone.
+  const ext = getFileExtension(format);
+  if (!outputPath) {
+    let filename;
+    if (opts.input) {
+      const base = path.basename(opts.input, path.extname(opts.input));
+      filename = base + ext;
+    } else {
+      const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+      filename = 'narration-' + ts + ext;
+    }
+    outputPath = path.join(process.cwd(), filename);
+  }
+  if (!outputPath.endsWith(ext)) {
+    // Replace wrong extension or append
+    outputPath = outputPath.replace(/\.(wav|mp3|pcm)$/i, '') + ext;
+  }
+
+  // Print header
+  console.log('\n=== VoxFlow Narrate ===');
+  console.log(`Input:    ${inputLabel}`);
+  console.log(`Voice:    ${defaultVoice}${opts.script ? ' (may be overridden per segment)' : ''}`);
+  console.log(`Format:   ${format === 'pcm' ? 'wav (pcm)' : format}`);
+  console.log(`Speed:    ${defaultSpeed}`);
+  if (format === 'mp3') {
+    console.log(`Output:   ${outputPath}`);
+    console.log(`          (MP3 mode: no silence inserted between segments)`);
+  } else {
+    console.log(`Silence:  ${silence}s`);
+    console.log(`Output:   ${outputPath}`);
+  }
+
+  // ─── Pre-flight risk scan ──────────────────────────────────────────────
+  // Flag segments likely to hit known provider edge cases (e.g. #2901)
+  // BEFORE making any API calls. Informational only — does not block.
+
+  const risks = scanSegmentRisks(segments);
+  if (risks.length > 0) {
+    console.log('');
+    console.log(`⚠ ${risks.length} segment(s) may trigger TTS edge cases:`);
+    for (const r of risks) {
+      const preview = r.text.length > 50 ? `${r.text.slice(0, 50)}…` : r.text;
+      console.log(`    [${r.severity}] segment ${r.index}: ${JSON.stringify(preview)}`);
+      console.log(`        → ${r.message}`);
+    }
+    console.log('  CLI will auto-retry with Chinese context wrap on tts_failed.');
+  }
+
+  // ─── TTS synthesis loop ────────────────────────────────────────────────
+
+  console.log(`\n[1/2] Synthesizing TTS audio (${segments.length} segments)...`);
+
+  const audioBuffers = [];
+  const skipped = [];   // [{ index, text, message }]
+  const succeededSegments = [];
+  let lastQuota = null;
+
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    try {
+      const result = await synthesizeWithRetry({
+        apiBase: api, token,
+        text: seg.text,
+        voiceId: seg.voiceId || defaultVoice,
+        speed: seg.speed ?? defaultSpeed,
+        volume: seg.volume,
+        pitch: seg.pitch,
+        format,
+        index: i, total: segments.length,
+      });
+      audioBuffers.push(result.audio);
+      succeededSegments.push(seg);
+      lastQuota = result.quota;
+    } catch (err) {
+      // Hard-fail conditions: user must act, no point continuing.
+      // 'quota_exceeded' kept as alias to remain backward-compatible with
+      // older bundled CLI builds that still emit it (renamed to
+      // 'insufficient_quota' in 2026-05 to disambiguate from 'rate_limited').
+      if (err instanceof ApiError && [
+        'insufficient_quota', 'quota_exceeded',
+        'token_expired', 'network_error'
+      ].includes(err.code)) {
+        throw err;
+      }
+      // Soft-fail: log + skip the segment, keep narrating the rest.
+      // Common cause: TTS provider rejects a particular text (e.g. Chinese voice
+      // on a pure-English short fragment left over from Markdown headings, see #2901).
+      const preview = seg.text.length > 60 ? `${seg.text.slice(0, 60)}…` : seg.text;
+      console.log(`    ⚠ Segment ${i + 1} skipped: ${err.message}`);
+      console.log(`      text: ${JSON.stringify(preview)}`);
+      skipped.push({ index: i + 1, text: seg.text, message: err.message });
+    }
+  }
+
+  if (audioBuffers.length === 0) {
+    // All segments failed. Build a concrete, actionable error rather than just
+    // re-throwing the first message: list the offending segments and suggest
+    // the most common fix (#2901 — pad short Latin lines with Chinese context).
+    const lines = [
+      `All ${segments.length} segments failed TTS synthesis.`,
+      '',
+      'Failed segments:',
+      ...skipped.map((s) => {
+        const preview = s.text.length > 60 ? `${s.text.slice(0, 60)}…` : s.text;
+        return `  [${s.index}] ${JSON.stringify(preview)}\n      ${s.message}`;
+      }),
+      '',
+      'How to fix:',
+      '  • Short pure-English lines (brand names, English headings) often fail',
+      '    on Chinese TTS voices (Issue #2901). Pad with Chinese context, e.g.',
+      '    "VoxFlow" → "VoxFlow 工具介绍" or merge into adjacent paragraphs.',
+      '  • CLI already auto-retries with Chinese wrap; if that also failed, the',
+      '    provider may be down — try `voxflow voices` to check connectivity.',
+      '  • Re-run with -vv to see full TTS request/response for each segment.',
+    ];
+    throw new Error(lines.join('\n'));
+  }
+
+  // ─── Build WAV ─────────────────────────────────────────────────────────
+
+  console.log('\n[2/2] Merging audio...');
+  const { audio, wav, duration } = format === 'mp3' || format === 'wav'
+    ? concatAudioBuffers(audioBuffers, format, silence)
+    : buildWav(audioBuffers, silence);
+
+  const outBuffer = audio || wav;
+
+  // Write files
+  const outDir = path.dirname(outputPath);
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(outputPath, outBuffer);
+
+  const textPath = outputPath.replace(/\.(wav|mp3)$/i, '.txt');
+  const textContent = succeededSegments.map((s, i) => {
+    const prefix = s.voiceId ? `[${i + 1}|${s.voiceId}]` : `[${i + 1}]`;
+    return `${prefix} ${s.text}`;
+  }).join('\n\n');
+  fs.writeFileSync(textPath, textContent, 'utf8');
+
+  const quotaUsed = succeededSegments.length;
+  console.log(`\n=== Done ===`);
+  console.log(`Output:   ${outputPath} (${(outBuffer.length / 1024).toFixed(1)} KB, ${duration.toFixed(1)}s)`);
+  console.log(`Transcript: ${textPath}`);
+  console.log(`Segments: ${succeededSegments.length}/${segments.length}${skipped.length ? ` (${skipped.length} skipped)` : ''}`);
+  console.log(`Quota:    ${quotaUsed} used, ${lastQuota?.remaining ?? '?'} remaining`);
+
+  return {
+    outputPath,
+    textPath,
+    duration,
+    quotaUsed,
+    segmentCount: succeededSegments.length,
+    skippedCount: skipped.length,
+    format,
+  };
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseFloatFlag, validateSpeed, validateSilence, validateOutput, validateFormat, runWithRetry } = require('../core/args');
+  const { getToken, getTokenInfo } = require('../core/auth');
+  const { API_BASE } = require('../core/config');
+
+  const api = parseFlag(args, '--api') || API_BASE;
+  const explicitToken = parseFlag(args, '--token');
+
+  // Parse and validate before auth
+  const input = parseFlag(args, '--input');
+  const text = parseFlag(args, '--text');
+  const script = parseFlag(args, '--script');
+  const speed = parseFloatFlag(args, '--speed');
+  const silence = parseFloatFlag(args, '--silence');
+  const output = parseFlag(args, '--output', '-o');
+  const format = parseFlag(args, '--format');
+
+  validateSpeed(args, speed);
+  validateSilence(args, silence);
+  validateOutput(output, format);
+  validateFormat(format);
+
+  // Validate file existence for --input and --script
+  if (input) {
+    const fs = require('fs');
+    const path = require('path');
+    const resolved = path.resolve(input);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Error: Input file not found: ${resolved}`);
+      // Common user mistake: passing inline text to --input. Detect it
+      // (no slash, no extension, contains non-ASCII or spaces) and suggest
+      // the right flag instead of just blaming "file not found".
+      const looksLikeText = !input.includes('/') &&
+        !/\.[a-z0-9]{1,4}$/i.test(input) &&
+        (/[^\x20-\x7e]/.test(input) || input.includes(' '));
+      if (looksLikeText) {
+        console.error('');
+        console.error('  Hint: --input expects a FILE PATH. For inline text use:');
+        console.error(`    voxflow narrate --text ${JSON.stringify(input)}`);
+        console.error(`    voxflow say ${JSON.stringify(input)}            # simpler for one-liners`);
+      }
+      process.exit(1);
+    }
+  }
+
+  if (script) {
+    const fs = require('fs');
+    const path = require('path');
+    const resolved = path.resolve(script);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Error: Script file not found: ${resolved}`);
+      process.exit(1);
+    }
+  }
+
+  // Authenticate after validation
+  let token;
+  if (explicitToken) {
+    token = explicitToken;
+  } else {
+    token = await getToken({ api });
+    const info = getTokenInfo();
+    if (info) {
+      console.log(`\x1b[32mLogged in as ${info.email}\x1b[0m`);
+    }
+  }
+
+  const opts = {
+    token, api,
+    input, text, script,
+    voice: parseFlag(args, '--voice'),
+    output, speed, silence,
+    format: format || undefined,
+  };
+
+  await runWithRetry(narrate, opts, api, explicitToken);
+}
+
+const meta = {
+  narrate: {
+    usage: '[opts]',
+    description: 'Narrate a file, text, or script to audio',
+    options: [
+      `--input <file>       Input .txt or .md file`,
+      `--text <text>        Inline text to narrate`,
+      `--script <file>      JSON script with per-segment voice/speed control`,
+      `--voice <id>         Default voice ID (default: ${NARRATE_DEFAULTS.voice})`,
+      `--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)`,
+    ],
+    examples: [
+      'voxflow narrate --input article.txt --voice v-female-R2s4N9qJ',
+      'voxflow narrate --script narration-script.json',
+      'echo "Hello" | voxflow narrate --output hello.wav',
+    ],
+  },
+};
+
+module.exports = {
+  narrate,
+  handle,
+  meta,
+  ApiError,
+  _test: {
+    parseScript,
+    stripMarkdown,
+    scanSegmentRisks,
+    shouldAutoWrap,
+    chineseContextWrap,
+    synthesizeWithRetry,
+    isTtsProviderRejection,
+  },
+};