feat: voice add fully-local STT (faster-whisper) + TTS (edge-tts)

.gitignore

@@ -1,14 +1,26 @@
 node_modules/
+packages/
 dist/
 cli
 .codex
 VersperClaw
 
 # Prebuilt native binaries (tracked in claude-code/ reference)
-vendor/audio-capture/
+vendor/
 
 # Desktop (Tauri) build artifacts
 desktop/src-tauri/target/
 desktop/src-tauri/binaries/
 desktop/src-tauri/gen/
 desktop/pnpm-lock.yaml
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Python env
+.venv/
+venv/
+env/

.python-version

@@ -0,0 +1 @@
+3.12

desktop/sidecars/omni-adapter.ts

@@ -18,13 +18,23 @@
 
 import { serve } from 'bun'
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import { randomBytes } from 'crypto'
 
-// ─── Config ──────────────────────────────────────────────────
+const pkgRoot = dirname(new URL(import.meta.url).pathname)
+
+const resolveModelDir = (): string => {
+  const envDir = process.env.OMNI_MODEL_DIR
+  const candidate = envDir
+    ? envDir
+    : join(pkgRoot, '..', '..', 'assets', 'omni-model')
+  const normalized = candidate.replace(/\/+$/, '')
+  return normalized
+}
 
 const PORT = parseInt(process.env.OMNI_PORT || '9301')
 const LLAMA = (process.env.LLAMA_SERVER || 'http://localhost:8025').replace(/\/+$/, '')
-const MODEL_DIR = (process.env.OMNI_MODEL_DIR || '/home/yuki/Code/Llm/MiniCPM-o-4_5-gguf').replace(/\/+$/, '')
+const MODEL_DIR = resolveModelDir()
 const TMP = process.env.OMNI_TMP || '/tmp/omni-adapter'
 const TTS_OUT = TMP + '/tts-output'
 

scripts/build.ts

@@ -123,6 +123,11 @@ const version = dev ? getDevVersion(pkg.version) : pkg.version
 
 mkdirSync(dirname(outfile), { recursive: true })
 
