TTS Backend Architecture¶

The TTS system follows a plugin architecture with a Protocol-based contract. Each backend is a self-contained module with its own detection, startup, and audio generation logic.

The Protocol¶

Every backend implements the TTSBackend Protocol defined in hooks/tts/_protocol.py:

@runtime_checkable
class TTSBackend(Protocol):
    name: str       # "kokoro", "fish-speech", "chatterbox", "qwen3-tts", "pocket-tts"
    priority: int   # lower = tried first in auto mode

    def is_available(self) -> bool: ...
    def ensure_running(self) -> bool: ...
    def generate(self, text: str, voice: str, speed: float) -> bytes: ...

Conventions:

• voice is always passed in canonical Kokoro form — backends map internally
• speed may be ignored by backends that don't support it
• generate() returns raw WAV bytes
• GPU checks are internal to the backend (not in generic selection logic)

The Registry¶

hooks/tts/__init__.py maintains the backend registry:

def _registry() -> dict[str, type[TTSBackend]]:
    from .chatterbox import ChatterboxBackend
    from .fish_speech import FishSpeechBackend
    from .kokoro import KokoroBackend
    from .pocket_tts import PocketTTSBackend
    from .qwen3_tts import Qwen3TTSBackend

    return {
        "kokoro": KokoroBackend,
        "fish-speech": FishSpeechBackend,
        "pocket-tts": PocketTTSBackend,
        "chatterbox": ChatterboxBackend,
        "qwen3-tts": Qwen3TTSBackend,
    }

select_backend(backend_pref, fallback)¶

1. If backend_pref is a specific backend name, try it
2. If unavailable and fallback=True, fall through to auto
3. In auto mode, sort all backends by priority (ascending) and return the first that ensure_running() returns True
4. Returns None if nothing is reachable

Backend Implementations¶

KokoroBackend (kokoro.py)¶

FishSpeechBackend (fish_speech.py)¶

The is_available() method checks both service reachability and GPU utilization via nvidia-smi.

ChatterboxBackend (chatterbox.py)¶

Chatterbox uses a voice cloning model — it always sends "voice": "default" regardless of the configured voice name.

Qwen3TTSBackend (qwen3_tts.py)¶

Qwen3-TTS uses the default English voice from the model and passes the speed parameter via query string.

PocketTTSBackend (pocket_tts.py)¶

ensure_running() calls _start() which launches the server via uvx and polls /health for up to 60 seconds.

Playback System¶

play_audio(audio_data: bytes)¶

Audio player priority:

1. ffplay — streaming via stdin pipe (preferred, lowest latency)
2. afplay — macOS native player (temp file)
3. aplay — ALSA player on Linux (temp file)
4. paplay — PulseAudio player on Linux (temp file)

PlaybackLock¶

File-based mutex at /tmp/voice-playback.lock using fcntl.flock:

• Prevents overlapping audio from concurrent responses
• 30-second acquire timeout
• Supports context manager (with PlaybackLock(): ...)
• Writes PID for diagnostics

SessionState¶

Sentinel files in /tmp/ for stop-hook integration: