fix: voice input in Electron - local Whisper STT + network error handling

- Add local Whisper STT via Transformers.js with Web Worker (no UI freeze) - Default sttProvider to 'local' in Electron (browser STT unavailable) - Fix infinite toast loop: stop auto-restart on network errors - Add retry limit with exponential backoff for transient STT errors - Append voice transcript to input field (append-inline), not replace - Add model catalog with download/load button in Voice Settings
2026-05-14 01:19:52 +03:00
parent ceb5bbd5dd
commit ef85c63336
18 changed files with 1114 additions and 89 deletions
@@ -166,9 +166,10 @@ export type DesktopSettings = {
  responseStyleEnabled?: boolean;
  responseStylePreset?: 'concise' | 'detailed' | 'mentor' | 'pushback' | 'noFiller' | 'matchEnergy' | 'warmPeer' | 'custom';
  responseStyleCustomInstructions?: string;
-  sttProvider?: 'browser' | 'server';
+  sttProvider?: 'browser' | 'server' | 'wasm';
  sttServerUrl?: string;
  sttModel?: string;
+  wasmSttModel?: string;
  sttLanguage?: string;
  sttSilenceThresholdDb?: number;
  sttSilenceHoldMs?: number;
@@ -1301,6 +1301,14 @@ export const settingsDict = {
  'settings.voice.page.provider.custom': 'Custom',
  'settings.voice.page.provider.say': 'Say',
  'settings.voice.page.provider.server': 'Server',
+  'settings.voice.page.provider.wasm': 'Local',
+  'settings.voice.page.stt.wasmModel': 'Whisper Model',
+  'settings.voice.page.stt.wasmLoaded': 'Model loaded, ready',
+  'settings.voice.page.stt.wasmDownloading': 'Downloading model...',
+  'settings.voice.page.stt.wasmLoading': 'Loading model...',
+  'settings.voice.page.stt.wasmNotLoaded': 'Model will load on first voice use',
+  'settings.voice.page.stt.wasmDownload': 'Load',
+  'settings.voice.page.stt.wasmRetry': 'Retry',
  'settings.voice.page.tooltip.browser': 'Free, offline, limited mobile support.',
  'settings.voice.page.tooltip.openai': 'High quality, mobile ready, needs API key.',
  'settings.voice.page.tooltip.custom': 'OpenAI-compatible server (for example Kokoro).',
@@ -1301,6 +1301,14 @@ export const settingsDict = {
  "settings.voice.page.provider.custom": "Personalizado",
  "settings.voice.page.provider.say": "Decir",
  "settings.voice.page.provider.server": "Servidor",
+  "settings.voice.page.provider.wasm": "Local",
+  "settings.voice.page.stt.wasmModel": "Modelo Whisper",
+  "settings.voice.page.stt.wasmLoaded": "Modelo cargado",
+  "settings.voice.page.stt.wasmDownloading": "Descargando modelo...",
+  "settings.voice.page.stt.wasmLoading": "Cargando modelo...",
+  "settings.voice.page.stt.wasmNotLoaded": "El modelo se descargará en el primer uso de voz",
+  "settings.voice.page.stt.wasmDownload": "Descargar",
+  "settings.voice.page.stt.wasmRetry": "Reintentar",
  "settings.voice.page.tooltip.browser": "Gratuito, offline, soporte limitado en móvil.",
  "settings.voice.page.tooltip.openai": "Calidad alta, compatible con móviles, requiere clave de API.",
  "settings.voice.page.tooltip.custom": "Servidor compatible con OpenAI (por ejemplo Kokoro).",
@@ -1301,6 +1301,14 @@ export const settingsDict = {
  'settings.voice.page.provider.custom': '사용자 정의',
  'settings.voice.page.provider.say': 'Say',
  'settings.voice.page.provider.server': '서버',
+  'settings.voice.page.provider.wasm': '로컬',
+  'settings.voice.page.stt.wasmModel': 'Whisper 모델',
+  'settings.voice.page.stt.wasmLoaded': '모델 로드됨',
+  'settings.voice.page.stt.wasmDownloading': '모델 다운로드 중...',
+  'settings.voice.page.stt.wasmLoading': '모델 로드 중...',
+  'settings.voice.page.stt.wasmNotLoaded': '첫 음성 사용 시 모델이 다운로드됩니다',
+  'settings.voice.page.stt.wasmDownload': '다운로드',
+  'settings.voice.page.stt.wasmRetry': '재시도',
  'settings.voice.page.tooltip.browser': '무료, 오프라인, 모바일 지원 제한.',
  'settings.voice.page.tooltip.openai': '고품질, 모바일 지원, API key 필요.',
  'settings.voice.page.tooltip.custom': 'OpenAI 호환 서버(예: Kokoro).',
@@ -1527,6 +1527,14 @@ export const settingsDict = {
  'settings.voice.page.provider.custom': 'Własny',
  'settings.voice.page.provider.say': 'Say',
  'settings.voice.page.provider.server': 'Serwer',
+  'settings.voice.page.provider.wasm': 'Lokalny',
+  'settings.voice.page.stt.wasmModel': 'Model Whisper',
+  'settings.voice.page.stt.wasmLoaded': 'Model załadowany',
+  'settings.voice.page.stt.wasmDownloading': 'Pobieranie modelu...',
+  'settings.voice.page.stt.wasmLoading': 'Ładowanie modelu...',
+  'settings.voice.page.stt.wasmNotLoaded': 'Model zostanie pobrany przy pierwszym użyciu',
+  'settings.voice.page.stt.wasmDownload': 'Pobierz',
+  'settings.voice.page.stt.wasmRetry': 'Spróbuj ponownie',
  'settings.voice.page.section.playbackAndSummary': 'Odtwarzanie i podsumowanie',
  'settings.voice.page.section.speechRecognition': 'Rozpoznawanie mowy',
  'settings.voice.page.section.voiceSetup': 'Konfiguracja głosu',
@@ -1301,6 +1301,14 @@ export const settingsDict = {
  "settings.voice.page.provider.custom": "Personalizado",
  "settings.voice.page.provider.say": "Falar",
  "settings.voice.page.provider.server": "Servidor",
+  "settings.voice.page.provider.wasm": "Local",
+  "settings.voice.page.stt.wasmModel": "Modelo Whisper",
+  "settings.voice.page.stt.wasmLoaded": "Modelo carregado",
+  "settings.voice.page.stt.wasmDownloading": "Baixando modelo...",
+  "settings.voice.page.stt.wasmLoading": "Carregando modelo...",
+  "settings.voice.page.stt.wasmNotLoaded": "O modelo será baixado no primeiro uso",
+  "settings.voice.page.stt.wasmDownload": "Baixar",
+  "settings.voice.page.stt.wasmRetry": "Tentar novamente",
  "settings.voice.page.tooltip.browser": "Gratuito, offline, suporte limitado em dispositivos móveis.",
  "settings.voice.page.tooltip.openai": "Alta qualidade, compatível com dispositivos móveis, exige chave de API.",
  "settings.voice.page.tooltip.custom": "Servidor compatível com OpenAI (por exemplo Kokoro).",
@@ -1301,6 +1301,14 @@ export const settingsDict = {
  "settings.voice.page.provider.custom": "Власний",
  "settings.voice.page.provider.say": "Say",
  "settings.voice.page.provider.server": "Сервер",
+  "settings.voice.page.provider.wasm": "Локально",
+  "settings.voice.page.stt.wasmModel": "Модель Whisper",
+  "settings.voice.page.stt.wasmLoaded": "Модель завантажено",
+  "settings.voice.page.stt.wasmDownloading": "Завантаження моделі...",
+  "settings.voice.page.stt.wasmLoading": "Завантаження моделі...",
+  "settings.voice.page.stt.wasmNotLoaded": "Модель завантажиться при першому використанні",
+  "settings.voice.page.stt.wasmDownload": "Завантажити",
+  "settings.voice.page.stt.wasmRetry": "Спробувати знову",
  "settings.voice.page.tooltip.browser": "Безкоштовна, офлайн, обмежена мобільна підтримка.",
  "settings.voice.page.tooltip.openai": "Висока якість, готово для мобільних пристроїв, потрібен API ключ.",
  "settings.voice.page.tooltip.custom": "OpenAI-сумісний сервер, наприклад Kokoro.",
@@ -1301,6 +1301,14 @@ export const settingsDict = {
  'settings.voice.page.provider.custom': '自定义',
  'settings.voice.page.provider.say': 'Say',
  'settings.voice.page.provider.server': '服务器',
+  'settings.voice.page.provider.wasm': '本地',
+  'settings.voice.page.stt.wasmModel': 'Whisper 模型',
+  'settings.voice.page.stt.wasmLoaded': '模型已加载',
+  'settings.voice.page.stt.wasmDownloading': '下载模型中...',
+  'settings.voice.page.stt.wasmLoading': '加载模型中...',
+  'settings.voice.page.stt.wasmNotLoaded': '模型将在首次使用时下载',
+  'settings.voice.page.stt.wasmDownload': '下载',
+  'settings.voice.page.stt.wasmRetry': '重试',
  'settings.voice.page.tooltip.browser': '免费、离线，移动端支持有限。',
  'settings.voice.page.tooltip.openai': '质量高，移动端可用，需要 API Key。',
  'settings.voice.page.tooltip.custom': 'OpenAI 兼容服务器（例如 Kokoro）。',
@@ -282,8 +282,10 @@ class BrowserVoiceService {
      const errorMessage = this.getErrorMessage(event.error);
      this.onErrorCallback?.(errorMessage);

-      // Don't restart on certain errors
-      if (event.error === 'not-allowed' || event.error === 'service-not-allowed') {
+      // Don't restart on fatal / unrecoverable errors.
+      // "network" in Electron/Chromium means Google's speech servers are unreachable;
+      // auto-restarting immediately creates an infinite error → end → start → error loop.
+      if (event.error === 'not-allowed' || event.error === 'service-not-allowed' || event.error === 'network') {
        this.restartOnEnd = false;
        this.isListening = false;
      }
@@ -292,12 +294,13 @@ class BrowserVoiceService {
    this.recognition.onend = () => {
      this.isListening = false;
      
-      // Auto-restart if still supposed to be listening and not speaking
+      // Auto-restart if still supposed to be listening and not speaking.
+      // Only restart when we have a valid recognition instance and restartOnEnd is set.
      if (this.restartOnEnd && this.recognition && !this.isSpeaking) {
        try {
          this.recognition.start();
        } catch {
-          // Ignore restart errors
+          // Ignore restart errors — onerror / onend will fire if it's fatal.
        }
      }
    };
@@ -0,0 +1,556 @@
+/**
+ * WASM Speech-to-Text Service
+ *
+ * Local Whisper transcription via Transformers.js (ONNX Runtime Web).
+ * Captures microphone audio, detects utterance boundaries via silence-based
+ * VAD, then transcribes each utterance locally — no cloud API required.
+ *
+ * Works in Electron and all modern browsers that support Web Audio API.
+ * First use downloads a Whisper model (~40–166 MB, cached).
+ */
+
+export type WasmModelStatus =
+  | { state: 'unloaded' }
+  | { state: 'downloading'; progress: number }
+  | { state: 'loading' }
+  | { state: 'ready' }
+  | { state: 'error'; error: string };
+
+export interface WasmModelInfo {
+  id: string;
+  name: string;
+  size: string;
+  languages: string;
+  description: string;
+}
+
+export const WASM_MODELS: WasmModelInfo[] = [
+  {
+    id: 'Xenova/whisper-tiny.en',
+    name: 'Whisper Tiny (EN)',
+    size: '~39 MB',
+    languages: 'English',
+    description: 'Fastest, lowest accuracy. Good for quick dictation.',
+  },
+  {
+    id: 'Xenova/whisper-base.en',
+    name: 'Whisper Base (EN)',
+    size: '~73 MB',
+    languages: 'English',
+    description: 'Balanced speed and accuracy. Default for English.',
+  },
+  {
+    id: 'Xenova/whisper-small.en',
+    name: 'Whisper Small (EN)',
+    size: '~166 MB',
+    languages: 'English',
+    description: 'Higher accuracy, slower. Best for noisy environments.',
+  },
+];
+
+export type SpeechResultCallback = (text: string, isFinal: boolean) => void;
+export type ErrorCallback = (error: string) => void;
+
+const VAD_POLL_MS = 80;
+const MIN_UTTERANCE_MS = 300;
+const WHISPER_SAMPLE_RATE = 16000;
+
+interface WasmSttConfig {
+  silenceThresholdDb?: number;
+  silenceHoldMs?: number;
+}
+
+class WasmSttService {
+  private transcriber: unknown = null;
+  private worker: Worker | null = null;
+  private modelStatus: WasmModelStatus = { state: 'unloaded' };
+  private currentModelId: string | null = null;
+
+  private stream: MediaStream | null = null;
+  private mediaRecorder: MediaRecorder | null = null;
+  private audioContext: AudioContext | null = null;
+  private analyser: AnalyserNode | null = null;
+  private vadTimer: ReturnType<typeof setInterval> | null = null;
+  private chunks: Blob[] = [];
+  private recordingStartMs = 0;
+  private isActive = false;
+  private isSpeaking = false;
+  private silenceSince: number | null = null;
+  private onResult: SpeechResultCallback | null = null;
+  private onError: ErrorCallback | null = null;
+  private finishResolver: (() => void) | null = null;
+  private lang = 'en';
+
+  private cfg: Required<WasmSttConfig> = {
+    silenceThresholdDb: -45,
+    silenceHoldMs: 1500,
+  };
+
+  public onModelStatusChange: ((status: WasmModelStatus) => void) | null = null;
+
+  configure(config: WasmSttConfig): void {
+    this.cfg = { ...this.cfg, ...config };
+  }
+
+  isSupported(): boolean {
+    return (
+      typeof window !== 'undefined' &&
+      typeof navigator !== 'undefined' &&
+      typeof navigator.mediaDevices?.getUserMedia === 'function' &&
+      typeof window.MediaRecorder !== 'undefined' &&
+      typeof window.AudioContext !== 'undefined'
+    );
+  }
+
+  getModelStatus(): WasmModelStatus {
+    return this.modelStatus;
+  }
+
+  getCurrentModelId(): string | null {
+    return this.currentModelId;
+  }
+
+  private setModelStatus(status: WasmModelStatus): void {
+    this.modelStatus = status;
+    this.onModelStatusChange?.(status);
+  }
+
+  async loadModel(modelId: string): Promise<void> {
+    if (this.currentModelId === modelId && this.modelStatus.state === 'ready') {
+      return;
+    }
+
+    if (this.modelStatus.state === 'downloading' || this.modelStatus.state === 'loading') {
+      return;
+    }
+
+    this._terminateWorker();
+    this.transcriber = null;
+
+    this.setModelStatus({ state: 'downloading', progress: 0 });
+    this.currentModelId = modelId;
+
+    // Try Web Worker first — inference off main thread = no UI freeze.
+    try {
+      const WasmWorkerMod = await import('./wasmSttWorker?worker');
+      const WasmWorker = WasmWorkerMod.default as new () => Worker;
+      this.worker = new WasmWorker();
+
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('Worker init timed out')), 10000);
+
+        this.worker!.onmessage = (e: MessageEvent) => {
+          const data = e.data as { type: string; progress?: number; error?: string; text?: string };
+          if (data.type === 'progress') {
+            this.setModelStatus({ state: 'downloading', progress: data.progress ?? 0 });
+          } else if (data.type === 'loaded') {
+            clearTimeout(timer);
+            resolve();
+          } else if (data.type === 'error') {
+            clearTimeout(timer);
+            reject(new Error(data.error ?? 'Worker load failed'));
+          }
+        };
+
+        this.worker!.onerror = (err) => {
+          clearTimeout(timer);
+          reject(new Error(err.message || 'Worker error'));
+        };
+
+        this.worker!.postMessage({ type: 'load', modelId });
+      });
+
+      this.setModelStatus({ state: 'ready' });
+      return;
+    } catch (err) {
+      console.warn('[WasmStt] Worker failed, using main-thread:', err instanceof Error ? err.message : err);
+      this._terminateWorker();
+    }
+
+    // Fallback: main-thread pipeline (causes brief UI freeze during inference).
+    try {
+      const { pipeline, env } = await import('@xenova/transformers');
+      env.backends.onnx.wasm.numThreads = 1;
+      env.allowLocalModels = false;
+
+      const fileDoneBytes = new Map<string, number>();
+      let totalDone = 0;
+      let totalEstimate = 0;
+
+      this.transcriber = await pipeline('automatic-speech-recognition', modelId, {
+        progress_callback: (info: { status?: string; file?: string; loaded?: number; total?: number }) => {
+          if (info.status === 'progress' && info.file) {
+            const prevDone = fileDoneBytes.get(info.file) ?? 0;
+            const currentDone = info.loaded ?? 0;
+            const delta = Math.max(0, currentDone - prevDone);
+            fileDoneBytes.set(info.file, currentDone);
+            totalDone += delta;
+            if (info.total && info.total > totalEstimate) totalEstimate = info.total;
+            const effectiveTotal = Math.max(totalEstimate, totalDone);
+            const pct = effectiveTotal > 0 ? Math.min(100, Math.round((totalDone / effectiveTotal) * 100)) : 0;
+            this.setModelStatus({ state: 'downloading', progress: pct });
+          }
+        },
+      });
+
+      this.setModelStatus({ state: 'ready' });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : 'Unknown error loading model';
+      this.setModelStatus({ state: 'error', error: msg });
+      this.transcriber = null;
+      this.currentModelId = null;
+      throw err;
+    }
+  }
+
+  private _terminateWorker(): void {
+    if (this.worker) {
+      this.worker.terminate();
+      this.worker = null;
+    }
+  }
+
+  async unloadModel(): Promise<void> {
+    this._terminateWorker();
+    this.transcriber = null;
+    this.currentModelId = null;
+    this.setModelStatus({ state: 'unloaded' });
+  }
+
+  async startListening(
+    lang: string,
+    onResult: SpeechResultCallback,
+    onError?: ErrorCallback,
+  ): Promise<void> {
+    if (this.isActive) {
+      this.stopListening();
+    }
+
+    if (!this.transcriber && !this.worker) {
+      onError?.('Whisper model not loaded. Select a model in Voice Settings first.');
+      return;
+    }
+
+    this.lang = lang;
+    this.onResult = onResult;
+    this.onError = onError ?? null;
+    this.isActive = true;
+
+    try {
+      this.stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
+    } catch (err) {
+      this.isActive = false;
+      const msg = err instanceof Error ? err.message : 'Microphone access denied';
+      onError?.(msg);
+      return;
+    }
+
+    this._setupAudioContext();
+    this._startRecorder();
+    this._startVAD();
+  }
+
+  stopListening(): void {
+    this._stopVAD();
+    if (this.mediaRecorder && this.mediaRecorder.state === 'recording') {
+      try { this.mediaRecorder.stop(); } catch { /* ignore */ }
+    }
+    this._cleanupAfterStop(true);
+  }
+
+  async finishListening(): Promise<void> {
+    if (!this.isActive) return;
+
+    this._stopVAD();
+    this.isSpeaking = false;
+    this.silenceSince = null;
+
+    if (!this.mediaRecorder || this.mediaRecorder.state === 'inactive') {
+      this._cleanupAfterStop(true);
+      return;
+    }
+
+    await new Promise<void>((resolve) => {
+      this.finishResolver = resolve;
+      this._finaliseUtterance(false);
+    });
+
+    this._cleanupAfterStop(true);
+  }
+
+  getIsListening(): boolean {
+    return this.isActive;
+  }
+
+  // ── Audio capture ────────────────────────────────────────────────────
+
+  private _setupAudioContext(): void {
+    if (!this.stream) return;
+    const AudioContextClass = window.AudioContext ?? (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext;
+    this.audioContext = new AudioContextClass();
+    const source = this.audioContext.createMediaStreamSource(this.stream);
+    this.analyser = this.audioContext.createAnalyser();
+    this.analyser.fftSize = 512;
+    source.connect(this.analyser);
+  }
+
+  private _teardownAudioContext(): void {
+    try { this.audioContext?.close(); } catch { /* ignore */ }
+    this.audioContext = null;
+    this.analyser = null;
+  }
+
+  private _startRecorder(): void {
+    if (!this.stream) return;
+    const mimeType = this._pickMimeType();
+    const options: MediaRecorderOptions = {};
+    if (mimeType && MediaRecorder.isTypeSupported(mimeType)) {
+      options.mimeType = mimeType;
+    }
+    this.mediaRecorder = new MediaRecorder(this.stream, options);
+    this.chunks = [];
+    this.recordingStartMs = Date.now();
+
+    this.mediaRecorder.ondataavailable = (e) => {
+      if (e.data && e.data.size > 0) {
+        this.chunks.push(e.data);
+      }
+    };
+
+    this.mediaRecorder.onstop = () => {
+      const blobs = this.chunks.splice(0);
+      const durationMs = Date.now() - this.recordingStartMs;
+      if (blobs.length === 0 || durationMs < MIN_UTTERANCE_MS) {
+        this.finishResolver?.();
+        this.finishResolver = null;
+        return;
+      }
+      const mType = blobs[0].type || mimeType || 'audio/webm';
+      const blob = new Blob(blobs, { type: mType });
+      void this._transcribe(blob).finally(() => {
+        this.finishResolver?.();
+        this.finishResolver = null;
+      });
+    };
+
+    this.mediaRecorder.start(250);
+  }
+
+  private _releaseStream(): void {
+    if (this.stream) {
+      this.stream.getTracks().forEach((t) => t.stop());
+      this.stream = null;
+    }
+  }
+
+  // ── VAD ──────────────────────────────────────────────────────────────
+
+  private _startVAD(): void {
+    this._stopVAD();
+    this.silenceSince = null;
+    this.isSpeaking = false;
+
+    this.vadTimer = setInterval(() => {
+      if (!this.isActive || !this.analyser) return;
+      const db = this._getRmsDb();
+      const isSilent = db < this.cfg.silenceThresholdDb;
+
+      if (!isSilent) {
+        this.silenceSince = null;
+        if (!this.isSpeaking) {
+          this.isSpeaking = true;
+          if (this.mediaRecorder?.state === 'recording') {
+            this.recordingStartMs = Date.now();
+          }
+        }
+      } else {
+        if (this.isSpeaking) {
+          if (this.silenceSince === null) {
+            this.silenceSince = Date.now();
+          } else if (Date.now() - this.silenceSince >= this.cfg.silenceHoldMs) {
+            this.isSpeaking = false;
+            this.silenceSince = null;
+            this._finaliseUtterance(true);
+          }
+        }
+      }
+    }, VAD_POLL_MS);
+  }
+
+  private _stopVAD(): void {
+    if (this.vadTimer !== null) {
+      clearInterval(this.vadTimer);
+      this.vadTimer = null;
+    }
+  }
+
+  private _cleanupAfterStop(clearChunks: boolean): void {
+    const pendingResolver = this.finishResolver;
+    this.isActive = false;
+    this.finishResolver = null;
+    this.mediaRecorder = null;
+    this._teardownAudioContext();
+    this._releaseStream();
+    if (clearChunks) this.chunks = [];
+    this.isSpeaking = false;
+    this.silenceSince = null;
+    this.onResult = null;
+    this.onError = null;
+    pendingResolver?.();
+  }
+
+  private _finaliseUtterance(restart: boolean): void {
+    if (!this.isActive) return;
+    if (this.mediaRecorder && this.mediaRecorder.state === 'recording') {
+      this.mediaRecorder.stop();
+    }
+    if (!restart) return;
+    setTimeout(() => {
+      if (this.isActive && this.stream) {
+        this._startRecorder();
+      }
+    }, 100);
+  }
+
+  private _getRmsDb(): number {
+    if (!this.analyser) return -Infinity;
+    const buf = new Float32Array(this.analyser.fftSize);
+    this.analyser.getFloatTimeDomainData(buf);
+    let sumSq = 0;
+    for (const s of buf) sumSq += s * s;
+    const rms = Math.sqrt(sumSq / buf.length);
+    return rms === 0 ? -Infinity : 20 * Math.log10(rms);
+  }
+
+  // ── Transcription ────────────────────────────────────────────────────
+
+  private async _transcribe(blob: Blob): Promise<void> {
+    if (!this.onResult) return;
+    if (!this.transcriber && !this.worker) {
+      this.onError?.('Model not loaded');
+      return;
+    }
+
+    try {
+      const audioData = await this._decodeToFloat32(blob);
+      if (!audioData || audioData.length === 0) {
+        this.onError?.(`Failed to decode audio (${blob.size} bytes)`);
+        return;
+      }
+
+      const langHint = this._resolveLanguageHint();
+
+      // Prefer worker (non-blocking); fall back to main-thread pipeline.
+      const transcript = this.worker
+        ? await this._transcribeViaWorker(audioData, langHint)
+        : await this._transcribeMainThread(audioData, langHint);
+
+      if (transcript) {
+        this.onResult(transcript, true);
+      }
+    } catch (err) {
+      if (!this.isActive) return;
+      const msg = err instanceof Error ? err.message : 'Local transcription failed';
+      this.onError?.(msg);
+    }
+  }
+
+  private _transcribeViaWorker(audioData: Float32Array, langHint: string | undefined): Promise<string> {
+    return new Promise((resolve, reject) => {
+      if (!this.worker) return reject(new Error('Worker gone'));
+
+      const onMessage = (e: MessageEvent) => {
+        const data = e.data as { type: string; error?: string; transcript?: string; text?: string };
+        if (data.type === 'result') {
+          this.worker!.removeEventListener('message', onMessage);
+          resolve(data.transcript ?? '');
+        } else if (data.type === 'log') {
+          console.log('[WasmStt Worker]', data.text);
+        } else if (data.type === 'error') {
+          this.worker!.removeEventListener('message', onMessage);
+          reject(new Error(data.error ?? 'Transcription failed'));
+        }
+      };
+
+      this.worker.addEventListener('message', onMessage);
+      this.worker.postMessage(
+        { type: 'transcribe', audio: audioData.buffer, language: langHint },
+        [audioData.buffer],
+      );
+
+      setTimeout(() => {
+        this.worker?.removeEventListener('message', onMessage);
+        reject(new Error('Transcription timed out'));
+      }, 30000);
+    });
+  }
+
+  private async _transcribeMainThread(audioData: Float32Array, langHint: string | undefined): Promise<string> {
+    const pipelineFn = this.transcriber as (
+      input: Float32Array,
+      options?: Record<string, unknown>,
+    ) => Promise<{ text: string }>;
+
+    const result = await pipelineFn(audioData, {
+      task: 'transcribe',
+      ...(langHint ? { language: langHint } : {}),
+    });
+
+    return (result?.text ?? '').trim();
+  }
+
+  private async _decodeToFloat32(blob: Blob): Promise<Float32Array | null> {
+    if (!this.audioContext) return null;
+    const arrayBuffer = await blob.arrayBuffer();
+    let audioBuffer: AudioBuffer;
+    try {
+      audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
+    } catch {
+      return null;
+    }
+
+    const origRate = audioBuffer.sampleRate;
+    const origData = audioBuffer.getChannelData(0);
+    const targetRate = WHISPER_SAMPLE_RATE;
+
+    if (origRate === targetRate) {
+      return new Float32Array(origData);
+    }
+
+    const ratio = origRate / targetRate;
+    const newLength = Math.ceil(origData.length / ratio);
+    const result = new Float32Array(newLength);
+    for (let i = 0; i < newLength; i++) {
+      const origIdx = i * ratio;
+      const idx0 = Math.floor(origIdx);
+      const idx1 = Math.min(idx0 + 1, origData.length - 1);
+      const frac = origIdx - idx0;
+      result[i] = origData[idx0] * (1 - frac) + origData[idx1] * frac;
+    }
+    return result;
+  }
+
+  private _resolveLanguageHint(): string | undefined {
+    if (this.lang && this.lang !== 'auto') {
+      return this.lang.split('-')[0];
+    }
+    return undefined;
+  }
+
+  private _pickMimeType(): string {
+    const candidates = [
+      'audio/webm;codecs=opus',
+      'audio/webm',
+      'audio/ogg;codecs=opus',
+      'audio/ogg',
+      'audio/mp4',
+    ];
+    if (typeof MediaRecorder !== 'undefined' && MediaRecorder.isTypeSupported) {
+      return candidates.find((t) => MediaRecorder.isTypeSupported(t)) ?? '';
+    }
+    return '';
+  }
+}
+
+export const wasmSttService = new WasmSttService();
+export { WasmSttService };
@@ -0,0 +1,92 @@
+/**
+ * Web Worker for off-main-thread Whisper transcription.
+ *
+ * Receives `{ type: 'load', modelId }` to load a model, then
+ * `{ type: 'transcribe', audio: Float32Array (transferred buffer), language? }`
+ * to run inference. Posts progress, results, and errors back.
+ */
+
+import { pipeline, env } from '@xenova/transformers';
+
+let transcriber: unknown = null;
+
+self.onmessage = async (e: MessageEvent) => {
+  const { type } = e.data as { type: string };
+
+  if (type === 'load') {
+    const { modelId } = e.data as { modelId: string };
+    try {
+      env.backends.onnx.wasm.numThreads = 1;
+
+      const fileDoneBytes = new Map<string, number>();
+      let totalDone = 0;
+      let totalEstimate = 0;
+
+      transcriber = await pipeline('automatic-speech-recognition', modelId, {
+        progress_callback: (info: { status?: string; file?: string; loaded?: number; total?: number }) => {
+          if (info.status === 'progress' && info.file) {
+            const prevDone = fileDoneBytes.get(info.file) ?? 0;
+            const currentDone = info.loaded ?? 0;
+            const delta = Math.max(0, currentDone - prevDone);
+            fileDoneBytes.set(info.file, currentDone);
+            totalDone += delta;
+
+            if (info.total && info.total > totalEstimate) {
+              totalEstimate = info.total;
+            }
+
+            const effectiveTotal = Math.max(totalEstimate, totalDone);
+            const pct = effectiveTotal > 0 ? Math.min(100, Math.round((totalDone / effectiveTotal) * 100)) : 0;
+            self.postMessage({ type: 'progress', progress: pct });
+          }
+        },
+      });
+
+      self.postMessage({ type: 'loaded' });
+    } catch (err) {
+      self.postMessage({
+        type: 'error',
+        error: err instanceof Error ? err.message : 'Failed to load model',
+      });
+    }
+  } else if (type === 'transcribe') {
+    if (!transcriber) {
+      self.postMessage({ type: 'error', error: 'Model not loaded', seq: (e.data as { seq?: number }).seq });
+      return;
+    }
+
+    const { audio, language, seq } = e.data as { audio: ArrayBuffer; language?: string; seq?: number };
+
+    try {
+      const samples = new Float32Array(audio);
+      if (samples.length === 0) {
+        self.postMessage({ type: 'error', error: 'Empty audio received', seq });
+        return;
+      }
+
+      self.postMessage({ type: 'log', text: `Transcribing ${samples.length} samples (${(samples.length / 16000).toFixed(1)}s)` });
+
+      const pipelineFn = transcriber as (
+        input: Float32Array,
+        options?: Record<string, unknown>,
+      ) => Promise<{ text: string }>;
+
+      const result = await pipelineFn(samples, {
+        task: 'transcribe',
+        ...(language ? { language } : {}),
+      });
+
+      self.postMessage({
+        type: 'result',
+        transcript: (result?.text ?? '').trim(),
+        seq,
+      });
+    } catch (err) {
+      self.postMessage({
+        type: 'error',
+        error: err instanceof Error ? err.message : 'Transcription failed',
+        seq,
+      });
+    }
+  }
+};