voxflow 1.15.0 → 1.15.2

package/lib/core/image-client.js

@@ -0,0 +1,55 @@
+/**
+ * VoxFlow CLI — Image generation client
+ *
+ * Calls /api/image/generate to produce AI images for picstory scenes.
+ */
+
+const { request, throwApiError, throwNetworkError } = require('./http');
+
+/**
+ * Generate an image via the VoxFlow image API.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase  - API base URL
+ * @param {string} opts.token    - JWT auth token
+ * @param {string} opts.prompt   - Image generation prompt
+ * @param {string} [opts.ratio='portrait']  - 'portrait' | 'landscape' | 'square'
+ * @param {string} [opts.quality='fast']    - 'fast' | 'hd'
+ * @param {number} [opts.index]  - Current scene index (for progress output)
+ * @param {number} [opts.total]  - Total scene count (for progress output)
+ * @returns {Promise<{ imageDataUrl: string, quota: object }>}
+ */
+async function generateImage({ apiBase, token, prompt, ratio = 'portrait', quality = 'fast', index, total }) {
+  if (index !== undefined && total !== undefined) {
+    process.stdout.write(`    Image [${index + 1}/${total}]...`);
+  }
+
+  let status, data;
+  try {
+    ({ status, data } = await request(`${apiBase}/api/image/generate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+      },
+      timeoutMs: 180_000,
+    }, { prompt, ratio, quality }));
+  } catch (err) {
+    if (index !== undefined) console.log(' FAIL');
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') {
+    if (index !== undefined) console.log(' FAIL');
+    throwApiError(status, data, `Image generation scene ${(index ?? 0) + 1}`);
+  }
+
+  if (index !== undefined) {
+    const sizeKb = Math.round(data.image.length * 0.75 / 1024); // base64 → approx bytes
+    console.log(` OK (~${sizeKb} KB)`);
+  }
+
+  return { imageDataUrl: data.image, quota: data.quota };
+}
+
+module.exports = { generateImage };

package/lib/core/intent-params.js

@@ -0,0 +1,11 @@
+/**
+ * Intent → TTS parameter mapping for podcast synthesis.
+ *
+ * Single source of truth: backend/config/intent-tts-params.js
+ * This file re-exports from backend to avoid duplication.
+ * ncc bundles from the monorepo at build time, so the relative path works.
+ */
+
+const { INTENT_TTS_PARAMS, getIntentParams } = require('../../../backend/config/intent-tts-params');
+
+module.exports = { INTENT_TTS_PARAMS, getIntentParams };

package/lib/core/llm-client.js

@@ -0,0 +1,76 @@
+/**
+ * VoxFlow CLI — LLM API client
+ *
+ * Thin wrapper for /api/llm/chat and /api/lang-detect/detect endpoints.
+ */
+const { request, throwApiError, throwNetworkError } = require('./http');
+
+/**
+ * Call /api/llm/chat for text completion.
+ * Cost: 1 quota per call.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase  - API server base URL
+ * @param {string} opts.token    - JWT auth token
+ * @param {Array}  opts.messages - [{ role, content }]
+ * @param {number} [opts.temperature=0.3]
+ * @param {number} [opts.maxTokens=2000]
+ * @param {string} [opts.model] - Override LLM model (e.g. 'openai/gpt-4o-mini')
+ * @returns {{ content: string, usage: object, quota: object }}
+ */
+async function chatCompletion({ apiBase, token, messages, temperature = 0.3, maxTokens = 2000, model, modelPreset, timeoutMs }) {
+  const body = { messages, temperature, max_tokens: maxTokens };
+  if (modelPreset) body.modelPreset = modelPreset;
+  else if (model) body.model = model;
+
+  let status, data;
+  try {
+    // Default 180s — slide generation at maxTokens=4000 on Sonnet/GPT-4o
+    // routinely needs 60-120s and the old 60s default was timing out
+    // before the LLM finished streaming (issue #2916).
+    ({ status, data } = await request(`${apiBase}/api/llm/chat`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      timeoutMs: Number(timeoutMs) > 0 ? Number(timeoutMs) : 180_000,
+    }, body));
+  } catch (err) {
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') {
+    throwApiError(status, data, 'LLM chat');
+  }
+
+  return { content: data.content, usage: data.usage, quota: data.quota };
+}
+
+/**
+ * Call /api/lang-detect/detect for language detection.
+ * Cost: FREE (no auth required).
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase - API server base URL
+ * @param {string} opts.text    - Text sample to detect
+ * @returns {string} language code (e.g. 'zh', 'en') or 'auto' on failure
+ */
+async function detectLanguage({ apiBase, text }) {
+  let status, data;
+  try {
+    ({ status, data } = await request(`${apiBase}/api/lang-detect/detect`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }, { text: text.slice(0, 200) }));
+  } catch {
+    return 'auto'; // Fallback on network error
+  }
+
+  if (status === 200 && data.code === 'success') {
+    return data.language;
+  }
+  return 'auto';
+}
+
+module.exports = { chatCompletion, detectLanguage };

package/lib/core/logger.js

@@ -0,0 +1,208 @@
+/**
+ * VoxFlow CLI — structured stderr logger.
+ *
+ * Zero external deps (project convention). Adds what a CLI user-facing tool
+ * actually needs:
+ *
+ *  - `-v / -vv / -vvv` (+ `--verbose[=level]`) parsed from argv to set level.
+ *    Also honours `DEBUG=voxflow:*` and plain `DEBUG=voxflow` for parity with
+ *    the wider Node ecosystem (wrangler, vercel, etc).
+ *  - Everything writes to **stderr** so `voxflow xxx --json` stays pipeable on
+ *    stdout. `voxflow dub ... --json | jq` must keep working.
+ *  - Pretty when stderr is a TTY (ANSI colors + aligned level tag); JSON when
+ *    piped / in CI. No `process.env.CI` magic — we key strictly on
+ *    `isTTY`, which is what terminals set.
+ *  - Sub-loggers via `logger.with({ command: 'dub', jobId: '...' })` —
+ *    context is merged into every record so greppable metadata flows without
+ *    threading arguments through every helper.
+ *
+ * Usage:
+ *
+ *   const { logger, parseVerbosityFromArgv } = require('./core/logger');
+ *
+ *   const { level, rest } = parseVerbosityFromArgv(process.argv.slice(2));
+ *   logger.setLevel(level);
+ *
+ *   const log = logger.with({ cmd: 'dub' });
+ *   log.info({ captions: 47, voice: voiceId }, 'pipeline start');
+ *   log.debug({ url }, 'POST /api/tts/synthesize');
+ *   log.error({ err }, 'pipeline failed');
+ *
+ * The first arg is the context object (pino style). The string is the
+ * message. Either may be omitted.
+ */
+
+const LEVELS = Object.freeze({
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+    trace: 5
+});
+
+const LEVEL_LABEL = Object.freeze({
+    error: 'ERR',
+    warn: 'WRN',
+    info: 'INF',
+    debug: 'DBG',
+    trace: 'TRC'
+});
+
+// ANSI colour codes. Plain strings — keeps zero-dep promise.
+const COLOR = Object.freeze({
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    magenta: '\x1b[35m',
+    grey: '\x1b[90m'
+});
+
+const LEVEL_COLOR = Object.freeze({
+    error: COLOR.red,
+    warn: COLOR.yellow,
+    info: COLOR.cyan,
+    debug: COLOR.magenta,
+    trace: COLOR.grey
+});
+
+/**
+ * Parse `-v / -vv / -vvv / --verbose[=N]` flags out of argv.
+ * Returns `{ level, rest }` where `rest` has the flags stripped so the
+ * subcommand parser doesn't trip on them.
+ *
+ * Precedence: explicit `--verbose=N` > repeated short flags > default.
+ * `DEBUG` env var forces at least debug if matches `voxflow*`.
+ */
+function parseVerbosityFromArgv(argv) {
+    let vCount = 0;
+    let explicit = null;
+    const rest = [];
+
+    for (const arg of argv) {
+        if (arg === '-v' || arg === '--verbose') { vCount += 1; continue; }
+        if (arg === '-vv') { vCount += 2; continue; }
+        if (arg === '-vvv') { vCount += 3; continue; }
+        if (arg.startsWith('--verbose=')) {
+            const v = arg.slice('--verbose='.length).toLowerCase();
+            if (v in LEVELS) explicit = v;
+            continue;
+        }
+        rest.push(arg);
+    }
+
+    // `DEBUG=voxflow` or `DEBUG=voxflow:*` → at least debug.
+    const debugEnv = process.env.DEBUG || '';
+    const debugMatchesUs = debugEnv.split(',').some(
+        part => part.trim() === 'voxflow' || part.trim().startsWith('voxflow:') || part.trim() === '*'
+    );
+
+    if (explicit) return { level: explicit, rest };
+    if (vCount >= 3) return { level: 'trace', rest };
+    if (vCount === 2) return { level: 'debug', rest };
+    if (vCount === 1) return { level: 'info', rest };
+    if (debugMatchesUs) return { level: 'debug', rest };
+    return { level: 'warn', rest };
+}
+
+// Internal state
+let currentLevel = LEVELS.warn;
+let useColor = Boolean(process.stderr.isTTY) && process.env.NO_COLOR !== '1';
+let prettyMode = Boolean(process.stderr.isTTY);
+
+function setLevel(levelName) {
+    if (!(levelName in LEVELS)) return;
+    currentLevel = LEVELS[levelName];
+}
+
+function getLevel() {
+    for (const [name, value] of Object.entries(LEVELS)) {
+        if (value === currentLevel) return name;
+    }
+    return 'warn';
+}
+
+/**
+ * Format one log record. Pretty for TTY stderr, single-line JSON otherwise
+ * (CI, piping `2>` to a file, etc).
+ */
+function formatRecord(levelName, ctx, msg) {
+    const record = {
+        time: new Date().toISOString(),
+        level: levelName,
+        msg: msg || '',
+        ...(ctx || {})
+    };
+
+    // Lift Error objects into message + stack — JSON.stringify loses them otherwise.
+    if (record.err instanceof Error) {
+        record.errorMessage = record.err.message;
+        record.errorStack = record.err.stack;
+        delete record.err;
+    }
+
+    if (!prettyMode) {
+        return JSON.stringify(record);
+    }
+
+    const tag = LEVEL_LABEL[levelName] || levelName.toUpperCase();
+    const colour = useColor ? (LEVEL_COLOR[levelName] || '') : '';
+    const reset = useColor ? COLOR.reset : '';
+    const dim = useColor ? COLOR.dim : '';
+    const grey = useColor ? COLOR.grey : '';
+
+    const time = record.time.slice(11, 19); // HH:MM:SS
+    // Strip well-known fields to keep the context short.
+    const { time: _t, level: _l, msg: _m, ...kv } = record;
+    const extras = Object.entries(kv)
+        .map(([k, v]) => `${grey}${k}=${reset}${formatValue(v)}`)
+        .join(' ');
+
+    return `${dim}${time}${reset} ${colour}${tag}${reset} ${record.msg}${extras ? '  ' + extras : ''}`;
+}
+
+function formatValue(v) {
+    if (v === null || v === undefined) return String(v);
+    if (typeof v === 'string') return v.length > 200 ? JSON.stringify(v.slice(0, 200) + '…') : v;
+    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+    try { return JSON.stringify(v); } catch { return String(v); }
+}
+
+function emit(levelName, ctxOrMsg, maybeMsg) {
+    if (LEVELS[levelName] > currentLevel) return;
+    let ctx, msg;
+    if (typeof ctxOrMsg === 'string') { msg = ctxOrMsg; ctx = null; }
+    else { ctx = ctxOrMsg; msg = maybeMsg; }
+    const line = formatRecord(levelName, ctx, msg);
+    process.stderr.write(line + '\n');
+}
+
+/**
+ * Create a logger bound to a context object. Child ctx wins over parent.
+ */
+function createLogger(boundCtx) {
+    const ctx = boundCtx || {};
+    const merge = (c) => c ? { ...ctx, ...c } : ctx;
+    return {
+        error: (c, m) => emit('error', typeof c === 'string' ? c : merge(c), typeof c === 'string' ? c : m),
+        warn:  (c, m) => emit('warn',  typeof c === 'string' ? c : merge(c), typeof c === 'string' ? c : m),
+        info:  (c, m) => emit('info',  typeof c === 'string' ? c : merge(c), typeof c === 'string' ? c : m),
+        debug: (c, m) => emit('debug', typeof c === 'string' ? c : merge(c), typeof c === 'string' ? c : m),
+        trace: (c, m) => emit('trace', typeof c === 'string' ? c : merge(c), typeof c === 'string' ? c : m),
+        with: (extra) => createLogger({ ...ctx, ...extra }),
+        setLevel,
+        getLevel
+    };
+}
+
+const root = createLogger({});
+
+module.exports = {
+    logger: root,
+    parseVerbosityFromArgv,
+    // Exposed for tests only — not part of the public API.
+    LEVELS,
+    _formatRecord: formatRecord
+};

package/lib/core/mic-recorder.js

@@ -0,0 +1,182 @@
+/**
+ * VoxFlow CLI — Microphone recording via sox/rec
+ *
+ * Records audio from the default microphone into a 16kHz mono WAV file
+ * suitable for Tencent Cloud ASR APIs.
+ *
+ * Requires: sox (with rec) installed on the system.
+ *   macOS:   brew install sox
+ *   Ubuntu:  sudo apt install sox
+ *   Windows: https://sourceforge.net/projects/sox/
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+// ─── Check availability ─────────────────────────────────────────────────────
+
+/**
+ * Check whether the `rec` command (part of sox) is available.
+ * @returns {Promise<{available: boolean, error?: string}>}
+ */
+async function checkRecAvailable() {
+  return new Promise((resolve) => {
+    const proc = spawn('rec', ['--version'], { stdio: 'pipe' });
+    let out = '';
+
+    proc.stdout.on('data', (d) => { out += d; });
+    proc.stderr.on('data', (d) => { out += d; });
+
+    proc.on('error', () => {
+      resolve({
+        available: false,
+        error:
+          'rec (sox) not found. Please install sox:\n' +
+          '  macOS:   brew install sox\n' +
+          '  Ubuntu:  sudo apt install sox\n' +
+          '  Windows: https://sourceforge.net/projects/sox/',
+      });
+    });
+
+    proc.on('close', (code) => {
+      resolve({ available: code === 0 || out.length > 0 });
+    });
+  });
+}
+
+// ─── Recording ──────────────────────────────────────────────────────────────
+
+/**
+ * Record audio from the microphone until the user presses Enter or a stop
+ * callback is invoked.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.outputDir]   - Directory for the WAV file (default: os.tmpdir())
+ * @param {number} [opts.maxSeconds]  - Maximum recording duration (default: 300 = 5 min)
+ * @param {number} [opts.silenceThreshold] - Stop after this many seconds of silence (0 = disabled)
+ * @returns {Promise<{wavPath: string, durationMs: number, stopped: 'user'|'timeout'|'silence'}>}
+ */
+function recordMic(opts = {}) {
+  const {
+    outputDir = os.tmpdir(),
+    maxSeconds = 300,
+    silenceThreshold = 0,
+  } = opts;
+
+  const wavPath = path.join(outputDir, `mic-${Date.now()}.wav`);
+
+  return new Promise((resolve, reject) => {
+    // Build rec arguments:
+    //   rec -r 16000 -c 1 -b 16 -e signed-integer output.wav trim 0 <max>
+    const args = [
+      '-r', '16000',          // 16kHz sample rate (ASR requirement)
+      '-c', '1',              // mono
+      '-b', '16',             // 16-bit
+      '-e', 'signed-integer', // PCM encoding
+      wavPath,
+      'trim', '0', String(maxSeconds),
+    ];
+
+    // Add silence detection if requested
+    if (silenceThreshold > 0) {
+      args.push('silence', '1', '0.1', '1%', '1', String(silenceThreshold), '1%');
+    }
+
+    const proc = spawn('rec', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stderr = '';
+
+    proc.stderr.on('data', (d) => { stderr += d.toString(); });
+
+    proc.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        reject(new Error(
+          'rec (sox) not found. Please install sox:\n' +
+          '  macOS:   brew install sox\n' +
+          '  Ubuntu:  sudo apt install sox\n' +
+          '  Windows: https://sourceforge.net/projects/sox/'
+        ));
+      } else {
+        reject(new Error(`Microphone recording failed: ${err.message}`));
+      }
+    });
+
+    let stoppedBy = 'timeout';
+
+    proc.on('close', (_code) => {
+      if (!fs.existsSync(wavPath)) {
+        return reject(new Error(
+          `Recording failed — no output file created.\n${stderr.slice(0, 500)}`
+        ));
+      }
+
+      const stat = fs.statSync(wavPath);
+      if (stat.size < 100) {
+        fs.unlinkSync(wavPath);
+        return reject(new Error(
+          'Recording produced an empty file. Check that your microphone is connected and accessible.'
+        ));
+      }
+
+      // PCM s16le, 16kHz, mono: 32000 bytes per second
+      const durationMs = Math.round((stat.size - 44) / 32);
+
+      resolve({ wavPath, durationMs, stopped: stoppedBy });
+    });
+
+    // Allow the caller to stop recording by sending SIGTERM
+    // Also handle SIGINT gracefully (user presses Ctrl+C)
+    const stopRecording = () => {
+      stoppedBy = 'user';
+      proc.kill('SIGTERM');
+    };
+
+    // Listen for Enter key on stdin to stop recording
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+
+      const onKey = (key) => {
+        // Enter key (CR or LF) or 'q' to stop
+        if (key[0] === 0x0d || key[0] === 0x0a || key[0] === 0x71) {
+          stoppedBy = 'user';
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener('data', onKey);
+          process.stdin.pause();
+          proc.kill('SIGTERM');
+        }
+        // Ctrl+C
+        if (key[0] === 0x03) {
+          stoppedBy = 'user';
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener('data', onKey);
+          process.stdin.pause();
+          proc.kill('SIGTERM');
+        }
+      };
+
+      process.stdin.on('data', onKey);
+
+      // Clean up stdin listener when process ends (regardless of how)
+      proc.on('close', () => {
+        try {
+          process.stdin.removeListener('data', onKey);
+          if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+          }
+          process.stdin.pause();
+        } catch {
+          // stdin may already be closed
+        }
+      });
+    }
+
+    // Expose stop function on the returned promise (for programmatic use)
+    // Callers can do: const p = recordMic(); p.stop();
+    // But since we return a promise, we attach it as a non-standard property
+    proc._stopRecording = stopRecording;
+  });
+}
+
+module.exports = { recordMic, checkRecAvailable };

package/lib/core/pause-markers.js

@@ -0,0 +1,94 @@
+/**
+ * Pause Markers — CLI mirror of backend/utils/pause-markers.js.
+ *
+ * Markers (forward-compat with MiniMax T2A v2 PROSODY_TOKENS spec):
+ *   <|break|>   — long pause   (LONG_PAUSE_MS = 600 ms)
+ *   <|s_break|> — short pause  (SHORT_PAUSE_MS = 300 ms)
+ *
+ * Tencent flow_01_turbo (current podcast provider) does NOT recognize
+ * these tokens, so we strip-and-splice client-side. The same `turn.text`
+ * payload Just Works if a voice ever routes through MiniMax — no schema
+ * change needed.
+ *
+ * Keep in sync with backend/utils/pause-markers.js + studio/src/shared/audio/pause-markers.js.
+ */
+
+'use strict';
+
+const LONG_PAUSE = '<|break|>';
+const SHORT_PAUSE = '<|s_break|>';
+const LONG_PAUSE_MS = 600;
+const SHORT_PAUSE_MS = 300;
+
+function insertPauseMarkers(text) {
+  if (!text || typeof text !== 'string') return '';
+  // Only paragraph breaks auto-insert. Per-sentence and per-clause auto-
+  // insertion removed — TTS already pauses on punctuation natively, so
+  // adding `<|break|>` after every `。！？` and `<|s_break|>` after every
+  // long clause just stacked pause on pause.
+  let result = text.replace(/\n\n+/g, `\n\n${LONG_PAUSE}\n\n`);
+  const shortThenLong = new RegExp(escapeForRegex(SHORT_PAUSE) + '\\s*' + escapeForRegex(LONG_PAUSE), 'g');
+  result = result.replace(shortThenLong, LONG_PAUSE);
+  const doubleLong = new RegExp('(' + escapeForRegex(LONG_PAUSE) + '\\s*){2,}', 'g');
+  result = result.replace(doubleLong, LONG_PAUSE);
+  const doubleShort = new RegExp('(' + escapeForRegex(SHORT_PAUSE) + '\\s*){2,}', 'g');
+  result = result.replace(doubleShort, SHORT_PAUSE);
+  const trailingMarker = new RegExp(
+    '(' + escapeForRegex(LONG_PAUSE) + '|' + escapeForRegex(SHORT_PAUSE) + ')\\s*$'
+  );
+  result = result.replace(trailingMarker, '');
+  return result.trim();
+}
+
+function stripPauseMarkers(text) {
+  if (!text || typeof text !== 'string') return '';
+  return text
+    .replace(new RegExp(escapeForRegex(LONG_PAUSE), 'g'), '')
+    .replace(new RegExp(escapeForRegex(SHORT_PAUSE), 'g'), '')
+    .trim();
+}
+
+/**
+ * Split marked-up text into segments + the silence (ms) that follows each.
+ * Last segment's pauseAfterMs is 0 — caller decides trailing silence.
+ *
+ * Returns: [{ text, pauseAfterMs }, ...]
+ */
+function splitOnPauseMarkers(text) {
+  if (!text || typeof text !== 'string') return [];
+  const tokenPattern = new RegExp(`(${escapeForRegex(LONG_PAUSE)}|${escapeForRegex(SHORT_PAUSE)})`, 'g');
+  const parts = text.split(tokenPattern).filter(p => p !== '');
+  const segments = [];
+  let current = '';
+  for (const part of parts) {
+    if (part === LONG_PAUSE || part === SHORT_PAUSE) {
+      const trimmed = current.trim();
+      if (trimmed) {
+        segments.push({
+          text: trimmed,
+          pauseAfterMs: part === LONG_PAUSE ? LONG_PAUSE_MS : SHORT_PAUSE_MS,
+        });
+      }
+      current = '';
+    } else {
+      current += part;
+    }
+  }
+  const tail = current.trim();
+  if (tail) segments.push({ text: tail, pauseAfterMs: 0 });
+  return segments;
+}
+
+function escapeForRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = {
+  LONG_PAUSE,
+  SHORT_PAUSE,
+  LONG_PAUSE_MS,
+  SHORT_PAUSE_MS,
+  insertPauseMarkers,
+  stripPauseMarkers,
+  splitOnPauseMarkers,
+};