voxflow 1.15.0 → 1.15.2

package/lib/commands/slides.js

@@ -0,0 +1,11 @@
+/**
+ * VoxFlow CLI — Slides command
+ *
+ * Thin dispatcher — delegates to submodules in ./slides/.
+ * See slides/index.js for the orchestrator, slides/constants.js,
+ * slides/html-renderer.js for layout rendering and CSS.
+ */
+
+'use strict';
+
+module.exports = require('./slides/index');

package/lib/commands/story.js

@@ -0,0 +1,302 @@
+/**
+ * VoxFlow CLI — Story command
+ *
+ * Generates a story with TTS narration.
+ * Pipeline: LLM → parse paragraphs → TTS per paragraph → WAV
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { STORY_DEFAULTS } = require('../core/config');
+const { request, throwApiError, throwNetworkError, ApiError } = require('../core/http');
+const { parseParagraphs, buildWav, createSilence } = require('../core/audio');
+const { startSpinner } = require('../core/spinner');
+const { synthesizeTTS } = require('../core/tts-synthesizer');
+
+// ─── Step 1: Generate Story ─────────────────────────────────────────────────
+
+async function generateStory(apiBase, token, topic) {
+  const spinner = startSpinner('\n[1/3] Generating story text...');
+
+  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,
+    }, {
+      messages: [{ role: 'user', content: topic }],
+      stream: false,
+      temperature: 0.8,
+    }));
+  } catch (err) {
+    spinner.stop('FAIL');
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') {
+    spinner.stop('FAIL');
+    throwApiError(status, data, 'LLM');
+  }
+
+  const story = data.content;
+  const quota = data.quota;
+  spinner.stop('OK');
+  console.log(`    ${story.length} chars. Quota remaining: ${quota?.remaining ?? '?'}`);
+  return { story, quota };
+}
+
+// ─── Step 2: TTS Synthesis ──────────────────────────────────────────────────
+
+async function synthesizeParagraph(apiBase, token, text, voiceId, speed, index, total) {
+  const result = await synthesizeTTS({
+    apiBase, token, text, voiceId, speed,
+    index, total,
+  });
+
+  console.log(` OK (${(result.audio.length / 1024).toFixed(0)} KB)`);
+  return { pcm: result.audio, quota: result.quota };
+}
+
+async function synthesizeAll(apiBase, token, paragraphs, voiceId, speed) {
+  console.log(`\n[2/3] Synthesizing TTS audio (${paragraphs.length} segments)...`);
+
+  const pcmBuffers = [];
+  let lastQuota = null;
+  for (let i = 0; i < paragraphs.length; i++) {
+    const result = await synthesizeParagraph(apiBase, token, paragraphs[i], voiceId, speed, i, paragraphs.length);
+    pcmBuffers.push(result.pcm);
+    lastQuota = result.quota;
+  }
+
+  return { pcmBuffers, quota: lastQuota };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate a story with TTS narration.
+ *
+ * @param {object} opts
+ * @param {string} opts.token       - JWT token
+ * @param {string} opts.api         - API base URL
+ * @param {string} [opts.voice]     - TTS voice ID
+ * @param {string} [opts.topic]     - Story prompt
+ * @param {string} [opts.output]    - Output WAV path
+ * @param {number} [opts.paragraphs]- Number of paragraphs
+ * @param {number} [opts.speed]     - TTS speed
+ * @param {number} [opts.silence]   - Silence gap between paragraphs (seconds)
+ * @returns {Promise<{outputPath: string, textPath: string, duration: number, quotaUsed: number}>}
+ */
+async function story(opts) {
+  // SIGINT handler for graceful cancellation
+  const sigintHandler = () => {
+    console.log('\n\nGeneration cancelled.');
+    process.exit(130);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  try {
+    return await _story(opts);
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+  }
+}
+
+function buildStoryPrompt(userTopic, paragraphCount) {
+  if (userTopic) {
+    return `${userTopic}\n\n要求：\n1. 严格输出 ${paragraphCount} 段（不多不少）\n2. 段落之间用且仅用一个空行分隔\n3. 不要添加段落编号、标题或前言，直接输出正文`;
+  }
+  return `请写一个适合5岁儿童的短故事，要求：
+1. 严格输出 ${paragraphCount} 段（不多不少），每段 2-3 句话
+2. 每段描述一个清晰的画面场景
+3. 语言简单易懂，充满童趣
+4. 段落之间用且仅用一个空行分隔
+5. 不要添加段落编号、标题或前言，直接输出故事内容`;
+}
+
+/**
+ * Clamp parsed paragraphs to exactly `target` count.
+ *
+ * The LLM doesn't always strictly honor the prompt constraint — if it
+ * returns more paragraphs than requested, we merge consecutive ones into
+ * roughly equal-sized buckets. If it returns fewer, we keep what we got.
+ *
+ * Issue #2916: `voxflow story --topic ... --paragraphs 1` was returning
+ * 5+ paragraphs even after the prompt fix. Hard-clamp guarantees the user
+ * gets exactly N TTS segments and quota cost is what they expected.
+ */
+function clampParagraphs(paragraphs, target) {
+  if (!Array.isArray(paragraphs)) return [];
+  if (paragraphs.length <= target || target < 1) return paragraphs;
+  const buckets = Array.from({ length: target }, () => []);
+  for (let i = 0; i < paragraphs.length; i++) {
+    const slot = Math.min(target - 1, Math.floor((i * target) / paragraphs.length));
+    buckets[slot].push(paragraphs[i]);
+  }
+  return buckets.map(b => b.join(' ')).filter(s => s.trim().length > 0);
+}
+
+async function _story(opts) {
+  const voice = opts.voice || STORY_DEFAULTS.voice;
+  const paragraphCount = opts.paragraphs || STORY_DEFAULTS.paragraphs;
+  const speed = opts.speed ?? STORY_DEFAULTS.speed;
+  const silence = opts.silence ?? STORY_DEFAULTS.silence;
+  const api = opts.api;
+  const token = opts.token;
+
+  // When the user passes --topic, the default paragraph-structure prompt
+  // was dropped, so --paragraphs was silently ignored (issue #2916).
+  // buildStoryPrompt always injects the paragraph constraint.
+  const topic = buildStoryPrompt(opts.topic, paragraphCount);
+
+  // Default output path
+  let outputPath = opts.output;
+  if (!outputPath) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    outputPath = path.resolve(`story-${ts}.wav`);
+  }
+
+  console.log('\n=== VoxFlow Story Generator ===');
+  console.log(`Voice:      ${voice}`);
+  console.log(`API:        ${api}`);
+  console.log(`Paragraphs: ${paragraphCount}`);
+  console.log(`Speed:      ${speed}`);
+  console.log(`Output:     ${outputPath}`);
+
+  // Step 1: LLM
+  const { story: storyText } = await generateStory(api, token, topic);
+
+  // Step 2: Parse + clamp to requested paragraph count
+  const rawParagraphs = parseParagraphs(storyText);
+  if (rawParagraphs.length === 0) {
+    throw new Error('No paragraphs found in generated story');
+  }
+  const paragraphs = clampParagraphs(rawParagraphs, paragraphCount);
+  if (rawParagraphs.length !== paragraphs.length) {
+    console.log(`    ${rawParagraphs.length} paragraphs from LLM → merged to ${paragraphs.length} (--paragraphs ${paragraphCount})`);
+  } else {
+    console.log(`    ${paragraphs.length} paragraphs`);
+  }
+
+  // Step 3: TTS
+  const { pcmBuffers, quota: lastQuota } = await synthesizeAll(api, token, paragraphs, voice, speed);
+
+  // Step 4: WAV
+  console.log('\n[3/3] Merging audio...');
+  const { wav, duration } = buildWav(pcmBuffers, silence);
+
+  // Write files
+  const outDir = path.dirname(outputPath);
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const outputExt = path.extname(outputPath).toLowerCase();
+  const needsConvert = outputExt !== '.wav';
+
+  if (needsConvert) {
+    // Write WAV to a temp file, then convert to the target format
+    const tempWavPath = outputPath.replace(/\.[^.]+$/, '.tmp.wav');
+    fs.writeFileSync(tempWavPath, wav);
+
+    const { checkFfmpeg, convertAudioFormat } = require('../core/ffmpeg');
+    const ffmpegInfo = await checkFfmpeg();
+    if (!ffmpegInfo.available) {
+      // Fallback: keep the WAV temp file as the output
+      fs.renameSync(tempWavPath, outputPath);
+      console.log(`\n    Warning: ffmpeg not found, saved as WAV in ${outputPath}`);
+    } else {
+      await convertAudioFormat(tempWavPath, outputPath);
+      try { fs.unlinkSync(tempWavPath); } catch { /* ignore */ }
+    }
+  } else {
+    fs.writeFileSync(outputPath, wav);
+  }
+
+  // Derive text path using path.extname for robustness (works for any extension)
+  const textPath = outputPath.slice(0, -path.extname(outputPath).length) + '.txt';
+  const textContent = paragraphs.map((p, i) => `[${i + 1}] ${p}`).join('\n\n');
+  fs.writeFileSync(textPath, textContent, 'utf8');
+
+  const quotaUsed = 1 + paragraphs.length;
+  console.log(`\n=== Done ===`);
+  console.log(`Output: ${outputPath} (${(fs.statSync(outputPath).size / 1024).toFixed(1)} KB, ${duration.toFixed(1)}s)`);
+  console.log(`Story:  ${textPath}`);
+  console.log(`Quota:  ${quotaUsed} used, ${lastQuota?.remaining ?? '?'} remaining`);
+
+  return { outputPath, textPath, duration, quotaUsed };
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseIntFlag, parseFloatFlag, validateSpeed, validateSilence, validateOutput, 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 options before auth
+  const paragraphs = parseIntFlag(args, '--paragraphs');
+  const speed = parseFloatFlag(args, '--speed');
+  const silence = parseFloatFlag(args, '--silence');
+  const output = parseFlag(args, '--output', '-o');
+
+  if (paragraphs !== undefined) {
+    if (isNaN(paragraphs) || paragraphs < 1 || paragraphs > 20) {
+      console.error(`Error: --paragraphs must be an integer between 1 and 20 (got: "${parseFlag(args, '--paragraphs')}")`);
+      process.exit(1);
+    }
+  }
+
+  validateSpeed(args, speed);
+  validateSilence(args, silence);
+  validateOutput(output);
+
+  // 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,
+    topic: parseFlag(args, '--topic'),
+    voice: parseFlag(args, '--voice'),
+    output, paragraphs, speed, silence,
+  };
+
+  await runWithRetry(story, opts, api, explicitToken);
+}
+
+const meta = {
+  story: {
+    usage: '[opts]',
+    description: 'Generate a story with TTS narration',
+    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)`,
+      `--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})`,
+    ],
+    examples: [
+      'voxflow story --topic "三只小猪"',
+      'voxflow story --topic "space adventure" --voice v-male-Bk7vD3xP --paragraphs 10',
+    ],
+  },
+  // Alias picked up by the CLI router (issue #2389)
+  generate: { alias: 'story', description: 'Alias for story' },
+};
+
+module.exports = { story, handle, meta, ApiError, _test: { parseParagraphs, buildWav, createSilence, buildStoryPrompt, clampParagraphs } };