voxflow 1.15.0 → 1.15.2

package/lib/core/podcast-pacing.js

@@ -0,0 +1,118 @@
+/**
+ * Podcast pacing helpers — per-segment silence + pace presets.
+ *
+ * Mirrors `backend/config/intent-tts-params.js`. The backend stamps each
+ * dialogue turn's `pauseAfterMs` (base) into the script JSON; here we apply
+ * the user's pace preset and a speaker-change boost when the JSON is missing
+ * those fields (older payloads, hand-edited scripts).
+ *
+ * Keep these constants in sync with the backend file.
+ */
+
+'use strict';
+
+const INTENT_PAUSE_AFTER_MS = Object.freeze({
+  opening: 600,
+  explain: 450,
+  question: 750,
+  react: 350,
+  debate: 400,
+  summary: 600,
+  summarize: 600,
+  transition: 1000,
+  joke: 500,
+  closing: 1500,
+});
+
+const DEFAULT_PAUSE_AFTER_MS = 500;
+const SPEAKER_CHANGE_BOOST_MS = 100;
+
+// Silence multiplier for inter-turn gaps (client-side splice).
+const PACE_MULTIPLIERS = Object.freeze({ tight: 0.7, natural: 1.0, relaxed: 1.3 });
+
+// Speed multiplier for the TRTC `Speed` API param. Reciprocals of
+// PACE_MULTIPLIERS so within-turn pauses (TRTC scales them by Speed) and
+// inter-turn silences (client-side, scaled by PACE_MULTIPLIERS) move
+// together. Final Speed is clamped to [0.5, 2.0] (TRTC's API range).
+const PACE_SPEED_MULTIPLIERS = Object.freeze({ tight: 1.43, natural: 1.0, relaxed: 0.77 });
+const TRTC_SPEED_MIN = 0.5;
+const TRTC_SPEED_MAX = 2.0;
+
+const VALID_PACE = Object.freeze(['tight', 'natural', 'relaxed']);
+
+function resolvePaceMultiplier(pace) {
+  if (typeof pace !== 'string') return PACE_MULTIPLIERS.natural;
+  return PACE_MULTIPLIERS[pace] ?? PACE_MULTIPLIERS.natural;
+}
+
+function resolvePaceSpeedMultiplier(pace) {
+  if (typeof pace !== 'string') return PACE_SPEED_MULTIPLIERS.natural;
+  return PACE_SPEED_MULTIPLIERS[pace] ?? PACE_SPEED_MULTIPLIERS.natural;
+}
+
+function composeTtsSpeed({ voiceSpeed = 1.0, intentSpeed = 1.0, pace = 'natural' } = {}) {
+  const paceMult = resolvePaceSpeedMultiplier(pace);
+  const raw = voiceSpeed * intentSpeed * paceMult;
+  return Math.min(TRTC_SPEED_MAX, Math.max(TRTC_SPEED_MIN, raw));
+}
+
+function intentBaseMs(intent) {
+  if (!intent || typeof intent !== 'string') return DEFAULT_PAUSE_AFTER_MS;
+  return INTENT_PAUSE_AFTER_MS[intent] ?? DEFAULT_PAUSE_AFTER_MS;
+}
+
+/**
+ * Resolve the per-segment silence array (in ms) for `buildWav({ gapsMs })`.
+ *
+ *  - If a segment has a numeric `pauseAfterMs` (stamped by backend), use it
+ *  - Otherwise compute from `intent` + speaker-change boost
+ *  - Apply pace multiplier last
+ *  - Last segment's gap is ignored by buildWav (no trailing silence)
+ *
+ * @param {{intent?:string|null,speaker?:string|null,pauseAfterMs?:number|null}[]} segments
+ * @param {object} [options]
+ * @param {string} [options.pace='natural']
+ * @param {number} [options.fallbackSec] — when neither pauseAfterMs nor intent
+ *   yields a value AND a uniform legacy override is in play, use this seconds value
+ * @returns {number[]} gapsMs aligned to segments[]
+ */
+function computeGapsMs(segments, options = {}) {
+  const multiplier = resolvePaceMultiplier(options.pace);
+  const fallbackMs = Number.isFinite(options.fallbackSec) ? options.fallbackSec * 1000 : null;
+
+  return segments.map((seg, i) => {
+    const next = segments[i + 1] || null;
+    if (!next) return 0;
+
+    let base;
+    if (Number.isFinite(seg?.pauseAfterMs)) {
+      base = seg.pauseAfterMs;
+    } else if (seg?.intent) {
+      base = intentBaseMs(seg.intent);
+      if ((seg?.speaker || null) !== (next?.speaker || null)) base += SPEAKER_CHANGE_BOOST_MS;
+    } else if (fallbackMs !== null) {
+      base = fallbackMs;
+    } else {
+      base = DEFAULT_PAUSE_AFTER_MS;
+      if ((seg?.speaker || null) !== (next?.speaker || null)) base += SPEAKER_CHANGE_BOOST_MS;
+    }
+
+    return Math.round(base * multiplier);
+  });
+}
+
+module.exports = {
+  INTENT_PAUSE_AFTER_MS,
+  DEFAULT_PAUSE_AFTER_MS,
+  SPEAKER_CHANGE_BOOST_MS,
+  PACE_MULTIPLIERS,
+  PACE_SPEED_MULTIPLIERS,
+  TRTC_SPEED_MIN,
+  TRTC_SPEED_MAX,
+  VALID_PACE,
+  resolvePaceMultiplier,
+  resolvePaceSpeedMultiplier,
+  composeTtsSpeed,
+  intentBaseMs,
+  computeGapsMs,
+};

