voxflow 1.15.0 → 1.15.2

package/lib/core/timeline.js

@@ -0,0 +1,92 @@
+/**
+ * VoxFlow CLI — Timeline audio builder
+ *
+ * Places audio segments at precise millisecond positions on a timeline,
+ * filling gaps with silence. Used for dubbing where each caption must
+ * start at its exact SRT timestamp.
+ *
+ * Audio format: 24kHz, 16-bit, mono PCM (matches TTS API output).
+ */
+
+const { buildWav } = require('./audio');
+
+const SAMPLE_RATE = 24000;
+const BYTES_PER_SAMPLE = 2; // 16-bit
+const BYTES_PER_MS = (SAMPLE_RATE * BYTES_PER_SAMPLE) / 1000; // 48 bytes/ms
+
+/**
+ * Convert milliseconds to PCM byte offset.
+ * @param {number} ms - Time in milliseconds
+ * @returns {number} Byte offset (even number, aligned to sample boundary)
+ */
+function msToBytes(ms) {
+  const bytes = Math.round(ms * BYTES_PER_MS);
+  // Ensure alignment to 2-byte (sample) boundary
+  return bytes - (bytes % BYTES_PER_SAMPLE);
+}
+
+/**
+ * Build a single PCM buffer with audio segments placed at their timeline positions.
+ *
+ * @param {Array<{startMs: number, endMs: number, audioBuffer: Buffer}>} segments
+ *   Audio segments with their target start/end times.
+ *   audioBuffer is raw PCM data (24kHz, 16-bit, mono).
+ * @param {number} [totalDurationMs] - Total timeline duration in ms.
+ *   If omitted, uses the endMs of the last segment.
+ * @returns {{ pcm: Buffer, durationMs: number }}
+ */
+function buildTimelinePcm(segments, totalDurationMs) {
+  if (!segments || segments.length === 0) {
+    return { pcm: Buffer.alloc(0), durationMs: 0 };
+  }
+
+  // Determine total length
+  const lastEndMs = Math.max(...segments.map((s) => s.endMs));
+  const durationMs = totalDurationMs || lastEndMs;
+  const totalBytes = msToBytes(durationMs);
+
+  // Allocate zero-filled buffer (silence by default)
+  const pcm = Buffer.alloc(totalBytes, 0);
+
+  // Place each segment at its start position
+  for (const seg of segments) {
+    const startByte = msToBytes(seg.startMs);
+    const slotBytes = msToBytes(seg.endMs) - startByte;
+
+    // Determine how many bytes to copy (don't exceed slot or total buffer)
+    const copyLen = Math.min(seg.audioBuffer.length, slotBytes, totalBytes - startByte);
+    if (copyLen > 0 && startByte < totalBytes) {
+      seg.audioBuffer.copy(pcm, startByte, 0, copyLen);
+    }
+  }
+
+  return { pcm, durationMs };
+}
+
+/**
+ * Build a complete WAV file with audio segments placed at timeline positions.
+ *
+ * @param {Array<{startMs: number, endMs: number, audioBuffer: Buffer}>} segments
+ * @param {number} [totalDurationMs]
+ * @returns {{ wav: Buffer, duration: number }} wav buffer and duration in seconds
+ */
+function buildTimelineAudio(segments, totalDurationMs) {
+  const { pcm, durationMs } = buildTimelinePcm(segments, totalDurationMs);
+
+  if (pcm.length === 0) {
+    return { wav: Buffer.alloc(0), duration: 0 };
+  }
+
+  // Use buildWav with a single PCM buffer and zero silence gap
+  const { wav } = buildWav([pcm], 0);
+  return { wav, duration: durationMs / 1000 };
+}
+
+module.exports = {
+  buildTimelinePcm,
+  buildTimelineAudio,
+  msToBytes,
+  SAMPLE_RATE,
+  BYTES_PER_SAMPLE,
+  BYTES_PER_MS,
+};

package/lib/core/tts-synthesizer.js

