@elizaos/ui 2.0.0-beta.1 → 2.0.3-beta.2

package/hooks/useVoiceChat.js

@@ -0,0 +1,1831 @@
+/**
+ * Bidirectional voice hook for chat + avatar lip sync.
+ *
+ * TTS providers (in priority order):
+ *  1. ElevenLabs  — streaming endpoint; assistant replies enqueue text deltas as
+ *     the stream grows (no sentence-boundary wait — lower time-to-first-audio).
+ *  2. Browser SpeechSynthesis — fallback when ElevenLabs isn't configured.
+ *
+ * STT: local-inference ASR on local desktop, then native TalkMode or browser
+ * SpeechRecognition fallback.
+ */
+import { Capacitor } from "@capacitor/core";
+import { useCallback, useEffect, useEffectEvent, useMemo, useRef, useState, } from "react";
+import { fetchWithCsrf } from "../api/csrf-client.js";
+import { getElectrobunRendererRpc, invokeDesktopBridgeRequest, } from "../bridge/electrobun-rpc.js";
+import { getTalkModePlugin, } from "../bridge/native-plugins.js";
+import { resolveApiUrl } from "../utils/index.js";
+import { getElizaApiToken } from "../utils/eliza-globals.js";
+import { isTtsDebugEnabled, ttsDebug, ttsDebugTextPreview, } from "../utils/tts-debug.js";
+import { hasConfiguredApiKey } from "../voice/index.js";
+import { isLocalAsrCaptureSupported, startLocalAsrRecorder, } from "../voice/local-asr-capture.js";
+import { isLocalInferenceAsrReady, transcribeLocalInferenceWav, } from "../voice/local-asr-transcribe.js";
+import { collapseWhitespace, nextIdleMouthOpen, normalizeCacheText, normalizeMouthOpen, queueableSpeechPrefix, remainderAfter, shouldCacheGeneratedSpeech, splitFirstSentence, toSpeakableText, } from "../voice/voice-chat-playback.js";
+import { mergeTranscriptWindows } from "../voice/voice-chat-recording.js";
+import { ASSISTANT_TTS_DEBOUNCE_MS, ASSISTANT_TTS_FINAL_ONLY, ASSISTANT_TTS_FIRST_FLUSH_CHARS, ASSISTANT_TTS_MIN_CHUNK_CHARS, DEFAULT_ELEVEN_MODEL, DEFAULT_ELEVEN_VOICE, describeTtsCloudFetchTargetForDebug, getSpeechRecognitionCtor, globalAudioCache, isAbortError, localePrefix, MAX_CACHED_SEGMENTS, matchesVoiceLocale, normalizeSpeechLocale, resolveEffectiveVoiceConfig, resolveVoiceMode, resolveVoiceProxyEndpoint, TALKMODE_STOP_SETTLE_MS, toArrayBuffer, webSpeechVoiceDebugFields, } from "../voice/voice-chat-types.js";
+// ── Re-exports (public API) ──────────────────────────────────────────
+export { nextIdleMouthOpen } from "../voice/voice-chat-playback.js";
+// ── Shared mutable state ─────────────────────────────────────────────
+let sharedAudioCtx = null;
+const AUDIO_CONTEXT_RESUME_TIMEOUT_MS = 1200;
+const LOCAL_INFERENCE_TTS_TIMEOUT_MS = 60_000;
+/** How long the transient `micReconnected` pulse stays set after an auto-restart. */
+const MIC_RECONNECT_PULSE_MS = 1500;
+// ── Internal helpers ─────────────────────────────────────────────────
+async function resumeAudioContextForPlayback(ctx, timeoutMs = AUDIO_CONTEXT_RESUME_TIMEOUT_MS) {
+    if (ctx.state !== "suspended")
+        return true;
+    let timeoutId;
+    try {
+        const resumed = await Promise.race([
+            ctx.resume().then(() => true, () => false),
+            new Promise((resolve) => {
+                timeoutId = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+        return resumed && ctx.state !== "suspended";
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+function shouldPreferNativeTalkMode() {
+    if (typeof window === "undefined")
+        return false;
+    return Capacitor.isNativePlatform() || !!getElectrobunRendererRpc();
+}
+function isWindowsElectrobunRenderer() {
+    return (typeof window !== "undefined" &&
+        !!getElectrobunRendererRpc() &&
+        typeof process !== "undefined" &&
+        process.platform === "win32");
+}
+function shouldAutoRestartBrowserRecognition() {
+    if (typeof window === "undefined")
+        return false;
+    if (isWindowsElectrobunRenderer()) {
+        return false;
+    }
+    return true;
+}
+function shouldUseLocalInferenceAsr(config) {
+    return config?.asr?.provider === "local-inference";
+}
+const ACTIVE_VOICE_SESSION_MODES = new Set([
+    "compose",
+    "push-to-talk",
+    "hands-free",
+    "passive",
+]);
+function normalizeActiveVoiceSessionMode(mode) {
+    return typeof mode === "string" &&
+        ACTIVE_VOICE_SESSION_MODES.has(mode)
+        ? mode
+        : null;
+}
+// ── Test-visible internals ───────────────────────────────────────────
+export const __voiceChatInternals = {
+    isWindowsElectrobunRenderer,
+    shouldPreferNativeTalkMode,
+    shouldAutoRestartBrowserRecognition,
+    shouldUseLocalInferenceAsr,
+    resumeAudioContextForPlayback,
+    splitFirstSentence,
+    remainderAfter,
+    queueableSpeechPrefix,
+    resolveEffectiveVoiceConfig,
+    resolveVoiceMode,
+    resolveVoiceProxyEndpoint,
+    toSpeakableText,
+    mergeTranscriptWindows,
+    webSpeechVoiceDebugFields,
+    ASSISTANT_TTS_FINAL_ONLY,
+    ASSISTANT_TTS_FIRST_FLUSH_CHARS,
+    ASSISTANT_TTS_MIN_CHUNK_CHARS,
+};
+// ── Hook ──────────────────────────────────────────────────────────────
+export function useVoiceChat(options) {
+    const [isListening, setIsListening] = useState(false);
+    const [captureMode, setCaptureMode] = useState("idle");
+    const [isSpeaking, setIsSpeaking] = useState(false);
+    const [mouthOpen, setMouthOpen] = useState(0);
+    const [interimTranscript, setInterimTranscript] = useState("");
+    const [supported, setSupported] = useState(false);
+    const [usingAudioAnalysis, setUsingAudioAnalysis] = useState(false);
+    const [voiceUnlockedGeneration, setVoiceUnlockedGeneration] = useState(0);
+    // True when a TTS clip was blocked because the AudioContext is still
+    // suspended (browser autoplay policy). Callers surface an "tap to enable
+    // sound" hint. Cleared on the next user-gesture unlock.
+    const [needsAudioUnlock, setNeedsAudioUnlock] = useState(false);
+    // Transient pulse: set when browser SpeechRecognition silently auto-restarts
+    // (the engine ends a segment mid-session and we restart it). Lets callers
+    // flash a brief "reconnected" indicator instead of the restart being silent.
+    const [micReconnected, setMicReconnected] = useState(false);
+    const micReconnectTimerRef = useRef(null);
+    // Refs — stable across renders, read from animation loop & callbacks
+    const recognitionRef = useRef(null);
+    const localAsrRecorderRef = useRef(null);
+    const sttBackendRef = useRef(null);
+    const talkModeHandlesRef = useRef([]);
+    const synthRef = useRef(null);
+    const utteranceRef = useRef(null);
+    const animFrameRef = useRef(0);
+    const speakingStartRef = useRef(0);
+    const speechTimeoutRef = useRef(null);
+    const enabledRef = useRef(false);
+    const listeningModeRef = useRef("idle");
+    const transcriptBufferRef = useRef("");
+    const latestTranscriptTurnRef = useRef(null);
+    const emitTranscript = useEffectEvent((text, event) => {
+        options.onTranscript(text, event);
+    });
+    const emitTranscriptPreview = useEffectEvent((text, event) => {
+        options.onTranscriptPreview?.(text, event);
+    });
+    const emitPlaybackStart = useEffectEvent((event) => {
+        options.onPlaybackStart?.(event);
+        // Headless-test observability: a real TTS playback actually started. The
+        // voice self-test + real-audio e2e poll this to prove audio flowed (the
+        // only honest "reply was spoken" signal in a headless browser).
+        if (typeof window !== "undefined") {
+            window.__voicePlaybackStarted = true;
+        }
+    });
+    const effectiveVoiceConfig = useMemo(() => resolveEffectiveVoiceConfig(options.voiceConfig, {
+        cloudConnected: options.cloudConnected,
+    }), [options.cloudConnected, options.voiceConfig]);
+    const assistantTtsQuality = useMemo(() => {
+        return effectiveVoiceConfig?.provider === "elevenlabs"
+            ? "enhanced"
+            : "standard";
+    }, [effectiveVoiceConfig?.provider]);
+    const ttsDebugConfigKeyRef = useRef("");
+    useEffect(() => {
+        const key = JSON.stringify({
+            c: options.cloudConnected,
+            p: effectiveVoiceConfig?.provider,
+            m: effectiveVoiceConfig?.mode,
+            v: effectiveVoiceConfig?.elevenlabs?.voiceId,
+            q: assistantTtsQuality,
+        });
+        if (ttsDebugConfigKeyRef.current === key)
+            return;
+        ttsDebugConfigKeyRef.current = key;
+        ttsDebug("useVoiceChat:config", {
+            cloudConnected: options.cloudConnected,
+            provider: effectiveVoiceConfig?.provider,
+            mode: effectiveVoiceConfig?.mode,
+            voiceId: effectiveVoiceConfig?.elevenlabs?.voiceId,
+            assistantTtsQuality,
+            ttsCloudUrl: resolveApiUrl("/api/tts/cloud"),
+        });
+    }, [
+        assistantTtsQuality,
+        effectiveVoiceConfig?.elevenlabs?.voiceId,
+        effectiveVoiceConfig?.mode,
+        effectiveVoiceConfig?.provider,
+        options.cloudConnected,
+    ]);
+    // Voice config ref (latest value always available to callbacks)
+    const voiceConfigRef = useRef(effectiveVoiceConfig);
+    voiceConfigRef.current = effectiveVoiceConfig;
+    const interruptOnSpeechRef = useRef(options.interruptOnSpeech ?? true);
+    interruptOnSpeechRef.current = options.interruptOnSpeech ?? true;
+    const interruptSpeechRef = useRef(() => { });
+    // ── ElevenLabs Web Audio refs ──────────────────────────────────────
+    const analyserRef = useRef(null);
+    const audioSourceRef = useRef(null);
+    const timeDomainDataRef = useRef(null);
+    const usingAudioAnalysisRef = useRef(false);
+    const mouthOpenRef = useRef(0);
+    mouthOpenRef.current = mouthOpen;
+    // ── Progressive speech queue state ────────────────────────────────
+    const queueRef = useRef([]);
+    const queueWorkerRunningRef = useRef(false);
+    const generationRef = useRef(0);
+    const activeTaskFinishRef = useRef(null);
+    const activeFetchAbortRef = useRef(null);
+    const assistantSpeechRef = useRef(null);
+    const assistantTtsDebounceRef = useRef(null);
+    const clearSpeechTimers = useCallback(() => {
+        if (speechTimeoutRef.current) {
+            clearTimeout(speechTimeoutRef.current);
+            speechTimeoutRef.current = null;
+        }
+    }, []);
+    // Playback was rejected because the AudioContext is still suspended (autoplay
+    // policy). Raise the unlock hint so a caller can prompt for a user gesture.
+    const markAudioBlocked = useCallback(() => {
+        setNeedsAudioUnlock(true);
+    }, []);
+    // A clip played (or the context was already running). Any prior unlock hint is
+    // stale, so clear it.
+    const markAudioPlaying = useCallback(() => {
+        setNeedsAudioUnlock(false);
+    }, []);
+    // Explicitly unlock audio playback in response to a user gesture (e.g. the
+    // status-bar "enable sound" button). Warms/resumes the shared AudioContext,
+    // bumps the unlock generation so a blocked greeting retries, and clears the
+    // hint. The passive first-gesture listener covers the common case; this covers
+    // a context that re-suspended after the initial unlock (tab switch, etc.).
+    const unlockAudio = useCallback(() => {
+        if (typeof window === "undefined")
+            return;
+        if (!sharedAudioCtx) {
+            sharedAudioCtx = new AudioContext({ latencyHint: "interactive" });
+        }
+        void sharedAudioCtx.resume().catch(() => { });
+        setVoiceUnlockedGeneration((g) => g + 1);
+        setNeedsAudioUnlock(false);
+    }, []);
+    const rememberCachedSegment = useCallback((key, bytes) => {
+        globalAudioCache.delete(key);
+        globalAudioCache.set(key, bytes);
+        if (globalAudioCache.size <= MAX_CACHED_SEGMENTS)
+            return;
+        const oldest = globalAudioCache.keys().next().value;
+        if (oldest)
+            globalAudioCache.delete(oldest);
+    }, []);
+    const makeElevenCacheKey = useCallback((text, config) => {
+        const voiceId = config.voiceId ?? DEFAULT_ELEVEN_VOICE;
+        const modelId = config.modelId ?? DEFAULT_ELEVEN_MODEL;
+        const stability = typeof config.stability === "number"
+            ? config.stability.toFixed(2)
+            : "0.50";
+        const similarity = typeof config.similarityBoost === "number"
+            ? config.similarityBoost.toFixed(2)
+            : "0.75";
+        const speed = typeof config.speed === "number" ? config.speed.toFixed(2) : "1.00";
+        return [
+            "elevenlabs",
+            voiceId,
+            modelId,
+            stability,
+            similarity,
+            speed,
+            normalizeCacheText(text),
+        ].join("|");
+    }, []);
+    const makeLocalInferenceCacheKey = useCallback((text) => ["local-inference", normalizeCacheText(text)].join("|"), []);
+    const updateMouthOpen = useCallback((value) => {
+        const previousValue = mouthOpenRef.current;
+        const resolvedValue = typeof value === "function" ? value(previousValue) : value;
+        const nextValue = normalizeMouthOpen(resolvedValue);
+        if (nextValue === previousValue) {
+            return;
+        }
+        mouthOpenRef.current = nextValue;
+        setMouthOpen(nextValue);
+    }, []);
+    // ── Init ──────────────────────────────────────────────────────────
+    useEffect(() => {
+        let cancelled = false;
+        const syncVoiceSupport = async () => {
+            const browserSpeechSupported = !!getSpeechRecognitionCtor();
+            const localAsrSupported = shouldUseLocalInferenceAsr(voiceConfigRef.current) &&
+                isLocalAsrCaptureSupported();
+            if (localAsrSupported) {
+                if (!cancelled) {
+                    setSupported(true);
+                }
+                return;
+            }
+            if (!shouldPreferNativeTalkMode()) {
+                if (!cancelled) {
+                    setSupported(browserSpeechSupported);
+                }
+                return;
+            }
+            try {
+                const permissions = await getTalkModePlugin().checkPermissions();
+                if (cancelled) {
+                    return;
+                }
+                setSupported(permissions.speechRecognition !== "not_supported" ||
+                    browserSpeechSupported);
+            }
+            catch {
+                if (!cancelled) {
+                    setSupported(browserSpeechSupported);
+                }
+            }
+        };
+        void syncVoiceSupport();
+        synthRef.current = window.speechSynthesis ?? null;
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    // ── Mouth animation loop ──────────────────────────────────────────
+    useEffect(() => {
+        let frameId = 0;
+        const animate = () => {
+            if (!isSpeaking) {
+                const nextMouth = nextIdleMouthOpen(mouthOpenRef.current);
+                updateMouthOpen(nextMouth);
+                if (nextMouth > 0) {
+                    frameId = requestAnimationFrame(animate);
+                    animFrameRef.current = frameId;
+                }
+                else {
+                    animFrameRef.current = 0;
+                }
+                return;
+            }
+            // ── ElevenLabs: real audio volume analysis ────────────────────
+            if (usingAudioAnalysisRef.current) {
+                const analyser = analyserRef.current;
+                const data = timeDomainDataRef.current;
+                if (analyser && data) {
+                    analyser.getFloatTimeDomainData(data);
+                    let sum = 0;
+                    for (let i = 0; i < data.length; i++) {
+                        const v = data[i] ?? 0;
+                        sum += v * v;
+                    }
+                    const rms = Math.sqrt(sum / data.length);
+                    const volume = Math.max(0, Math.min(1, 1 / (1 + Math.exp(-(rms * 30 - 2)))));
+                    updateMouthOpen(volume);
+                }
+                frameId = requestAnimationFrame(animate);
+                animFrameRef.current = frameId;
+                return;
+            }
+            // ── Browser TTS: sine-wave mouth + safety check ──────────────
+            const sinceStart = Date.now() - speakingStartRef.current;
+            if (sinceStart > 500 &&
+                synthRef.current &&
+                !synthRef.current.speaking &&
+                !synthRef.current.pending) {
+                utteranceRef.current = null;
+                setIsSpeaking(false);
+                return;
+            }
+            const elapsed = sinceStart / 1000;
+            const base = Math.sin(elapsed * 12) * 0.3 + 0.4;
+            const detail = Math.sin(elapsed * 18.7) * 0.15;
+            const slow = Math.sin(elapsed * 4.2) * 0.1;
+            updateMouthOpen(Math.max(0, Math.min(1, base + detail + slow)));
+            frameId = requestAnimationFrame(animate);
+            animFrameRef.current = frameId;
+        };
+        if (isSpeaking || mouthOpenRef.current > 0) {
+            frameId = requestAnimationFrame(animate);
+            animFrameRef.current = frameId;
+        }
+        else {
+            animFrameRef.current = 0;
+        }
+        return () => {
+            cancelAnimationFrame(frameId);
+            if (animFrameRef.current === frameId) {
+                animFrameRef.current = 0;
+            }
+        };
+    }, [isSpeaking, updateMouthOpen]);
+    // ── STT (Speech Recognition) ──────────────────────────────────────
+    const applyTranscriptUpdate = useCallback((transcript, isFinal, metadata = {}) => {
+        const mode = metadata.mode ?? listeningModeRef.current;
+        if (mode === "idle")
+            return;
+        const normalized = collapseWhitespace(transcript);
+        if (!normalized)
+            return;
+        const nextText = mergeTranscriptWindows(transcriptBufferRef.current, normalized);
+        if (nextText === transcriptBufferRef.current)
+            return;
+        transcriptBufferRef.current = nextText;
+        setInterimTranscript(nextText);
+        const turn = {
+            ...metadata.turn,
+            text: nextText,
+            mode,
+            isFinal,
+            speaker: metadata.speaker ?? metadata.turn?.speaker,
+            source: metadata.source ??
+                metadata.turn?.source ??
+                sttBackendRef.current ??
+                undefined,
+            confidence: metadata.confidence ?? metadata.turn?.confidence,
+            metadata: metadata.metadata ?? metadata.turn?.metadata,
+        };
+        latestTranscriptTurnRef.current = turn;
+        emitTranscriptPreview(nextText, {
+            text: nextText,
+            mode,
+            isFinal,
+            turn,
+            speaker: turn.speaker,
+        });
+        if (interruptOnSpeechRef.current) {
+            interruptSpeechRef.current();
+        }
+        if (isFinal && mode === "passive") {
+            emitTranscript(nextText, {
+                text: nextText,
+                mode,
+                isFinal: true,
+                turn,
+                speaker: turn.speaker,
+            });
+            transcriptBufferRef.current = "";
+            latestTranscriptTurnRef.current = null;
+            setInterimTranscript("");
+        }
+    }, []);
+    const removeTalkModeListeners = useCallback(async () => {
+        const handles = talkModeHandlesRef.current;
+        talkModeHandlesRef.current = [];
+        await Promise.all(handles.map((handle) => handle.remove().catch(() => {
+            /* ignore */
+        })));
+    }, []);
+    const resetListeningState = useCallback(() => {
+        transcriptBufferRef.current = "";
+        latestTranscriptTurnRef.current = null;
+        recognitionRef.current = null;
+        localAsrRecorderRef.current = null;
+        sttBackendRef.current = null;
+        enabledRef.current = false;
+        listeningModeRef.current = "idle";
+        setIsListening(false);
+        setCaptureMode("idle");
+        setInterimTranscript("");
+    }, []);
+    const ensureTalkModeListeners = useCallback(async () => {
+        if (talkModeHandlesRef.current.length > 0)
+            return;
+        const talkMode = getTalkModePlugin();
+        const transcriptHandle = await talkMode.addListener("transcript", (event) => {
+            const typedEvent = event;
+            applyTranscriptUpdate(event.transcript ?? "", event.isFinal === true, {
+                mode: normalizeActiveVoiceSessionMode(typedEvent.mode) ?? undefined,
+                speaker: typedEvent.speaker,
+                source: typedEvent.source,
+                confidence: typedEvent.confidence,
+                turn: typedEvent.turn,
+                metadata: typedEvent.metadata,
+            });
+        });
+        const errorHandle = await talkMode.addListener("error", (event) => {
+            if (sttBackendRef.current === "talkmode" ||
+                event.code === "not-allowed" ||
+                event.code === "service-not-allowed") {
+                resetListeningState();
+                if (event.code === "not-allowed" ||
+                    event.code === "service-not-allowed") {
+                    setSupported(false);
+                }
+            }
+        });
+        const stateHandle = await talkMode.addListener("stateChange", (event) => {
+            if ((event.state === "error" || event.state === "idle") &&
+                sttBackendRef.current === "talkmode") {
+                resetListeningState();
+            }
+        });
+        talkModeHandlesRef.current = [transcriptHandle, errorHandle, stateHandle];
+    }, [applyTranscriptUpdate, resetListeningState]);
+    const transcribeLocalInferenceAudio = useCallback(async (audio, signal) => {
+        const { text } = await transcribeLocalInferenceWav(audio, { signal });
+        return text;
+    }, []);
+    const startLocalInferenceRecognition = useCallback(async (mode) => {
+        if (!shouldUseLocalInferenceAsr(voiceConfigRef.current)) {
+            return false;
+        }
+        if (!isLocalAsrCaptureSupported()) {
+            return false;
+        }
+        // Defer to the next backend (talk-mode / browser) when the server can't
+        // transcribe right now — capturing here would only 502 at stop() with no
+        // recoverable fallback (no whisper model / native adapter installed).
+        if (!(await isLocalInferenceAsrReady())) {
+            return false;
+        }
+        try {
+            const recorder = await startLocalAsrRecorder();
+            localAsrRecorderRef.current = recorder;
+            sttBackendRef.current = "local-inference";
+            enabledRef.current = true;
+            listeningModeRef.current = mode;
+            setSupported(true);
+            setCaptureMode(mode);
+            setIsListening(true);
+            return true;
+        }
+        catch {
+            localAsrRecorderRef.current = null;
+            return false;
+        }
+    }, []);
+    const startBrowserRecognition = useCallback((mode) => {
+        const SpeechRecognitionAPI = getSpeechRecognitionCtor();
+        if (!SpeechRecognitionAPI)
+            return false;
+        const recognition = new SpeechRecognitionAPI();
+        recognition.continuous = true;
+        recognition.interimResults = true;
+        recognition.lang = options.lang ?? "en-US";
+        recognition.onresult = (event) => {
+            let transcript = "";
+            let isFinal = false;
+            for (let index = 0; index < event.results.length; index += 1) {
+                const result = event.results[index];
+                const chunk = result?.[0]?.transcript ?? "";
+                if (chunk) {
+                    transcript = transcript ? `${transcript} ${chunk}` : chunk;
+                }
+                if (result?.isFinal) {
+                    isFinal = true;
+                }
+            }
+            applyTranscriptUpdate(transcript, isFinal);
+        };
+        recognition.onerror = (event) => {
+            if (event.error === "not-allowed" ||
+                event.error === "service-not-allowed") {
+                enabledRef.current = false;
+                listeningModeRef.current = "idle";
+                sttBackendRef.current = null;
+                setCaptureMode("idle");
+                setIsListening(false);
+            }
+        };
+        recognition.onend = () => {
+            if (shouldAutoRestartBrowserRecognition() &&
+                enabledRef.current &&
+                listeningModeRef.current === mode) {
+                try {
+                    recognition.start();
+                    // Surface the silent restart as a brief pulse so the UI can show a
+                    // "mic reconnected" indicator instead of an unexplained gap.
+                    setMicReconnected(true);
+                    if (micReconnectTimerRef.current !== null) {
+                        clearTimeout(micReconnectTimerRef.current);
+                    }
+                    micReconnectTimerRef.current = setTimeout(() => {
+                        micReconnectTimerRef.current = null;
+                        setMicReconnected(false);
+                    }, MIC_RECONNECT_PULSE_MS);
+                }
+                catch {
+                    /* already started */
+                }
+            }
+        };
+        recognitionRef.current = recognition;
+        try {
+            recognition.start();
+            sttBackendRef.current = "browser";
+            enabledRef.current = true;
+            listeningModeRef.current = mode;
+            setCaptureMode(mode);
+            setIsListening(true);
+            return true;
+        }
+        catch {
+            recognitionRef.current = null;
+            return false;
+        }
+    }, [applyTranscriptUpdate, options.lang]);
+    const startTalkModeRecognition = useCallback(async (mode) => {
+        if (!shouldPreferNativeTalkMode()) {
+            return false;
+        }
+        try {
+            await ensureTalkModeListeners();
+            const talkMode = getTalkModePlugin();
+            const browserSpeechSupported = !!getSpeechRecognitionCtor();
+            let permissions = await talkMode.checkPermissions().catch(() => null);
+            const nativeSpeechSupported = permissions?.speechRecognition !== "not_supported";
+            if (!nativeSpeechSupported && !browserSpeechSupported) {
+                setSupported(false);
+                return false;
+            }
+            if (permissions?.microphone === "prompt" && nativeSpeechSupported) {
+                await talkMode.requestPermissions().catch(() => {
+                    /* ignore */
+                });
+                permissions = await talkMode
+                    .checkPermissions()
+                    .catch(() => permissions);
+            }
+            const directRpc = getElectrobunRendererRpc();
+            const result = await talkMode.start({
+                config: {
+                    stt: {
+                        ...(directRpc ? { engine: "web" } : {}),
+                        language: options.lang ?? "en-US",
+                        modelSize: "base",
+                        sampleRate: 16000,
+                    },
+                    silenceWindowMs: 350,
+                    interruptOnSpeech: true,
+                },
+            });
+            if (!result.started) {
+                if (!browserSpeechSupported) {
+                    setSupported(false);
+                }
+                return false;
+            }
+            setSupported(true);
+            enabledRef.current = true;
+            listeningModeRef.current = mode;
+            sttBackendRef.current = "talkmode";
+            setCaptureMode(mode);
+            setIsListening(true);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, [ensureTalkModeListeners, options.lang]);
+    const finalizeRecognition = useCallback((submit) => {
+        const mode = normalizeActiveVoiceSessionMode(listeningModeRef.current) ?? "compose";
+        const transcript = collapseWhitespace(transcriptBufferRef.current);
+        if (submit && transcript) {
+            const latestTurn = latestTranscriptTurnRef.current;
+            const turn = {
+                ...latestTurn,
+                text: transcript,
+                mode,
+                isFinal: true,
+                endedAtMs: latestTurn?.endedAtMs ?? Date.now(),
+            };
+            emitTranscript(transcript, {
+                text: transcript,
+                mode,
+                isFinal: true,
+                turn,
+                speaker: turn.speaker,
+            });
+        }
+        resetListeningState();
+    }, [resetListeningState]);
+    const startListening = useCallback(async (mode = "compose") => {
+        if (enabledRef.current)
+            return;
+        transcriptBufferRef.current = "";
+        setInterimTranscript("");
+        if (interruptOnSpeechRef.current) {
+            interruptSpeechRef.current();
+        }
+        const localStarted = await startLocalInferenceRecognition(mode);
+        if (localStarted) {
+            return;
+        }
+        if (shouldPreferNativeTalkMode()) {
+            const started = await startTalkModeRecognition(mode);
+            if (started) {
+                return;
+            }
+        }
+        startBrowserRecognition(mode);
+    }, [
+        startBrowserRecognition,
+        startLocalInferenceRecognition,
+        startTalkModeRecognition,
+    ]);
+    const stopListening = useCallback(async (options) => {
+        const mode = listeningModeRef.current;
+        if (mode === "idle")
+            return;
+        const submit = options?.submit === true;
+        enabledRef.current = false;
+        if (sttBackendRef.current === "talkmode") {
+            await getTalkModePlugin()
+                .stop()
+                .catch(() => {
+                /* ignore */
+            });
+            await new Promise((resolve) => window.setTimeout(resolve, TALKMODE_STOP_SETTLE_MS));
+        }
+        else if (sttBackendRef.current === "local-inference") {
+            const recorder = localAsrRecorderRef.current;
+            localAsrRecorderRef.current = null;
+            if (recorder) {
+                try {
+                    const audio = await recorder.stop();
+                    const transcript = await transcribeLocalInferenceAudio(audio);
+                    applyTranscriptUpdate(transcript, true, {
+                        mode: normalizeActiveVoiceSessionMode(mode) ??
+                            normalizeActiveVoiceSessionMode(listeningModeRef.current) ??
+                            "compose",
+                        source: "local-inference",
+                        metadata: { source: "local-inference" },
+                    });
+                }
+                catch (error) {
+                    ttsDebug("asr:local-inference:error", {
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        else {
+            recognitionRef.current?.stop();
+            await new Promise((resolve) => window.setTimeout(resolve, TALKMODE_STOP_SETTLE_MS));
+        }
+        finalizeRecognition(submit);
+    }, [applyTranscriptUpdate, finalizeRecognition, transcribeLocalInferenceAudio]);
+    const toggleListening = useCallback(() => {
+        if (enabledRef.current && listeningModeRef.current === "compose") {
+            void stopListening();
+            return;
+        }
+        if (enabledRef.current)
+            return;
+        void startListening("compose");
+    }, [startListening, stopListening]);
+    // ── Cancel helpers ────────────────────────────────────────────────
+    /** Stop all in-progress speech playback/requests but keep assistant queue state. */
+    const cancelPlayback = useCallback(() => {
+        generationRef.current += 1;
+        queueRef.current = [];
+        activeFetchAbortRef.current?.abort();
+        activeFetchAbortRef.current = null;
+        activeTaskFinishRef.current?.();
+        activeTaskFinishRef.current = null;
+        // Browser TTS
+        synthRef.current?.cancel();
+        utteranceRef.current = null;
+        // ElevenLabs audio
+        if (audioSourceRef.current) {
+            try {
+                audioSourceRef.current.stop();
+            }
+            catch {
+                /* ok */
+            }
+            try {
+                audioSourceRef.current.disconnect();
+            }
+            catch {
+                /* ok */
+            }
+            audioSourceRef.current = null;
+        }
+        // Native TalkMode TTS — interrupt any in-flight native speak so barge-in
+        // actually silences the agent. Without this the awaited TalkMode.speak()
+        // plays to completion and the agent talks over the user.
+        if (Capacitor.isNativePlatform()) {
+            void getTalkModePlugin()
+                .stopSpeaking?.()
+                .catch(() => { });
+        }
+        clearSpeechTimers();
+        usingAudioAnalysisRef.current = false;
+        setUsingAudioAnalysis(false);
+    }, [clearSpeechTimers]);
+    const stopSpeaking = useCallback(() => {
+        if (assistantTtsDebounceRef.current != null) {
+            clearTimeout(assistantTtsDebounceRef.current);
+            assistantTtsDebounceRef.current = null;
+        }
+        assistantSpeechRef.current = null;
+        cancelPlayback();
+        setIsSpeaking(false);
+        setUsingAudioAnalysis(false);
+    }, [cancelPlayback]);
+    interruptSpeechRef.current = stopSpeaking;
+    // ── ElevenLabs TTS ────────────────────────────────────────────────
+    const speakElevenLabs = useCallback(async (text, elConfig, task, generation) => {
+        let ctx = sharedAudioCtx;
+        if (!ctx) {
+            ctx = new AudioContext({ latencyHint: "interactive" });
+            sharedAudioCtx = ctx;
+        }
+        if (ctx.state === "suspended") {
+            const resumed = await resumeAudioContextForPlayback(ctx);
+            if (!resumed) {
+                ttsDebug("play:audio-context-blocked", {
+                    provider: "elevenlabs",
+                    state: ctx.state,
+                });
+                markAudioBlocked();
+                throw new DOMException("Audio playback is blocked until a user gesture unlocks the audio context", "NotAllowedError");
+            }
+        }
+        markAudioPlaying();
+        const voiceId = elConfig.voiceId ?? DEFAULT_ELEVEN_VOICE;
+        const modelId = elConfig.modelId ?? DEFAULT_ELEVEN_MODEL;
+        const cacheKey = task.cacheKey ??
+            (shouldCacheGeneratedSpeech(text, task.segment)
+                ? makeElevenCacheKey(text, elConfig)
+                : undefined);
+        const cachedBytes = cacheKey ? globalAudioCache.get(cacheKey) : undefined;
+        let audioBytes = null;
+        let cached = false;
+        if (cacheKey && cachedBytes) {
+            rememberCachedSegment(cacheKey, cachedBytes);
+            audioBytes = cachedBytes.slice();
+            cached = true;
+        }
+        if (!audioBytes) {
+            const controller = new AbortController();
+            activeFetchAbortRef.current = controller;
+            const requestBody = {
+                text,
+                model_id: modelId,
+                apply_text_normalization: "auto",
+                voice_settings: {
+                    stability: elConfig.stability ?? 0.5,
+                    similarity_boost: elConfig.similarityBoost ?? 0.75,
+                    speed: elConfig.speed ?? 1.0,
+                },
+            };
+            const apiToken = getElizaApiToken()?.trim() ?? "";
+            const proxyRequestBody = JSON.stringify({
+                ...requestBody,
+                voiceId,
+                modelId,
+                outputFormat: "mp3_44100_128",
+            });
+            /**
+             * Server-side TTS when the browser has no `xi-api-key`.
+             * Always try Eliza Cloud (`/api/tts/cloud`) first — that is where a
+             * persisted Eliza Cloud API key is used. `voiceMode` may still be
+             * `own-key` when the UI has not yet marked cloud as connected (e.g.
+             * disconnect preference, status poll race), which previously routed
+             * here to `/api/tts/elevenlabs` only; The framework does not implement that
+             * path, so chat fell back to browser (Edge) TTS. If cloud rejects
+             * (no key), fall back to the upstream ElevenLabs proxy.
+             */
+            const makeProxyRequestInit = () => {
+                const dbg = task.debugUtteranceContext;
+                return {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Accept: "audio/mpeg",
+                        ...(apiToken ? { Authorization: `Bearer ${apiToken}` } : {}),
+                        ...(isTtsDebugEnabled() && dbg
+                            ? {
+                                "x-elizaos-tts-message-id": encodeURIComponent(dbg.messageId),
+                                "x-elizaos-tts-clip-segment": encodeURIComponent(task.segment),
+                                "x-elizaos-tts-full-preview": encodeURIComponent(dbg.fullAssistTextPreview),
+                            }
+                            : {}),
+                    },
+                    body: proxyRequestBody,
+                    signal: controller.signal,
+                };
+            };
+            const shouldFallbackFromCloudProxy = (status) => status === 400 ||
+                status === 401 ||
+                status === 403 ||
+                status === 404 ||
+                status === 405 ||
+                status === 501;
+            const fetchViaBestAvailableProxy = async () => {
+                const cloudTarget = resolveApiUrl("/api/tts/cloud");
+                try {
+                    const cloudRes = await fetchWithCsrf(cloudTarget, makeProxyRequestInit());
+                    if (cloudRes.ok || !shouldFallbackFromCloudProxy(cloudRes.status)) {
+                        return cloudRes;
+                    }
+                    ttsDebug("useVoiceChat:cloud-proxy-fallback", {
+                        status: cloudRes.status,
+                        ttsTarget: describeTtsCloudFetchTargetForDebug(),
+                    });
+                }
+                catch (error) {
+                    ttsDebug("useVoiceChat:cloud-proxy-unavailable", {
+                        ttsTarget: describeTtsCloudFetchTargetForDebug(),
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                return fetchWithCsrf(resolveApiUrl("/api/tts/elevenlabs"), makeProxyRequestInit());
+            };
+            const trimmedApiKey = typeof elConfig.apiKey === "string" ? elConfig.apiKey.trim() : "";
+            const hasDirectKey = hasConfiguredApiKey(trimmedApiKey);
+            let res;
+            if (hasDirectKey) {
+                try {
+                    const url = new URL(`https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voiceId)}/stream`);
+                    url.searchParams.set("output_format", "mp3_44100_128");
+                    res = await fetch(url.toString(), {
+                        method: "POST",
+                        headers: {
+                            "xi-api-key": trimmedApiKey,
+                            "Content-Type": "application/json",
+                            Accept: "audio/mpeg",
+                        },
+                        body: JSON.stringify(requestBody),
+                        signal: controller.signal,
+                    });
+                }
+                catch {
+                    res = await fetchViaBestAvailableProxy();
+                }
+                // If the locally-available key is stale, fall back to server-side key.
+                if (!res.ok && (res.status === 401 || res.status === 403)) {
+                    const proxyRes = await fetchViaBestAvailableProxy();
+                    if (proxyRes.ok) {
+                        res = proxyRes;
+                    }
+                }
+            }
+            else {
+                res = await fetchViaBestAvailableProxy();
+            }
+            if (activeFetchAbortRef.current === controller) {
+                activeFetchAbortRef.current = null;
+            }
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                ttsDebug("useVoiceChat:elevenlabs-http-error", {
+                    status: res.status,
+                    ttsTarget: describeTtsCloudFetchTargetForDebug(),
+                    hadBearer: Boolean(apiToken),
+                    bodyPreview: body.slice(0, 120),
+                });
+                throw new Error(`ElevenLabs ${res.status}: ${body.slice(0, 200)}`);
+            }
+            const audioData = await res.arrayBuffer();
+            audioBytes = new Uint8Array(audioData);
+            if (cacheKey) {
+                rememberCachedSegment(cacheKey, audioBytes.slice());
+            }
+        }
+        if (generation !== generationRef.current)
+            return;
+        const audioBuffer = await ctx.decodeAudioData(toArrayBuffer(audioBytes));
+        if (generation !== generationRef.current)
+            return;
+        const analyser = ctx.createAnalyser();
+        analyser.fftSize = 2048;
+        analyser.smoothingTimeConstant = 0.8;
+        analyserRef.current = analyser;
+        timeDomainDataRef.current = new Float32Array(new ArrayBuffer(analyser.fftSize * Float32Array.BYTES_PER_ELEMENT));
+        const source = ctx.createBufferSource();
+        source.buffer = audioBuffer;
+        source.connect(analyser);
+        analyser.connect(ctx.destination);
+        audioSourceRef.current = source;
+        await new Promise((resolve) => {
+            let finished = false;
+            const playStartMs = performance.now();
+            let wrappedFinish = null;
+            const finish = () => {
+                if (finished)
+                    return;
+                finished = true;
+                if (wrappedFinish && activeTaskFinishRef.current === wrappedFinish) {
+                    activeTaskFinishRef.current = null;
+                }
+                if (audioSourceRef.current === source) {
+                    audioSourceRef.current = null;
+                }
+                source.onended = null;
+                try {
+                    source.disconnect();
+                }
+                catch {
+                    /* ok */
+                }
+                try {
+                    analyser.disconnect();
+                }
+                catch {
+                    /* ok */
+                }
+                clearSpeechTimers();
+                resolve();
+            };
+            wrappedFinish = () => {
+                ttsDebug("play:web-audio:end", {
+                    segment: task.segment,
+                    elapsedMs: Math.round(performance.now() - playStartMs),
+                });
+                finish();
+            };
+            ttsDebug("play:web-audio:start", {
+                segment: task.segment,
+                append: task.append,
+                cached,
+                textChars: text.length,
+                preview: ttsDebugTextPreview(text),
+                durationSecApprox: Math.round(audioBuffer.duration * 100) / 100,
+            });
+            activeTaskFinishRef.current = wrappedFinish;
+            source.onended = wrappedFinish;
+            speechTimeoutRef.current = setTimeout(wrappedFinish, Math.max(2500, Math.ceil(audioBuffer.duration * 1000) + 1200));
+            source.start(0);
+            emitPlaybackStart({
+                text,
+                segment: task.segment,
+                provider: "elevenlabs",
+                cached,
+                startedAtMs: playStartMs,
+                ...task.telemetry,
+            });
+        });
+    }, [
+        clearSpeechTimers,
+        makeElevenCacheKey,
+        markAudioBlocked,
+        markAudioPlaying,
+        rememberCachedSegment,
+    ]);
+    // ── Local inference TTS ───────────────────────────────────────────────
+    const speakLocalInference = useCallback(async (text, task, generation) => {
+        let ctx = sharedAudioCtx;
+        if (!ctx) {
+            ctx = new AudioContext({ latencyHint: "interactive" });
+            sharedAudioCtx = ctx;
+        }
+        if (ctx.state === "suspended") {
+            const resumed = await resumeAudioContextForPlayback(ctx);
+            if (!resumed) {
+                ttsDebug("play:audio-context-blocked", {
+                    provider: "local-inference",
+                    state: ctx.state,
+                });
+                markAudioBlocked();
+                throw new DOMException("Audio playback is blocked until a user gesture unlocks the audio context", "NotAllowedError");
+            }
+        }
+        markAudioPlaying();
+        const cacheKey = task.cacheKey ??
+            (shouldCacheGeneratedSpeech(text, task.segment)
+                ? makeLocalInferenceCacheKey(text)
+                : undefined);
+        const cachedBytes = cacheKey ? globalAudioCache.get(cacheKey) : undefined;
+        let audioBytes = null;
+        let cached = false;
+        if (cacheKey && cachedBytes) {
+            rememberCachedSegment(cacheKey, cachedBytes);
+            audioBytes = cachedBytes.slice();
+            cached = true;
+        }
+        if (!audioBytes) {
+            const controller = new AbortController();
+            activeFetchAbortRef.current = controller;
+            const timeoutId = setTimeout(() => {
+                controller.abort(new DOMException("Local inference TTS timed out", "TimeoutError"));
+            }, LOCAL_INFERENCE_TTS_TIMEOUT_MS);
+            let res;
+            try {
+                res = await fetchWithCsrf(resolveApiUrl("/api/tts/local-inference"), {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Accept: "audio/wav, audio/*;q=0.9",
+                    },
+                    body: JSON.stringify({ text }),
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timeoutId);
+                if (activeFetchAbortRef.current === controller) {
+                    activeFetchAbortRef.current = null;
+                }
+            }
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`Local inference TTS ${res.status}: ${body.slice(0, 200)}`);
+            }
+            audioBytes = new Uint8Array(await res.arrayBuffer());
+            if (cacheKey) {
+                rememberCachedSegment(cacheKey, audioBytes.slice());
+            }
+        }
+        if (generation !== generationRef.current)
+            return;
+        const audioBuffer = await ctx.decodeAudioData(toArrayBuffer(audioBytes));
+        if (generation !== generationRef.current)
+            return;
+        const analyser = ctx.createAnalyser();
+        analyser.fftSize = 2048;
+        analyser.smoothingTimeConstant = 0.8;
+        analyserRef.current = analyser;
+        timeDomainDataRef.current = new Float32Array(new ArrayBuffer(analyser.fftSize * Float32Array.BYTES_PER_ELEMENT));
+        const source = ctx.createBufferSource();
+        source.buffer = audioBuffer;
+        source.connect(analyser);
+        analyser.connect(ctx.destination);
+        audioSourceRef.current = source;
+        await new Promise((resolve) => {
+            let finished = false;
+            const playStartMs = performance.now();
+            let wrappedFinish = null;
+            const finish = () => {
+                if (finished)
+                    return;
+                finished = true;
+                if (wrappedFinish && activeTaskFinishRef.current === wrappedFinish) {
+                    activeTaskFinishRef.current = null;
+                }
+                if (audioSourceRef.current === source) {
+                    audioSourceRef.current = null;
+                }
+                source.onended = null;
+                try {
+                    source.disconnect();
+                }
+                catch {
+                    /* ok */
+                }
+                try {
+                    analyser.disconnect();
+                }
+                catch {
+                    /* ok */
+                }
+                clearSpeechTimers();
+                resolve();
+            };
+            wrappedFinish = finish;
+            activeTaskFinishRef.current = wrappedFinish;
+            source.onended = wrappedFinish;
+            speechTimeoutRef.current = setTimeout(wrappedFinish, Math.max(2500, Math.ceil(audioBuffer.duration * 1000) + 1200));
+            source.start(0);
+            emitPlaybackStart({
+                text,
+                segment: task.segment,
+                provider: "local-inference",
+                cached,
+                startedAtMs: playStartMs,
+                ...task.telemetry,
+            });
+        });
+    }, [
+        clearSpeechTimers,
+        makeLocalInferenceCacheKey,
+        markAudioBlocked,
+        markAudioPlaying,
+        rememberCachedSegment,
+    ]);
+    // ── Browser SpeechSynthesis TTS ───────────────────────────────────
+    const speakBrowser = useCallback((text, task, generation) => {
+        const config = voiceConfigRef.current;
+        const synth = synthRef.current;
+        const requestedLocale = normalizeSpeechLocale(options.lang);
+        const words = text.trim().split(/\s+/).length;
+        const estimatedMs = Math.max(1200, (words / 3) * 1000);
+        const useTalkModeTts = !synth && Boolean(getElectrobunRendererRpc());
+        ttsDebug("speakBrowser:enter", {
+            path: synth
+                ? "speechSynthesis"
+                : useTalkModeTts
+                    ? "talkmode-bridge"
+                    : "no-synth",
+            segment: task.segment,
+            append: task.append,
+            textChars: text.trim().length,
+            preview: ttsDebugTextPreview(text),
+            voiceConfigProvider: config?.provider ?? null,
+            ...(config?.provider === "edge" && config.edge?.voice
+                ? { edgeVoiceSetting: config.edge.voice }
+                : {}),
+        });
+        return new Promise((resolve) => {
+            let finished = false;
+            const finish = () => {
+                if (finished)
+                    return;
+                finished = true;
+                if (activeTaskFinishRef.current === finish) {
+                    activeTaskFinishRef.current = null;
+                }
+                clearSpeechTimers();
+                utteranceRef.current = null;
+                resolve();
+            };
+            activeTaskFinishRef.current = finish;
+            if (!synth) {
+                if (!getElectrobunRendererRpc()) {
+                    ttsDebug("play:browser:no-synth", {
+                        segment: task.segment,
+                        textChars: text.trim().length,
+                        preview: ttsDebugTextPreview(text),
+                        engine: "none",
+                        note: "No SpeechSynthesis or Talk Mode bridge; no playback emitted",
+                    });
+                    finish();
+                    return;
+                }
+                ttsDebug("play:talkmode:dispatch", {
+                    segment: task.segment,
+                    append: task.append,
+                    textChars: text.trim().length,
+                    preview: ttsDebugTextPreview(text),
+                    engine: "native-talkmode-bridge",
+                    note: "No window.speechSynthesis — routing TTS to main-process talkmodeSpeak",
+                });
+                void invokeDesktopBridgeRequest({
+                    rpcMethod: "talkmodeSpeak",
+                    ipcChannel: "talkmode:speak",
+                    params: { text: text.trim() },
+                }).catch((err) => {
+                    ttsDebug("play:talkmode:speak-failed", {
+                        segment: task.segment,
+                        preview: ttsDebugTextPreview(text),
+                        err: err instanceof Error
+                            ? `${err.name}: ${err.message.slice(0, 200)}`
+                            : String(err).slice(0, 200),
+                    });
+                });
+                emitPlaybackStart({
+                    text,
+                    segment: task.segment,
+                    provider: "browser",
+                    cached: false,
+                    startedAtMs: performance.now(),
+                    ...task.telemetry,
+                });
+                speechTimeoutRef.current = setTimeout(finish, estimatedMs);
+                return;
+            }
+            const utterance = new SpeechSynthesisUtterance(text.trim());
+            utterance.lang = requestedLocale;
+            utteranceRef.current = utterance;
+            let selectedVoice;
+            if (synth?.getVoices) {
+                const voices = synth.getVoices();
+                if (config?.provider === "edge" && config.edge?.voice) {
+                    const edgeVoiceName = config.edge.voice;
+                    selectedVoice = voices.find((v) => v.voiceURI === edgeVoiceName || v.name === edgeVoiceName);
+                    if (!selectedVoice) {
+                        const isMale = edgeVoiceName.toLowerCase().includes("guy") ||
+                            edgeVoiceName.toLowerCase().includes("male");
+                        selectedVoice = voices.find((v) => {
+                            if (!matchesVoiceLocale(v, requestedLocale))
+                                return false;
+                            const nameLower = v.name.toLowerCase();
+                            if (isMale) {
+                                return (nameLower.includes("male") ||
+                                    nameLower.includes("alex") ||
+                                    nameLower.includes("david") ||
+                                    nameLower.includes("daniel"));
+                            }
+                            else {
+                                return (nameLower.includes("female") ||
+                                    nameLower.includes("sam") ||
+                                    nameLower.includes("victoria") ||
+                                    nameLower.includes("zira") ||
+                                    nameLower.includes("karen"));
+                            }
+                        });
+                    }
+                }
+                if (!selectedVoice) {
+                    if (localePrefix(requestedLocale) === "en") {
+                        selectedVoice =
+                            voices.find((v) => matchesVoiceLocale(v, requestedLocale) &&
+                                !v.name.toLowerCase().includes("alex") &&
+                                !v.name.toLowerCase().includes("david")) || voices.find((v) => matchesVoiceLocale(v, requestedLocale));
+                    }
+                    else {
+                        selectedVoice = voices.find((v) => matchesVoiceLocale(v, requestedLocale));
+                    }
+                }
+                if (selectedVoice) {
+                    utterance.voice = selectedVoice;
+                    utterance.lang = selectedVoice.lang || requestedLocale;
+                }
+            }
+            utterance.rate = 1.0;
+            utterance.pitch = 1.0;
+            ttsDebug("play:browser:web-speech:enqueued", {
+                segment: task.segment,
+                append: task.append,
+                textChars: text.trim().length,
+                preview: ttsDebugTextPreview(text),
+                requestedLocale,
+                engine: "speechSynthesis",
+                ...webSpeechVoiceDebugFields(selectedVoice),
+            });
+            const browserPlayStartMsRef = { value: 0 };
+            utterance.onstart = () => {
+                if (generation !== generationRef.current)
+                    return;
+                browserPlayStartMsRef.value = performance.now();
+                ttsDebug("play:browser:speechSynthesis:start", {
+                    segment: task.segment,
+                    append: task.append,
+                    textChars: text.trim().length,
+                    preview: ttsDebugTextPreview(text),
+                    requestedLocale,
+                    engine: "speechSynthesis-utterance-onstart",
+                    ...webSpeechVoiceDebugFields(selectedVoice),
+                });
+                emitPlaybackStart({
+                    text,
+                    segment: task.segment,
+                    provider: "browser",
+                    cached: false,
+                    startedAtMs: browserPlayStartMsRef.value,
+                    ...task.telemetry,
+                });
+            };
+            const endBrowserUtterance = () => {
+                if (browserPlayStartMsRef.value > 0) {
+                    ttsDebug("play:browser:speechSynthesis:end", {
+                        segment: task.segment,
+                        elapsedMs: Math.round(performance.now() - browserPlayStartMsRef.value),
+                    });
+                }
+                finish();
+            };
+            utterance.onend = endBrowserUtterance;
+            utterance.onerror = (ev) => {
+                const errEv = ev;
+                ttsDebug("play:browser:speechSynthesis:error", {
+                    segment: task.segment,
+                    synthesisError: errEv.error ?? "unknown",
+                    preview: ttsDebugTextPreview(text),
+                    requestedLocale,
+                    ...webSpeechVoiceDebugFields(selectedVoice),
+                });
+                endBrowserUtterance();
+            };
+            synth.speak(utterance);
+            speechTimeoutRef.current = setTimeout(finish, estimatedMs + 5000);
+        });
+    }, [clearSpeechTimers, options.lang]);
+    const processQueue = useCallback(() => {
+        if (queueWorkerRunningRef.current)
+            return;
+        queueWorkerRunningRef.current = true;
+        const workerGeneration = generationRef.current;
+        void (async () => {
+            let workerError = null;
+            try {
+                while (queueRef.current.length > 0) {
+                    if (workerGeneration !== generationRef.current)
+                        break;
+                    const task = queueRef.current.shift();
+                    if (!task)
+                        break;
+                    const config = voiceConfigRef.current;
+                    const elConfig = config?.elevenlabs;
+                    const useElevenLabs = config?.provider === "elevenlabs";
+                    const useLocalInference = config?.provider === "local-inference";
+                    ttsDebug("processQueue:task", {
+                        useElevenLabs,
+                        useLocalInference,
+                        hasElConfig: Boolean(elConfig),
+                        segment: task.segment,
+                        append: task.append,
+                        textChars: task.text.length,
+                        preview: ttsDebugTextPreview(task.text),
+                        ...(task.debugUtteranceContext
+                            ? {
+                                messageId: task.debugUtteranceContext.messageId,
+                                hearingFull: task.debugUtteranceContext.fullAssistTextPreview,
+                            }
+                            : {}),
+                    });
+                    // Native mobile (Android/iOS Capacitor): route the reply through the
+                    // native TalkMode engine (Kotlin AudioTrack / on-device local-inference
+                    // TTS) per the Android TTS-owner decision, instead of the WebView
+                    // AudioContext path. Falls through to the web TTS path on a native error.
+                    if (Capacitor.isNativePlatform()) {
+                        const trimmed = task.text.trim();
+                        if (!trimmed)
+                            continue;
+                        usingAudioAnalysisRef.current = false;
+                        setUsingAudioAnalysis(false);
+                        emitPlaybackStart({
+                            text: task.text,
+                            segment: task.segment,
+                            provider: "browser",
+                            cached: false,
+                            startedAtMs: performance.now(),
+                            ...task.telemetry,
+                        });
+                        try {
+                            const result = await getTalkModePlugin().speak({
+                                text: trimmed,
+                                useLocalInferenceTts: true,
+                            });
+                            if (workerGeneration !== generationRef.current)
+                                break;
+                            if (result?.error)
+                                throw new Error(result.error);
+                            continue;
+                        }
+                        catch (error) {
+                            if (workerGeneration !== generationRef.current ||
+                                isAbortError(error)) {
+                                break;
+                            }
+                            ttsDebug("useVoiceChat:native-talkmode-failed-fallback", {
+                                err: error instanceof Error
+                                    ? `${error.name}: ${error.message.slice(0, 200)}`
+                                    : String(error).slice(0, 200),
+                            });
+                            // Fall through to the web TTS path (elevenlabs/local/browser).
+                        }
+                    }
+                    if (useLocalInference) {
+                        usingAudioAnalysisRef.current = true;
+                        setUsingAudioAnalysis(true);
+                        try {
+                            await speakLocalInference(task.text, task, workerGeneration);
+                            continue;
+                        }
+                        catch (error) {
+                            if (workerGeneration !== generationRef.current ||
+                                isAbortError(error)) {
+                                break;
+                            }
+                            usingAudioAnalysisRef.current = false;
+                            setUsingAudioAnalysis(false);
+                            ttsDebug("useVoiceChat:local-inference-failed", {
+                                err: error instanceof Error
+                                    ? `${error.name}: ${error.message.slice(0, 200)}`
+                                    : String(error).slice(0, 200),
+                            });
+                            // Local TTS failed — fall back to browser SpeechSynthesis so the
+                            // reply stays audible rather than going silent. Only hard-error
+                            // if the fallback ALSO fails.
+                            try {
+                                await speakBrowser(task.text, task, workerGeneration);
+                                continue;
+                            }
+                            catch (fallbackError) {
+                                if (workerGeneration !== generationRef.current ||
+                                    isAbortError(fallbackError)) {
+                                    break;
+                                }
+                                workerError = fallbackError;
+                                queueRef.current = [];
+                                break;
+                            }
+                        }
+                    }
+                    if (useElevenLabs && elConfig) {
+                        usingAudioAnalysisRef.current = true;
+                        setUsingAudioAnalysis(true);
+                        try {
+                            await speakElevenLabs(task.text, elConfig, task, workerGeneration);
+                            continue;
+                        }
+                        catch (error) {
+                            if (workerGeneration !== generationRef.current ||
+                                isAbortError(error)) {
+                                break;
+                            }
+                            ttsDebug("useVoiceChat:elevenlabs-failed", {
+                                err: error instanceof Error
+                                    ? `${error.name}: ${error.message.slice(0, 200)}`
+                                    : String(error).slice(0, 200),
+                                ttsTarget: describeTtsCloudFetchTargetForDebug(),
+                                hadBearer: Boolean(getElizaApiToken()?.trim()),
+                            });
+                            usingAudioAnalysisRef.current = false;
+                            setUsingAudioAnalysis(false);
+                            // Cloud TTS failed (commonly: no ElevenLabs / cloud key on a
+                            // default deploy). Fall back to the browser's built-in
+                            // SpeechSynthesis so the reply is still AUDIBLE instead of going
+                            // silent. Only hard-error if that fallback ALSO fails.
+                            try {
+                                await speakBrowser(task.text, task, workerGeneration);
+                                continue;
+                            }
+                            catch (fallbackError) {
+                                if (workerGeneration !== generationRef.current ||
+                                    isAbortError(fallbackError)) {
+                                    break;
+                                }
+                                workerError = fallbackError;
+                                queueRef.current = [];
+                                break;
+                            }
+                        }
+                    }
+                    else {
+                        usingAudioAnalysisRef.current = false;
+                        setUsingAudioAnalysis(false);
+                        ttsDebug("processQueue:browser-tts-direct", {
+                            reason: elConfig
+                                ? "provider_not_elevenlabs"
+                                : "missing_elevenlabs_config",
+                            provider: config?.provider ?? null,
+                            nextPath: "speakBrowser — OS Web Speech (often msedge/Microsoft) or Electrobun talkmode",
+                        });
+                    }
+                    await speakBrowser(task.text, task, workerGeneration);
+                }
+            }
+            catch (error) {
+                workerError = error;
+                queueRef.current = [];
+                ttsDebug("processQueue:error", {
+                    err: error instanceof Error
+                        ? `${error.name}: ${error.message.slice(0, 200)}`
+                        : String(error).slice(0, 200),
+                });
+            }
+            finally {
+                queueWorkerRunningRef.current = false;
+            }
+            if (workerGeneration !== generationRef.current) {
+                if (queueRef.current.length > 0) {
+                    processQueue();
+                }
+                return;
+            }
+            if (workerError) {
+                usingAudioAnalysisRef.current = false;
+                setUsingAudioAnalysis(false);
+                setIsSpeaking(false);
+                return;
+            }
+            if (queueRef.current.length > 0) {
+                processQueue();
+                return;
+            }
+            usingAudioAnalysisRef.current = false;
+            setUsingAudioAnalysis(false);
+            setIsSpeaking(false);
+        })();
+    }, [speakBrowser, speakElevenLabs, speakLocalInference]);
+    const enqueueSpeech = useCallback((task) => {
+        const speakable = toSpeakableText(task.text);
+        if (!speakable)
+            return;
+        if (!task.append) {
+            cancelPlayback();
+        }
+        queueRef.current.push({
+            ...task,
+            text: speakable,
+            telemetry: task.telemetry
+                ? {
+                    ...task.telemetry,
+                    queuedAtMs: typeof performance !== "undefined"
+                        ? performance.now()
+                        : Date.now(),
+                }
+                : undefined,
+        });
+        ttsDebug("enqueueSpeech", {
+            segment: task.segment,
+            append: task.append,
+            textChars: speakable.length,
+            preview: ttsDebugTextPreview(speakable),
+            queueLen: queueRef.current.length,
+        });
+        speakingStartRef.current = Date.now();
+        setIsSpeaking(true);
+        processQueue();
+    }, [cancelPlayback, processQueue]);
+    // ── Public speak APIs ─────────────────────────────────────────────
+    const speak = useCallback((text, speakOptions) => {
+        if (assistantTtsDebounceRef.current != null) {
+            clearTimeout(assistantTtsDebounceRef.current);
+            assistantTtsDebounceRef.current = null;
+        }
+        assistantSpeechRef.current = null;
+        enqueueSpeech({
+            text,
+            append: Boolean(speakOptions?.append),
+            segment: "full",
+        });
+    }, [enqueueSpeech]);
+    const clearAssistantTtsDebounce = useCallback(() => {
+        if (assistantTtsDebounceRef.current != null) {
+            clearTimeout(assistantTtsDebounceRef.current);
+            assistantTtsDebounceRef.current = null;
+        }
+    }, []);
+    const flushPendingAssistantTts = useCallback(() => {
+        assistantTtsDebounceRef.current = null;
+        const state = assistantSpeechRef.current;
+        if (!state || state.finalQueued)
+            return;
+        const latest = state.latestSpeakable;
+        if (!latest)
+            return;
+        const unsent = remainderAfter(latest, state.queuedSpeakablePrefix);
+        if (!unsent)
+            return;
+        const elConfig = voiceConfigRef.current?.elevenlabs;
+        const isFirstClip = state.queuedSpeakablePrefix.length === 0;
+        const segment = isFirstClip ? "full" : "remainder";
+        const cacheKey = voiceConfigRef.current?.provider === "elevenlabs" &&
+            elConfig &&
+            shouldCacheGeneratedSpeech(unsent, segment)
+            ? makeElevenCacheKey(unsent, elConfig)
+            : undefined;
+        const dbgUtterance = isTtsDebugEnabled()
+            ? {
+                messageId: state.messageId,
+                fullAssistTextPreview: ttsDebugTextPreview(latest, 220),
+            }
+            : undefined;
+        enqueueSpeech({
+            text: unsent,
+            append: !isFirstClip || !state.replacePlaybackOnFirstClip,
+            segment,
+            cacheKey,
+            debugUtteranceContext: dbgUtterance,
+            telemetry: state.telemetry,
+        });
+        state.queuedSpeakablePrefix = latest;
+    }, [enqueueSpeech, makeElevenCacheKey]);
+    const queueAssistantSpeech = useCallback((messageId, text, isFinal, queueOptions) => {
+        if (!messageId)
+            return;
+        const speakable = toSpeakableText(text);
+        if (!speakable) {
+            ttsDebug("queueAssistantSpeech:skip-empty", { messageId });
+            return;
+        }
+        ttsDebug("queueAssistantSpeech", {
+            messageId,
+            isFinal,
+            speakableChars: speakable.length,
+            preview: ttsDebugTextPreview(speakable),
+        });
+        const current = assistantSpeechRef.current;
+        if (!current || current.messageId !== messageId) {
+            clearAssistantTtsDebounce();
+            assistantSpeechRef.current = {
+                messageId,
+                queuedSpeakablePrefix: "",
+                latestSpeakable: "",
+                finalQueued: false,
+                replacePlaybackOnFirstClip: queueOptions?.replace !== false,
+                telemetry: queueOptions?.telemetry,
+            };
+        }
+        else if (queueOptions?.telemetry) {
+            current.telemetry = {
+                ...current.telemetry,
+                ...queueOptions.telemetry,
+            };
+        }
+        const state = assistantSpeechRef.current;
+        if (!state)
+            return;
+        state.latestSpeakable = speakable;
+        if (ASSISTANT_TTS_FINAL_ONLY && !isFinal) {
+            // Band-aid mode: never speak partial stream chunks.
+            return;
+        }
+        if (ASSISTANT_TTS_FINAL_ONLY) {
+            if (state.finalQueued)
+                return;
+            clearAssistantTtsDebounce();
+            const elConfig = voiceConfigRef.current?.elevenlabs;
+            const cacheKey = voiceConfigRef.current?.provider === "elevenlabs" &&
+                elConfig &&
+                shouldCacheGeneratedSpeech(speakable, "full")
+                ? makeElevenCacheKey(speakable, elConfig)
+                : undefined;
+            const dbgUtterance = isTtsDebugEnabled()
+                ? {
+                    messageId,
+                    fullAssistTextPreview: ttsDebugTextPreview(speakable, 220),
+                }
+                : undefined;
+            // Final-only means one utterance per assistant message.
+            enqueueSpeech({
+                text: speakable,
+                append: false,
+                segment: "full",
+                cacheKey,
+                debugUtteranceContext: dbgUtterance,
+                telemetry: state.telemetry,
+            });
+            state.queuedSpeakablePrefix = speakable;
+            state.finalQueued = true;
+            return;
+        }
+        if (speakable === state.queuedSpeakablePrefix &&
+            (!isFinal || state.finalQueued)) {
+            return;
+        }
+        if (speakable === state.queuedSpeakablePrefix && isFinal) {
+            clearAssistantTtsDebounce();
+            state.finalQueued = true;
+            return;
+        }
+        const boundaryPrefix = queueableSpeechPrefix(speakable, isFinal);
+        const boundaryUnsent = boundaryPrefix
+            ? remainderAfter(boundaryPrefix, state.queuedSpeakablePrefix)
+            : "";
+        const rawUnsent = remainderAfter(speakable, state.queuedSpeakablePrefix);
+        if (!rawUnsent) {
+            if (isFinal) {
+                clearAssistantTtsDebounce();
+                state.finalQueued = true;
+            }
+            return;
+        }
+        const isFirstClip = state.queuedSpeakablePrefix.length === 0;
+        const thresholdFlush = isFinal ||
+            (isFirstClip && rawUnsent.length >= ASSISTANT_TTS_FIRST_FLUSH_CHARS) ||
+            (!isFirstClip && rawUnsent.length >= ASSISTANT_TTS_MIN_CHUNK_CHARS);
+        const targetPrefix = boundaryUnsent
+            ? boundaryPrefix
+            : thresholdFlush
+                ? speakable
+                : "";
+        const unsent = targetPrefix
+            ? remainderAfter(targetPrefix, state.queuedSpeakablePrefix)
+            : "";
+        const flushNow = Boolean(unsent);
+        if (flushNow) {
+            clearAssistantTtsDebounce();
+            const elConfig = voiceConfigRef.current?.elevenlabs;
+            const segment = isFirstClip ? "full" : "remainder";
+            const cacheKey = voiceConfigRef.current?.provider === "elevenlabs" &&
+                elConfig &&
+                shouldCacheGeneratedSpeech(unsent, segment)
+                ? makeElevenCacheKey(unsent, elConfig)
+                : undefined;
+            const dbgUtterance = isTtsDebugEnabled()
+                ? {
+                    messageId,
+                    fullAssistTextPreview: ttsDebugTextPreview(speakable, 220),
+                }
+                : undefined;
+            enqueueSpeech({
+                text: unsent,
+                append: !isFirstClip || !state.replacePlaybackOnFirstClip,
+                segment,
+                cacheKey,
+                debugUtteranceContext: dbgUtterance,
+                telemetry: state.telemetry,
+            });
+            state.queuedSpeakablePrefix = targetPrefix;
+            if (isFinal)
+                state.finalQueued = true;
+            return;
+        }
+        clearAssistantTtsDebounce();
+        assistantTtsDebounceRef.current = setTimeout(() => {
+            flushPendingAssistantTts();
+        }, ASSISTANT_TTS_DEBOUNCE_MS);
+    }, [
+        clearAssistantTtsDebounce,
+        enqueueSpeech,
+        flushPendingAssistantTts,
+        makeElevenCacheKey,
+    ]);
+    // ── Unlock audio on first user gesture ─────────────────────────────
+    // Browsers block AudioContext and SpeechSynthesis until a user gesture.
+    // On the first interaction we warm AudioContext (for ElevenLabs) and
+    // bump voiceUnlockedGeneration so the auto-speak effect retries any
+    // greeting that was silently dropped by autoplay policy.
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const handleUserGesture = () => {
+            window.removeEventListener("pointerdown", handleUserGesture, true);
+            window.removeEventListener("keydown", handleUserGesture, true);
+            // Warm/resume the context and clear any stale unlock hint. Shared with the
+            // explicit `unlockAudio` action so both paths behave identically.
+            unlockAudio();
+        };
+        window.addEventListener("pointerdown", handleUserGesture, true);
+        window.addEventListener("keydown", handleUserGesture, true);
+        return () => {
+            window.removeEventListener("pointerdown", handleUserGesture, true);
+            window.removeEventListener("keydown", handleUserGesture, true);
+        };
+    }, [unlockAudio]);
+    // ── Cleanup on unmount ────────────────────────────────────────────
+    useEffect(() => {
+        return () => {
+            void stopListening();
+            void removeTalkModeListeners();
+            stopSpeaking();
+            if (micReconnectTimerRef.current !== null) {
+                clearTimeout(micReconnectTimerRef.current);
+                micReconnectTimerRef.current = null;
+            }
+        };
+    }, [removeTalkModeListeners, stopListening, stopSpeaking]);
+    return {
+        isListening,
+        captureMode,
+        isSpeaking,
+        mouthOpen,
+        interimTranscript,
+        supported,
+        usingAudioAnalysis,
+        toggleListening,
+        startListening,
+        stopListening,
+        speak,
+        queueAssistantSpeech,
+        stopSpeaking,
+        voiceUnlockedGeneration,
+        needsAudioUnlock,
+        micReconnected,
+        unlockAudio,
+        assistantTtsQuality,
+    };
+}