package/lib/core/spinner.js

@@ -0,0 +1,33 @@
+/**
+ * VoxFlow CLI — Terminal spinner utility
+ */
+
+/**
+ * Start a simple CLI spinner with a message.
+ * @param {string} message - Text to display before the spinner
+ * @returns {{ stop: (suffix: string) => void, update: (newMessage: string) => void }}
+ */
+function startSpinner(message) {
+  const frames = ['|', '/', '-', '\\'];
+  let i = 0;
+  let currentMessage = message;
+  process.stdout.write(message + ' ' + frames[0]);
+  const id = setInterval(() => {
+    i = (i + 1) % frames.length;
+    process.stdout.write('\b' + frames[i]);
+  }, 120);
+  return {
+    stop(suffix) {
+      clearInterval(id);
+      process.stdout.write('\b' + suffix + '\n');
+    },
+    update(newMessage) {
+      // Clear the current line and rewrite with new message + spinner frame
+      process.stdout.write('\r' + ' '.repeat(currentMessage.length + 4) + '\r');
+      currentMessage = newMessage;
+      process.stdout.write(newMessage + ' ' + frames[i]);
+    },
+  };
+}
+
+module.exports = { startSpinner };

package/lib/core/srt.js

@@ -0,0 +1,394 @@
+/**
+ * VoxFlow CLI — SRT subtitle parser and formatter
+ *
+ * Parses standard SRT files into Caption objects with millisecond timestamps.
+ * Supports extended [Speaker: name] tags for multi-speaker dubbing.
+ */
+
+/**
+ * Parse an SRT timestamp string into milliseconds.
+ * @param {string} str - Timestamp in format "HH:MM:SS,mmm"
+ * @returns {number} Time in milliseconds
+ */
+function parseTimestamp(str) {
+  const match = str.trim().match(/^(\d{1,2}):(\d{2}):(\d{2})[,.](\d{3})$/);
+  if (!match) {
+    throw new Error(`Invalid SRT timestamp: "${str}"`);
+  }
+  const [, h, m, s, ms] = match;
+  return (
+    parseInt(h, 10) * 3600000 +
+    parseInt(m, 10) * 60000 +
+    parseInt(s, 10) * 1000 +
+    parseInt(ms, 10)
+  );
+}
+
+/**
+ * Format milliseconds into an SRT timestamp string.
+ * @param {number} ms - Time in milliseconds
+ * @returns {string} Timestamp in format "HH:MM:SS,mmm"
+ */
+function formatTimestamp(ms) {
+  if (ms < 0) ms = 0;
+  const h = Math.floor(ms / 3600000);
+  ms %= 3600000;
+  const m = Math.floor(ms / 60000);
+  ms %= 60000;
+  const s = Math.floor(ms / 1000);
+  const remainder = ms % 1000;
+  return (
+    String(h).padStart(2, '0') + ':' +
+    String(m).padStart(2, '0') + ':' +
+    String(s).padStart(2, '0') + ',' +
+    String(remainder).padStart(3, '0')
+  );
+}
+
+/**
+ * @typedef {object} Caption
+ * @property {number} id        - Sequence number (1-based)
+ * @property {number} startMs   - Start time in milliseconds
+ * @property {number} endMs     - End time in milliseconds
+ * @property {string} text      - Subtitle text (may span multiple lines)
+ * @property {string} [speakerId] - Optional speaker name from [Speaker: xxx] tag
+ */
+
+/**
+ * Parse SRT content into an array of Caption objects.
+ *
+ * Supports:
+ *   - Standard SRT format (index, timestamp line, text, blank separator)
+ *   - Extended [Speaker: name] tags in text lines
+ *   - Both comma and dot as ms separator (00:00:01,000 or 00:00:01.000)
+ *
+ * @param {string} content - Raw SRT file content
+ * @returns {Caption[]} Parsed captions sorted by startMs
+ */
+function parseSrt(content) {
+  if (!content || content.trim().length === 0) {
+    return [];
+  }
+
+  const captions = [];
+  // Normalize line endings and split into blocks by blank lines
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const blocks = normalized.split(/\n\s*\n/).filter((b) => b.trim().length > 0);
+
+  for (const block of blocks) {
+    const lines = block.trim().split('\n');
+    if (lines.length < 2) continue;
+
+    // Line 1: sequence number (may be missing or non-numeric in some SRT files)
+    let lineIdx = 0;
+    let id;
+    const firstLine = lines[0].trim();
+
+    // Check if first line is a number (sequence ID)
+    if (/^\d+$/.test(firstLine)) {
+      id = parseInt(firstLine, 10);
+      lineIdx = 1;
+    } else {
+      // First line might be the timestamp directly
+      id = captions.length + 1;
+    }
+
+    // Line 2 (or 1): timestamp line "HH:MM:SS,mmm --> HH:MM:SS,mmm"
+    if (lineIdx >= lines.length) continue;
+    const tsLine = lines[lineIdx].trim();
+    const tsMatch = tsLine.match(
+      /^(\d{1,2}:\d{2}:\d{2}[,.]\d{3})\s*-->\s*(\d{1,2}:\d{2}:\d{2}[,.]\d{3})/
+    );
+    if (!tsMatch) continue; // skip blocks without valid timestamp
+
+    const startMs = parseTimestamp(tsMatch[1]);
+    const endMs = parseTimestamp(tsMatch[2]);
+    lineIdx++;
+
+    // Remaining lines: subtitle text
+    const textLines = lines.slice(lineIdx).filter((l) => l.trim().length > 0);
+    if (textLines.length === 0) continue;
+
+    const rawText = textLines.join('\n');
+
+    // Extract optional [Speaker: xxx] tag
+    let speakerId;
+    let text = rawText;
+    const speakerMatch = rawText.match(/^\[Speaker:\s*([^\]]+)\]\s*/i);
+    if (speakerMatch) {
+      speakerId = speakerMatch[1].trim();
+      text = rawText.slice(speakerMatch[0].length);
+    }
+
+    if (text.trim().length === 0) continue;
+
+    captions.push({
+      id,
+      startMs,
+      endMs,
+      text: text.trim(),
+      ...(speakerId ? { speakerId } : {}),
+    });
+  }
+
+  // Sort by startMs for safety
+  captions.sort((a, b) => a.startMs - b.startMs);
+
+  return captions;
+}
+
+/**
+ * Format an array of Caption objects back into SRT string.
+ *
+ * @param {Caption[]} captions - Array of caption objects
+ * @returns {string} Formatted SRT content
+ */
+function formatSrt(captions) {
+  return captions
+    .map((cap, i) => {
+      const id = cap.id || i + 1;
+      const start = formatTimestamp(cap.startMs);
+      const end = formatTimestamp(cap.endMs);
+      const speakerPrefix = cap.speakerId ? `[Speaker: ${cap.speakerId}] ` : '';
+      return `${id}\n${start} --> ${end}\n${speakerPrefix}${cap.text}`;
+    })
+    .join('\n\n') + '\n';
+}
+
+// ─── ASR result → Caption[] converters ──────────────────────────────────────
+
+/**
+ * Convert Flash ASR result into Caption objects.
+ *
+ * Flash API returns an array of channel results, each containing a
+ * `sentence_list` with per-sentence start/end times and optional speaker_id.
+ *
+ * @param {Array} flashResult - flash_result array from /api/asr/flash
+ * @returns {Caption[]}
+ */
+function buildCaptionsFromFlash(flashResult) {
+  const captions = [];
+  let idx = 1;
+
+  for (const channel of flashResult) {
+    const sentences = channel.sentence_list || [];
+    for (const s of sentences) {
+      const cap = {
+        id: idx++,
+        startMs: s.start_time || 0,
+        endMs: s.end_time || 0,
+        text: (s.text || '').trim(),
+      };
+      if (s.speaker_id !== undefined && s.speaker_id !== null) {
+        cap.speakerId = `Speaker${s.speaker_id}`;
+      }
+      if (cap.text.length > 0) {
+        captions.push(cap);
+      }
+    }
+  }
+
+  return captions;
+}
+
+/**
+ * Convert Sentence ASR result into a single Caption.
+ *
+ * Sentence mode returns one text blob and optionally a wordList with
+ * per-word timestamps. If wordList is available, we can create more
+ * granular captions (one per sentence/segment), but for simplicity
+ * we produce a single caption spanning the full audio.
+ *
+ * @param {string} result    - Recognition text
+ * @param {number} audioTime - Audio duration in seconds
+ * @param {Array}  [wordList] - Optional word-level timestamps
+ * @returns {Caption[]}
+ */
+function buildCaptionsFromSentence(result, audioTime, wordList) {
+  if (!result || result.trim().length === 0) return [];
+
+  // If we have word-level data, try to split by natural pauses (>500ms gap)
+  if (wordList && wordList.length > 0) {
+    return buildCaptionsFromWordList(wordList, result);
+  }
+
+  // Fallback: single caption for the full audio
+  return [
+    {
+      id: 1,
+      startMs: 0,
+      endMs: Math.round(audioTime * 1000),
+      text: result.trim(),
+    },
+  ];
+}
+
+/**
+ * Convert word-level timestamps into sentence-level captions.
+ *
+ * Splitting strategy (in priority order):
+ *   1. Natural pauses > 500ms between words
+ *   2. Sentence-ending punctuation (. ! ? etc.) when caption exceeds 5 seconds
+ *   3. Hard split at MAX_CAPTION_DURATION_MS (15s) on word boundaries
+ *
+ * Automatically detects whether to join words with spaces (alphabetic languages)
+ * or without (CJK languages).
+ *
+ * @param {Array} wordList - Array of {word, startTime, endTime} or {Word, StartTime, EndTime} (ms)
+ * @param {string} fullText - Full recognition text (fallback)
+ * @returns {Caption[]}
+ */
+function buildCaptionsFromWordList(wordList, fullText) {
+  if (!wordList || wordList.length === 0) {
+    return fullText
+      ? [{ id: 1, startMs: 0, endMs: 0, text: fullText }]
+      : [];
+  }
+
+  const PAUSE_THRESHOLD_MS = 500;
+  const MIN_DURATION_FOR_PUNCT_SPLIT_MS = 5000;
+  const MAX_CAPTION_DURATION_MS = 15000;
+  const SENTENCE_ENDERS = /[.!?。！？…]+$/;
+
+  // Support both casing: API returns {Word, StartTime, EndTime}, normalize here
+  const getWord = (w) => w.word || w.Word || '';
+  const getStart = (w) => w.startTime ?? w.StartTime ?? 0;
+  const getEnd = (w) => w.endTime ?? w.EndTime ?? 0;
+
+  // Detect if words need space separators (alphabetic vs CJK)
+  const sampleWords = wordList.slice(0, 10).map(getWord).join('');
+  const cjkChars = (sampleWords.match(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g) || []).length;
+  const needsSpaces = cjkChars < sampleWords.length * 0.3;
+  const joiner = needsSpaces ? ' ' : '';
+
+  const captions = [];
+  let currentWords = [];
+  let currentStart = getStart(wordList[0]);
+  let prevEnd = currentStart;
+
+  function flushCaption() {
+    if (currentWords.length === 0) return;
+    const text = currentWords.join(joiner).trim();
+    if (text.length > 0) {
+      captions.push({
+        id: captions.length + 1,
+        startMs: currentStart,
+        endMs: prevEnd,
+        text,
+      });
+    }
+    currentWords = [];
+  }
+
+  for (let i = 0; i < wordList.length; i++) {
+    const w = wordList[i];
+    const wordStart = getStart(w);
+    const wordEnd = getEnd(w);
+    const gap = wordStart - prevEnd;
+    const captionDuration = wordStart - currentStart;
+
+    // Split on natural pauses > 500ms
+    if (gap > PAUSE_THRESHOLD_MS && currentWords.length > 0) {
+      flushCaption();
+      currentStart = wordStart;
+    }
+    // Split on sentence-ending punctuation if caption is already > 5 seconds
+    else if (
+      currentWords.length > 0 &&
+      captionDuration > MIN_DURATION_FOR_PUNCT_SPLIT_MS &&
+      SENTENCE_ENDERS.test(currentWords[currentWords.length - 1])
+    ) {
+      flushCaption();
+      currentStart = wordStart;
+    }
+    // Hard split if caption exceeds max duration
+    else if (
+      currentWords.length > 0 &&
+      captionDuration > MAX_CAPTION_DURATION_MS
+    ) {
+      flushCaption();
+      currentStart = wordStart;
+    }
+
+    currentWords.push(getWord(w));
+    prevEnd = wordEnd || prevEnd;
+  }
+
+  // Flush remaining
+  flushCaption();
+
+  return captions;
+}
+
+/**
+ * Convert File ASR (async) result into captions.
+ *
+ * The file mode Result field is a plain text string. If ResTextFormat was
+ * set to SRT (1), it may already be SRT formatted. Otherwise it is plain
+ * text that we wrap as a single caption.
+ *
+ * @param {string} result    - Recognition result text
+ * @param {number} audioTime - Audio duration in seconds
+ * @returns {Caption[]}
+ */
+function buildCaptionsFromFile(result, audioTime) {
+  if (!result || result.trim().length === 0) return [];
+
+  // Check if the result is already SRT formatted
+  if (/^\d+\s*\n\d{2}:\d{2}:\d{2}[,.]\d{3}\s*-->/.test(result.trim())) {
+    return parseSrt(result);
+  }
+
+  // Plain text — wrap as a single caption
+  return [
+    {
+      id: 1,
+      startMs: 0,
+      endMs: Math.round(audioTime * 1000),
+      text: result.trim(),
+    },
+  ];
+}
+
+/**
+ * Format captions as plain text (no timestamps).
+ *
+ * @param {Caption[]} captions
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeSpeakers] - Prefix each line with speaker name
+ * @returns {string}
+ */
+function formatPlainText(captions, opts = {}) {
+  return captions
+    .map((cap) => {
+      const prefix =
+        opts.includeSpeakers && cap.speakerId
+          ? `[${cap.speakerId}] `
+          : '';
+      return `${prefix}${cap.text}`;
+    })
+    .join('\n') + '\n';
+}
+
+/**
+ * Format captions as JSON (with full metadata).
+ *
+ * @param {Caption[]} captions
+ * @returns {string}
+ */
+function formatJson(captions) {
+  return JSON.stringify(captions, null, 2) + '\n';
+}
+
+module.exports = {
+  parseSrt,
+  formatSrt,
+  parseTimestamp,
+  formatTimestamp,
+  buildCaptionsFromFlash,
+  buildCaptionsFromSentence,
+  buildCaptionsFromWordList,
+  buildCaptionsFromFile,
+  formatPlainText,
+  formatJson,
+};

