voxflow 1.15.0 → 1.15.2

package/lib/core/whisper-local.js

@@ -0,0 +1,279 @@
+/**
+ * VoxFlow CLI — Local Whisper ASR engine adapter
+ *
+ * Wraps nodejs-whisper (whisper.cpp Node.js binding) to provide
+ * local, offline speech recognition. No API key or network needed.
+ *
+ * nodejs-whisper is an OPTIONAL dependency — users install it
+ * separately: npm install -g nodejs-whisper
+ *
+ * Supports GGML models: tiny (39 MB), base (142 MB), small (461 MB),
+ * medium (1.5 GB), large (2.9 GB).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// ─── Language mapping ────────────────────────────────────────────────────────
+
+/**
+ * Map ASR lang codes (Tencent-style 16k_zh, etc.) and short codes
+ * to Whisper language names.
+ */
+const LANG_MAP = {
+  // Tencent-style codes
+  '16k_zh':        'Chinese',
+  '16k_en':        'English',
+  '16k_zh_en':     'Chinese',
+  '16k_ja':        'Japanese',
+  '16k_ko':        'Korean',
+  '16k_zh_dialect': 'Chinese',
+  '8k_zh':         'Chinese',
+  '8k_en':         'English',
+  // Short codes
+  'zh':            'Chinese',
+  'en':            'English',
+  'ja':            'Japanese',
+  'ko':            'Korean',
+  'auto':          'auto',
+};
+
+// ─── Availability check ──────────────────────────────────────────────────────
+
+/**
+ * Check if nodejs-whisper is installed and usable.
+ *
+ * @returns {{ available: boolean, version?: string, error?: string }}
+ */
+function checkWhisperAvailable() {
+  try {
+    const modPath = resolveWhisperModule();
+    if (modPath) {
+      return { available: true };
+    }
+    return {
+      available: false,
+      error:
+        'nodejs-whisper is not installed.\n' +
+        'Install it with: npm install -g nodejs-whisper\n' +
+        'Then download a model: npx nodejs-whisper download',
+    };
+  } catch {
+    return {
+      available: false,
+      error:
+        'nodejs-whisper is not installed.\n' +
+        'Install it with: npm install -g nodejs-whisper\n' +
+        'Then download a model: npx nodejs-whisper download',
+    };
+  }
+}
+
+/**
+ * Try to resolve the nodejs-whisper module from various locations.
+ * Returns the module path or null.
+ */
+function resolveWhisperModule() {
+  // 1. Try normal require resolution (local node_modules)
+  try {
+    return require.resolve('nodejs-whisper');
+  } catch { /* not in local node_modules */ }
+
+  // 2. Try global npm prefix using execFileSync (safe, no shell injection)
+  try {
+    const prefix = execFileSync('npm', ['root', '-g'], { encoding: 'utf8' }).trim();
+    const globalPath = path.join(prefix, 'nodejs-whisper');
+    if (fs.existsSync(globalPath)) {
+      return globalPath;
+    }
+  } catch { /* can't find global */ }
+
+  return null;
+}
+
+/**
+ * Dynamically load nodejs-whisper module.
+ * @returns {Function} The nodewhisper function
+ */
+function loadWhisperModule() {
+  const modPath = resolveWhisperModule();
+  if (!modPath) {
+    throw new Error(
+      'nodejs-whisper is not installed.\n' +
+      'Install: npm install -g nodejs-whisper\n' +
+      'Then: npx nodejs-whisper download'
+    );
+  }
+  const mod = require(modPath);
+  // nodejs-whisper exports { nodewhisper } as named export
+  return mod.nodewhisper || mod.default || mod;
+}
+
+// ─── Transcription ───────────────────────────────────────────────────────────
+
+/**
+ * Transcribe a 16kHz WAV file using local whisper.cpp.
+ *
+ * @param {string} wavPath - Path to 16kHz mono WAV file
+ * @param {object} opts
+ * @param {string} [opts.model='base']  - Model name: tiny, base, small, medium, large
+ * @param {string} [opts.lang='16k_zh'] - Language code
+ * @returns {Promise<Caption[]>}
+ */
+async function transcribeLocal(wavPath, opts = {}) {
+  const { model = 'base', lang = '16k_zh' } = opts;
+
+  if (!fs.existsSync(wavPath)) {
+    throw new Error(`WAV file not found: ${wavPath}`);
+  }
+
+  const nodewhisper = loadWhisperModule();
+  const whisperLang = LANG_MAP[lang] || LANG_MAP['auto'] || 'auto';
+
+  // Model name (e.g. 'base', 'small', 'tiny.en')
+  const modelName = model;
+
+  // Call nodejs-whisper
+  // It writes output files next to the input: <input>.json, <input>.srt, etc.
+  await nodewhisper(wavPath, {
+    modelName,
+    autoDownloadModelName: modelName,
+    removeWavFileAfterTranscription: false,
+    whisperOptions: {
+      outputInJson: true,
+      outputInSrt: false,
+      outputInVtt: false,
+      outputInTxt: false,
+      wordTimestamps: true,
+      splitOnWord: true,
+      language: whisperLang === 'auto' ? undefined : whisperLang,
+    },
+  });
+
+  // Parse the JSON output file
+  const jsonPath = wavPath + '.json';
+
+  if (!fs.existsSync(jsonPath)) {
+    // Fallback: look for common output patterns
+    const baseName = wavPath.replace(/\.wav$/i, '');
+    const altPaths = [
+      baseName + '.json',
+      wavPath + '.json',
+    ];
+    const found = altPaths.find(p => fs.existsSync(p));
+    if (!found) {
+      throw new Error(
+        'Whisper completed but no JSON output found.\n' +
+        `Expected: ${jsonPath}\n` +
+        'Ensure nodejs-whisper is correctly installed.'
+      );
+    }
+  }
+
+  // Read and parse whisper JSON output
+  const jsonContent = fs.readFileSync(jsonPath, 'utf8');
+  const whisperResult = JSON.parse(jsonContent);
+
+  // Convert to Caption[]
+  const segments = whisperResult.transcription || whisperResult.segments || [];
+  const captions = parseWhisperOutput(segments);
+
+  // Clean up whisper output files
+  cleanupWhisperFiles(wavPath);
+
+  return captions;
+}
+
+// ─── Output parsing ──────────────────────────────────────────────────────────
+
+/**
+ * Parse whisper.cpp JSON output into Caption[] format.
+ *
+ * Whisper JSON structure (from nodejs-whisper):
+ *   { transcription: [{ timestamps: { from: "HH:MM:SS.mmm", to: "HH:MM:SS.mmm" }, text: " Hello world" }] }
+ *
+ * @param {Array|null|undefined} segments - Whisper transcription segments
+ * @returns {Caption[]} Array of { id, startMs, endMs, text }
+ */
+function parseWhisperOutput(segments) {
+  if (!segments || !Array.isArray(segments)) return [];
+
+  let id = 0;
+  const captions = [];
+
+  for (const seg of segments) {
+    const text = (seg.text || '').trim();
+    if (!text) continue;
+
+    id++;
+
+    let startMs = 0;
+    let endMs = 0;
+
+    if (seg.timestamps) {
+      startMs = parseTimestamp(seg.timestamps.from);
+      endMs = parseTimestamp(seg.timestamps.to);
+    } else if (seg.offsets) {
+      // Alternative format: { offsets: { from, to } } in milliseconds
+      startMs = seg.offsets.from || 0;
+      endMs = seg.offsets.to || 0;
+    } else if (typeof seg.start === 'number') {
+      // Another format: { start, end } in seconds
+      startMs = Math.round(seg.start * 1000);
+      endMs = Math.round(seg.end * 1000);
+    }
+
+    captions.push({ id, startMs, endMs, text });
+  }
+
+  return captions;
+}
+
+/**
+ * Parse a timestamp string "HH:MM:SS.mmm" to milliseconds.
+ *
+ * @param {string} ts - Timestamp like "00:01:23.456"
+ * @returns {number} Milliseconds
+ */
+function parseTimestamp(ts) {
+  if (!ts || typeof ts !== 'string') return 0;
+
+  const match = ts.match(/^(\d+):(\d+):(\d+)\.(\d+)$/);
+  if (!match) return 0;
+
+  const hours = parseInt(match[1], 10);
+  const minutes = parseInt(match[2], 10);
+  const seconds = parseInt(match[3], 10);
+  const millis = parseInt(match[4].padEnd(3, '0').slice(0, 3), 10);
+
+  return (hours * 3600 + minutes * 60 + seconds) * 1000 + millis;
+}
+
+// ─── Cleanup ─────────────────────────────────────────────────────────────────
+
+/**
+ * Remove whisper-generated output files next to the WAV input.
+ *
+ * @param {string} wavPath - Original WAV file path
+ */
+function cleanupWhisperFiles(wavPath) {
+  const extensions = ['.json', '.srt', '.vtt', '.txt', '.lrc', '.wts'];
+
+  for (const ext of extensions) {
+    const filePath = wavPath + ext;
+    try {
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+      }
+    } catch { /* ignore cleanup errors */ }
+  }
+}
+
+module.exports = {
+  checkWhisperAvailable,
+  transcribeLocal,
+  parseWhisperOutput,
+  parseTimestamp,
+  LANG_MAP,
+};