ui/components/audio_controls.py

"""
ui.components.audio_controls
=============================
Web Speech API TTS playback controls.
Injects JavaScript into the Gradio app to drive the browser's
built-in SpeechSynthesis engine — zero API cost.

Capabilities (Phase 5):
  - Speak answer text token-by-token as it streams in
  - Pause / Resume / Restart controls
  - Voice selector (lists OS/browser voices)
  - Rate and pitch sliders synced from Settings tab

Status: PLACEHOLDER — JavaScript bridge implemented in Phase 5.
"""

from __future__ import annotations


# JavaScript that will be injected via gr.HTML in Phase 5.
# Listed here as a module constant so it's discoverable and testable.
WEB_SPEECH_JS = """
<script>
(function () {
    // VoiceVault Web Speech API bridge
    // Injected by ui/components/audio_controls.py
    window._vv_tts = {
        utterance: null,
        speak: function (text, rate, pitch) {
            if (!window.speechSynthesis) return;
            this.stop();
            this.utterance = new SpeechSynthesisUtterance(text);
            this.utterance.rate  = rate  || 1.0;
            this.utterance.pitch = pitch || 1.0;
            window.speechSynthesis.speak(this.utterance);
        },
        pause:   function () { window.speechSynthesis.pause();  },
        resume:  function () { window.speechSynthesis.resume(); },
        stop:    function () { window.speechSynthesis.cancel(); },
        voices:  function () { return window.speechSynthesis.getVoices(); },
    };
})();
</script>
"""


def get_tts_html() -> str:
    """Return the HTML/JS snippet to inject into the Gradio app."""
    return WEB_SPEECH_JS