package/lib/core/telemetry.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Anonymous, fire-and-forget event sink for the `voxflow` CLI.
+ *
+ * Used to answer one product question at a time without spinning up an
+ * analytics SDK. First event: `cli.slice.stage.launched` — feeds into the
+ * "should we build a Stage MCP?" decision (PR #3317 follow-up).
+ *
+ * Design rules — keep them, expanding scope is a separate review:
+ *   • Anonymous. No JWT, no email, no userId. Random per-process session id
+ *     so we can dedupe accidental duplicate events from a single launch.
+ *   • Opt-out: VOXFLOW_TELEMETRY=0 OR DO_NOT_TRACK=1 disables. CI envs
+ *     (CI=1, GITHUB_ACTIONS=true) auto-disable so test runs don't pollute.
+ *   • Fail-silent: any network error, timeout, or thrown handler is
+ *     swallowed. Telemetry MUST NEVER block a CLI command.
+ *   • Allowlisted prop keys only — backend rejects unknown event names.
+ */
+
+const http = require('http');
+const https = require('https');
+const crypto = require('crypto');
+
+const { API_BASE } = require('./config');
+const { logger } = require('./logger');
+
+let sessionId = null;
+function getSessionId() {
+  if (!sessionId) sessionId = crypto.randomUUID();
+  return sessionId;
+}
+
+function isDisabled() {
+  if (process.env.VOXFLOW_TELEMETRY === '0' || process.env.VOXFLOW_TELEMETRY === 'false') return true;
+  if (process.env.DO_NOT_TRACK === '1' || process.env.DO_NOT_TRACK === 'true') return true;
+  if (process.env.CI || process.env.GITHUB_ACTIONS || process.env.NODE_ENV === 'test') return true;
+  return false;
+}
+
+function readCliVersion() {
+  try {
+    return require('../../package.json').version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Emit a telemetry event. Never throws; never returns a meaningful value
+ * to callers — it's intentionally fire-and-forget.
+ *
+ * @param {string} event   Allowlisted event name (see backend/routes/cli-telemetry.js)
+ * @param {object} [props] Plain object; only theme / cli_version / node_version /
+ *                         platform / session_id keys are forwarded.
+ * @param {object} [opts]
+ * @param {string} [opts.apiBase] Override API base (used by tests)
+ */
+function emit(event, props = {}, opts = {}) {
+  if (isDisabled()) return;
+
+  const apiBase = opts.apiBase || API_BASE;
+  let url;
+  try {
+    url = new URL('/api/cli-telemetry', apiBase);
+  } catch {
+    return;
+  }
+
+  const payload = JSON.stringify({
+    event,
+    props: {
+      cli_version: readCliVersion(),
+      node_version: process.version,
+      platform: process.platform,
+      session_id: getSessionId(),
+      ...props
+    }
+  });
+
+  const mod = url.protocol === 'https:' ? https : http;
+  let req;
+  try {
+    req = mod.request(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload)
+      }
+    }, (res) => { res.resume(); });
+  } catch (err) {
+    logger.debug({ err: err.message }, '[telemetry] request build failed');
+    return;
+  }
+  req.on('error', (err) => logger.debug({ err: err.message }, '[telemetry] network error'));
+  req.setTimeout(1500, () => req.destroy());
+  req.write(payload);
+  req.end();
+}
+
+module.exports = { emit, _isDisabled: isDisabled, _getSessionId: getSessionId };