@@ -0,0 +1,70 @@
+/**
+ * VoxFlow CLI — Shared TTS synthesis function
+ *
+ * Consolidates the duplicated TTS API call pattern from narrate, dub, story,
+ * and podcast commands into a single reusable function.
+ */
+
+const { request, throwApiError, throwNetworkError } = require('./http');
+
+/**
+ * Synthesize text to audio via the TTS API.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase    - API base URL
+ * @param {string} opts.token      - JWT auth token
+ * @param {string} opts.text       - Text to synthesize
+ * @param {string} opts.voiceId    - TTS voice ID
+ * @param {number} [opts.speed=1.0]   - TTS speed (0.5-2.0)
+ * @param {number} [opts.volume=1.0]  - TTS volume (0-2.0)
+ * @param {number} [opts.pitch]       - TTS pitch adjustment
+ * @param {string} [opts.format='pcm'] - Audio format: pcm | wav | mp3
+ * @param {number} opts.index      - Current segment index (0-based)
+ * @param {number} opts.total      - Total number of segments
+ * @param {string} [opts.label]    - Optional label for progress output (e.g. speaker name)
+ * @returns {Promise<{ audio: Buffer, quota: object }>}
+ */
+async function synthesizeTTS(opts) {
+  const {
+    apiBase, token, text, voiceId,
+    speed = 1.0, volume = 1.0, pitch,
+    format = 'pcm',
+    index, total, label,
+  } = opts;
+
+  // Progress output
+  const labelSuffix = label ? ` ${label}` : '';
+  process.stdout.write(`    TTS [${index + 1}/${total}]${labelSuffix}...`);
+
+  // Build request body
+  const body = { text, voiceId, speed, volume, format };
+  if (pitch != null && pitch !== 0) body.pitch = pitch;
+
+  let status, data, headers;
+  try {
+    // 180s — server-side TTS synthesis for a long paragraph can take ~60-90s
+    // on first hit (cold edge) and the previous 60s default was timing out
+    // the very first segment of `voxflow story` (issue #2916).
+    ({ status, data, headers } = await request(`${apiBase}/api/tts/synthesize`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      timeoutMs: 180_000,
+    }, body));
+  } catch (err) {
+    console.log(' FAIL');
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') {
+    console.log(' FAIL');
+    throwApiError(status, data, `TTS segment ${index + 1}`, headers);
+  }
+
+  const audio = Buffer.from(data.audio, 'base64');
+  return { audio, quota: data.quota };
+}
+
+module.exports = { synthesizeTTS };

package/lib/core/update-check.js

