tts-studio 1.0.0__py3-none-any.whl

tts_studio/__init__.py

@@ -0,0 +1,11 @@
+"""TTS Studio - local-first text-to-speech studio.
+
+Pick an engine, pick a voice, type your text and get audio - all running on
+your own machine. Engines: Kokoro-82M, KittenTTS, Pocket TTS and Piper.
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__"]

tts_studio/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m tts_studio`` to work the same as the ``tts-studio`` command."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tts_studio/audio_convert.py

@@ -0,0 +1,186 @@
+"""Audio rendering for the OpenAI-compatible speech endpoint.
+
+Engines return float PCM at their native sample rate. The public API can
+deliver ``wav``, ``flac`` and ``pcm`` directly through soundfile, while
+``mp3``, ``opus`` and ``aac`` are transcoded with ffmpeg when available.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import uuid
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+from . import config
+
+logger = logging.getLogger("tts.openai.audio")
+
+
+class AudioFormatError(RuntimeError):
+    """Raised when a requested response format cannot be produced."""
+
+    def __init__(self, message: str, code: str = "format_unavailable") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+FFMPEG = shutil.which("ffmpeg")
+
+MEDIA_TYPES = {
+    "mp3": "audio/mpeg",
+    "opus": "audio/ogg",
+    "aac": "audio/aac",
+    "flac": "audio/flac",
+    "wav": "audio/wav",
+    "pcm": "audio/pcm",  # raw 16-bit little-endian samples, no header
+}
+
+EXTENSIONS = {
+    "mp3": ".mp3",
+    "opus": ".opus",
+    "aac": ".aac",
+    "flac": ".flac",
+    "wav": ".wav",
+    "pcm": ".pcm",
+}
+
+# ffmpeg output args per container/format.
+FFMPEG_ARGS = {
+    "mp3": ["-c:a", "libmp3lame", "-b:a", "128k", "-f", "mp3"],
+    "opus": ["-c:a", "libopus", "-b:a", "64k", "-f", "ogg"],
+    "aac": ["-c:a", "aac", "-b:a", "128k", "-f", "adts"],
+}
+
+
+def formats_available() -> dict[str, bool]:
+    """Which response formats can currently be produced."""
+    return {
+        "mp3": FFMPEG is not None,
+        "opus": FFMPEG is not None,
+        "aac": FFMPEG is not None,
+        "flac": True,
+        "wav": True,
+        "pcm": True,
+    }
+
+
+def _ensure_workdir() -> Path:
+    config.API_AUDIO_DIR.mkdir(parents=True, exist_ok=True)
+    return config.API_AUDIO_DIR
+
+
+def _write_wav(audio: np.ndarray, sample_rate: int, target: Path) -> None:
+    samples = np.clip(np.asarray(audio, dtype=np.float32).reshape(-1), -1.0, 1.0)
+    sf.write(str(target), samples, sample_rate, subtype="PCM_16")
+
+
+def _ffmpeg_transcode(source: Path, fmt: str, target: Path) -> None:
+    if FFMPEG is None:
+        raise AudioFormatError(
+            f"response_format '{fmt}' requires the ffmpeg binary on the host, "
+            "but none was found. Install ffmpeg or use 'wav', 'flac' or 'pcm'.",
+            code="format_unavailable",
+        )
+    command = [
+        FFMPEG,
+        "-y",
+        "-loglevel",
+        "error",
+        "-i",
+        str(source),
+        *FFMPEG_ARGS[fmt],
+        str(target),
+    ]
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=180,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise AudioFormatError(
+            f"Transcoding to '{fmt}' timed out.", code="transcode_timeout"
+        ) from exc
+    if result.returncode != 0 or not target.is_file():
+        detail = (result.stderr or "").strip().splitlines()
+        message = detail[-1] if detail else f"ffmpeg exited with {result.returncode}"
+        raise AudioFormatError(
+            f"Could not transcode audio to '{fmt}': {message}",
+            code="transcode_failed",
+        )
+
+
+def render_audio(
+    audio: np.ndarray,
+    sample_rate: int,
+    fmt: str,
+) -> tuple[Path, str]:
+    """Write ``audio`` in the requested format inside the API audio dir.
+
+    Returns ``(path, media_type)``. The caller is responsible for scheduling
+    :func:`cleanup_paths` with the returned files after the response is sent.
+    """
+    fmt = (fmt or "wav").lower()
+    if fmt not in MEDIA_TYPES:
+        raise AudioFormatError(
+            f"Unknown response_format '{fmt}'. Supported formats: "
+            + ", ".join(MEDIA_TYPES),
+            code="invalid_response_format",
+        )
+
+    workdir = _ensure_workdir()
+    stem = f"api_{uuid.uuid4().hex[:16]}"
+    wav_path = workdir / f"{stem}.wav"
+    out_path = workdir / f"{stem}{EXTENSIONS[fmt]}"
+
+    _write_wav(audio, sample_rate, wav_path)
+
+    if fmt == "wav":
+        out_path = wav_path
+    elif fmt == "pcm":
+        samples, _ = sf.read(str(wav_path), dtype="int16")
+        out_path.write_bytes(np.asarray(samples, dtype=np.int16).tobytes())
+        wav_path.unlink(missing_ok=True)
+    elif fmt == "flac":
+        samples = np.clip(np.asarray(audio, dtype=np.float32).reshape(-1), -1.0, 1.0)
+        sf.write(str(out_path), samples, sample_rate, format="FLAC", subtype="PCM_16")
+        wav_path.unlink(missing_ok=True)
+    else:
+        _ffmpeg_transcode(wav_path, fmt, out_path)
+        wav_path.unlink(missing_ok=True)
+
+    return out_path, MEDIA_TYPES[fmt]
+
+
+def cleanup_paths(*paths: Path | None) -> None:
+    """Best-effort removal of temporary API audio files."""
+    for path in paths:
+        if not path:
+            continue
+        try:
+            if Path(path).is_file():
+                Path(path).unlink()
+        except OSError:  # pragma: no cover - best effort
+            logger.debug("Could not remove %s", path)
+
+
+def prune_old_files(max_age_s: int = 3600) -> None:
+    """Remove leftover API audio older than ``max_age_s`` (crash safety net)."""
+    workdir = config.API_AUDIO_DIR
+    if not workdir.is_dir():
+        return
+    import time
+
+    now = time.time()
+    for path in workdir.glob("api_*"):
+        try:
+            if now - path.stat().st_mtime > max_age_s:
+                path.unlink()
+        except OSError:  # pragma: no cover
+            continue

