verbalcoding 0.2.11 → 0.2.13

package/app-node/voice_turn_runner.test.mjs

@@ -0,0 +1,289 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createVoiceTurnRunner } from './voice_turn_runner.mjs';
+import { createUtteranceRouter } from './utterance_router.mjs';
+import { createPlanDispatcher } from './plan_dispatcher.mjs';
+import { createBridge } from './bridge_context.mjs';
+import { createAgentTurnLifecycle } from './agent_turn.mjs';
+
+function noop() {}
+async function noopAsync() {}
+
+// Build a complete dep set for voiceTurnRunner by first constructing a
+// real utterance_router with stubbed pure-function deps, then threading
+// its outputs into the runner alongside the rest. This mirrors main.mjs's
+// real construction order so the tests catch any inter-module wiring drift.
+function makeDeps(overrides = {}) {
+  const bridge = createBridge();
+  bridge.bridgeState = {
+    deferredSize: () => 0,
+    currentEpoch: () => 1,
+    discardQueues: () => 0,
+  };
+  const agentTurnLifecycle = createAgentTurnLifecycle({ bridge, warn: noop });
+
+  const agentAdapter = {
+    label: 'default-agent', backend: 'hermes',
+    readSessionId: () => null,
+    ask: async () => 'mock agent answer',
+  };
+
+  // Construct the router (post-Phase 7b: dispatch + adapter selection only).
+  const router = createUtteranceRouter({
+    bridge,
+    log: noop, warn: noop, path: { join: (...a) => a.join('/') },
+    ROOT: '/tmp/vc', TTS_VOICE_CONFIG_PATH: '/tmp/voices.json',
+    agentAdapter,
+    settings: { voiceLanguage: 'ko', transcriptChannelId: 'tx-ch', agent: { backend: 'hermes', label: 'hermes' }, tts: {} },
+    projectSessionContextText: () => '',
+    createBridgeAgentAdapter: s => ({ label: s?.label || 'fake', backend: s?.backend || 'hermes', ask: async () => '' }),
+    buildAgentSettings: () => ({ backend: 'hermes', label: 'hermes' }),
+    commandIsInstalled: async () => true,
+    shellSplit: s => String(s).split(' '),
+    sendText: noopAsync, speakText: noopAsync,
+    ensureTtsVoiceConfig: () => ({ backends: {} }),
+    updateTtsVoiceConfig: c => c,
+    writeTtsVoiceConfig: noop,
+    applyVoiceConfigToProcessEnv: () => ({ selection: { backend: 'edge', voiceType: 'female', voice: { language: 'ko', voice: 'x' } } }),
+    ensureSelectedTtsBackendInstalled: noopAsync,
+    rebuildTtsRuntimeSettings: noop,
+    voiceCommandFromTranscript: () => null,
+    voiceChangedText: () => '',
+    voiceLanguageCommandFromTranscript: () => null,
+    voiceCloneCommandFromText: () => null,
+    voiceCloneCapture: { arm: () => ({ targetPath: '' }), cancel: () => false, current: () => null },
+    notifyVoiceCloneSampleGapIfNeeded: noopAsync,
+    languageChangedText: () => '',
+    applyRuntimeLanguage: noop,
+    persistEnvValues: noop,
+    discardVoiceInputQueues: () => 0,
+  });
+
+  // Construct the plan dispatcher (Phase 7b) consuming router outputs.
+  const planDispatcher = createPlanDispatcher({
+    bridge,
+    settings: { voiceLanguage: 'ko', transcriptChannelId: 'tx-ch', agent: { backend: 'hermes', label: 'hermes' } },
+    sendText: noopAsync,
+    speakText: noopAsync,
+    routingStateFor: router.routingStateFor,
+    adapterForBackend: router.adapterForBackend,
+    adapterForProjectSession: router.adapterForProjectSession,
+    resolveProjectSessionForChannel: () => null,
+    isAgentRoutingDecision: () => false,
+    parseDecisionAnswer: () => ({ type: 'unknown' }),
+    parsePlanVoiceCommand: () => ({ type: 'unknown' }),
+    applyPlanCommand: s => s,
+    parsePlanOutput: () => ({ steps: [], decisions: [] }),
+    renderDecisionPrompt: d => d?.text || '',
+    renderResolvedDecisions: () => '',
+    renderFinalPlan: () => '',
+    planModePreamble: () => '',
+    planExecutionPreamble: () => '',
+    isPlanEntryUtterance: () => false,
+  });
+
+  const settings = { voiceLanguage: 'ko', transcriptChannelId: 'tx-ch', agent: { backend: 'hermes', label: 'hermes' }, tts: {} };
+
+  return {
+    bridge,
+    agentTurnLifecycle,
+    settings,
+    client: { channels: { cache: new Map() } },
+    log: noop, warn: noop, fs: { rm: (_p, _o, cb) => cb && cb() },
+    // voice_io
+    transcribe: async () => 'hey hermes do a thing',
+    // tts_player
+    beginStreamingTurn: () => false,
+    endStreamingTurn: noopAsync,
+    speakText: noopAsync,
+    // progress_handler
+    queueProgressSpeechText: noop,
+    stopProgressSpeech: noop,
+    speakImmediateNotice: noopAsync,
+    // notification_handler
+    maybeNotifyTaskComplete: noopAsync,
+    // utterance_router outputs (real router instance built above)
+    handleLanguageCommand: router.handleLanguageCommand,
+    handleTtsVoiceCommand: router.handleTtsVoiceCommand,
+    handleVoiceCloneCommand: router.handleVoiceCloneCommand,
+    dispatchPlanModeUtterance: planDispatcher.dispatchPlanModeUtterance,
+    adapterForBackend: router.adapterForBackend,
+    adapterForProjectSession: router.adapterForProjectSession,
+    planChannelKey: planDispatcher.planChannelKey,
+    routingStateFor: router.routingStateFor,
+    recordUtterance: router.recordUtterance,
+    clearTransientRouting: router.clearTransientRouting,
+    // pure helpers
+    isAllowed: () => true,
+    isAbortError: e => e?.name === 'AbortError',
+    sleep: async () => {},
+    sendText: noopAsync,
+    sendEmbed: async () => true,
+    reloadRuntimeLanguageFromEnv: () => ({ changed: false, voiceLanguage: 'ko', whisperLanguage: 'ko' }),
+    drainDeferredProcessingUtterances: noopAsync,
+    resolveProjectSessionForChannel: () => null,
+    projectSessionContextText: () => '',
+    ontologyStateFor: () => ({ nodeCount: 0, serializeForHandoff: () => '' }),
+    captureOntologyFromTurn: noop,
+    formatRecentDiscordContext: () => '',
+    formatSttResultMessage: (_lang, _u, t) => `you said: ${t}`,
+    formatSttStartMessage: () => '🎧',
+    formatVoiceErrorMessage: (_lang, m) => m,
+    formatWakeRejectedMessage: () => 'no wake word',
+    agentAnswerHeader: () => 'agent says:',
+    emptyAgentAnswer: () => '(empty)',
+    spokenResultOnly: (_p, a) => a,
+    stripWake: t => t,
+    acceptsWake: () => true,
+    sensitivityChangedSpeech: () => '',
+    sensitivityModeFromTranscript: () => null,
+    sensitivityStatusText: () => '',
+    setSensitivityMode: () => ({ mode: 'normal' }),
+    isSensitivityOnlyRequest: () => false,
+    verboseChangedSpeech: () => '',
+    verboseModeFromTranscript: () => null,
+    verboseStatusText: () => '',
+    setVerboseProgress: noop,
+    isVerboseOnlyRequest: () => false,
+    isRoutingOnlyUtterance: () => false,
+    parseAgentRoutingCommand: () => ({ type: 'none' }),
+    renderAgentPrefix: () => '',
+    buildCrossAgentPrompt: ({ prompt }) => prompt,
+    buildFallbackDecision: () => ({ slot: 'fallback' }),
+    parseDecisionAnswer: () => ({ type: 'unknown' }),
+    parseResearchCommand: () => ({ type: 'none' }),
+    runResearchTurn: async () => ({ status: 'no_backend' }),
+    PROGRESS_IDLE_CHECK_MS: 5000,
+    PROGRESS_IDLE_NOTICE_INITIAL_MS: 10000,
+    PROGRESS_IDLE_NOTICE_LIMIT: 20,
+    PROGRESS_IDLE_NOTICE_MAX_MS: 30000,
+    PROGRESS_IDLE_NOTICE_MULTIPLIER: 1.8,
+    STT_START_VOICE_NOTICE: false,
+    ...overrides,
+  };
+}
+
+test('createVoiceTurnRunner exposes handleRecording', () => {
+  const runner = createVoiceTurnRunner(makeDeps());
+  assert.equal(typeof runner.handleRecording, 'function');
+});
+
+test('handleRecording happy path: transcribe -> agent -> send + speak + notify, cleanup green', async () => {
+  const calls = { transcribe: 0, askPrompt: '', sendText: [], speakText: [], notify: [] };
+  // Capture the exact prompt the runner sends to the agent and the exact
+  // answer that flows back out.
+  const fakeAdapter = {
+    label: 'hermes', backend: 'hermes', readSessionId: () => null,
+    ask: async (prompt, _signal, plan) => {
+      calls.askPrompt = prompt;
+      assert.equal(plan.label, 'hermes', 'plan label = agent label');
+      assert.equal(plan.task, true, 'plan.task=true for voice turn');
+      return 'twelve apples';
+    },
+  };
+  const deps = makeDeps({
+    transcribe: async wav => { calls.transcribe++; assert.equal(wav, '/tmp/u.wav'); return 'hermes do the thing'; },
+    sendText: async t => { calls.sendText.push(t); return true; },
+    speakText: async t => { calls.speakText.push(t); },
+    maybeNotifyTaskComplete: async ({ answer, label }) => { calls.notify.push({ answer, label }); },
+    // Force the runner's adapter lookup to return our test adapter rather
+    // than the router's auto-created one (the router builds a fresh adapter
+    // per backend via createBridgeAgentAdapter).
+    adapterForBackend: () => fakeAdapter,
+    adapterForProjectSession: () => fakeAdapter,
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  assert.equal(deps.bridge.processing, false);
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, null);
+  assert.equal(calls.transcribe, 1, 'transcribe called once');
+  assert.equal(calls.askPrompt, 'hermes do the thing', 'agent receives the post-wake prompt');
+  assert.deepEqual(calls.speakText.at(-1), 'twelve apples', 'agent answer is spoken');
+  assert.ok(calls.sendText.some(s => /you said: hermes do the thing/.test(s)), 'STT echoed');
+  assert.ok(calls.sendText.some(s => /twelve apples/.test(s)), 'agent answer surfaced as text');
+  assert.equal(calls.notify.length, 1, 'maybeNotifyTaskComplete fired once');
+  assert.equal(calls.notify[0].label, 'hermes', 'notify carries the agent label');
+  assert.equal(deps.bridge.processing, false, 'processing flag cleared in finally');
+  assert.equal(deps.bridge.activeTurnId, 0, 'activeTurnId cleared');
+  assert.equal(deps.bridge.activeProgressAbortController, null, 'progress controller cleared');
+});
+
+test('handleRecording cleans up progress controller even when agent throws', async () => {
+  const fakeAdapter = {
+    label: 'hermes', backend: 'hermes', readSessionId: () => null,
+    ask: async () => { throw new Error('agent boom'); },
+  };
+  const deps = makeDeps({
+    adapterForBackend: () => fakeAdapter,
+    adapterForProjectSession: () => fakeAdapter,
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  let finishError = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; finishError = r.error; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'error');
+  assert.match(finishError || '', /agent boom/);
+  // Cleanup invariants — the bug Codex flagged on the original voice-path
+  // finally is now guarded by agentTurnLifecycle.finish, so we double-check.
+  assert.equal(deps.bridge.processing, false);
+  assert.equal(deps.bridge.activeProgressAbortController, null);
+  assert.equal(deps.bridge.currentAbortController, null);
+});
+
+test('handleRecording drops when bridge.processing is already true', async () => {
+  const deps = makeDeps();
+  deps.bridge.processing = true;
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'drop_processing');
+  assert.equal(deps.bridge.processing, true, 'processing flag left intact (other turn owns it)');
+});
+
+test('handleRecording rejects unauthorized users', async () => {
+  const deps = makeDeps({ isAllowed: () => false });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('intruder', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'unauthorized');
+});
+
+test('handleRecording short-circuits on empty transcript', async () => {
+  const deps = makeDeps({ transcribe: async () => '' });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'empty_transcript');
+  assert.equal(deps.bridge.processing, false, 'processing flag still cleaned up');
+});
+
+test('handleRecording short-circuits when wake word missing', async () => {
+  const sent = [];
+  const deps = makeDeps({
+    acceptsWake: () => false,
+    sendText: async t => { sent.push(t); return true; },
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(finishStatus, 'wake_rejected');
+  assert.ok(sent.some(t => /no wake word/.test(t)), 'wake-rejected message sent');
+});
+
+test('handleRecording with stale language reload aborts before transcribe', async () => {
+  let transcribed = false;
+  const deps = makeDeps({
+    reloadRuntimeLanguageFromEnv: () => ({ changed: true, voiceLanguage: 'en', whisperLanguage: 'en' }),
+    transcribe: async () => { transcribed = true; return 'hi'; },
+  });
+  const { handleRecording } = createVoiceTurnRunner(deps);
+  let finishStatus = null;
+  const metricsTurn = { mark: () => {}, addMeta: () => {}, stage: () => {}, finish: r => { finishStatus = r.status; } };
+  await handleRecording('user-1', '/tmp/u.wav', 8192, 1, metricsTurn);
+  assert.equal(transcribed, false, 'transcribe not called when language changed');
+  assert.equal(finishStatus, 'drop_stale_language_change');
+});

package/docs/CONFIGURATION.md

@@ -1,32 +1,70 @@
 # VerbalCoding Configuration
 
-## Setup Wizard
+<!-- readme-glow-up:intro -->
+<p align="center">
+  <a href="../README.md">README</a> ·
+  <a href="README.md">Docs hub</a> ·
+  <a href="FRESH_INSTALL.md">Fresh Install</a> ·
+  <a href="USAGE.md">Usage</a> ·
+  <a href="CONFIGURATION.md">Configuration</a> ·
+  <a href="TROUBLESHOOTING.md">Troubleshooting</a> ·
+  <a href="MULTI_INSTANCE.md">Multi-Instance</a>
+</p>
+
+> Settings reference for Discord, agents, TTS, MCP, and runtime behavior.
+>
+> Fast path: `vc setup handles normal config; edit .env only for advanced overrides`
+<!-- /readme-glow-up:intro -->
+
+## Setup Command Map
+
+For npm/global installs, use `vc` commands instead of manually editing `.env`:
 
-Discord bot/application setup is intentionally not re-explained from scratch here. Use these upstream guides for the Discord-side steps, then return to VerbalCoding setup:
+```bash
+vc setup                               # guided setup: prerequisites, Discord token, voice channels
+vc setup --yes                         # non-interactive bootstrap/starter config
+vc setup token                         # later update Discord bot token
+vc setup channels "General,Team Voice" # later update auto-join voice channel names
+vc setup channel "General"             # alias
+vc setup voice "General"               # alias
+vc doctor                               # redacted health check and supported auto-fixes
+vc start                                # run the default bridge
+```
 
-- Hermes Agent Discord messaging guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
-- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
-- Discord official quick start: <https://docs.discord.com/developers/quick-start/getting-started>
+Clone-only setup remains available:
 
 ```bash
-./scripts/install.sh
+./scripts/install.sh --yes
 ```
 
-The installer asks for Discord token, allowed users, auto-join voice channel names, transcript channel/thread, CLI harness backend, default voice language, TTS settings, and wake-word behavior. It writes `.env` with mode `0600`; `.env` is ignored by git. It also links the short shell command `vc`.
+`vc setup token` updates `DISCORD_BOT_TOKEN` and optional `DISCORD_CLIENT_ID`. `vc setup channels` updates `AUTO_JOIN_VOICE_CHANNELS`. Both preserve unrelated `.env` values, write the file with mode `0600`, and avoid printing token values.
+
+## Discord Bot/Application Setup
+
+Use these upstream guides for the Discord-side steps, then return to VerbalCoding setup:
 
-If you only need the shell command after manual install:
+- Hermes Agent Discord messaging guide: <https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord>
+- Discord official bot overview: <https://docs.discord.com/developers/bots/overview>
+- Discord official quick start: <https://docs.discord.com/developers/quick-start/getting-started>
+
+Minimum flow:
 
 ```bash
-npm link
+vc bot invite <discord-client-id>
+vc setup token <bot-token> --client-id <discord-client-id>
+vc setup channels "VerbalCoding,General"
+vc doctor
 ```
 
+The bot needs Message Content privileged intent plus text/voice permissions for the target channels.
+
 ## Supported Agent Backends
 
 Set `AGENT_BACKEND` in `.env`.
 
 | Backend | Default command | Notes |
 |---|---|---|
-| `hermes` | `hermes chat -Q -q` | Default. Preserves `.verbalcoding-session` resume behavior. |
+| `hermes` | `hermes chat -Q -q` | Default. Preserves `.verbalcoding-session` resume behavior. `vc doctor` can auto-install the Hermes CLI on supported macOS/Linux installs. |
 | `claude-code` / `claude` | `claude -p` | Override with `CLAUDE_COMMAND` or `AGENT_COMMAND`. |
 | `codex` | `codex exec` | Override with `CODEX_COMMAND` or `AGENT_COMMAND`. |
 | `gemini` | `gemini -p` | Override with `GEMINI_COMMAND` or `AGENT_COMMAND`. |
@@ -62,8 +100,9 @@ New backends should implement the same contract and keep voice/STT/TTS behavior
 
 ```bash
 DISCORD_BOT_TOKEN="***"
+DISCORD_CLIENT_ID="123456789012345678"
 DISCORD_ALLOWED_USERS="123456789012345678"
-AUTO_JOIN_VOICE_CHANNELS="일반,General,general"
+AUTO_JOIN_VOICE_CHANNELS="VerbalCoding,General"
 TRANSCRIPT_CHANNEL_ID="123456789012345678"
 
 AGENT_BACKEND="hermes"
@@ -95,9 +134,7 @@ Language presets and voice selection are separate:
 - Live voice commands such as “남자 한국어 목소리로 바꿔”, “여자 한국어 목소리로 바꿔”, `change voice to Korean female`, and `switch speaker to English` change only the speaker/voice type.
 - `!voice-test <text>` plays a quick sample with the currently selected backend and voice.
 
-Voice selection is stored in `config/tts-voices.json` by default. Override the path with `TTS_VOICE_CONFIG`. The running bridge re-reads/applies voice selection before synthesis, so voice commands take effect without a full restart.
-
-Default Edge catalog:
+Voice selection is stored in `config/tts-voices.json` by default. Override the path with `TTS_VOICE_CONFIG`.
 
 | `TTS_VOICE_TYPE` | `TTS_VOICE` | Language |
 |---|---|---|
@@ -107,29 +144,9 @@ Default Edge catalog:
 | `english_male` | `en-US-GuyNeural` | English |
 | `english_female` | `en-US-AriaNeural` | English |
 
-Manual persistent override:
-
-```bash
-TTS_BACKEND="edge"
-TTS_VOICE_TYPE="korean_male"
-TTS_VOICE="ko-KR-InJoonNeural"
-TTS_VOICE_CONFIG="config/tts-voices.json"
-```
-
-For OpenVoice, SpeechSwift, or Supertonic, keep the backend-specific voice/reference settings in the sections below; the same voice catalog file can still track the active voice type.
-
-Backend-specific voice options:
-
-| Backend | Settings | Voice choices |
-|---|---|---|
-| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Built-in types above, plus any voice returned by `edge-tts --list-voices` |
-| Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5`; language `ko`, `en`, `es`, `pt`, `fr` |
-| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | User-provided permitted reference WAV; style defaults to `default` |
-| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | Reference-sample voices for CosyVoice, or backend-supported speaker/model IDs |
-
 ## Utterance Segmentation
 
-`UTTERANCE_IDLE_MS` controls how long the bridge waits after a speech segment before it decides the user is done and starts STT. The default is `4500` ms to preserve longer spoken instructions with natural pauses. Lower values feel faster for short commands but can split long dictation; higher values are safer for thoughtful speech.
+`UTTERANCE_IDLE_MS` controls how long the bridge waits after a speech segment before it decides the user is done and starts STT.
 
 ```bash
 UTTERANCE_IDLE_MS="4500"  # balanced default
@@ -138,7 +155,7 @@ UTTERANCE_IDLE_MS="6000"  # safer for long dictation with pauses
 
 ## MCP Server
 
-VerbalCoding ships a stdio MCP server so Hermes Agent or any MCP client can control the bridge through tools instead of relying on skills or free-form shell commands.
+VerbalCoding ships a stdio MCP server so Hermes Agent or any MCP client can control the bridge through tools.
 
 Hermes config example:
 
@@ -161,74 +178,40 @@ Exposed MCP tools:
 | `set_language` | Update STT/progress/TTS language together |
 | `start`, `stop`, `restart` | Control the Discord voice bridge |
 
-## Optional OpenVoice TTS
+## Docker / Container Networking
 
-Edge TTS remains the default and fallback. To try local voice cloning with OpenVoice V2:
+Discord voice needs outbound UDP. If Docker logs show `Cannot perform IP discovery - socket closed`, try Linux host networking:
 
-```bash
-./scripts/setup_openvoice.sh
-# Download checkpoints_v2_0417.zip from OpenVoice docs and extract under vendor/OpenVoice/checkpoints_v2/
-mkdir -p voice-samples
-# Put a permitted reference sample at voice-samples/user-reference.wav,
-# or capture one from Discord with !voice-clone capture.
-python3 integrations/openvoice/synth.py --openvoice-dir vendor/OpenVoice --ref-audio voice-samples/user-reference.wav --text '안녕하세요. 버벌코딩 목소리 복제 테스트입니다.' --output /tmp/verbalcoding-openvoice-smoke.wav
-```
-
-Then set:
-
-```bash
-TTS_BACKEND="openvoice"
-OPENVOICE_REF_AUDIO="./voice-samples/user-reference.wav"
-OPENVOICE_PROGRESS="0"
-```
-
-Only clone voices you own or have permission to use. If OpenVoice fails or times out, VerbalCoding falls back to Edge TTS.
-
-## Optional Supertonic TTS
-
-```bash
-./scripts/setup_supertonic.sh
-supertonic tts '안녕하세요. 수퍼토닉 테스트입니다.' --lang ko --voice M1 --steps 2 --speed 1.0 -o /tmp/verbalcoding-supertonic.wav
-```
-
-Then set:
-
-```bash
-TTS_BACKEND="supertonic"
-SUPERTONIC_COMMAND="./.venv-supertonic/bin/supertonic"
-SUPERTONIC_VOICE="M1"
-SUPERTONIC_LANGUAGE="ko"
-SUPERTONIC_STEPS="2"
-SUPERTONIC_SPEED="1.0"
-SUPERTONIC_PROGRESS="0"
+```yaml
+services:
+  verbalcoding:
+    network_mode: "host"
 ```
 
-If Supertonic is missing, fails, or times out, VerbalCoding falls back to Edge TTS.
-
-## Optional SpeechSwift / CosyVoice TTS
+Remove `ports:` from that Compose service. On Docker Desktop for macOS/Windows, host networking may not expose UDP the same way; run on the host or a Linux VM if voice still fails.
 
-On Apple Silicon, `speech-swift` is a local backend for Korean voice cloning with MLX-native CosyVoice/Qwen3-TTS.
+## Optional TTS Backends
 
-```bash
-brew tap soniqo/speech https://github.com/soniqo/speech-swift
-brew install speech
-```
+For the full backend matrix, latency notes, aliases, and Mac mini caveats, see [TTS Backends](TTS_BACKENDS.md).
 
-Recommended env:
-
-```bash
-TTS_BACKEND="speechswift"
-SPEECHSWIFT_MODE="server"
-SPEECHSWIFT_ENGINE="cosyvoice"
-SPEECHSWIFT_LANGUAGE="korean"
-SPEECHSWIFT_REF_AUDIO="./voice-samples/user-reference.wav"
-SPEECHSWIFT_SERVER_HOST="127.0.0.1"
-SPEECHSWIFT_SERVER_PORT="18080"
-SPEECHSWIFT_SERVER_URL="http://127.0.0.1:18080"
-SPEECHSWIFT_PROGRESS="0"
-```
+Edge TTS remains the default and fallback. Optional local backends are configured with their own env vars:
 
-Keep Edge for quick progress/backchannel prompts.
+| Backend | Settings | Voice choices |
+|---|---|---|
+| Edge | `TTS_VOICE_TYPE`, `TTS_VOICE` | Built-in types above, plus any voice returned by `edge-tts --list-voices` |
+| Supertonic | `SUPERTONIC_VOICE`, `SUPERTONIC_LANGUAGE` | `M1`–`M5`, `F1`–`F5`; language `ko`, `en`, `es`, `pt`, `fr` |
+| OpenVoice | `OPENVOICE_REF_AUDIO`, `OPENVOICE_STYLE`, `OPENVOICE_LANGUAGE` | User-provided permitted reference WAV; style defaults to `default` |
+| SpeechSwift / CosyVoice | `SPEECHSWIFT_REF_AUDIO`, `SPEECHSWIFT_ENGINE`, `SPEECHSWIFT_SPEAKER`, `SPEECHSWIFT_MODEL_ID` | Reference-sample voices for CosyVoice, or backend-supported speaker/model IDs |
+| OmniVoice | `OMNIVOICE_PYTHON`, `OMNIVOICE_MODEL`, `OMNIVOICE_REF_AUDIO`, `OMNIVOICE_REF_TEXT`, `OMNIVOICE_LANGUAGE`, `OMNIVOICE_SPEAKER` | k2-fsa/OmniVoice reference-sample cloning or optional voice-design attributes |
+| Qwen3 TTS | `QWEN3TTS_COMMAND`, `QWEN3TTS_MODE`, `QWEN3TTS_MODEL`, `QWEN3TTS_SPEAKER` | Preset speaker such as `sohee`, reference mode, or designed speaker text |
+| MLX Audio | `MLXAUDIO_PYTHON`, `MLXAUDIO_MODEL`, `MLXAUDIO_VOICE`, `MLXAUDIO_LANG_CODE` | MLX Qwen3 voice/speaker IDs such as `Chelsie` |
+| NeuTTS Air | `NEUTTSAIR_PYTHON`, `NEUTTSAIR_BACKBONE_REPO`, `NEUTTSAIR_CODEC_REPO`, `NEUTTSAIR_REF_AUDIO`, `NEUTTSAIR_REF_TEXT` | English NeuTTS Air reference-sample cloning; use Q4 GGUF for lower latency |
+| FireRedTTS-2 | `FIREREDTTS2_COMMAND`, `FIREREDTTS2_PRETRAINED_DIR`, `FIREREDTTS2_PROMPT_AUDIO`, `FIREREDTTS2_PROMPT_TEXT` | Prompt-reference voice or random speaker |
+| FireRedTTS-2 MLX helper | `integrations/fireredtts2/synth_mlx.py` | Experimental Apple Silicon LLM-port helper; not a canonical `TTS_BACKEND` yet |
+| MOSS-TTS-Nano | `MOSSTTSNANO_COMMAND`, `MOSSTTSNANO_SCRIPT`, `MOSSTTSNANO_CHECKPOINT`, `MOSSTTSNANO_PROMPT_AUDIO` | OpenMOSS prompt reference or continuation mode |
+| MOSS-TTS-Nano MLX | `MOSSTTSNANO_MLX_PYTHON`, `MOSSTTSNANO_MLX_SCRIPT`, `MOSSTTSNANO_MLX_WORKER`, `MOSSTTSNANO_PROMPT_AUDIO` | Experimental MLX hybrid prompt reference or continuation mode |
+
+Only clone voices you own or have permission to use. For OmniVoice, install it in a separate Python environment such as `.venv-omnivoice` (`pip install torch torchaudio soundfile omnivoice`) and set `TTS_BACKEND=omnivoice`. For NeuTTS Air, install the local `neutts` package in `.venv-neuttsair`, set `TTS_BACKEND=neuttsair`, and keep progress prompts on Edge unless explicitly testing local progress TTS. If a local backend fails or times out, VerbalCoding falls back to Edge TTS.
 
 ## Operational Notes