@@ -0,0 +1,185 @@
+/**
+ * VoxFlow CLI — update-notifier
+ *
+ * Background check against the npm registry; prints a one-line stderr hint at
+ * process exit when a newer version is available. Zero runtime deps.
+ *
+ * Design:
+ * - Cached at `<configDir>/update-check.json`, refreshed at most once / 24h.
+ * - Fire-and-forget: never blocks the CLI command. Errors are swallowed.
+ * - Skipped when stderr is not a TTY, in CI, or when `VOXFLOW_NO_UPDATE_CHECK=1`.
+ * - The hint is printed at `process.on('exit')`, so it never interleaves with
+ *   the command's own output (which finishes synchronously before exit).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const { getConfigDir } = require('./config');
+
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;   // 24h
+const REGISTRY_URL = 'https://registry.npmjs.org/voxflow/latest';
+const NETWORK_TIMEOUT_MS = 2_000;
+
+function cachePath() {
+  return path.join(getConfigDir(), 'update-check.json');
+}
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(payload) {
+  try {
+    fs.mkdirSync(getConfigDir(), { recursive: true });
+    fs.writeFileSync(cachePath(), JSON.stringify(payload), 'utf8');
+  } catch {
+    // Cache is best-effort; ignore failures.
+  }
+}
+
+/**
+ * Detect whether an AI agent is reading this CLI's stderr.
+ * We use a single explicit signal: `CLAUDECODE=1`. Other agents that want the
+ * structured hint can set `VOXFLOW_AGENT=1`. We intentionally do NOT treat
+ * generic `CI=true` as "agent reading" — many CI users still benefit from a
+ * fail-silent CLI, not a banner on every job.
+ */
+function isAgentChannel() {
+  return process.env.CLAUDECODE === '1' || process.env.VOXFLOW_AGENT === '1';
+}
+
+/**
+ * Decide whether the update check should run at all. Agents skip the human
+ * `▲` banner but still get the structured `<voxflow-hint>` tag; the test
+ * suite + NO_UPDATE_NOTIFIER opt-out skip everything.
+ */
+function shouldSkip() {
+  if (process.env.VOXFLOW_NO_UPDATE_CHECK === '1') return true;
+  if (process.env.NO_UPDATE_NOTIFIER === '1') return true; // industry standard (npm, update-notifier)
+  if (process.env.NODE_ENV === 'test') return true;
+  // Skip when neither a human TTY nor an agent is reading stderr.
+  if (!process.stderr.isTTY && !isAgentChannel()) return true;
+  return false;
+}
+
+/**
+ * Compare semver-ish versions. Returns positive if a > b, 0 if equal, negative
+ * if a < b. Ignores pre-release suffixes (good enough for "is there an update").
+ */
+function cmpVersion(a, b) {
+  const parse = (v) => String(v).split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function fetchLatest() {
+  return new Promise((resolve, reject) => {
+    const req = https.get(REGISTRY_URL, { timeout: NETWORK_TIMEOUT_MS }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`registry HTTP ${res.statusCode}`));
+        return;
+      }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(body);
+          if (typeof json.version === 'string') resolve(json.version);
+          else reject(new Error('no version field'));
+        } catch (err) {
+          reject(err);
+        }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(new Error('timeout')); });
+  });
+}
+
+/**
+ * Kick off an update check. Non-blocking. Schedules a stderr hint at exit
+ * if a newer version is available (either from cache or a fresh fetch).
+ *
+ * @param {string} currentVersion - from package.json
+ */
+function scheduleUpdateCheck(currentVersion) {
+  if (shouldSkip() || !currentVersion) return;
+
+  const cached = readCache();
+  const now = Date.now();
+  const fresh = cached && typeof cached.checkedAt === 'number' && (now - cached.checkedAt) < CHECK_INTERVAL_MS;
+
+  // If cache is fresh and reports a newer version, queue the hint now.
+  if (fresh && cached.latest && cmpVersion(cached.latest, currentVersion) > 0) {
+    queueHint(currentVersion, cached.latest);
+    return;
+  }
+
+  // Otherwise, fetch in the background. Don't await — the process can exit
+  // earlier; that's fine, we'll just check again on the next run.
+  fetchLatest()
+    .then((latest) => {
+      writeCache({ latest, checkedAt: now });
+      if (cmpVersion(latest, currentVersion) > 0) queueHint(currentVersion, latest);
+    })
+    .catch(() => { /* swallow — update check is best-effort */ });
+}
+
+let hintQueued = false;
+/**
+ * Render the hint line(s) for a (current, latest) version pair.
+ * Returns the exact stderr string (or empty string when nothing to emit).
+ *
+ * The agent line is a stable, regex-parseable contract — SKILL.md grep-rules
+ * depend on this format. Don't reorder attrs or change tag name without
+ * updating cli/skills/hub/SKILL.md in the same commit.
+ */
+function renderHintLines(current, latest, { agent, human }) {
+  const lines = [];
+  if (agent) {
+    // Mirrors the shape of Anthropic's <claude-code-hint v="1" type="plugin" .../>
+    // (the only structured agent-targeted hint protocol in the wild today).
+    // type="cli-outdated" is our own, forward-compatible; Anthropic may
+    // someday standardize a variant we can swap in.
+    lines.push(
+      `<voxflow-hint v="1" type="cli-outdated" current="${current}" latest="${latest}" action="voxflow upgrade -y" />`
+    );
+  }
+  if (human) {
+    lines.push(
+      `\x1b[2m▲ voxflow ${current} → ${latest} available · run \`voxflow upgrade -y\` (or \`npm i -g voxflow@latest\`)\x1b[0m`
+    );
+  }
+  return lines.length ? '\n' + lines.join('\n') + '\n' : '';
+}
+
+function queueHint(current, latest) {
+  if (hintQueued) return;
+  hintQueued = true;
+  process.on('exit', () => {
+    const out = renderHintLines(current, latest, {
+      agent: isAgentChannel(),
+      human: process.stderr.isTTY && !isAgentChannel(),
+    });
+    if (out) process.stderr.write(out);
+  });
+}
+
+module.exports = {
+  scheduleUpdateCheck,
+  // Exposed for tests:
+  _test: { cmpVersion, shouldSkip, cachePath, readCache, writeCache, isAgentChannel, renderHintLines },
+};