tts_studio/cli.py

@@ -0,0 +1,145 @@
+"""``tts-studio`` command line interface.
+
+Starts the whole application in a single process:
+
+* The FastAPI backend serves the built web UI, the studio API and the
+  OpenAI-compatible ``/v1`` API - all on ONE local port.
+* Your browser opens the app automatically.
+* There is no separate backend port to remember or expose: the single URL
+  printed in the terminal IS the application.
+
+Runtime data (models, voices, audio, config) lives in ``~/.tts-studio`` by
+default; override with ``--data-dir`` or the ``TTS_DATA_DIR`` environment
+variable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import socket
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+
+
+def _free_port(host: str, preferred: int) -> int:
+    """Return ``preferred`` if it is available, else the next free port."""
+    for port in range(preferred, preferred + 50):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind((host, port))
+            except OSError:
+                continue
+            return port
+    raise SystemExit(
+        f"error: no free port found between {preferred} and {preferred + 49}"
+    )
+
+
+def _open_browser_when_ready(url: str, host: str, port: int) -> None:
+    """Wait until the server accepts connections, then open the browser."""
+
+    def _wait_and_open() -> None:
+        deadline = time.time() + 30
+        while time.time() < deadline:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                sock.settimeout(0.5)
+                try:
+                    sock.connect((host, port))
+                except OSError:
+                    time.sleep(0.25)
+                    continue
+                break
+        webbrowser.open(url)
+
+    threading.Thread(target=_wait_and_open, daemon=True).start()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="tts-studio",
+        description=(
+            "Launch the TTS Studio web app - local-first text-to-speech with "
+            "Kokoro, Kitten, Pocket and Piper. One command, one port, no API keys."
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default=DEFAULT_HOST,
+        help=f"Bind address (default: {DEFAULT_HOST})",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help=f"Port to serve on (default: {DEFAULT_PORT}; auto-skips busy ports)",
+    )
+    parser.add_argument(
+        "--data-dir",
+        type=str,
+        default=None,
+        help="Directory for models, voices and audio (default: ~/.tts-studio)",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Do not open the browser automatically",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__import__('tts_studio').__version__}",
+    )
+    args = parser.parse_args(argv)
+
+    # --- Configure the runtime environment BEFORE importing the app. -------
+    # tts_studio.config reads these at import time.
+    if args.data_dir:
+        os.environ["TTS_DATA_DIR"] = str(Path(args.data_dir).expanduser().resolve())
+    os.environ.setdefault("TTS_HOST", args.host)
+
+    from tts_studio import __version__
+
+    port = _free_port(args.host, args.port if args.port is not None else DEFAULT_PORT)
+    display_host = "localhost" if args.host in ("0.0.0.0", "::", "") else args.host
+    url = f"http://{display_host}:{port}"
+    data_dir = os.environ.get("TTS_DATA_DIR", "~/.tts-studio")
+
+    print()
+    print(f"  TTS Studio v{__version__}")
+    print(f"  {'-' * 46}")
+    print(f"  App      : {url}")
+    print(f"  Data dir : {data_dir}")
+    print(f"  Stop     : Ctrl+C")
+    print()
+    print("  The UI, the studio API and the OpenAI-compatible /v1 API are all")
+    print("  served from the single URL above - no backend port to manage.")
+    print()
+
+    if not args.no_browser:
+        _open_browser_when_ready(url, args.host, port)
+
+    try:
+        import uvicorn
+
+        uvicorn.run(
+            "tts_studio.main:app",
+            host=args.host,
+            port=port,
+            log_level="warning",
+            # The app prints its own banner; uvicorn stays quiet.
+        )
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

tts_studio/config.py

@@ -0,0 +1,81 @@
+"""Application paths and settings.
+
+All runtime data (models, downloaded voices, generated audio, logs) is kept
+inside ``~/.tts-studio`` by default so that everything stays local and the
+installed package never writes into ``site-packages``. Override with the
+``TTS_DATA_DIR`` environment variable or the ``--data-dir`` CLI flag.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+
+APP_NAME = "TTS Studio"
+APP_VERSION = "1.0.0"
+
+DATA_DIR = Path(
+    os.environ.get("TTS_DATA_DIR", str(Path.home() / ".tts-studio"))
+).resolve()
+
+# Keep every Hugging Face download (Kokoro weights, Kitten weights, Pocket
+# weights and voices) inside the local data directory. Must be set before
+# huggingface_hub is imported anywhere.
+HF_CACHE_DIR = DATA_DIR / "hf_cache"
+os.environ.setdefault("HF_HOME", str(HF_CACHE_DIR))
+
+MODELS_DIR = DATA_DIR / "models"
+PIPER_VOICES_DIR = DATA_DIR / "piper_voices"
+OUTPUTS_DIR = DATA_DIR / "audio"
+PREVIEWS_DIR = DATA_DIR / "previews"
+CUSTOM_VOICES_DIR = DATA_DIR / "custom_voices"
+LOGS_DIR = DATA_DIR / "logs"
+API_AUDIO_DIR = DATA_DIR / "api_audio"
+
+HISTORY_FILE = DATA_DIR / "history.json"
+SETTINGS_FILE = DATA_DIR / "settings.json"
+PIPER_CATALOG_FILE = DATA_DIR / "piper_catalog.json"
+API_KEYS_FILE = DATA_DIR / "api_keys.json"
+API_CONFIG_FILE = DATA_DIR / "api_config.json"
+
+HOST = os.environ.get("TTS_HOST", "127.0.0.1")
+PORT = int(os.environ.get("TTS_PORT", "8000"))
+
+# Comma separated origins; "*" by default so the Vite dev server and
+# reverse-proxied deployments both work out of the box.
+CORS_ORIGINS = [
+    origin.strip()
+    for origin in os.environ.get("TTS_CORS_ORIGINS", "*").split(",")
+    if origin.strip()
+]
+
+# Seconds before the Piper voice catalogue is considered stale and re-fetched.
+PIPER_CATALOG_TTL = int(os.environ.get("TTS_PIPER_CATALOG_TTL", str(7 * 24 * 3600)))
+
+PIPER_CATALOG_URL = (
+    "https://huggingface.co/rhasspy/piper-voices/resolve/main/voices.json"
+)
+PIPER_VOICE_BASE_URL = "https://huggingface.co/rhasspy/piper-voices/resolve/main/"
+
+KOKORO_REPO = "hexgrad/Kokoro-82M"
+KOKORO_SAMPLE_RATE = 24000
+
+
+def ensure_dirs() -> None:
+    for directory in (
+        DATA_DIR,
+        HF_CACHE_DIR,
+        MODELS_DIR,
+        PIPER_VOICES_DIR,
+        OUTPUTS_DIR,
+        PREVIEWS_DIR,
+        CUSTOM_VOICES_DIR,
+        LOGS_DIR,
+        API_AUDIO_DIR,
+    ):
+        directory.mkdir(parents=True, exist_ok=True)
+
+
+ensure_dirs()

