voxflow 1.14.0 → 1.15.1

package/lib/commands/picstory.js

@@ -0,0 +1,547 @@
+/**
+ * VoxFlow CLI — PicStory command
+ *
+ * Generates a narrated visual story video:
+ *   1. LLM script → structured scenes (heading + keyPoints + narration)
+ *   2. TTS per scene (sequential)
+ *   3. AI image per scene (parallel via /api/image/generate)
+ *   4. FFmpeg Ken Burns render + concat → MP4
+ *
+ * Visual styles: sketchnote, neon_noir, minimal_3d, chalkboard (card),
+ *                photo, manga_panel, vintage_newspaper (scene)
+ * Ratios: portrait (1080×1920), landscape (1920×1080), square (1080×1080)
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { PICSTORY_DEFAULTS } = require('../core/config');
+const { request, throwApiError, throwNetworkError } = require('../core/http');
+const { buildWav } = require('../core/audio');
+const { BYTES_PER_MS } = require('../core/timeline');
+const { synthesizeTTS } = require('../core/tts-synthesizer');
+const { generateImage } = require('../core/image-client');
+const { runCommand, checkFfmpeg, concatVideos } = require('../core/ffmpeg');
+const { startSpinner } = require('../core/spinner');
+const {
+  RATIO_CONFIG, VALID_RATIOS, VALID_STYLES,
+  buildSystemPrompt, buildImagePrompt,
+  buildSketchnotePrompt, buildPhotoPrompt,
+} = require('./picstory-templates');
+
+// ─── Script Model Presets ─────────────────────────────────────────────────────
+
+/**
+ * Named model presets for LLM script generation.
+ * Must stay in sync with PICSTORY_SCRIPT_PRESETS in backend/utils/llm-request.js.
+ * Users pick a preset name; the CLI resolves it to {provider, model} for the API call.
+ */
+const SCRIPT_MODEL_PRESETS = {
+  'default':      null,  // use server default (LLM_DEFAULT_PROVIDER + LLM_MODEL)
+  'gemini-flash': { provider: 'openrouter', model: 'google/gemini-3-flash-preview' },
+  'deepseek':     { provider: 'deepseek',   model: 'deepseek-chat' },
+  'hunyuan':      { provider: 'hunyuan',    model: 'hunyuan-lite' },
+  'moonshot':     { provider: 'moonshot',   model: 'moonshot-v1-8k' },
+};
+
+const VALID_SCRIPT_MODELS = Object.keys(SCRIPT_MODEL_PRESETS);
+
+// ─── LLM Script Generation ────────────────────────────────────────────────────
+
+async function generateScript(apiBase, token, topic, { language, sceneCount, style, scriptModel }) {
+  const systemPrompt = buildSystemPrompt(style);
+  const userPrompt = [
+    `Topic: ${topic}`,
+    `Language: ${language}`,
+    `Number of scenes: ${sceneCount}`,
+    `Visual style: ${style}`,
+    '',
+    `Generate a compelling ${sceneCount}-scene picstory script about the topic above.`,
+    'Each scene should cover a distinct aspect or step.',
+  ].join('\n');
+
+  const preset = scriptModel && scriptModel !== 'default'
+    ? SCRIPT_MODEL_PRESETS[scriptModel]
+    : null;
+
+  const body = {
+    messages: [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userPrompt },
+    ],
+    temperature: 0.7,
+    max_tokens: 2000,
+  };
+  if (preset) {
+    body.model = preset.model;
+    body.provider = preset.provider;
+  }
+
+  let status, data;
+  try {
+    ({ status, data } = await request(`${apiBase}/api/llm/chat`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      timeoutMs: 180_000,
+    }, body));
+  } catch (err) {
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') throwApiError(status, data, 'LLM script');
+
+  let script;
+  try {
+    const raw = data.content.trim().replace(/^```json\s*/i, '').replace(/```\s*$/, '');
+    script = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`LLM returned invalid JSON: ${err.message}\nContent: ${data.content.slice(0, 200)}`);
+  }
+
+  if (!script.title || !Array.isArray(script.scenes) || script.scenes.length === 0) {
+    throw new Error('LLM script missing required fields: title, scenes[]');
+  }
+
+  return { script, quota: data.quota };
+}
+
+// ─── FFmpeg Per-Scene Render ──────────────────────────────────────────────────
+
+// Zoom anchor positions — varied per scene for visual interest
+const ZOOM_ANCHORS = [
+  { x: `'iw/2-(iw/zoom/2)'`,  y: `'ih/2-(ih/zoom/2)'`  }, // center
+  { x: `'0'`,                  y: `'0'`                   }, // top-left
+  { x: `'iw-iw/zoom'`,         y: `'ih-ih/zoom'`          }, // bottom-right
+  { x: `'iw-iw/zoom'`,         y: `'0'`                   }, // top-right
+];
+
+/**
+ * Render a single scene: image + WAV → MP4 with Ken Burns zoom + fade transitions.
+ * Uses output-frame-counter `on` for drift-free linear zoom.
+ * fadeSeconds > 0 adds fade-in from black and fade-out to black at scene boundaries,
+ * creating smooth transitions when scenes are concatenated.
+ */
+async function renderScene({ imgPath, wavPath, outPath, durationMs, ratio, sceneIndex = 0, fadeSeconds = 0.4 }) {
+  const { w, h } = RATIO_CONFIG[ratio] || RATIO_CONFIG.portrait;
+  const fps = 30;
+  const durationSec = durationMs / 1000;
+  const frames = Math.max(2, Math.round(durationSec * fps));
+
+  // Drift-free Ken Burns: z = 1.0 + rate*on, no accumulated floating-point error
+  const zoomRate = (0.25 / Math.max(frames - 1, 1)).toFixed(8);
+  const zoomExpr = `'min(1.0+${zoomRate}*on,1.25)'`;
+  const { x: xExpr, y: yExpr } = ZOOM_ANCHORS[sceneIndex % ZOOM_ANCHORS.length];
+
+  const fd = fadeSeconds > 0 && durationSec > fadeSeconds * 2.5 ? fadeSeconds : 0;
+  const fadeOutStart = (durationSec - fd).toFixed(3);
+
+  const vfParts = [
+    `scale=${w}:${h}:force_original_aspect_ratio=increase`,
+    `crop=${w}:${h}`,
+    `zoompan=z=${zoomExpr}:x=${xExpr}:y=${yExpr}:d=${frames}:s=${w}x${h}:fps=${fps}`,
+  ];
+  if (fd > 0) {
+    vfParts.push(`fade=t=in:st=0:d=${fd}`, `fade=t=out:st=${fadeOutStart}:d=${fd}`);
+  }
+  vfParts.push('format=yuv420p');
+
+  const audioFilterParts = fd > 0
+    ? [`afade=t=in:st=0:d=${fd}`, `afade=t=out:st=${fadeOutStart}:d=${fd}`]
+    : [];
+
+  const args = [
+    '-loop', '1',
+    '-t', String(durationSec + 0.1),
+    '-i', path.resolve(imgPath),
+    '-i', path.resolve(wavPath),
+    '-vf', vfParts.join(','),
+  ];
+
+  if (audioFilterParts.length > 0) {
+    args.push('-af', audioFilterParts.join(','));
+  }
+
+  args.push(
+    '-c:v', 'libx264', '-preset', 'fast', '-crf', '22',
+    '-c:a', 'aac', '-b:a', '128k', '-ar', '24000', '-ac', '1',
+    '-shortest',
+    '-movflags', '+faststart',
+    '-y', path.resolve(outPath),
+  );
+
+  await runCommand('ffmpeg', args);
+}
+
+/**
+ * Mix background music into a video file.
+ * BGM loops to cover the full video duration, fades in at start.
+ */
+async function mixBgmIntoVideo(videoPath, bgmPath, outputPath, opts = {}) {
+  const volume = opts.volume ?? 0.1;
+  const fadeIn = opts.fadeIn ?? 2.0;
+  await runCommand('ffmpeg', [
+    '-i', path.resolve(videoPath),
+    '-stream_loop', '-1',
+    '-i', path.resolve(bgmPath),
+    '-filter_complex',
+    `[1:a]volume=${volume},afade=t=in:st=0:d=${fadeIn}[bgm];[0:a][bgm]amix=inputs=2:duration=first:dropout_transition=2[out]`,
+    '-map', '0:v',
+    '-map', '[out]',
+    '-c:v', 'copy',
+    '-c:a', 'aac', '-b:a', '128k',
+    '-y', path.resolve(outputPath),
+  ]);
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Generate a narrated visual story video.
+ */
+async function picstory(opts) {
+  const {
+    token, api: apiBase,
+    topic, text: inputText,
+    voice = PICSTORY_DEFAULTS.voice,
+    speed = PICSTORY_DEFAULTS.speed,
+    style = PICSTORY_DEFAULTS.style,
+    ratio = PICSTORY_DEFAULTS.ratio,
+    language = PICSTORY_DEFAULTS.language,
+    sceneCount = PICSTORY_DEFAULTS.sceneCount,
+    quality = PICSTORY_DEFAULTS.quality,
+    fadeSeconds = PICSTORY_DEFAULTS.fadeSeconds,
+    bgm,
+    bgmVolume = PICSTORY_DEFAULTS.bgmVolume,
+    imageOnly = false,
+    scriptModel = 'default',
+  } = opts;
+
+  const scriptInput = inputText || topic;
+  if (!scriptInput) throw new Error('No input provided. Use --topic or --text');
+
+  const sigintHandler = () => { console.log('\n\nGeneration cancelled.'); process.exit(130); };
+  process.on('SIGINT', sigintHandler);
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'voxflow-picstory-'));
+
+  try {
+    // ── Step 1: LLM script ────────────────────────────────────────────────────
+    console.log('\n[1/4] Generating script via LLM...');
+    const modelLabel = scriptModel && scriptModel !== 'default' ? `, model: ${scriptModel}` : '';
+    console.log(`    Topic: "${scriptInput.slice(0, 80)}" (${language}, ${sceneCount} scenes, ${style}${modelLabel})`);
+
+    const spinner1 = startSpinner('    Thinking...');
+    let script, llmQuota;
+    try {
+      ({ script, quota: llmQuota } = await generateScript(
+        apiBase, token, scriptInput, { language, sceneCount, style, scriptModel }
+      ));
+      spinner1.stop(`OK — "${script.title}" (${script.scenes.length} scenes)`);
+    } catch (err) {
+      spinner1.stop('FAIL');
+      throw err;
+    }
+
+    // ── Step 2: TTS narration ─────────────────────────────────────────────────
+    console.log(`\n[2/4] Synthesizing narration (${script.scenes.length} scenes)...`);
+
+    const sceneData = [];
+    let lastTtsQuota = llmQuota;
+
+    for (let i = 0; i < script.scenes.length; i++) {
+      const narration = script.scenes[i].narration || '';
+      if (!narration.trim()) {
+        sceneData.push({ scene: script.scenes[i], pcm: Buffer.alloc(48 * 1000), durationMs: 1000 });
+        continue;
+      }
+      const result = await synthesizeTTS({
+        apiBase, token, text: narration, voiceId: voice, speed,
+        index: i, total: script.scenes.length,
+      });
+      const durationMs = Math.round(result.audio.length / BYTES_PER_MS);
+      console.log(` OK (${(result.audio.length / 1024).toFixed(0)} KB, ${(durationMs / 1000).toFixed(1)}s)`);
+      lastTtsQuota = result.quota;
+      sceneData.push({ scene: script.scenes[i], pcm: result.audio, durationMs });
+    }
+
+    // ── Step 3: Image generation (parallel) ──────────────────────────────────
+    console.log(`\n[3/4] Generating images (${script.scenes.length} scenes, parallel)...`);
+
+    let lastImgQuota = lastTtsQuota;
+    const imageTasks = script.scenes.map((scene, i) => {
+      const prompt = buildImagePrompt(scene, style, ratio);
+      return generateImage({ apiBase, token, prompt, ratio, quality, index: i, total: script.scenes.length })
+        .then(result => { lastImgQuota = result.quota; return result.imageDataUrl; });
+    });
+    const imageDataUrls = await Promise.all(imageTasks);
+
+    // ── Step 4: Write temp files + FFmpeg render ──────────────────────────────
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const outputPath = opts.output || resolveOutputPath(`picstory-${timestamp}.mp4`, opts.outputDir);
+
+    if (imageOnly) {
+      console.log('\n[4/4] Saving images and audio...');
+      const base = outputPath.replace(/\.mp4$/i, '');
+      for (let i = 0; i < sceneData.length; i++) {
+        const imgPath = `${base}-scene-${i + 1}.jpg`;
+        const wavPath = `${base}-scene-${i + 1}.wav`;
+        saveImageDataUrl(imageDataUrls[i], imgPath);
+        fs.writeFileSync(wavPath, buildWav([sceneData[i].pcm], 0).wav);
+        console.log(`    Scene ${i + 1}: ${imgPath} + ${wavPath}`);
+      }
+      const totalMs = sceneData.reduce((s, d) => s + d.durationMs, 0);
+      const scriptPath = `${base}-script.json`;
+      fs.writeFileSync(scriptPath, JSON.stringify(script, null, 2));
+      printSummary({ outputPath: null, imageOnly: true, script, totalMs, sceneCount: sceneData.length, style, ratio, lastQuota: lastImgQuota });
+      return { outputPath: null, scriptPath, duration: totalMs };
+    }
+
+    const ffmpegInfo = await checkFfmpeg();
+    if (!ffmpegInfo.available) {
+      throw new Error(
+        'ffmpeg not found. picstory requires ffmpeg for video rendering.\n' +
+        '  Install: brew install ffmpeg (macOS) / sudo apt install ffmpeg (Linux)'
+      );
+    }
+
+    console.log('\n[4/4] Rendering video...');
+    const sceneMp4Paths = [];
+    for (let i = 0; i < sceneData.length; i++) {
+      process.stdout.write(`    Scene [${i + 1}/${sceneData.length}]...`);
+      const imgPath = path.join(tmpDir, `scene-${i}.jpg`);
+      const wavPath = path.join(tmpDir, `scene-${i}.wav`);
+      const mp4Path = path.join(tmpDir, `scene-${i}.mp4`);
+
+      saveImageDataUrl(imageDataUrls[i], imgPath);
+      fs.writeFileSync(wavPath, buildWav([sceneData[i].pcm], 0).wav);
+
+      try {
+        await renderScene({ imgPath, wavPath, outPath: mp4Path, durationMs: sceneData[i].durationMs, ratio, sceneIndex: i, fadeSeconds });
+        console.log(' OK');
+        sceneMp4Paths.push(mp4Path);
+      } catch (err) {
+        console.log(' FAIL');
+        throw new Error(`Scene ${i + 1} render failed: ${err.message}`);
+      }
+    }
+
+    // Concat all scenes; BGM needs a separate mux pass so use a temp path when BGM is present
+    const concatTarget = bgm ? path.join(tmpDir, 'concat.mp4') : path.resolve(outputPath);
+    process.stdout.write('    Concatenating scenes...');
+    try {
+      await concatVideos(sceneMp4Paths, concatTarget);
+      console.log(' OK');
+    } catch (err) {
+      console.log(' FAIL');
+      throw new Error(`Concat failed: ${err.message}`);
+    }
+
+    if (bgm) {
+      process.stdout.write('    Mixing BGM...');
+      try {
+        await mixBgmIntoVideo(concatTarget, bgm, path.resolve(outputPath), { volume: bgmVolume });
+        console.log(' OK');
+      } catch (err) {
+        console.log(` WARN (BGM mix failed: ${err.message.slice(0, 80)})`);
+        // Fall back to the no-BGM concat output
+        fs.copyFileSync(concatTarget, path.resolve(outputPath));
+      }
+    }
+
+    const scriptPath = outputPath.replace(/\.mp4$/i, '.json');
+    fs.writeFileSync(scriptPath, JSON.stringify(script, null, 2));
+    const totalMs = sceneData.reduce((s, d) => s + d.durationMs, 0);
+    printSummary({ outputPath, imageOnly: false, script, totalMs, sceneCount: sceneData.length, style, ratio, lastQuota: lastImgQuota, bgm });
+
+    return { outputPath, scriptPath, duration: totalMs };
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function resolveOutputPath(filename, outputDir) {
+  if (!outputDir) return filename;
+  fs.mkdirSync(outputDir, { recursive: true });
+  return path.join(outputDir, path.basename(filename));
+}
+
+function saveImageDataUrl(dataUrl, filePath) {
+  const base64 = dataUrl.startsWith('data:') ? dataUrl.slice(dataUrl.indexOf(',') + 1) : dataUrl;
+  fs.writeFileSync(filePath, Buffer.from(base64, 'base64'));
+}
+
+function printSummary({ outputPath, imageOnly, script, totalMs, sceneCount, style, ratio, lastQuota, bgm }) {
+  const totalSec = Math.round(totalMs / 1000);
+  const durationStr = totalSec >= 60
+    ? `${Math.floor(totalSec / 60)}m${String(totalSec % 60).padStart(2, '0')}s`
+    : `${totalSec}s`;
+
+  console.log('\n=== Output ===');
+  if (outputPath) {
+    console.log(`  Video:    ${outputPath} (${(fs.statSync(outputPath).size / (1024 * 1024)).toFixed(1)} MB, ${durationStr})`);
+  } else if (imageOnly) {
+    console.log(`  Mode:     images + audio saved (no video render)`);
+    console.log(`  Duration: ~${durationStr}`);
+  }
+  console.log(`  Title:    ${script.title}`);
+  console.log(`  Scenes:   ${sceneCount}`);
+  console.log(`  Style:    ${style} / ${ratio}`);
+  if (bgm) console.log(`  BGM:      ${path.basename(bgm)}`);
+  if (lastQuota) console.log(`  Quota:    ${lastQuota.remaining ?? '?'} remaining`);
+}
+
+// ─── CLI Handler ──────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const {
+    parseFlag, parseIntFlag, parseFloatFlag, parseBoolFlag,
+    validateSpeed, 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');
+  const speed = parseFloatFlag(args, '--speed');
+  const output = parseFlag(args, '--output', '-o');
+  const scenes = parseIntFlag(args, '--scenes');
+
+  validateSpeed(args, speed);
+
+  if (output && !/\.mp4$/i.test(output)) {
+    console.error('Error: --output path must end with .mp4');
+    process.exit(1);
+  }
+
+  const style = parseFlag(args, '--style');
+  if (style && !VALID_STYLES.includes(style)) {
+    console.error(`Error: --style must be one of: ${VALID_STYLES.join(', ')} (got: "${style}")`);
+    process.exit(1);
+  }
+
+  const ratio = parseFlag(args, '--ratio');
+  if (ratio && !VALID_RATIOS.includes(ratio)) {
+    console.error(`Error: --ratio must be one of: ${VALID_RATIOS.join(', ')} (got: "${ratio}")`);
+    process.exit(1);
+  }
+
+  if (scenes !== undefined && (isNaN(scenes) || scenes < 2 || scenes > 10)) {
+    console.error(`Error: --scenes must be between 2 and 10 (got: "${parseFlag(args, '--scenes')}")`);
+    process.exit(1);
+  }
+
+  const topic = parseFlag(args, '--topic');
+  const text = parseFlag(args, '--text');
+  if (!topic && !text) {
+    console.error('Error: provide --topic <text> or --text <content>');
+    process.exit(1);
+  }
+
+  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 quality = parseFlag(args, '--quality');
+  const VALID_QUALITIES = ['fast', 'hd', 'ultra', 'fast-aiberm', 'hd-aiberm'];
+  if (quality && !VALID_QUALITIES.includes(quality)) {
+    console.error(`Error: --quality must be one of: ${VALID_QUALITIES.join(', ')}`);
+    process.exit(1);
+  }
+
+  const scriptModel = parseFlag(args, '--script-model');
+  if (scriptModel && !VALID_SCRIPT_MODELS.includes(scriptModel)) {
+    console.error(`Error: --script-model must be one of: ${VALID_SCRIPT_MODELS.join(', ')} (got: "${scriptModel}")`);
+    process.exit(1);
+  }
+
+  const outputDir = parseFlag(args, '--output-dir', '-d');
+  const bgm = parseFlag(args, '--bgm');
+  if (bgm) {
+    const bgmResolved = path.resolve(bgm);
+    if (!fs.existsSync(bgmResolved)) {
+      console.error(`Error: --bgm file not found: ${bgm}`);
+      process.exit(1);
+    }
+  }
+  const bgmVolume = parseFloatFlag(args, '--bgm-volume');
+  if (bgmVolume !== undefined && (isNaN(bgmVolume) || bgmVolume < 0 || bgmVolume > 1)) {
+    console.error('Error: --bgm-volume must be between 0 and 1');
+    process.exit(1);
+  }
+  const fadeSeconds = parseFloatFlag(args, '--fade');
+
+  const opts = {
+    token, api,
+    topic: topic || undefined,
+    text: text || undefined,
+    voice: parseFlag(args, '--voice') || undefined,
+    speed, output,
+    outputDir: outputDir || undefined,
+    style: style || undefined,
+    ratio: ratio || undefined,
+    language: parseFlag(args, '--language') || undefined,
+    sceneCount: scenes,
+    quality: quality || undefined,
+    fadeSeconds: fadeSeconds !== undefined ? fadeSeconds : undefined,
+    bgm: bgm ? path.resolve(bgm) : undefined,
+    bgmVolume: bgmVolume !== undefined ? bgmVolume : undefined,
+    imageOnly: parseBoolFlag(args, '--image-only'),
+    scriptModel: scriptModel || undefined,
+  };
+
+  await runWithRetry(picstory, opts, api, explicitToken);
+}
+
+// ─── Metadata ─────────────────────────────────────────────────────────────────
+
+const meta = {
+  picstory: {
+    usage: '<--topic|--text> [opts]',
+    description: 'Generate a narrated visual story video (AI images + TTS + MP4)',
+    options: [
+      `--topic <text>       Story topic`,
+      `--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.`,
+      `--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`,
+      `--speed <n>          TTS speed 0.5-2.0 (default: ${PICSTORY_DEFAULTS.speed})`,
+      `--script-model <preset>  LLM model for script generation: ${VALID_SCRIPT_MODELS.join(', ')} (default: server default)`,
+      `--bgm <file>         Background music file (.mp3/.wav) to mix under narration`,
+      `--bgm-volume <n>     BGM volume 0-1 (default: ${PICSTORY_DEFAULTS.bgmVolume})`,
+      `--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)`,
+    ],
+    examples: [
+      'voxflow picstory --topic "AI Agent 入门" --style sketchnote',
+      'voxflow picstory --topic "React hooks explained" --style photo --ratio landscape --language en',
+      'voxflow picstory --topic "量子计算原理" --style minimal_3d --scenes 6',
+      'voxflow picstory --topic "产品增长故事" --style neon_noir --bgm ~/music/lofi.mp3',
+      'voxflow picstory --topic "三体故事" --style manga_panel --ratio portrait',
+      'voxflow picstory --topic "2026 AI趋势" --output-dir ~/my-videos --fade 0.6',
+    ],
+  },
+};
+
+module.exports = {
+  picstory, handle, meta,
+  buildSketchnotePrompt, buildPhotoPrompt, buildImagePrompt,
+  VALID_STYLES, VALID_RATIOS, RATIO_CONFIG,
+  SCRIPT_MODEL_PRESETS, VALID_SCRIPT_MODELS,
+  _test: {
+    buildSketchnotePrompt, buildPhotoPrompt, buildImagePrompt, buildSystemPrompt, saveImageDataUrl,
+    ...require('./picstory-templates')._test,
+  },
+};

