caudate-cli 0.1.0__py3-none-any.whl

voice/tts.py

@@ -0,0 +1,214 @@
+"""Text-to-speech backends.
+
+Pluggable, mirroring `voice/stt.py`. Three implementations ship:
+
+  - **KokoroTTS** (default) — Kokoro-82M, MIT-licensed, sounds genuinely
+    human. ~330MB model, fast on CPU and very fast on GPU. Many
+    expressive voices (af_heart, af_bella, am_adam, bm_george, ...).
+    Pip: `pip install kokoro soundfile`. Released by hexgrad on HF.
+
+  - **PiperTTS** (fallback) — what shipped before. Very lightweight,
+    runs anywhere, but obviously robotic. Kept for low-resource hosts.
+
+  - **XTTSTTS** (optional, voice cloning) — Coqui XTTS-v2. Heavy
+    (~2GB) but can clone any voice from a 6-second sample. Useful if
+    you want Cognos to sound like a specific person.
+
+All backends expose `synthesize(text) -> (samples_int16, sample_rate)`.
+The Speaker class plays them through `sounddevice`.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import os
+import wave
+from pathlib import Path
+from typing import Any, Protocol
+
+# Set BEFORE importing kokoro / transformers. A broken TF install can
+# poison transformers' lazy loader via the image_transforms module.
+os.environ.setdefault("USE_TF", "0")
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+# --- Protocol --------------------------------------------------------
+
+
+class TTS(Protocol):
+    """Synthesize text to int16 PCM samples + sample rate."""
+
+    def synthesize(self, text: str) -> tuple[np.ndarray, int]:
+        ...
+
+
+# --- Kokoro (default) ------------------------------------------------
+
+
+# Friendly catalog. Real list lives in the kokoro voices/ folder; these
+# are the most useful ones documented as of 2026-04.
+KOKORO_VOICES = {
+    "af_heart": "American English · warm, expressive female",
+    "af_bella": "American English · upbeat female",
+    "af_sarah": "American English · clear female",
+    "af_nicole": "American English · soft female",
+    "am_adam":  "American English · neutral male",
+    "am_michael": "American English · warm male",
+    "bf_emma":  "British English · expressive female",
+    "bf_isabella": "British English · soft female",
+    "bm_george": "British English · neutral male",
+    "bm_lewis": "British English · warm male",
+}
+DEFAULT_KOKORO_VOICE = "af_heart"
+
+
+class KokoroTTS:
+    """Kokoro-82M TTS via the `kokoro` pip package.
+
+    Lazy-loads on first synthesize() call. Picks the lang_code from the
+    voice name's first letter (`a` for American, `b` for British, etc.)
+    so callers only pass one identifier.
+    """
+
+    def __init__(self, voice: str = DEFAULT_KOKORO_VOICE):
+        self.voice = voice
+        self._pipeline = None
+        self._sample_rate = 24000
+
+    def _ensure_loaded(self) -> None:
+        if self._pipeline is not None:
+            return
+        try:
+            from kokoro import KPipeline
+        except ImportError as e:
+            raise RuntimeError(
+                "Kokoro TTS requested but `kokoro` is not installed. "
+                "Run: pip install kokoro soundfile"
+            ) from e
+        # First letter of the voice name encodes the language family
+        # (kokoro convention: a=American, b=British, e=European Spanish,
+        # j=Japanese, etc).
+        lang_code = (self.voice[:1] or "a").lower()
+        logger.info(f"Loading Kokoro pipeline (voice={self.voice}, lang={lang_code})")
+        self._pipeline = KPipeline(lang_code=lang_code)
+        logger.info("Kokoro loaded.")
+
+    def synthesize(self, text: str) -> tuple[np.ndarray, int]:
+        self._ensure_loaded()
+        audio_chunks: list[np.ndarray] = []
+        # KPipeline yields (graphemes, phonemes, audio). We only want audio.
+        for _, _, audio in self._pipeline(text, voice=self.voice):
+            if audio is None:
+                continue
+            arr = audio.cpu().numpy() if hasattr(audio, "cpu") else np.asarray(audio)
+            audio_chunks.append(arr.astype(np.float32))
+        if not audio_chunks:
+            return np.zeros(0, dtype=np.int16), self._sample_rate
+        full = np.concatenate(audio_chunks)
+        # Kokoro emits float in [-1, 1]; convert to int16 PCM for sounddevice.
+        full = np.clip(full, -1.0, 1.0)
+        return (full * 32767.0).astype(np.int16), self._sample_rate
+
+
+# --- Piper (fallback, kept for compat) ------------------------------
+
+
+class PiperTTS:
+    """Piper TTS — original backend. Fast, light, robotic."""
+
+    def __init__(self, voice_path: str | Path | None = None):
+        from pathlib import Path as _P
+        default = _P(__file__).parent.parent / "data" / "voices" / "en_US-amy-medium.onnx"
+        self.voice_path = str(voice_path or default)
+        self._voice = None
+
+    def _ensure_loaded(self) -> None:
+        if self._voice is not None:
+            return
+        try:
+            from piper import PiperVoice
+        except ImportError as e:
+            raise RuntimeError(
+                "Piper TTS requested but `piper-tts` is not installed."
+            ) from e
+        logger.info(f"Loading Piper voice from {self.voice_path}")
+        self._voice = PiperVoice.load(self.voice_path)
+        logger.info("Piper voice loaded.")
+
+    def synthesize(self, text: str) -> tuple[np.ndarray, int]:
+        self._ensure_loaded()
+        chunks: list[bytes] = []
+        for chunk in self._voice.synthesize(text):
+            chunks.append(chunk.audio_int16_bytes)
+        if not chunks:
+            return np.zeros(0, dtype=np.int16), self._voice.config.sample_rate
+        raw = b"".join(chunks)
+        audio = np.frombuffer(raw, dtype=np.int16)
+        return audio, self._voice.config.sample_rate
+
+
+# --- XTTS (optional, voice cloning) ---------------------------------
+
+
+class XTTSTTS:
+    """Coqui XTTS-v2 — natural and clones voices from a short sample.
+
+    Heavier than Kokoro (~2GB model, slower first-token latency). Useful
+    when you want Cognos to sound like a specific recorded voice.
+    """
+
+    def __init__(
+        self,
+        speaker_wav: str | Path | None = None,
+        language: str = "en",
+        model_name: str = "tts_models/multilingual/multi-dataset/xtts_v2",
+    ):
+        self.speaker_wav = str(speaker_wav) if speaker_wav else None
+        self.language = language
+        self.model_name = model_name
+        self._tts = None
+        self._sample_rate = 24000
+
+    def _ensure_loaded(self) -> None:
+        if self._tts is not None:
+            return
+        try:
+            from TTS.api import TTS as _TTS
+        except ImportError as e:
+            raise RuntimeError(
+                "XTTS requested but `TTS` is not installed. "
+                "Run: pip install TTS"
+            ) from e
+        logger.info(f"Loading XTTS model {self.model_name}")
+        self._tts = _TTS(self.model_name, progress_bar=False)
+        logger.info("XTTS loaded.")
+
+    def synthesize(self, text: str) -> tuple[np.ndarray, int]:
+        self._ensure_loaded()
+        kwargs: dict[str, Any] = {"text": text, "language": self.language}
+        if self.speaker_wav:
+            kwargs["speaker_wav"] = self.speaker_wav
+        wav = self._tts.tts(**kwargs)
+        arr = np.asarray(wav, dtype=np.float32)
+        arr = np.clip(arr, -1.0, 1.0)
+        return (arr * 32767.0).astype(np.int16), self._sample_rate
+
+
+# --- Factory --------------------------------------------------------
+
+
+def make_tts(name: str = "kokoro", **kwargs: Any) -> TTS:
+    n = name.lower()
+    if n == "kokoro":
+        return KokoroTTS(**kwargs)
+    if n == "piper":
+        return PiperTTS(**kwargs)
+    if n in ("xtts", "coqui"):
+        return XTTSTTS(**kwargs)
+    raise ValueError(
+        f"Unknown TTS backend: {name!r} (try 'kokoro', 'piper', or 'xtts')"
+    )