voxflow 1.15.0 → 1.15.2

package/lib/commands/asr/cloud-transcribe.js

@@ -0,0 +1,384 @@
+/**
+ * ASR command — Tencent cloud transcription pipeline.
+ *
+ * Handles: input validation, audio extraction, upload, ASR API call,
+ * caption building, output formatting, and resume-polling.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { API_BASE, ASR_DEFAULTS } = require('../../core/config');
+const { getMediaInfo, extractAudioForAsr } = require('../../core/audio-extract');
+const { uploadAsrAudio } = require('../../core/asr-upload');
+const { downloadUrlToTempFile } = require('../../core/url-download');
+const {
+  recognize,
+  detectMode,
+  BASE64_MAX_BYTES,
+  TASK_STATUS,
+} = require('../../core/asr-client');
+const {
+  formatSrt,
+  formatPlainText,
+  formatJson,
+  buildCaptionsFromFlash,
+  buildCaptionsFromSentence,
+  buildCaptionsFromFile,
+} = require('../../core/srt');
+const { FORMAT_EXTENSIONS, LANG_LABELS, formatDuration, formatSize } = require('./helpers');
+
+/**
+ * Cloud (Tencent) ASR pipeline.
+ *
+ * @param {object} opts - Same shape as asr() opts
+ * @param {string[]} tempFiles - Mutable array for SIGINT cleanup
+ * @returns {Promise<object>}
+ */
+async function asrCloud(opts, tempFiles) {
+  const {
+    token,
+    api = API_BASE,
+    input,
+    url: remoteUrl,
+    mic = false,
+    mode: requestedMode = ASR_DEFAULTS.mode,
+    lang = ASR_DEFAULTS.lang,
+    format = ASR_DEFAULTS.format,
+    output: userOutput,
+    speakers = false,
+    speakerNumber = 0,
+  } = opts;
+
+  // ── Validate input source ────────────────────────────────────────────
+  const sources = [input, remoteUrl, mic].filter(Boolean).length;
+  if (sources === 0) {
+    throw new Error(
+      'No input specified. Provide one of:\n' +
+      '  --input <file>   Local audio/video file\n' +
+      '  --url <url>      Remote audio URL\n' +
+      '  --mic            Record from microphone'
+    );
+  }
+  if (sources > 1) {
+    throw new Error('Specify only one input source: --input, --url, or --mic');
+  }
+
+  console.log('\n=== VoxFlow ASR ===');
+
+  // ── Handle microphone input ──────────────────────────────────────────
+  let localFile = input ? path.resolve(input) : null;
+  let resolvedRemoteUrl = remoteUrl;
+
+  if (mic) {
+    localFile = await handleMicInput();
+    tempFiles.push(localFile);
+  }
+
+  // ── Fetch remote URL → temp file ─────────────────────────────────────
+  if (resolvedRemoteUrl && !localFile) {
+    console.log(`Input:    ${resolvedRemoteUrl}`);
+    console.log(`\nFetching remote URL...`);
+    try {
+      const dl = await downloadUrlToTempFile(resolvedRemoteUrl, {
+        onProgress: (received, total) => {
+          const mb = (received / 1024 / 1024).toFixed(1);
+          if (total) {
+            const pct = Math.round((received / total) * 100);
+            process.stdout.write(`\r    ${mb} MB / ${(total / 1024 / 1024).toFixed(1)} MB (${pct}%)   `);
+          } else {
+            process.stdout.write(`\r    ${mb} MB downloaded   `);
+          }
+        },
+      });
+      process.stdout.write(`\n`);
+      console.log(`    OK (${(dl.size / 1024 / 1024).toFixed(1)} MB → ${dl.filePath})`);
+      localFile = dl.filePath;
+      tempFiles.push(localFile);
+      resolvedRemoteUrl = null;
+    } catch (err) {
+      throw new Error(`Failed to fetch ${resolvedRemoteUrl}: ${err.message}`);
+    }
+  }
+
+  try {
+  // ── Validate local file ──────────────────────────────────────────────
+  if (localFile && !fs.existsSync(localFile)) {
+    throw new Error(`Input file not found: ${localFile}`);
+  }
+
+  // ── Probe media info ─────────────────────────────────────────────────
+  let durationMs = 0;
+  let fileSize = 0;
+  let audioUrl = resolvedRemoteUrl || null;
+
+  if (localFile) {
+    console.log(`Input:    ${path.basename(localFile)}`);
+
+    const info = await getMediaInfo(localFile);
+    durationMs = info.durationMs;
+    fileSize = fs.statSync(localFile).size;
+
+    const durationStr = formatDuration(durationMs);
+    const sizeStr = formatSize(fileSize);
+    console.log(`Duration: ${durationStr}`);
+    console.log(`Size:     ${sizeStr}`);
+
+    if (!info.hasAudio) {
+      throw new Error('Input file has no audio track.');
+    }
+
+    // Extract & convert to 16kHz WAV for ASR
+    console.log(`\n[1/3] Extracting audio (16kHz mono WAV)...`);
+    const extracted = await extractAudioForAsr(localFile);
+    tempFiles.push(extracted.wavPath);
+    durationMs = extracted.durationMs;
+    fileSize = fs.statSync(extracted.wavPath).size;
+    localFile = extracted.wavPath;
+
+    console.log(`    OK (${formatSize(fileSize)}, ${formatDuration(durationMs)})`);
+  } else {
+    console.log(`Input:    ${remoteUrl}`);
+    console.log(`(Remote URL — duration will be detected by ASR API)`);
+  }
+
+  // ── Determine mode ───────────────────────────────────────────────────
+  const hasUrl = !!audioUrl;
+  const actualMode = requestedMode === 'auto'
+    ? detectMode(durationMs, hasUrl || !!localFile, fileSize)
+    : requestedMode;
+
+  console.log(`Mode:     ${actualMode}`);
+  console.log(`Language: ${LANG_LABELS[lang] || lang}`);
+  console.log(`Format:   ${format}`);
+
+  // ── Upload to COS if needed ──────────────────────────────────────────
+  if (localFile && !audioUrl) {
+    const needsUpload =
+      actualMode === 'flash' ||
+      (actualMode === 'file' && fileSize > BASE64_MAX_BYTES) ||
+      (actualMode === 'sentence' && fileSize > BASE64_MAX_BYTES);
+
+    if (needsUpload) {
+      console.log(`\n[2/3] Uploading to Supabase Storage...`);
+      const uploadResult = await uploadAsrAudio(localFile, api, token);
+      audioUrl = uploadResult.downloadUrl;
+      console.log(`    OK (${uploadResult.path})`);
+    } else {
+      console.log(`\n[2/3] Uploading... (skipped, using base64)`);
+    }
+  } else if (!localFile && audioUrl) {
+    console.log(`\n[2/3] Uploading... (skipped, using remote URL)`);
+  }
+
+  // ── Call ASR API ─────────────────────────────────────────────────────
+  console.log(`\n[3/3] ASR speech recognition (${actualMode})...`);
+
+  const startTime = Date.now();
+
+  const result = await recognize({
+    apiBase: api,
+    token,
+    mode: actualMode,
+    url: audioUrl,
+    filePath: !audioUrl ? localFile : undefined,
+    durationMs,
+    fileSize,
+    lang,
+    speakerDiarization: speakers,
+    speakerNumber,
+    wordInfo: format === 'srt',
+    onProgress: (status, elapsed) => {
+      const statusLabel =
+        status === TASK_STATUS.WAITING ? 'Queued' :
+        status === TASK_STATUS.PROCESSING ? 'Recognizing' : 'Unknown';
+      process.stdout.write(`\r    ${statusLabel}... (${Math.round(elapsed / 1000)}s)`);
+    },
+  });
+
+  const elapsedSec = ((Date.now() - startTime) / 1000).toFixed(1);
+  console.log(`\n    OK (${elapsedSec}s)`);
+
+  // ── Build captions ───────────────────────────────────────────────────
+  const effectiveAudioTime = result.audioTime || (durationMs / 1000) || 0;
+
+  let captions;
+  switch (result.mode) {
+    case 'flash':
+      captions = buildCaptionsFromFlash(result.flashResult || []);
+      break;
+    case 'sentence':
+      captions = buildCaptionsFromSentence(
+        result.result,
+        effectiveAudioTime,
+        result.wordList
+      );
+      break;
+    case 'file':
+      captions = buildCaptionsFromFile(result.result, effectiveAudioTime);
+      break;
+    default:
+      captions = [{ id: 1, startMs: 0, endMs: 0, text: result.result || '' }];
+  }
+
+  // ── Format output ────────────────────────────────────────────────────
+  let outputContent;
+  switch (format) {
+    case 'srt':
+      outputContent = formatSrt(captions);
+      break;
+    case 'txt':
+      outputContent = formatPlainText(captions, { includeSpeakers: speakers });
+      break;
+    case 'json':
+      outputContent = formatJson(captions);
+      break;
+    default:
+      throw new Error(`Unknown format: ${format}. Use: srt, txt, json`);
+  }
+
+  // ── Determine output path ────────────────────────────────────────────
+  const ext = FORMAT_EXTENSIONS[format] || '.txt';
+  const anchor = opts._initialCwd || process.cwd();
+  let outputPath;
+
+  if (userOutput) {
+    outputPath = path.isAbsolute(userOutput) ? userOutput : path.resolve(anchor, userOutput);
+  } else if (input) {
+    const inputAbs = path.isAbsolute(input) ? input : path.resolve(anchor, input);
+    const base = path.basename(inputAbs, path.extname(inputAbs));
+    const fname = base + ext;
+    outputPath = path.join(path.dirname(inputAbs), fname);
+  } else if (mic) {
+    const fname = 'mic-' + Date.now() + ext;
+    outputPath = path.join(anchor, fname);
+  } else {
+    try {
+      const urlObj = new URL(remoteUrl);
+      const base = path.basename(urlObj.pathname, path.extname(urlObj.pathname)) || 'asr';
+      const fname = base + ext;
+      outputPath = path.join(anchor, fname);
+    } catch {
+      const fname = 'asr-' + Date.now() + ext;
+      outputPath = path.join(anchor, fname);
+    }
+  }
+
+  // ── Write output ─────────────────────────────────────────────────────
+  fs.writeFileSync(outputPath, outputContent, 'utf8');
+
+  // ── Summary ──────────────────────────────────────────────────────────
+  const quota = result.quota || {};
+  const quotaUsed = 1;
+  const remaining = quota.remaining ?? '?';
+
+  console.log(`\n=== Done ===`);
+  console.log(`Output:     ${outputPath}`);
+  console.log(`Captions:   ${captions.length}`);
+  console.log(`Duration:   ${formatDuration(durationMs || (result.audioTime || 0) * 1000)}`);
+  console.log(`Mode:       ${result.mode}`);
+  console.log(`Quota:      ${quotaUsed} used, ${remaining} remaining`);
+
+  // Print preview (first 3 captions)
+  if (captions.length > 0 && format !== 'json') {
+    console.log(`\n--- Preview ---`);
+    const preview = captions.slice(0, 3);
+    for (const cap of preview) {
+      const ts = formatDuration(cap.startMs);
+      const speaker = cap.speakerId ? `[${cap.speakerId}] ` : '';
+      const textSnippet = cap.text.length > 60
+        ? cap.text.slice(0, 57) + '...'
+        : cap.text;
+      console.log(`  ${ts}  ${speaker}${textSnippet}`);
+    }
+    if (captions.length > 3) {
+      console.log(`  ... (${captions.length - 3} more)`);
+    }
+  }
+
+  return {
+    outputPath,
+    mode: result.mode,
+    duration: durationMs / 1000,
+    captionCount: captions.length,
+    quotaUsed,
+  };
+
+  } finally {
+    // ── Clean up temp files ──────────────────────────────────────────────
+    for (const tmp of tempFiles) {
+      try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    }
+  }
+}
+
+// ─── Resume polling ─────────────────────────────────────────────────────────
+
+async function resumePoll({ apiBase, token, taskId, format, output }) {
+  console.log(`\n=== VoxFlow ASR — Resume Task ===`);
+  console.log(`Task ID:  ${taskId}`);
+
+  const { pollTaskResult, TASK_STATUS: TS } = require('../../core/asr-client');
+
+  console.log(`Polling...`);
+
+  const result = await pollTaskResult({
+    apiBase,
+    token,
+    taskId,
+    onProgress: (status, elapsed) => {
+      const label = status === TS.WAITING ? 'Queued' : status === TS.PROCESSING ? 'Recognizing' : '?';
+      process.stdout.write(`\r  ${label}... (${Math.round(elapsed / 1000)}s)`);
+    },
+  });
+
+  console.log(`\n  OK`);
+
+  const captions = buildCaptionsFromFile(result.result, result.audioTime);
+
+  let outputContent;
+  switch (format) {
+    case 'srt': outputContent = formatSrt(captions); break;
+    case 'txt': outputContent = formatPlainText(captions); break;
+    case 'json': outputContent = formatJson(captions); break;
+    default: outputContent = formatPlainText(captions);
+  }
+
+  const ext = FORMAT_EXTENSIONS[format] || '.txt';
+  const outputPath = output
+    ? path.resolve(output)
+    : path.resolve(`task-${taskId}${ext}`);
+
+  fs.writeFileSync(outputPath, outputContent, 'utf8');
+
+  console.log(`\n=== Done ===`);
+  console.log(`Output:   ${outputPath}`);
+  console.log(`Captions: ${captions.length}`);
+  console.log(`Duration: ${formatDuration((result.audioTime || 0) * 1000)}`);
+
+  return { outputPath, mode: 'file', duration: result.audioTime, captionCount: captions.length };
+}
+
+// ─── Microphone input ───────────────────────────────────────────────────────
+
+async function handleMicInput() {
+  const { recordMic, checkRecAvailable } = require('../../core/mic-recorder');
+
+  const check = await checkRecAvailable();
+  if (!check.available) {
+    throw new Error(check.error);
+  }
+
+  console.log(`\nRecording from microphone...`);
+  console.log(`  Press Enter or Q to stop recording.`);
+  console.log(`  Max duration: 5 minutes.\n`);
+
+  const { wavPath, durationMs, stopped } = await recordMic({ maxSeconds: 300 });
+
+  console.log(`\n  Recording ${stopped === 'user' ? 'stopped' : 'finished'}: ${formatDuration(durationMs)}`);
+
+  return wavPath;
+}
+
+module.exports = { asrCloud, resumePoll };