package/lib/commands/podcast/dialogue.js

@@ -0,0 +1,109 @@
+/**
+ * Podcast command — Dialogue parsing and script loading.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// CJK range covers CJK Unified Ideographs + Hiragana/Katakana
+const CJK_REGEX = /[぀-ヿ㐀-䶿一-鿿]/;
+
+/**
+ * Load and validate a podcast script JSON file.
+ *
+ * Expected format:
+ *   {
+ *     "segments": [
+ *       { "speaker": "Host", "text": "Welcome to the show" },
+ *       { "speaker": "Guest", "text": "Thanks for having me" }
+ *     ],
+ *     "voiceMapping": { ... }
+ *   }
+ */
+function loadScript(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Script file not found: ${resolved}`);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  } catch (err) {
+    throw new Error(`Invalid JSON in script file: ${err.message}`);
+  }
+
+  if (!Array.isArray(raw.segments) || raw.segments.length === 0) {
+    throw new Error(
+      'Script must contain a non-empty "segments" array.\n' +
+      'Expected: { "segments": [{ "speaker": "Host", "text": "Hello" }, ...] }'
+    );
+  }
+
+  for (let i = 0; i < raw.segments.length; i++) {
+    const seg = raw.segments[i];
+    if (!seg || typeof seg.speaker !== 'string' || !seg.speaker.trim()) {
+      throw new Error(`Script segment [${i}] is missing a valid "speaker" field`);
+    }
+    if (!seg || typeof seg.text !== 'string' || !seg.text.trim()) {
+      throw new Error(`Script segment [${i}] is missing a valid "text" field`);
+    }
+  }
+
+  return {
+    segments: raw.segments.map(s => ({ speaker: s.speaker.trim(), text: s.text.trim() })),
+    voiceMapping: raw.voiceMapping || {},
+  };
+}
+
+/**
+ * Parse dialogue text into segments with speaker and text.
+ * Format: "SpeakerName：content" or "SpeakerName: content".
+ */
+function parseDialogueText(text, opts = {}) {
+  const lines = text.split('\n').filter(line => line.trim());
+  const segments = [];
+  const dialoguePattern = /^([^:：]+)[：:]\s*(.+)$/;
+
+  const narratorLabel = opts.narratorLabel
+    || (CJK_REGEX.test(text) ? '旁白' : 'Narrator');
+
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine) continue;
+
+    const match = trimmedLine.match(dialoguePattern);
+    if (match) {
+      const speaker = match[1].trim();
+      const content = match[2].trim();
+      if (content) {
+        segments.push({ speaker, text: content });
+      }
+    } else if (trimmedLine.length > 0) {
+      segments.push({ speaker: narratorLabel, text: trimmedLine });
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Convert structured PodcastScript dialogue array to segments.
+ */
+function parseStructuredScript(script) {
+  if (!script?.dialogue || !Array.isArray(script.dialogue)) return [];
+  return script.dialogue.map(turn => {
+    const speakerInfo = script.speakers?.[turn.speaker];
+    const speakerName = speakerInfo?.name || turn.speaker;
+    return {
+      speaker: speakerName,
+      text: turn.text,
+      intent: turn.intent || null,
+      pauseAfterMs: Number.isFinite(turn.pauseAfterMs) ? turn.pauseAfterMs : null
+    };
+  });
+}
+
+module.exports = { loadScript, parseDialogueText, parseStructuredScript };