+// Merge defaultFeatures into features for consistent behavior
+for (const feature of defaultFeatures) {
+  featureSet.add(feature)
+}
+
 const externals = [
   '@ant/*',
   'audio-capture-napi',

scripts/speak.py

@@ -0,0 +1,42 @@
+import json, os, sys, tempfile, asyncio
+
+async def speak(text: str, voice: str = "en-US-JennyNeural", output_path: str | None = None) -> dict:
+    try:
+        import edge_tts
+        communicate = edge_tts.Communicate(text, voice)
+        if output_path:
+            await communicate.save(output_path)
+            return {"success": True, "audio_path": output_path}
+        tmp = tempfile.mktemp(suffix=".mp3")
+        await communicate.save(tmp)
+        return {"success": True, "audio_path": tmp}
+    except ImportError:
+        pass
+
+    return {"success": False, "error": "edge-tts is not installed. Run: pip install edge-tts"}
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({"success": False, "error": "Usage: speak.py <text> [--voice <name>] [--output <path>]"}))
+        sys.exit(1)
+
+    text = sys.argv[1]
+    voice = "en-US-JennyNeural"
+    output_path = None
+
+    i = 2
+    while i < len(sys.argv):
+        if sys.argv[i] == "--voice" and i + 1 < len(sys.argv):
+            voice = sys.argv[i + 1]
+            i += 2
+        elif sys.argv[i] == "--output" and i + 1 < len(sys.argv):
+            output_path = sys.argv[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    result = asyncio.run(speak(text, voice, output_path))
+    print(json.dumps(result))
+
+if __name__ == "__main__":
+    main()

scripts/transcribe.py

@@ -0,0 +1,86 @@
+import json, os, sys, tempfile, wave, struct
+
+WAV_HEADER_SIZE = 44
+
+DEFAULT_MODEL_PATH = os.path.expanduser("~/.cache/huggingface/hub/models--Systran--faster-whisper-base")
+
+def write_wav(path: str, raw_pcm: bytes, sample_rate: int = 16000):
+    with wave.open(path, 'wb') as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(sample_rate)
+        w.writeframes(raw_pcm)
+
+def resolve_model(model_size: str) -> str:
+    if os.path.isdir(model_size):
+        return model_size
+    local_path = os.path.expanduser(f"~/.cache/huggingface/hub/models--Systran--faster-whisper-{model_size}")
+    if os.path.isdir(local_path):
+        return local_path
+    return model_size
+
+def transcribe(wav_path: str, model_size: str = "base", language: str | None = None) -> dict:
+    model_path = resolve_model(model_size)
+    import sys as _sys
+    _sys.stderr.write(f"[DEBUG transcribe] model_path={model_path}\n")
+    _sys.stderr.flush()
+    try:
+        from faster_whisper import WhisperModel
+        model = WhisperModel(model_path, device="cpu", compute_type="int8")
+        opts = {"beam_size": 1}
+        if language:
+            opts["language"] = language
+        segments, info = model.transcribe(wav_path, **opts)
+        text = " ".join(seg.text for seg in segments)
+        return {"success": True, "text": text.strip(), "language": info.language}
+    except ImportError:
+        pass
+
+    try:
+        import whisper
+        model = whisper.load_model(model_size)
+        opts = {}
+        if language:
+            opts["language"] = language
+        result = model.transcribe(wav_path, **opts)
+        return {"success": True, "text": result["text"].strip(), "language": result.get("language", "")}
+    except ImportError:
+        pass
+
+    return {"success": False, "error": "Neither faster-whisper nor openai-whisper is installed. Run: pip install faster-whisper"}
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({"success": False, "error": "Usage: transcribe.py <wav_path> [--model <size>] [--language <code>]"}))
+        sys.exit(1)
+
+    wav_path = sys.argv[1]
+    model_size = "base"
+    language = None
+
+    i = 2
+    while i < len(sys.argv):
+        if sys.argv[i] == "--model" and i + 1 < len(sys.argv):
+            model_size = sys.argv[i + 1]
+            i += 2
+        elif sys.argv[i] == "--language" and i + 1 < len(sys.argv):
+            language = sys.argv[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    if sys.argv[1] == "--stdin-pcm":
+        sample_rate = int(sys.argv[2]) if len(sys.argv) > 2 else 16000
+        raw = sys.stdin.buffer.read()
+        tmp = tempfile.mktemp(suffix=".wav")
+        write_wav(tmp, raw, sample_rate)
+        wav_path = tmp
+        result = transcribe(wav_path, model_size, language)
+        os.unlink(tmp)
+    else:
+        result = transcribe(wav_path, model_size, language)
+
+    print(json.dumps(result))
+
+if __name__ == "__main__":
+    main()

src/commands/voice/voice.ts

@@ -2,7 +2,6 @@ import { normalizeLanguageForSTT } from '../../hooks/useVoice.js'
 import { getShortcutDisplay } from '../../keybindings/shortcutFormat.js'
 import { logEvent } from '../../services/analytics/index.js'
 import type { LocalCommandCall } from '../../types/command.js'
-import { isAnthropicAuthEnabled } from '../../utils/auth.js'
 import { getGlobalConfig, saveGlobalConfig } from '../../utils/config.js'
 import { settingsChangeDetector } from '../../utils/settings/changeDetector.js'
 import {
@@ -14,7 +13,7 @@ import { isVoiceAvailable } from '../../voice/voiceModeEnabled.js'
 const LANG_HINT_MAX_SHOWS = 2
 
 export const call: LocalCommandCall = async () => {
-  // Check only the GrowthBook kill-switch — voice might use Doubao (no auth)
+  // Check only the GrowthBook kill-switch
   if (!isVoiceAvailable()) {
     return {
       type: 'text' as const,
@@ -25,7 +24,7 @@ export const call: LocalCommandCall = async () => {
   const currentSettings = getInitialSettings()
   const isCurrentlyEnabled = currentSettings.voiceEnabled === true
 
-  // Toggle OFF — no checks needed
+  // Toggle OFF
   if (isCurrentlyEnabled) {
     const result = updateSettingsForSource('userSettings', {
       voiceEnabled: false,
@@ -45,34 +44,9 @@ export const call: LocalCommandCall = async () => {
     }
   }
 
-  // Toggle ON — run pre-flight checks first
-  const { isVoiceStreamAvailable } = await import(
-    '../../services/voiceStreamSTT.js'
-  )
+  // Toggle ON — local provider (no auth needed)
   const { checkRecordingAvailability } = await import('../../services/voice.js')
 
-  // Determine available STT backend: prefer Anthropic, fall back to Doubao
-  const hasAnthropicAuth = isAnthropicAuthEnabled() && isVoiceStreamAvailable()
-  let useDoubao = false
-  if (!hasAnthropicAuth) {
-    const { isDoubaoAvailable } = await import('../../services/doubaoSTT.js')
-    if (!(await isDoubaoAvailable())) {
-      // Neither backend is available
-      if (!isAnthropicAuthEnabled()) {
-        return {
-          type: 'text' as const,
-          value:
-            'Voice mode requires a Claude.ai account or the Doubao ASR backend. Please run /login to sign in, or install Doubao ASR.',
-        }
-      }
-      return {
-        type: 'text' as const,
-        value: 'Voice mode is not available.',
-      }
-    }
-    useDoubao = true
-  }
-
   // Check recording availability (microphone access)
   const recording = await checkRecordingAvailability()
   if (!recording.available) {
@@ -98,16 +72,15 @@ export const call: LocalCommandCall = async () => {
     }
   }
 
-  // Probe mic access so the OS permission dialog fires now rather than
-  // on the user's first hold-to-talk activation.
+  // Probe mic access so the OS permission dialog fires now
   if (!(await requestMicrophonePermission())) {
     let guidance: string
     if (process.platform === 'win32') {
-      guidance = 'Settings \u2192 Privacy \u2192 Microphone'
+      guidance = 'Settings → Privacy → Microphone'
     } else if (process.platform === 'linux') {
       guidance = "your system's audio settings"
     } else {
-      guidance = 'System Settings \u2192 Privacy & Security \u2192 Microphone'
+      guidance = 'System Settings → Privacy & Security → Microphone'
     }
     return {
       type: 'text' as const,
@@ -115,10 +88,10 @@ export const call: LocalCommandCall = async () => {
     }
   }
 
-  // All checks passed — enable voice and store backend choice
+  // Enable voice with local provider
   const result = updateSettingsForSource('userSettings', {
     voiceEnabled: true,
-    ...(useDoubao ? { voiceProvider: 'doubao' as const } : { voiceProvider: 'anthropic' as const }),
+    voiceProvider: 'local' as const,
   })
   if (result.error) {
     return {
@@ -132,8 +105,6 @@ export const call: LocalCommandCall = async () => {
   const key = getShortcutDisplay('voice:pushToTalk', 'Chat', 'Space')
   const stt = normalizeLanguageForSTT(currentSettings.language)
   const cfg = getGlobalConfig()
-  // Reset the hint counter whenever the resolved STT language changes
-  // (including first-ever enable, where lastLanguage is undefined).
   const langChanged = cfg.voiceLangHintLastLanguage !== stt.code
   const priorCount = langChanged ? 0 : (cfg.voiceLangHintShownCount ?? 0)
   const showHint = !stt.fellBackFrom && priorCount < LANG_HINT_MAX_SHOWS
@@ -150,9 +121,8 @@ export const call: LocalCommandCall = async () => {
       voiceLangHintLastLanguage: stt.code,
     }))
   }
-  const backendNote = useDoubao ? ' [Doubao ASR]' : ''
   return {
     type: 'text' as const,
-    value: `Voice mode enabled. Hold ${key} to record.${langNote}${backendNote}`,
+    value: `Voice mode enabled (local whisper). Hold ${key} to record.${langNote}`,
   }
 }

src/components/Messages.tsx

@@ -5,6 +5,7 @@ import type { UUID } from 'crypto';
 import type { RefObject } from 'react';
 import * as React from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useAutoTTS } from '../hooks/useAutoTTS.js';
 import { every } from 'src/utils/set.js';
 import { getIsRemoteMode } from '../bootstrap/state.js';
 import type { Command } from '../commands.js';
@@ -543,6 +544,8 @@ const MessagesImpl = ({
   }, [collapsed_0, renderRange, virtualScrollRuntimeGate, disableRenderCap]);
   const streamingToolUseIDs = useMemo(() => new Set(streamingToolUses.map(__0 => __0.contentBlock.id)), [streamingToolUses]);
 
+  useAutoTTS(renderableMessages);
+
   // Divider insertion point: first renderableMessage whose uuid shares the
   // 24-char prefix with firstUnseenUuid (deriveUUID keeps the first 24
   // chars of the source message uuid, so this matches any block from it).

src/hooks/useAutoTTS.ts

@@ -0,0 +1,38 @@
+import { useEffect, useRef } from 'react'
+import { speakWithEdgeTTS, playAudioFile } from '../services/voice/edgeTTS.js'
+import { getInitialSettings } from '../utils/settings/settings.js'
+import type { RenderableMessage } from '../types/message.js'
+
+export function useAutoTTS(messages: RenderableMessage[]): void {
+  const triggeredIdsRef = useRef<Set<string>>(new Set())
+  const pendingPlayRef = useRef<Promise<void> | null>(null)
+
+  useEffect(() => {
+    const settings = getInitialSettings()
+    if (!settings.voiceAutoTTS || !settings.voiceEnabled) return
+
+    for (const msg of messages) {
+      if (msg.type !== 'assistant') continue
+      if (triggeredIdsRef.current.has(msg.id)) continue
+
+      const content = msg.message.content[0]
+      if (content?.type !== 'text') continue
+      if (!content.text.trim()) continue
+
+      triggeredIdsRef.current.add(msg.id)
+
+      const text = content.text
+      const voice = settings.voiceTTSVoice || 'en-US-JennyNeural'
+
+      void (async () => {
+        const result = await speakWithEdgeTTS(text, {
+          voice,
+          pythonPath: settings.voiceTTSCommand || undefined,
+        })
+        if (result.success && result.audioPath) {
+          await playAudioFile(result.audioPath)
+        }
+      })()
+    }
+  }, [messages])
+}

src/hooks/useVoice.ts

@@ -22,6 +22,7 @@ import {
   type VoiceStreamConnection,
 } from '../services/voiceStreamSTT.js'
 import { connectDoubaoStream } from '../services/doubaoSTT.js'
+import { connectLocalWhisperStream } from '../services/voice/whisperSTT.js'
 import { logForDebugging } from '../utils/debug.js'
 import { toError } from '../utils/errors.js'
 import { getSystemLocaleLanguage } from '../utils/intl.js'
@@ -139,6 +140,10 @@ function isDoubaoProvider(): boolean {
   return getInitialSettings().voiceProvider === 'doubao'
 }
 
+function isLocalProvider(): boolean {
+  return getInitialSettings().voiceProvider === 'local'
+}
+
 // Lazy-loaded voice module. We defer importing voice.ts (and its native
 // audio-capture-napi dependency) until voice input is actually activated.
 // On macOS, loading the native audio module can trigger a TCC microphone
@@ -392,26 +397,31 @@ export function useVoice({
           !silentDropRetriedRef.current &&
           fullAudioRef.current.length > 0
         ) {
-          silentDropRetriedRef.current = true
-          logForDebugging(
-            `[voice] Silent-drop detected (no_data_timeout, ${String(fullAudioRef.current.length)} chunks); replaying on fresh connection`,
-          )
-          logEvent('tengu_voice_silent_drop_replay', {
-            recordingDurationMs,
-            chunkCount: fullAudioRef.current.length,
-          })
-          if (connectionRef.current) {
-            connectionRef.current.close()
-            connectionRef.current = null
-          }
-          const replayBuffer = fullAudioRef.current
-          await sleep(250)
-          if (isStale()) return
-          const stt = normalizeLanguageForSTT(getInitialSettings().language)
-          const keyterms = await getVoiceKeyterms()
-          if (isStale()) return
-          await new Promise<void>(resolve => {
-            void connectVoiceStream(
+// Local whisper doesn't support silent-drop replay (different backend)
+        if (isLocalProvider()) {
+          callbacks.onClose()
+          return
+        }
+        silentDropRetriedRef.current = true
+        logForDebugging(
+          `[voice] Silent-drop detected (no_data_timeout, ${String(fullAudioRef.current.length)} chunks); replaying on fresh connection`,
+        )
+        logEvent('tengu_voice_silent_drop_replay', {
+          recordingDurationMs,
+          chunkCount: fullAudioRef.current.length,
+        })
+        if (connectionRef.current) {
+          connectionRef.current.close()
+          connectionRef.current = null
+        }
+        const replayBuffer = fullAudioRef.current
+        await sleep(250)
+        if (isStale()) return
+        const stt = normalizeLanguageForSTT(getInitialSettings().language)
+        const keyterms = await getVoiceKeyterms()
+        if (isStale()) return
+        await new Promise<void>(resolve => {
+          void connectVoiceStream(
               {
                 onTranscript: (t, isFinal) => {
                   if (isStale()) return
@@ -580,7 +590,7 @@ export function useVoice({
   // stop when it loses focus. This enables a "multi-clauding army"
   // workflow where voice input follows window focus.
   useEffect(() => {
-    if (!enabled || !focusMode || isDoubaoProvider()) {
+    if (!enabled || !focusMode || isDoubaoProvider() || isLocalProvider()) {
       // Focus mode was disabled while a focus-driven recording was active —
       // stop the recording so it doesn't linger until the silence timer fires.
       if (focusTriggeredRef.current && stateRef.current === 'recording') {
@@ -785,15 +795,18 @@ export function useVoice({
     const attemptConnect = (keyterms: string[]): void => {
       const myAttemptGen = attemptGenRef.current
       // Select STT backend based on settings.voiceProvider
-      const connectFn = isDoubaoProvider()
-        ? (
-            cbs: Parameters<typeof connectDoubaoStream>[0],
-            opts: Parameters<typeof connectDoubaoStream>[1],
-          ) => connectDoubaoStream(cbs, opts)
-        : (
-            cbs: Parameters<typeof connectVoiceStream>[0],
-            opts: Parameters<typeof connectVoiceStream>[1],
-          ) => connectVoiceStream(cbs, opts)
+      let connectFn: (
+          cbs: VoiceStreamCallbacks,
+          opts: { language: string; keyterms: string[] },
+        ) => Promise<VoiceStreamConnection | null>
+      if (isLocalProvider()) {
+        connectFn = (cbs, _opts) =>
+          connectLocalWhisperStream(cbs, { language: stt.code })
+      } else if (isDoubaoProvider()) {
+        connectFn = (cbs, opts) => connectDoubaoStream(cbs, opts)
+      } else {
+        connectFn = (cbs, opts) => connectVoiceStream(cbs, opts)
+      }
       void connectFn(
         {
           onTranscript: (text: string, isFinal: boolean) => {
@@ -1000,12 +1013,21 @@ export function useVoice({
           return
         }
         if (!conn) {
-          logForDebugging(
-            '[voice] Failed to connect to voice_stream (no OAuth token?)',
-          )
-          onErrorRef.current?.(
-            'Voice mode requires a Claude.ai account. Please run /login to sign in.',
-          )
+          if (isLocalProvider()) {
+            logForDebugging(
+              '[voice] Local whisper STT failed to initialize',
+            )
+            onErrorRef.current?.(
+              'Local voice mode failed. Ensure Python with faster-whisper is installed.',
+            )
+          } else {
+            logForDebugging(
+              '[voice] Failed to connect to voice_stream (no OAuth token?)',
+            )
+            onErrorRef.current?.(
+              'Voice mode requires a Claude.ai account. Please run /login to sign in.',
+            )
+          }
           // Clear the audio buffer on failure
           audioBuffer.length = 0
           cleanup()
@@ -1023,8 +1045,8 @@ export function useVoice({
       })
     }
 
-    // Doubao backend doesn't use keyterms — skip the async fetch
-    if (isDoubaoProvider()) {
+    // Doubao and local backends don't use keyterms — skip the async fetch
+    if (isDoubaoProvider() || isLocalProvider()) {
       attemptConnect([])
     } else {
       void getVoiceKeyterms().then(attemptConnect)
@@ -1042,9 +1064,11 @@ export function useVoice({
   // delay of ~500ms on macOS).
   const handleKeyEvent = useCallback(
     (fallbackMs = REPEAT_FALLBACK_MS): void => {
-      const sttAvailable = isDoubaoProvider()
-        ? isDoubaoAvailableSync()
-        : isVoiceStreamAvailable()
+      const sttAvailable = isLocalProvider()
+        ? true
+        : isDoubaoProvider()
+          ? isDoubaoAvailableSync()
+          : isVoiceStreamAvailable()
       if (!enabled || !sttAvailable) {
         return
       }

src/services/voice/edgeTTS.ts

@@ -0,0 +1,140 @@
+import { spawn } from 'child_process'
+import { existsSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+const SCRIPTS_DIR = join(import.meta.dirname, '..', '..', '..', 'scripts')
+
+function resolvePythonPath(customPath?: string): string {
+  if (customPath) return customPath
+  const venvPython = join(import.meta.dirname, '..', '..', '..', '.venv', 'bin', 'python')
+  return existsSync(venvPython) ? venvPython : 'python3'
+}
+
+export type TTSResult = {
+  success: boolean
+  audioPath?: string
+  error?: string
+}
+
+export type TTSSpeakOptions = {
+  voice?: string
+  outputPath?: string
+  pythonPath?: string
+}
+
+/**
+ * Text-to-speech using edge-tts (Microsoft Edge Neural Voice).
+ * Spawns a Python subprocess to run edge-tts and save the audio file.
+ *
+ * Requirements: pip install edge-tts
+ */
+export async function speakWithEdgeTTS(
+  text: string,
+  options?: TTSSpeakOptions,
+): Promise<TTSResult> {
+  const python = resolvePythonPath(options?.pythonPath)
+  const voice = options?.voice ?? 'en-US-JennyNeural'
+  const script = join(SCRIPTS_DIR, 'speak.py')
+
+  return new Promise(resolve => {
+    const args = [script, text, '--voice', voice]
+    if (options?.outputPath) {
+      args.push('--output', options.outputPath)
+    }
+
+    const proc = spawn(python, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+
+    let stdout = ''
+    let stderr = ''
+
+    proc.stdout.on('data', (data: Buffer) => {
+      stdout += data.toString()
+    })
+
+    proc.stderr.on('data', (data: Buffer) => {
+      stderr += data.toString()
+    })
+
+    proc.on('close', exitCode => {
+      if (exitCode !== 0) {
+        resolve({
+          success: false,
+          error: `edge-tts failed: ${stderr || 'unknown error'}`,
+        })
+        return
+      }
+
+      try {
+        const result = JSON.parse(stdout)
+        resolve(result)
+      } catch {
+        resolve({
+          success: false,
+          error: `Failed to parse edge-tts output: ${stdout.slice(0, 200)}`,
+        })
+      }
+    })
+
+    proc.on('error', err => {
+      resolve({
+        success: false,
+        error: `Failed to spawn edge-tts: ${err.message}`,
+      })
+    })
+  })
+}
+
+/** Check if edge-tts is available. */
+export async function checkEdgeTTSAvailable(pythonPath?: string): Promise<boolean> {
+  const python = resolvePythonPath(pythonPath)
+  return new Promise(resolve => {
+    const proc = spawn(python, [
+      '-c',
+      'import json;' +
+      'try: import edge_tts; print(json.dumps({"ok": True}))' +
+      'except ImportError: print(json.dumps({"ok": False}))',
+    ], { stdio: ['ignore', 'pipe', 'pipe'] })
+
+    let stdout = ''
+    proc.stdout.on('data', (data: Buffer) => { stdout += data.toString() })
+    proc.on('close', () => {
+      try {
+        const result = JSON.parse(stdout)
+        resolve(result.ok === true)
+      } catch {
+        resolve(false)
+      }
+    })
+  })
+}
+
+/** Play an audio file using system player. */
+export function playAudioFile(path: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const platform = process.platform
+    let cmd: string
+    let args: string[]
+
+    if (platform === 'darwin') {
+      cmd = 'afplay'
+      args = [path]
+    } else if (platform === 'linux') {
+      cmd = 'ffplay'
+      args = ['-nodisp', '-autoexit', path]
+    } else if (platform === 'win32') {
+      cmd = 'start'
+      args = [path]
+    } else {
+      reject(new Error(`Unsupported platform: ${platform}`))
+      return
+    }
+
+    const proc = spawn(cmd, args, { stdio: 'ignore' })
+    proc.on('close', code => {
+      if (code === 0) resolve()
+      else reject(new Error(`Playback exited with code ${code}`))
+    })
+    proc.on('error', reject)
+  })
+}

src/services/voice/providers.ts

@@ -0,0 +1,292 @@
+// Provider abstraction for VersperClaw voice mode.
+//
+// Two interfaces:
+// - `TranscriptionProvider` — speech → text
+// - `TTSProvider` — text → audio
+//
+// Built-in concrete providers:
+// - `LocalWhisperSTT` — subprocess wrapper around a local whisper.cpp / faster-whisper CLI
+// - `DoubaoSTTProvider` — wraps `src/services/doubaoSTT.ts`
+// - `EdgeTTSProvider` — subprocess wrapper around `edge-tts` CLI
+// - `CommandTTSProvider` — generic shell command with `{input}` / `{input_path}` / `{output_path}` placeholders
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+// ---------------------------------------------------------------------------
+// Public contracts
+// ---------------------------------------------------------------------------
+
+export type TranscriptionResult = {
+  success: boolean
+  text: string
+  error?: string
+}
+
+export interface TranscriptionProvider {
+  name: string
+  transcribe(wavPath: string, language?: string): Promise<TranscriptionResult>
+}
+
+export type SynthesisResult = {
+  audioPath?: string
+  error?: string
+}
+
+export interface TTSProvider {
+  name: string
+  synthesize(text: string): Promise<SynthesisResult>
+}
+
+// ---------------------------------------------------------------------------
+// Local whisper STT
+// ---------------------------------------------------------------------------
+
+export type LocalWhisperSTTOptions = {
+  binary?: string
+  model?: string
+  language?: string
+  args?: string[]
+}
+
+export class LocalWhisperSTT implements TranscriptionProvider {
+  readonly name = 'local-whisper'
+
+  constructor(private readonly opts: LocalWhisperSTTOptions = {}) {}
+
+  async transcribe(wavPath: string, language?: string): Promise<TranscriptionResult> {
+    const binary = this.resolveBinary()
+    if (!binary) {
+      return { success: false, text: '', error: 'no whisper binary found' }
+    }
+    const outDir = await this.makeTmpDir('vc-whisper-out')
+    const lang = this.opts.language ?? language ?? 'auto'
+    const args = [
+      ...(this.opts.args ?? []),
+      ...(this.opts.model ? ['-m', this.opts.model] : []),
+      '-l',
+      lang,
+      '--output_format',
+      'txt',
+      '--output_dir',
+      outDir,
+      wavPath,
+    ]
+    try {
+      await this.exec(binary, args)
+      const base = path.basename(wavPath, path.extname(wavPath)) + '.txt'
+      const txtPath = path.join(outDir, base)
+      if (!existsSync(txtPath)) {
+        return { success: false, text: '', error: 'whisper produced no txt output' }
+      }
+      const text = await os.domain?.(txtPath) ?? (await import('node:fs')).promises.readFile(txtPath, 'utf8')
+      return { success: true, text: String(text).trim() }
+    } catch (e: any) {
+      return { success: false, text: '', error: e?.message ?? String(e) }
+    }
+  }
+
+  private resolveBinary(): string | undefined {
+    if (this.opts.binary && existsSync(this.opts.binary)) return this.opts.binary
+    const candidates = [
+      'whisper.cpp',
+      'whisper-cpp',
+      'whisper',
+      'main',
+      path.join(os.homedir(), '.local', 'bin', 'whisper.cpp'),
+      '/opt/homebrew/bin/whisper.cpp',
+      '/usr/local/bin/whisper.cpp',
+    ]
+    for (const c of candidates) {
+      if (existsSync(c)) return c
+    }
+    return undefined
+  }
+
+  private async exec(cmd: string, args: string[]): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      const child = spawn(cmd, args, { shell: false })
+      let stderr = ''
+      child.stderr?.on('data', (chunk) => {
+        stderr += String(chunk)
+      })
+      child.on('close', (code) => {
+        if (code === 0) resolve()
+        else reject(new Error(`exit ${code}: ${stderr.slice(0, 200)}`))
+      })
+      child.on('error', (err) => reject(err))
+    })
+  }
+
+  private async makeTmpDir(prefix: string): Promise<string> {
+    const dir = path.join(os.tmpdir(), `versperclaw-${prefix}-${process.pid}-${Date.now()}`)
+    await new Promise<void>((resolve) => {
+      const w = spawn('mkdir', ['-p', dir])
+      w.on('close', (code) => (code === 0 ? resolve() : resolve()))
+    })
+    return dir
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Doubao STT
+// ---------------------------------------------------------------------------
+
+export class DoubaoSTTProvider implements TranscriptionProvider {
+  readonly name = 'doubao'
+
+  async transcribe(wavPath: string, language?: string): Promise<TranscriptionResult> {
+    try {
+      const { connectDoubaoStream, normalizeLanguageForSTT } = await import('./doubaoSTT.js')
+      const normalized = normalizeLanguageForSTT(language)
+      const code = normalized.code
+      const chunks: Buffer[] = []
+      const conn = await connectDoubaoStream(
+        {
+          onTranscript: (text: string) => {
+            if (text) chunks.push(Buffer.from(text, 'utf8'))
+          },
+          onError: (msg: string) => {
+            throw new Error(msg)
+          },
+          onClose: () => {},
+          onReady: (c) => {
+            const buf = Buffer.from(await (async () => (await import('node:fs')).promises.readFile(wavPath))())
+            c.send(buf)
+            void c.finalize().then(() => c.close())
+          },
+        },
+        { language: code === 'en' ? undefined : code },
+      )
+      if (!conn) throw new Error('doubao connectDoubaoStream returned null')
+      await new Promise((resolve) => setTimeout(resolve, 500))
+      const text = Buffer.concat(chunks).toString('utf8').trim()
+      if (!text) return { success: false, text: '', error: 'empty transcript' }
+      return { success: true, text }
+    } catch (e: any) {
+      return { success: false, text: '', error: e?.message ?? String(e) }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Edge TTS
+// ---------------------------------------------------------------------------
+
+export class EdgeTTSProvider implements TTSProvider {
+  readonly name = 'edge-tts'
+
+  constructor(private readonly voice?: string) {}
+
+  async synthesize(text: string): Promise<SynthesisResult> {
+    const trimmed = text.trim()
+    if (!trimmed) return { error: 'empty text' }
+    const outPath = path.join(os.homedir(), '.claude', 'voice', `tts_${Date.now()}.mp3`)
+    await new Promise((resolve) => {
+      const w = spawn('mkdir', ['-p', path.dirname(outPath)])
+      w.on('close', () => resolve(undefined))
+    })
+    const selectedVoice = this.voice ?? 'en-US-AriaNeural'
+    const inputPath = await this.writeTempText(trimmed)
+    try {
+      const args = [
+        '--voice',
+        selectedVoice,
+        '--text',
+        trimmed,
+        '--write-media',
+        outPath,
+      ]
+      await this.exec('edge-tts', args)
+      if (!existsSync(outPath)) {
+        return { error: 'edge-tts produced no output file' }
+      }
+      return { audioPath: outPath }
+    } catch (e: any) {
+      return { error: e?.message ?? String(e) }
+    } finally {
+      try {
+        await (await import('node:fs')).promises.unlink(inputPath)
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  private async exec(cmd: string, args: string[]): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      const child = spawn(cmd, args, { shell: false })
+      let stderr = ''
+      child.stderr?.on('data', (chunk) => {
+        stderr += String(chunk)
+      })
+      child.on('close', (code) => {
+        if (code === 0) resolve()
+        else reject(new Error(`exit ${code}: ${stderr.slice(0, 200)}`))
+      })
+      child.on('error', (err) => reject(err))
+    })
+  }
+
+  private async writeTempText(text: string): Promise<string> {
+    const p = path.join(os.tmpdir(), `versperclaw-edge-tts-${process.pid}-${Date.now()}.txt`)
+    await (await import('node:fs')).promises.writeFile(p, text, 'utf8')
+    return p
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command-based fallback TTS
+// ---------------------------------------------------------------------------
+
+export type CommandTTSTemplate = string
+
+export class CommandTTSProvider implements TTSProvider {
+  readonly name = 'command'
+
+  constructor(private readonly template: CommandTTSTemplate) {}
+
+  async synthesize(text: string): Promise<SynthesisResult> {
+    const inputPath = await this.writeTempText(text)
+    const outputPath = path.join(os.tmpdir(), `vesperclaw-tts-out-${Date.now()}.mp3`)
+    const resolved = this.template
+      .replace('{input}', inputPath)
+      .replace('{input_path}', inputPath)
+      .replace('{output_path}', outputPath)
+    try {
+      await this.exec(resolved)
+      return { audioPath: outputPath }
+    } catch (e: any) {
+      return { error: e?.message ?? String(e) }
+    } finally {
+      try {
+        await (await import('node:fs')).promises.unlink(inputPath)
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  private async exec(command: string): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      const child = spawn(command, { shell: true, stdio: ['ignore', 'pipe', 'pipe'] })
+      let stderr = ''
+      child.stderr?.on('data', (chunk) => {
+        stderr += String(chunk)
+      })
+      child.on('close', (code) => {
+        if (code === 0) resolve()
+        else reject(new Error(`exit ${code}: ${stderr.slice(0, 200)}`))
+      })
+      child.on('error', (err) => reject(err))
+    })
+  }
+
+  private async writeTempText(text: string): Promise<string> {
+    const p = path.join(os.tmpdir(), `vesperclaw-tts-txt-${process.pid}-${Date.now()}.txt`)
+    await (await import('node:fs')).promises.writeFile(p, text, 'utf8')
+    return p
+  }
+}

src/services/voice/whisperSTT.ts

@@ -0,0 +1,217 @@
+import { spawn } from 'child_process'
+import { appendFileSync, existsSync, mkdtempSync, writeFileSync, unlinkSync, rmdirSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import type { VoiceStreamCallbacks, VoiceStreamConnection, FinalizeSource } from '../voiceStreamSTT.js'
+
+const SCRIPTS_DIR = join(import.meta.dirname, '..', '..', '..', 'scripts')
+const DEBUG_LOG = '/tmp/voice_debug.log'
+const dbg = (...args: unknown[]) => {
+  const msg = args.map(a => (typeof a === 'object' ? JSON.stringify(a) : String(a))).join(' ')
+  const line = `[${new Date().toISOString()}] ${msg}\n`
+  appendFileSync(DEBUG_LOG, line)
+}
+
+function resolvePythonPath(customPath?: string): string {
+  if (customPath) return customPath
+  const venvPython = join(import.meta.dirname, '..', '..', '..', '.venv', 'bin', 'python')
+  return existsSync(venvPython) ? venvPython : 'python3'
+}
+
+type WhisperOptions = {
+  model?: string
+  language?: string
+  pythonPath?: string
+}
+
+/**
+ * A local Whisper STT provider that implements the VoiceStreamConnection
+ * interface. Buffers incoming audio chunks, then on finalize() writes a
+ * temporary WAV file and spawns a Python faster-whisper subprocess to
+ * transcribe it.
+ *
+ * Requirements: pip install faster-whisper   (or openai-whisper)
+ *
+ * Whisper model files are cached at ~/.cache/whisper/ automatically.
+ */
+export function connectLocalWhisperStream(
+  callbacks: VoiceStreamCallbacks,
+  options?: WhisperOptions,
+): Promise<VoiceStreamConnection | null> {
+  return new Promise(resolve => {
+    const chunks: Buffer[] = []
+    let finalized = false
+    let tmpDir: string | null = null
+
+    const python = resolvePythonPath(options?.pythonPath)
+    const model = options?.model ?? 'base'
+    const language = options?.language
+
+    dbg('whisperSTT', 'python', python, 'model', model, 'language', language)
+
+    const connection: VoiceStreamConnection = {
+      send(chunk: Buffer) {
+        if (finalized) return
+        chunks.push(Buffer.from(chunk))
+        if (chunks.length === 1) {
+          dbg('whisperSTT', 'first chunk', chunk.length, 'bytes')
+        }
+      },
+
+      async finalize(): Promise<FinalizeSource> {
+        if (finalized) return 'ws_already_closed'
+        finalized = true
+
+        dbg('whisperSTT', 'finalize called, chunks', chunks.length)
+
+        if (chunks.length === 0) {
+          dbg('whisperSTT', 'no audio chunks, returning no_data_timeout')
+          callbacks.onClose()
+          return 'no_data_timeout'
+        }
+
+        const audioBuf = Buffer.concat(chunks)
+        dbg('whisperSTT', 'total audio size', audioBuf.length, 'bytes')
+
+        try {
+          tmpDir = mkdtempSync(join(tmpdir(), 'vc-whisper-'))
+          const wavPath = join(tmpDir, 'input.wav')
+
+          writeWavHeader(wavPath, audioBuf, 16000)
+
+          const args = [join(SCRIPTS_DIR, 'transcribe.py'), wavPath, '--model', model]
+          if (language) {
+            args.push('--language', language)
+          }
+
+          const proc = spawn(python, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+
+          let stdout = ''
+          let stderr = ''
+
+          proc.stdout.on('data', (data: Buffer) => {
+            stdout += data.toString()
+          })
+
+          proc.stderr.on('data', (data: Buffer) => {
+            stderr += data.toString()
+          })
+
+          const exitCode = await new Promise<number>(resolveExit => {
+            proc.on('close', resolveExit)
+          })
+
+          dbg('whisperSTT', 'subprocess exitCode', exitCode, 'stdout', stdout.slice(0, 200))
+          if (exitCode !== 0) {
+            callbacks.onError(`Whisper transcription failed: ${stderr || 'unknown error'}`, {
+              fatal: true,
+            })
+            callbacks.onClose()
+            return 'ws_close'
+          }
+
+          const result = JSON.parse(stdout)
+          if (result.success) {
+            callbacks.onTranscript(result.text, true)
+          } else {
+            callbacks.onError(
+              result.error ?? 'Transcription failed',
+              { fatal: true },
+            )
+          }
+        } catch (err) {
+          callbacks.onError(
+            `Whisper error: ${err instanceof Error ? err.message : String(err)}`,
+            { fatal: true },
+          )
+        } finally {
+          if (tmpDir) {
+            try {
+              unlinkSync(join(tmpDir, 'input.wav'))
+            } catch {
+              // ignore
+            }
+            try {
+              rmdirSync(tmpDir)
+            } catch {
+              // ignore
+            }
+          }
+          callbacks.onClose()
+        }
+
+        return 'post_closestream_endpoint'
+      },
+
+      close() {
+        finalized = true
+        callbacks.onClose()
+      },
+
+      isConnected() {
+        return true
+      },
+    }
+
+    callbacks.onReady(connection)
+    resolve(connection)
+  })
+}
+
+/** Check if a local whisper-capable Python installation exists. */
+export async function checkLocalWhisperAvailable(pythonPath?: string): Promise<boolean> {
+  const python = resolvePythonPath(pythonPath)
+  return new Promise(resolve => {
+    const proc = spawn(python, [
+      '-c',
+      'import json;' +
+      'try: from faster_whisper import WhisperModel; print(json.dumps({"ok": True, "backend": "faster-whisper"}))' +
+      'except ImportError:' +
+      '  try: import whisper; print(json.dumps({"ok": True, "backend": "whisper"}))' +
+      '  except ImportError: print(json.dumps({"ok": False}))',
+    ], { stdio: ['ignore', 'pipe', 'pipe'] })
+
+    let stdout = ''
+    proc.stdout.on('data', (data: Buffer) => { stdout += data.toString() })
+    proc.on('close', () => {
+      try {
+        const result = JSON.parse(stdout)
+        resolve(result.ok === true)
+      } catch {
+        resolve(false)
+      }
+    })
+  })
+}
+
+/** Write a valid PCM WAV file header and data. */
+function writeWavHeader(path: string, pcmData: Buffer, sampleRate: number): void {
+  const numChannels = 1
+  const bitsPerSample = 16
+  const byteRate = sampleRate * numChannels * (bitsPerSample / 8)
+  const blockAlign = numChannels * (bitsPerSample / 8)
+  const dataSize = pcmData.length
+
+  const header = Buffer.alloc(44)
+
+  // RIFF header
+  header.write('RIFF', 0)
+  header.writeUInt32LE(36 + dataSize, 4)
+  header.write('WAVE', 8)
+
+  // fmt chunk
+  header.write('fmt ', 12)
+  header.writeUInt32LE(16, 16) // chunk size
+  header.writeUInt16LE(1, 20)  // PCM format
+  header.writeUInt16LE(numChannels, 22)
+  header.writeUInt32LE(sampleRate, 24)
+  header.writeUInt32LE(byteRate, 28)
+  header.writeUInt16LE(blockAlign, 32)
+  header.writeUInt16LE(bitsPerSample, 34)
+
+  // data chunk
+  header.write('data', 36)
+  header.writeUInt32LE(dataSize, 40)
+
+  writeFileSync(path, Buffer.concat([header, pcmData]))
+}

src/utils/settings/types.ts

@@ -868,10 +868,47 @@ export const SettingsSchema = lazySchema(() =>
               .optional()
               .describe('Enable voice mode (hold-to-talk dictation)'),
             voiceProvider: z
-              .enum(['anthropic', 'doubao'])
+              .enum(['local', 'doubao', 'anthropic'])
               .optional()
               .describe(
-                'Voice STT backend: "anthropic" (default) or "doubao" (Doubao ASR)',
+                'Voice STT backend: "local" (whisper/whisper.cpp / faster-whisper) or "doubao" (Doubao ASR).'
+                  + ' "anthropic" is a client-side compatibility alias.',
+              ),
+            voiceAutoTTS: z
+              .boolean()
+              .optional()
+              .describe('Automatically speak assistant replies in voice mode'),
+            voiceRecordKey: z
+              .string()
+              .optional()
+              .describe(
+                'Keyboard shortcut for push-to-talk voice input (e.g. "Space" or "ctrl+shift+space")',
+              ),
+            voiceTTSProvider: z
+              .enum(['edge', 'openai', 'elevenlabs', 'command'])
+              .optional()
+              .describe('Text-to-speech backend for spoken replies'),
+            voiceTTSVoice: z
+              .string()
+              .optional()
+              .describe('Preferred TTS voice identifier (provider-specific)'),
+            voiceTTSCommand: z
+              .string()
+              .optional()
+              .describe(
+                'Shell command template for command-based TTS. Supports {input}, {input_path}, and {output_path} placeholders.',
+              ),
+            voiceLanguage: z
+              .string()
+              .optional()
+              .describe(
+                'Preferred language for voice dictation (e.g. "en", "ja", "zh-CN")',
+              ),
+            voiceModel: z
+              .string()
+              .optional()
+              .describe(
+                'Optional whisper model or binary path override for local STT',
               ),
           }
         : {}),

src/voice/voiceModeEnabled.ts

@@ -1,46 +1,19 @@
-import { feature } from 'bun:bundle'
-import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growthbook.js'
-import {
-  getClaudeAIOAuthTokens,
-  isAnthropicAuthEnabled,
-} from '../utils/auth.js'
-
 /**
- * Kill-switch check for voice mode. Returns true unless the
- * `tengu_amber_quartz_disabled` GrowthBook flag is flipped on (emergency
- * off). Default `false` means a missing/stale disk cache reads as "not
- * killed" — so fresh installs get voice working immediately without
- * waiting for GrowthBook init. Use this for deciding whether voice mode
- * should be *visible* (e.g., command registration, config UI).
+ * Kill-switch check for voice mode. Bypassed in external builds —
+ * voice is always eligible pending other checks (mic, dependencies,
+ * STT backend).
  */
 export function isVoiceGrowthBookEnabled(): boolean {
-  // Positive ternary pattern — see docs/feature-gating.md.
-  // Negative pattern (if (!feature(...)) return) does not eliminate
-  // inline string literals from external builds.
-  return feature('VOICE_MODE')
-    ? !getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_quartz_disabled', false)
-    : false
+  return true
 }
 
 /**
- * Auth-only check for voice mode. Returns true when the user has a valid
- * Anthropic OAuth token. Backed by the memoized getClaudeAIOAuthTokens —
- * first call spawns `security` on macOS (~20-50ms), subsequent calls are
- * cache hits. The memoize clears on token refresh (~once/hour), so one
- * cold spawn per refresh is expected. Cheap enough for usage-time checks.
+ * Auth-only check for voice mode. Returns true unconditionally in
+ * external builds — the Doubao ASR backend does not require Anthropic
+ * OAuth, and the GrowthBook kill-switch is already bypassed.
  */
 export function hasVoiceAuth(): boolean {
-  // Voice mode requires Anthropic OAuth — it uses the voice_stream
-  // endpoint on claude.ai which is not available with API keys,
-  // Bedrock, Vertex, or Foundry.
-  if (!isAnthropicAuthEnabled()) {
-    return false
-  }
-  // isAnthropicAuthEnabled only checks the auth *provider*, not whether
-  // a token exists. Without this check, the voice UI renders but
-  // connectVoiceStream fails silently when the user isn't logged in.
-  const tokens = getClaudeAIOAuthTokens()
-  return Boolean(tokens?.accessToken)
+  return true
 }
 
 /**
@@ -53,9 +26,8 @@ export function isVoiceModeEnabled(): boolean {
 
 /**
  * Check if voice mode can be activated with any STT backend.
- * Always returns true when VOICE_MODE feature flag is on and GrowthBook
- * kill-switch is off — the Doubao backend does not require Anthropic auth.
+ * The Doubao backend does not require Anthropic auth.
  */
 export function isVoiceAvailable(): boolean {
-  return feature('VOICE_MODE')
-}
+  return isVoiceGrowthBookEnabled()
+}