tts_studio/engines/__init__.py

@@ -0,0 +1,30 @@
+"""TTS engine adapters."""
+
+from . import catalogs  # noqa: F401
+from .base import (  # noqa: F401
+    BaseEngine,
+    EngineError,
+    GenerationResult,
+    LoadedHandle,
+    Voice,
+    VoiceRef,
+    option,
+)
+from .kokoro_engine import KokoroEngine  # noqa: F401
+from .kitten_engine import KittenEngine  # noqa: F401
+from .piper_engine import PiperEngine  # noqa: F401
+from .pocket_engine import PocketEngine  # noqa: F401
+
+__all__ = [
+    "BaseEngine",
+    "EngineError",
+    "GenerationResult",
+    "LoadedHandle",
+    "Voice",
+    "VoiceRef",
+    "option",
+    "KokoroEngine",
+    "KittenEngine",
+    "PocketEngine",
+    "PiperEngine",
+]

tts_studio/engines/base.py

@@ -0,0 +1,222 @@
+"""Engine adapter interface shared by Kokoro / Kitten / Pocket / Piper."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import importlib.util
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+import numpy as np
+
+logger = logging.getLogger("tts.engines")
+
+
+class EngineError(RuntimeError):
+    """Raised for user-facing engine failures (missing model, bad options...)."""
+
+    def __init__(self, message: str, code: str = "engine_error") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def option(
+    key: str,
+    label: str,
+    type_: str = "float",
+    default: Any = None,
+    choices: list[Any] | None = None,
+    minimum: float | None = None,
+    maximum: float | None = None,
+    step: float | None = None,
+    help_: str = "",
+    advanced: bool = False,
+) -> dict[str, Any]:
+    """Describe a load/generation option so the frontend can render a form."""
+    return {
+        "key": key,
+        "label": label,
+        "type": type_,
+        "default": default,
+        "choices": choices,
+        "min": minimum,
+        "max": maximum,
+        "step": step,
+        "help": help_,
+        "advanced": advanced,
+    }
+
+
+@dataclass
+class Voice:
+    id: str
+    name: str
+    language: str  # human readable, e.g. "American English"
+    lang_code: str | None = None
+    gender: str | None = None  # "female" | "male" | None
+    description: str = ""
+    grade: str | None = None
+    tags: list[str] = field(default_factory=list)
+    variants: list[str] | None = None  # variant ids this voice works with
+    speaker_count: int = 1
+    speakers: list[dict[str, Any]] | None = None
+    size_bytes: int | None = None
+    downloaded: bool | None = None
+    custom: bool = False
+    path: str | None = None  # for custom voices
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "language": self.language,
+            "lang_code": self.lang_code,
+            "gender": self.gender,
+            "description": self.description,
+            "grade": self.grade,
+            "tags": self.tags,
+            "variants": self.variants,
+            "speaker_count": self.speaker_count,
+            "speakers": self.speakers or [],
+            "size_bytes": self.size_bytes,
+            "downloaded": self.downloaded,
+            "custom": self.custom,
+            "extra": self.extra,
+        }
+
+
+@dataclass
+class VoiceRef:
+    kind: str  # "builtin" | "file"
+    value: str  # builtin voice id/name or local file path
+    voice: Voice | None = None
+    language: str | None = None
+    reference_text: str | None = None
+
+
+ProgressFn = Callable[[float, str | None], None]
+CancelFn = Callable[[], bool]
+
+
+@dataclass
+class GenerationResult:
+    audio: np.ndarray
+    sample_rate: int
+    meta: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class LoadedHandle:
+    engine_id: str
+    variant_id: str
+    options: dict[str, Any]
+    handle: Any
+    loaded_at: float = field(default_factory=time.time)
+    device: str = "cpu"
+    sample_rate: int = 24000
+    meta: dict[str, Any] = field(default_factory=dict)
+
+
+class BaseEngine:
+    """Common behaviour for all engines."""
+
+    id: str = ""
+    name: str = ""
+    description: str = ""
+    homepage: str = ""
+    license: str = ""
+    install_specs: dict[str, list[str]] = {}
+    default_variant: str = ""
+    cloning: bool = False
+    custom_voice_types: list[dict[str, str]] = []
+    import_names: list[str] = []
+
+    # ------------------------------------------------------------------
+    # Installation / introspection
+    # ------------------------------------------------------------------
+    def installed(self) -> bool:
+        return all(
+            importlib.util.find_spec(name) is not None for name in self.import_names
+        )
+
+    def version(self) -> str | None:
+        if not self.installed():
+            return None
+        for package in self.installed_packages():
+            for name in (package.split("[")[0], self.id):
+                try:
+                    return importlib.metadata.version(name)
+                except importlib.metadata.PackageNotFoundError:
+                    continue
+        return None
+
+    def installed_packages(self) -> list[str]:
+        return self.install_specs.get("base", [])
+
+    # ------------------------------------------------------------------
+    # Catalogue
+    # ------------------------------------------------------------------
+    def variants(self) -> list[dict[str, Any]]:
+        return []
+
+    def voices(
+        self, variant_id: str | None, custom_voices: list[Any] | None = None
+    ) -> list[Voice]:
+        return []
+
+    # ------------------------------------------------------------------
+    # Model lifecycle
+    # ------------------------------------------------------------------
+    def load(self, variant_id: str, options: dict[str, Any]) -> LoadedHandle:
+        raise NotImplementedError
+
+    def unload(self, loaded: LoadedHandle) -> None:
+        """Release the handle. Best effort - used for logs/cleanup."""
+        handle = loaded.handle
+        try:
+            if hasattr(handle, "to"):
+                handle.to("cpu")  # type: ignore[operator]
+        except Exception:  # pragma: no cover - defensive
+            pass
+        try:
+            import gc
+
+            gc.collect()
+        except Exception:  # pragma: no cover - defensive
+            pass
+
+    # ------------------------------------------------------------------
+    # Generation
+    # ------------------------------------------------------------------
+    def generate(
+        self,
+        loaded: LoadedHandle,
+        text: str,
+        voice: VoiceRef,
+        options: dict[str, Any],
+        progress: ProgressFn,
+        cancelled: CancelFn,
+    ) -> GenerationResult:
+        raise NotImplementedError
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+    def describe(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "homepage": self.homepage,
+            "license": self.license,
+            "installed": self.installed(),
+            "version": self.version() if self.installed() else None,
+            "install_specs": self.install_specs,
+            "default_variant": self.default_variant,
+            "cloning": self.cloning,
+            "custom_voice_types": self.custom_voice_types,
+            "installed_packages": self.installed_packages(),
+        }