package/lib/commands/asr/helpers.js

@@ -0,0 +1,76 @@
+/**
+ * ASR command — shared helpers and constants.
+ */
+
+'use strict';
+
+const LANG_LABELS = {
+  '16k_zh':       'Chinese (16kHz)',
+  '16k_en':       'English (16kHz)',
+  '16k_zh_en':    'Chinese-English (16kHz)',
+  '16k_ja':       'Japanese (16kHz)',
+  '16k_ko':       'Korean (16kHz)',
+  '16k_zh_dialect': 'Chinese dialect (16kHz)',
+  '8k_zh':        'Chinese (8kHz phone)',
+  '8k_en':        'English (8kHz phone)',
+};
+
+const FORMAT_EXTENSIONS = {
+  srt: '.srt',
+  txt: '.txt',
+  json: '.json',
+};
+
+function formatDuration(ms) {
+  if (!ms || ms <= 0) return '0s';
+  const totalSec = Math.round(ms / 1000);
+  if (totalSec < 60) return `${totalSec}s`;
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  if (min < 60) return `${min}m${sec > 0 ? sec + 's' : ''}`;
+  const hr = Math.floor(min / 60);
+  const remMin = min % 60;
+  return `${hr}h${remMin > 0 ? remMin + 'm' : ''}`;
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/**
+ * Resolve engine selection: 'auto' checks whisper availability.
+ * @param {string} engine - 'auto', 'local', 'cloud', 'whisper', 'tencent', 'azure'
+ * @returns {'local'|'cloud'|'azure'}
+ */
+function resolveEngine(engine) {
+  const { checkWhisperAvailable } = require('../../core/whisper-local');
+  if (engine === 'local' || engine === 'whisper') {
+    const check = checkWhisperAvailable();
+    if (!check.available) {
+      throw new Error(
+        'Local whisper engine requires nodejs-whisper.\n' +
+        'Install: npm install -g nodejs-whisper\n' +
+        'Download a model: npx nodejs-whisper download\n' +
+        'Or use: --engine cloud'
+      );
+    }
+    return 'local';
+  }
+  if (engine === 'azure') return 'azure';
+  if (engine === 'cloud' || engine === 'tencent') return 'cloud';
+  if (engine === 'auto') {
+    const { available } = checkWhisperAvailable();
+    return available ? 'local' : 'cloud';
+  }
+  return 'cloud';
+}
+
+module.exports = {
+  LANG_LABELS,
+  FORMAT_EXTENSIONS,
+  formatDuration,
+  formatSize,
+  resolveEngine,
+};

package/lib/commands/asr/index.js

@@ -0,0 +1,236 @@
+/**
+ * VoxFlow CLI — ASR (Automatic Speech Recognition) command
+ *
+ * Thin orchestrator: dispatches to engine-specific submodules.
+ *
+ * Supported engines:
+ *   - cloud (Tencent): sentence/flash/file modes
+ *   - azure: batch transcription via R2 upload
+ *   - local: offline Whisper
+ */
+
+'use strict';
+
+const fs = require('fs');
+const { API_BASE, ASR_DEFAULTS } = require('../../core/config');
+const { ApiError } = require('../../core/http');
+const { resolveEngine } = require('./helpers');
+const { asrLocal } = require('./local-transcribe');
+const { asrAzure, asrAzureResume, joinWords, splitSegmentByWords, azureSegmentsToCaptions } = require('./azure-transcribe');
+const { asrCloud, resumePoll } = require('./cloud-transcribe');
+
+// ─── Main command ───────────────────────────────────────────────────────────
+
+/**
+ * ASR command entry point (with SIGINT guard).
+ */
+async function asr(opts) {
+  let isExiting = false;
+  let tempFiles = [];
+
+  const initialCwd = process.cwd();
+
+  const sigintHandler = () => {
+    if (isExiting) return;
+    isExiting = true;
+    console.log('\n\nASR cancelled.');
+    for (const f of tempFiles) {
+      try { fs.unlinkSync(f); } catch {}
+    }
+    process.exit(130);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  // Background refresh: Azure ASR jobs can poll for >1h (long lectures, batch
+  // dictation). Refresh proactively so the poll loop never sees a 401.
+  // No-op if `token` is the env-var path (refresh would fail anyway, env
+  // wins on re-read).
+  const { startBackgroundRefresh } = require('../../core/auth');
+  const stopRefresh = startBackgroundRefresh({ api: opts.api });
+
+  try {
+    return await _asr({ ...opts, _initialCwd: initialCwd }, tempFiles);
+  } finally {
+    stopRefresh();
+    process.removeListener('SIGINT', sigintHandler);
+  }
+}
+
+async function _asr(opts, tempFiles) {
+  const {
+    token,
+    api = API_BASE,
+    mode: requestedMode = ASR_DEFAULTS.mode,
+    lang = ASR_DEFAULTS.lang,
+    format = ASR_DEFAULTS.format,
+    output: userOutput,
+    taskId,
+    jobId,
+    engine = 'auto',
+    model = 'base',
+  } = opts;
+
+  // ── Resume Azure job (UUID jobId) ────────────────────────────────────
+  if (jobId) {
+    return await asrAzureResume({ apiBase: api, token, jobId, format, output: userOutput });
+  }
+
+  // ── Resume Tencent task (numeric taskId) ─────────────────────────────
+  if (taskId) {
+    return await resumePoll({
+      apiBase: api, token, taskId, format, output: userOutput, lang,
+    });
+  }
+
+  // ── Resolve engine ─────────────────────────────────────────────────
+  const resolvedEngine = resolveEngine(engine);
+
+  // If local engine, take the local whisper path
+  if (resolvedEngine === 'local') {
+    return await asrLocal({ input: opts.input, format, output: userOutput, model, lang });
+  }
+
+  // Azure engine takes a separate code path
+  if (resolvedEngine === 'azure') {
+    return await asrAzure({
+      apiBase: api, token, input: opts.input, lang, format, output: userOutput, opts, tempFiles
+    });
+  }
+
+  // Cloud (Tencent) engine
+  return await asrCloud(opts, tempFiles);
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseIntFlag, parseBoolFlag, runWithRetry } = require('../../core/args');
+  const { getToken, getTokenInfo } = require('../../core/auth');
+  const { API_BASE, ASR_DEFAULTS: ASR_DEFS, getConfigDir } = require('../../core/config');
+  const { warnIfMissingFfmpeg } = require('../../core/ffmpeg');
+
+  // Check FFmpeg availability (one-time hint)
+  await warnIfMissingFfmpeg(getConfigDir(), 'asr');
+
+  const api = parseFlag(args, '--api') || API_BASE;
+  const explicitToken = parseFlag(args, '--token');
+
+  // Parse engine and model flags first (affects auth requirement)
+  const engine = parseFlag(args, '--engine') || ASR_DEFS.engine;
+  const model = parseFlag(args, '--model') || ASR_DEFS.model;
+
+  // Validate engine
+  if (engine && !['auto', 'local', 'cloud', 'whisper', 'tencent', 'azure'].includes(engine)) {
+    console.error(`Error: --engine must be one of: auto, local, cloud, azure (got: "${engine}")`);
+    process.exit(1);
+  }
+
+  // Validate model
+  if (model && !['tiny', 'base', 'small', 'medium', 'large'].includes(model)) {
+    console.error(`Error: --model must be one of: tiny, base, small, medium, large (got: "${model}")`);
+    process.exit(1);
+  }
+
+  // Parse and validate ASR-specific flags before auth
+  const input = parseFlag(args, '--input');
+  const url = parseFlag(args, '--url');
+  const mic = parseBoolFlag(args, '--mic');
+  const mode = parseFlag(args, '--mode') || ASR_DEFS.mode;
+  const lang = parseFlag(args, '--lang') || parseFlag(args, '--language') || ASR_DEFS.lang;
+  const format = parseFlag(args, '--format') || ASR_DEFS.format;
+  const output = parseFlag(args, '--output', '-o');
+  const speakers = parseBoolFlag(args, '--speakers');
+  const speakerNumber = parseIntFlag(args, '--speaker-number');
+  const taskId = parseIntFlag(args, '--task-id');
+  const jobId = parseFlag(args, '--job-id');
+  const diarize = parseBoolFlag(args, '--diarize') || speakers;
+
+  // Validate mode
+  if (mode && !['auto', 'sentence', 'flash', 'file'].includes(mode)) {
+    console.error(`Error: --mode must be one of: auto, sentence, flash, file (got: "${mode}")`);
+    process.exit(1);
+  }
+
+  // Validate format
+  if (format && !['srt', 'txt', 'json'].includes(format)) {
+    console.error(`Error: --format must be one of: srt, txt, json (got: "${format}")`);
+    process.exit(1);
+  }
+
+  // Validate input file existence
+  if (input) {
+    const path = require('path');
+    const resolved = path.resolve(input);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Error: Input file not found: ${resolved}`);
+      process.exit(1);
+    }
+  }
+
+  // Authenticate after all validation (local engine skips auth)
+  const isLocalEngine = engine === 'local' || engine === 'whisper';
+
+  let token;
+  if (isLocalEngine) {
+    token = null; // no auth needed
+  } else 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, input, url, mic, mode, lang, format, output,
+    speakers, speakerNumber, taskId, jobId, diarize,
+    engine, model,
+  };
+
+  // Local engine: no retry needed (no API auth)
+  if (isLocalEngine) {
+    await asr(opts);
+  } else {
+    await runWithRetry(asr, opts, api, explicitToken);
+  }
+}
+
+const meta = {
+  asr: {
+    usage: '[opts]',
+    description: 'Transcribe audio/video to text (alias: transcribe)',
+    aliasOf: 'transcribe',
+    options: [
+      `--input <file>       Local audio or video file to transcribe`,
+      `--url <url>          Remote audio URL — CLI fetches it locally then re-uploads (cloud only)`,
+      `--mic                Record from microphone (cloud only, requires sox)`,
+      `--engine <type>      auto (default) | local | cloud | azure`,
+      `--model <name>       Whisper model: tiny, base (default), small, medium, large`,
+      `--mode <type>        auto (default) | sentence | flash | file (cloud only)`,
+      `--lang <model>       Language. Tencent: 16k_zh (default), 16k_en, ... | Azure: ja-JP, en-US, zh-CN, ...`,
+      `--format <fmt>       Output format: srt (default), txt, json`,
+      `--output <path>      Output file path (default: <input>.<format>)`,
+      `--speakers           Enable speaker diarization (alias of --diarize)`,
+      `--diarize            Enable speaker diarization (azure)`,
+      `--speaker-number <n> Expected number of speakers (with --speakers / --diarize)`,
+      `--task-id <id>       Resume polling an existing async task (Tencent — numeric)`,
+      `--job-id <uuid>      Resume polling an existing Azure job (UUID)`,
+    ],
+    examples: [
+      'voxflow asr --input recording.mp3',
+      'voxflow asr --input recording.mp3 --engine local --model small',
+      'voxflow asr --input video.mp4 --format srt --lang 16k_zh',
+      'voxflow asr --input meeting.mp4 --engine azure --lang ja-JP --diarize',
+      'voxflow asr --engine azure --job-id 6f3c2798-87bf-4367-bb4c-08b872e12bef',
+      'voxflow transcribe --input meeting.wav --speakers --speaker-number 3',
+    ],
+  },
+  // Alias picked up by the CLI router (issue #2389)
+  transcribe: { alias: 'asr', description: 'Alias for asr' },
+};
+
+module.exports = { asr, handle, meta, ApiError };
+// 以下导出仅用于单元测试：
+module.exports._internals = { joinWords, splitSegmentByWords, azureSegmentsToCaptions };