package/lib/core/url-download.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * Stream a remote URL to a temp file.
+ *
+ * Used by `voxflow asr --url` to work around Tencent Flash ASR not being
+ * able to resolve arbitrary external hosts — we fetch the file ourselves,
+ * then re-upload it via the existing Supabase Storage path.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+
+const MAX_DOWNLOAD_BYTES = 500 * 1024 * 1024; // 500 MB hard cap
+
+function pickClient(urlObj) {
+  if (urlObj.protocol === 'https:') return https;
+  if (urlObj.protocol === 'http:') return http;
+  return null;
+}
+
+function suggestExt(urlObj, contentType) {
+  const fromPath = path.extname(urlObj.pathname);
+  if (fromPath && fromPath.length <= 5) return fromPath;
+  if (contentType) {
+    const ct = contentType.split(';')[0].trim().toLowerCase();
+    if (ct === 'audio/mpeg') return '.mp3';
+    if (ct === 'audio/wav' || ct === 'audio/x-wav') return '.wav';
+    if (ct === 'audio/ogg') return '.ogg';
+    if (ct === 'audio/mp4' || ct === 'audio/m4a') return '.m4a';
+    if (ct === 'audio/flac') return '.flac';
+    if (ct === 'video/mp4') return '.mp4';
+  }
+  return '.bin';
+}
+
+/**
+ * Download `url` to a temp file. Follows up to 5 redirects.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {(received: number, total: number|null) => void} [opts.onProgress]
+ * @param {number} [opts.maxBytes]  hard cap, default 500 MB
+ * @returns {Promise<{ filePath: string, size: number }>}
+ */
+async function downloadUrlToTempFile(url, opts = {}) {
+  const maxBytes = opts.maxBytes ?? MAX_DOWNLOAD_BYTES;
+  const onProgress = opts.onProgress || (() => {});
+
+  return new Promise((resolve, reject) => {
+    const visited = new Set();
+    const start = (target, redirectsLeft) => {
+      let urlObj;
+      try {
+        urlObj = new URL(target);
+      } catch {
+        reject(new Error(`Invalid URL: ${target}`));
+        return;
+      }
+
+      const client = pickClient(urlObj);
+      if (!client) {
+        reject(new Error(`Unsupported URL scheme: ${urlObj.protocol} (use http or https)`));
+        return;
+      }
+
+      if (visited.has(target)) {
+        reject(new Error(`Redirect loop detected at ${target}`));
+        return;
+      }
+      visited.add(target);
+
+      const req = client.get(target, { headers: { 'User-Agent': 'voxflow-cli' } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          if (redirectsLeft <= 0) {
+            res.resume();
+            reject(new Error('Too many redirects (>5)'));
+            return;
+          }
+          const next = new URL(res.headers.location, target).toString();
+          res.resume();
+          start(next, redirectsLeft - 1);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          reject(new Error(`Download failed: HTTP ${res.statusCode} for ${target}`));
+          return;
+        }
+
+        const contentLength = res.headers['content-length']
+          ? parseInt(res.headers['content-length'], 10)
+          : null;
+        if (contentLength != null && contentLength > maxBytes) {
+          res.resume();
+          reject(new Error(`Remote file too large (${contentLength} bytes, max ${maxBytes})`));
+          return;
+        }
+
+        const ext = suggestExt(urlObj, res.headers['content-type']);
+        const filePath = path.join(
+          os.tmpdir(),
+          `voxflow-asr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`
+        );
+        const out = fs.createWriteStream(filePath);
+        let received = 0;
+        let aborted = false;
+
+        res.on('data', (chunk) => {
+          if (aborted) return;
+          received += chunk.length;
+          if (received > maxBytes) {
+            aborted = true;
+            out.destroy();
+            res.destroy();
+            try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+            reject(new Error(`Remote file exceeded ${maxBytes} bytes during download`));
+            return;
+          }
+          onProgress(received, contentLength);
+        });
+
+        res.pipe(out);
+
+        out.on('finish', () => {
+          if (aborted) return;
+          out.close(() => resolve({ filePath, size: received }));
+        });
+        out.on('error', (err) => {
+          try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+          reject(err);
+        });
+      });
+
+      req.on('error', reject);
+      req.setTimeout(60_000, () => {
+        req.destroy(new Error(`Download timed out after 60s: ${target}`));
+      });
+    };
+
+    start(url, 5);
+  });
+}
+
+module.exports = { downloadUrlToTempFile, MAX_DOWNLOAD_BYTES };