steppy-dev 0.3.0__py3-none-any.whl

steppy/tts/providers/http.py

@@ -0,0 +1,184 @@
+"""Generic HTTP text-to-speech provider — the engine every vendor preset runs on.
+
+One class serves ElevenLabs, OpenAI, Azure, Google, and any vendor that has not
+shipped yet, because the differences between them are data (``tts/presets.py``)
+rather than code. A user facing an unsupported API fills in ``video.tts.http``
+and is done — no fork, no plugin, no release of Steppy.
+
+``httpx`` is imported **inside** :meth:`synthesize`. It is already a Steppy
+dependency, but ``tests/test_no_playwright_import_on_default_path.py`` forbids
+it transitively from ``import steppy.cli``, and ``TtsConfig`` lives in
+``models.py`` on the eager path.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+from typing import Any
+
+from ..types import SpeechClip, SpeechRequest, TtsError, check_resolved
+
+# Only whole ``{name}`` tokens are substituted; ``{{`` / ``}}`` escape a literal
+# brace. Applied per string leaf, never to serialized JSON, so narration text
+# containing braces cannot alter the request structure.
+_TOKEN = re.compile(r"\{\{|\}\}|\{(\w+)\}")
+
+
+def substitute(value: Any, context: dict[str, str]) -> Any:
+    """Fill ``{placeholders}`` in every string leaf of a parsed structure."""
+    if isinstance(value, dict):
+        return {k: substitute(v, context) for k, v in value.items()}
+    if isinstance(value, list):
+        return [substitute(v, context) for v in value]
+    if not isinstance(value, str):
+        return value
+
+    def _sub(match: "re.Match") -> str:
+        token = match.group(0)
+        if token == "{{":
+            return "{"
+        if token == "}}":
+            return "}"
+        return context.get(match.group(1), "")
+
+    return _TOKEN.sub(_sub, value)
+
+
+def dig(payload: Any, path: str) -> Any:
+    """Follow a dotted path into a decoded JSON response."""
+    current = payload
+    for part in path.split("."):
+        if not isinstance(current, dict) or part not in current:
+            raise TtsError(f"TTS response has no field '{path}' (looking for '{part}')")
+        current = current[part]
+    return current
+
+
+class HttpTtsProvider:
+    """Config-driven REST provider.
+
+    ``spec`` is a merged preset + user override (see ``registry.resolve_spec``),
+    so this class never knows which vendor it is talking to.
+    """
+
+    def __init__(self, name: str, spec: dict, cfg) -> None:
+        self.name = name
+        self.spec = spec
+        self.cfg = cfg
+
+    def version(self) -> str:
+        """Model name plus a hash of the request shape.
+
+        A remote voice has nothing local to fingerprint, so the model id is the
+        only version there is — but the *request* is configuration too. Editing
+        ``video.tts.http.json`` (ElevenLabs ``stability``/``style``, Azure SSML
+        prosody, a different ``format``) changes the audio, and without the spec
+        in the key every existing clip would stay a hit forever.
+
+        The spec is hashed **pre-substitution**, so it holds ``{api_key}``
+        placeholders rather than the secret — safe to fold in, and rotating a
+        key does not churn the cache.
+        """
+        shape = hashlib.sha256(
+            json.dumps(self.spec, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")
+        ).hexdigest()[:12]
+        return f"{self.spec.get('model') or self.cfg.model or ''}:{shape}"
+
+    def _context(self, request: SpeechRequest) -> dict[str, str]:
+        api_key = check_resolved(self.cfg.api_key, "video.tts.api_key")
+        # Fall back to config so the provider is usable on its own, not only
+        # through synthesize_steps() — the request carries per-utterance intent,
+        # the config carries the project's defaults.
+        voice = request.voice or self.cfg.voice_for(request.locale) or ""
+        model = request.model or self.spec.get("model") or self.cfg.model or ""
+        context: dict[str, str] = {
+            "text": request.text,
+            "locale": request.locale,
+            "voice": voice,
+            "model": model,
+            "speed": _format_number(request.speed),
+            "api_key": api_key or "",
+            "region": self.cfg.region or "",
+            "base_url": (self.cfg.base_url or self.spec.get("base_url") or "").rstrip("/"),
+        }
+        # Provider-specific extras last, so a project can override anything above.
+        for key, value in (request.options or {}).items():
+            context[str(key)] = "" if value is None else str(value)
+        return context
+
+    def _require(self, context: dict[str, str]) -> None:
+        missing = [f for f in self.spec.get("requires", []) if not context.get(f)]
+        if not missing:
+            return
+        hint = self.spec.get("docs")
+        raise TtsError(
+            f"TTS provider '{self.name}' needs {', '.join('video.tts.' + m for m in missing)}."
+            + (f" See {hint}" if hint else "")
+        )
+
+    def synthesize(self, request: SpeechRequest) -> SpeechClip:
+        import httpx  # lazy: see the module docstring
+
+        context = self._context(request)
+        self._require(context)
+
+        url = substitute(self.spec.get("url") or "", context)
+        if not url:
+            raise TtsError(
+                f"TTS provider '{self.name}' has no URL. Set video.tts.http.url, or pick a "
+                "provider preset that supplies one."
+            )
+
+        headers = substitute(self.spec.get("headers") or {}, context)
+        json_body = self.spec.get("json")
+        raw_body = self.spec.get("body")
+        kwargs: dict[str, Any] = {"headers": headers}
+        if json_body is not None:
+            kwargs["json"] = substitute(json_body, context)
+        elif raw_body is not None:
+            kwargs["content"] = substitute(raw_body, context).encode("utf-8")
+
+        timeout = self.cfg.timeout / 1000
+        try:
+            response = httpx.request(self.spec.get("method", "POST"), url, timeout=timeout, **kwargs)
+        except Exception as exc:
+            raise TtsError(f"TTS request to '{self.name}' failed: {exc}") from exc
+
+        if response.status_code >= 400:
+            # Never echo the headers back — they carry the API key.
+            detail = response.text[:300].strip()
+            raise TtsError(f"TTS provider '{self.name}' returned HTTP {response.status_code}: {detail}")
+
+        audio = self._extract(response)
+        if not audio:
+            raise TtsError(f"TTS provider '{self.name}' returned no audio for a {len(request.text)}-char utterance")
+        return SpeechClip(audio=audio, fmt=self._format())
+
+    def _extract(self, response) -> bytes:
+        if self.spec.get("response") == "json":
+            payload = response.json()
+            value = dig(payload, self.spec.get("audio_path") or "")
+            if self.spec.get("encoding") == "base64":
+                return base64.b64decode(value)
+            return value.encode("utf-8") if isinstance(value, str) else bytes(value)
+        return response.content
+
+    def _format(self) -> str:
+        return str(self.cfg.format or self.spec.get("format") or "wav")
+
+
+def _format_number(value: float) -> str:
+    """1.0 renders as "1", not "1.0" — some APIs reject the float form."""
+    if float(value).is_integer():
+        return str(int(value))
+    return str(value)
+
+
+def build(name: str, spec: dict, cfg) -> HttpTtsProvider:
+    return HttpTtsProvider(name, spec, cfg)
+
+
+__all__ = ["HttpTtsProvider", "build", "dig", "substitute"]

steppy/tts/providers/local.py

@@ -0,0 +1,207 @@
+"""Offline text-to-speech providers: Piper (neural) and espeak-ng (formant).
+
+Both are driven as **subprocesses**, never imported. For espeak that is simply
+how it ships; for Piper it is a licensing boundary worth stating plainly:
+`piper1-gpl <https://github.com/OHF-Voice/piper1-gpl>`_ is GPL-3.0, and Steppy
+is headed for a permissive license. Running ``python -m piper`` is arms-length
+use of a tool the user installed — the same posture already taken with ffmpeg —
+whereas ``from piper import PiperVoice`` would make Steppy a derivative work.
+For the same reason Piper is deliberately **not** a ``pyproject.toml`` extra:
+users install it themselves with ``pip install piper-tts``.
+
+(The archived ``rhasspy/piper`` repo is not this. Development moved to
+OHF-Voice under the Open Home Foundation in late 2025; voice names and the
+``download_voices`` module below are that project's.)
+
+Both engines emit WAV, which is the format the narration assembler wants — so
+the free path never pays a transcode.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import tempfile
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+from ..types import SpeechClip, SpeechRequest, TtsError
+
+
+class PiperProvider:
+    """Free, offline, neural. Needs a per-language voice model on disk."""
+
+    name = "piper"
+
+    def __init__(self, cfg) -> None:
+        self.cfg = cfg
+        self.python = cfg.piper.python or sys.executable
+        self.data_dir = Path(cfg.piper.data_dir)
+
+    def version(self) -> str:
+        return _piper_version(self.python)
+
+    def synthesize(self, request: SpeechRequest) -> SpeechClip:
+        voice = request.voice
+        if not voice:
+            raise TtsError(
+                "video.tts.voice is required for the piper provider. Voices are "
+                "per-language, so use the map form:\n"
+                "  voice: { fr: fr_FR-siwis-medium, nl: nl_NL-mls-medium }\n"
+                "Browse them at https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md"
+            )
+        self._ensure_voice(voice)
+
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "clip.wav"
+            args = [
+                self.python,
+                "-m",
+                "piper",
+                "-m",
+                voice,
+                "--data-dir",
+                str(self.data_dir),
+                "-f",
+                str(out),
+            ]
+            # Piper's length_scale is inverse to speed: slower speech is longer.
+            if request.speed and request.speed != 1.0:
+                args += ["--length-scale", f"{1.0 / request.speed:.4f}"]
+            for flag in ("sentence_silence", "volume"):
+                value = (request.options or {}).get(flag)
+                if value is not None:
+                    args += [f"--{flag.replace('_', '-')}", str(value)]
+            args += ["--", request.text]
+
+            _run(args, what="piper", hint=_PIPER_HINT, timeout=self.cfg.timeout / 1000)
+            if not out.is_file():
+                raise TtsError("piper produced no audio file")
+            return SpeechClip(audio=out.read_bytes(), fmt="wav")
+
+    def _ensure_voice(self, voice: str) -> None:
+        if (self.data_dir / f"{voice}.onnx").is_file():
+            return
+        if not self.cfg.piper.download:
+            raise TtsError(
+                f"piper voice '{voice}' is not in {self.data_dir} and "
+                "video.tts.piper.download is false. Fetch it with:\n"
+                f"  {self.python} -m piper.download_voices --data-dir {self.data_dir} {voice}"
+            )
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        _run(
+            [self.python, "-m", "piper.download_voices", "--data-dir", str(self.data_dir), voice],
+            what="piper.download_voices",
+            hint=_PIPER_HINT,
+            # A voice model is tens of MB; the per-clip budget is far too small.
+            timeout=600,
+        )
+
+
+class EspeakProvider:
+    """Free, offline, zero-download — and audibly robotic.
+
+    Ships as the honest fallback for a machine that cannot spare a voice model:
+    fine for a CI smoke test, not for a guide a customer watches.
+    """
+
+    name = "espeak"
+
+    def __init__(self, cfg) -> None:
+        self.cfg = cfg
+
+    def version(self) -> str:
+        return _espeak_version()
+
+    def synthesize(self, request: SpeechRequest) -> SpeechClip:
+        binary = shutil.which("espeak-ng") or shutil.which("espeak")
+        if not binary:
+            raise TtsError(
+                "espeak-ng is not installed. Install it with:\n"
+                "  Windows:  winget install espeak-ng.espeak-ng\n"
+                "  macOS:    brew install espeak-ng\n"
+                "  Debian:   sudo apt-get install espeak-ng"
+            )
+        with tempfile.TemporaryDirectory() as tmp:
+            out = Path(tmp) / "clip.wav"
+            # espeak's default is ~175 wpm; scale it rather than exposing raw wpm.
+            args = [binary, "-w", str(out), "-s", str(int(175 * request.speed))]
+            voice = request.voice or request.locale
+            if voice:
+                args += ["-v", voice]
+            args += [request.text]
+            _run(args, what="espeak-ng", hint="", timeout=self.cfg.timeout / 1000)
+            if not out.is_file():
+                raise TtsError("espeak-ng produced no audio file")
+            return SpeechClip(audio=out.read_bytes(), fmt="wav")
+
+
+_PIPER_HINT = (
+    "Install it with:\n"
+    "  pip install piper-tts\n"
+    "It is not a Steppy dependency on purpose: piper1-gpl is GPL-3.0, so Steppy "
+    "runs it as a separate program rather than linking it."
+)
+
+
+def _run(args: list[str], *, what: str, hint: str, timeout: float) -> None:
+    try:
+        proc = subprocess.run(args, capture_output=True, timeout=max(10.0, timeout))
+    except FileNotFoundError as exc:
+        raise TtsError(f"{what} is not available: {exc}.\n{hint}".rstrip()) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise TtsError(f"{what} timed out after {exc.timeout:.0f}s") from exc
+    if proc.returncode != 0:
+        tail = (proc.stderr or b"").decode("utf-8", "replace").strip().splitlines()[-5:]
+        raise TtsError(f"{what} exited {proc.returncode}: " + " / ".join(tail))
+
+
+@lru_cache(maxsize=4)
+def _piper_version(python: str) -> str:
+    """Fold the engine version into the cache key.
+
+    Different Piper builds produce different audio, so clip durations differ,
+    so the whole video timeline shifts — with no other signal that anything
+    changed.
+    """
+    try:
+        proc = subprocess.run(
+            [python, "-c", "import piper,sys; sys.stdout.write(getattr(piper,'__version__','?'))"],
+            capture_output=True,
+            timeout=30,
+        )
+        return proc.stdout.decode("utf-8", "replace").strip() or "?"
+    except Exception:
+        return "?"
+
+
+@lru_cache(maxsize=1)
+def _espeak_version() -> str:
+    binary = shutil.which("espeak-ng") or shutil.which("espeak")
+    if not binary:
+        return "?"
+    try:
+        proc = subprocess.run([binary, "--version"], capture_output=True, timeout=20)
+        return proc.stdout.decode("utf-8", "replace").strip()[:80] or "?"
+    except Exception:
+        return "?"
+
+
+def build_piper(cfg) -> PiperProvider:
+    return PiperProvider(cfg)
+
+
+def build_espeak(cfg) -> EspeakProvider:
+    return EspeakProvider(cfg)
+
+
+def probe(provider: str, cfg) -> Optional[str]:
+    """One-line readiness report for ``steppy video check``."""
+    if provider == "piper":
+        version = _piper_version(cfg.piper.python or sys.executable)
+        return None if version != "?" else "piper is not installed (pip install piper-tts)"
+    if provider == "espeak":
+        return None if _espeak_version() != "?" else "espeak-ng is not on PATH"
+    return None

steppy/tts/providers/null.py

@@ -0,0 +1,28 @@
+"""The ``none`` provider — captions, no voiceover.
+
+Steppy's shipped default. A video renders with burned-in captions and a silent
+track, with no install, no network and no bill; adding a voice is one config
+line. That ordering is deliberate: the free path has to work out of the box,
+and a default that silently starts charging per character would not.
+"""
+
+from __future__ import annotations
+
+from ..types import SpeechClip, SpeechRequest
+
+
+class NullTtsProvider:
+    name = "none"
+
+    def __init__(self, cfg=None) -> None:
+        self.cfg = cfg
+
+    def version(self) -> str:
+        return "none"
+
+    def synthesize(self, request: SpeechRequest) -> SpeechClip:
+        return SpeechClip(audio=b"", fmt="wav")
+
+
+def build(cfg=None) -> NullTtsProvider:
+    return NullTtsProvider(cfg)

steppy/tts/registry.py

@@ -0,0 +1,201 @@
+"""Provider resolution — the seam that makes ``video.tts.provider`` a config knob.
+
+Four sources, in priority order:
+
+1. **Entry points** (``steppy.tts_providers``) — a third party ships a package,
+   declares one entry point, and their engine is nameable in ``config.yaml``
+   with no change to Steppy. This is why ``TtsConfig.provider`` is a plain
+   ``str`` and not a ``Literal``.
+2. **Built-in code providers** — ``none``, ``piper``, ``espeak``, ``http``.
+3. **Vendor presets** (``tts/presets.py``) — ``elevenlabs``, ``openai``,
+   ``azure``, ``google``, each a data row over the generic HTTP engine, with any
+   explicitly-set ``video.tts.http.*`` field layered on top.
+4. Anything else is an error that lists what *is* available.
+
+Layering in (3) follows the same rule as the UI-kit presets in ``models.py``:
+what the user set explicitly always wins, what they left alone gets filled in.
+
+Structured as a priority cascade returning a tagged result, like
+``_parallel/image.py:resolve_build_inputs`` — the caller can report which branch
+won, which is most of what ``steppy video check`` needs to be useful.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, Optional
+
+from .presets import TTS_PRESETS
+from .types import TtsError, TtsProvider
+
+ENTRY_POINT_GROUP = "steppy.tts_providers"
+
+_BUILTINS = ("none", "piper", "espeak", "http")
+
+# Fields a preset may supply and the user may override. ``defaults`` is handled
+# separately because it fills TtsConfig, not the request spec.
+_SPEC_FIELDS = (
+    "url",
+    "method",
+    "headers",
+    "json",
+    "body",
+    "response",
+    "audio_path",
+    "encoding",
+    "format",
+)
+
+
+@dataclass(frozen=True)
+class Resolved:
+    """A provider plus the branch that produced it."""
+
+    provider: TtsProvider
+    name: str
+    # entry_point | builtin | preset
+    source: str
+    spec: dict[str, Any]
+
+
+@lru_cache(maxsize=1)
+def _entry_point_providers() -> dict[str, Any]:
+    """Discover third-party providers.
+
+    Cached and called lazily: ``entry_points()`` walks the metadata of every
+    installed distribution, which is not a cost the default CLI path should pay.
+    """
+    from importlib.metadata import entry_points
+
+    found: dict[str, Any] = {}
+    try:
+        for entry in entry_points(group=ENTRY_POINT_GROUP):
+            found[entry.name] = entry
+    except Exception:  # pragma: no cover - broken metadata must not break a build
+        return {}
+    return found
+
+
+def available_providers() -> list[str]:
+    return sorted({*_BUILTINS, *TTS_PRESETS, *_entry_point_providers()})
+
+
+def resolve_spec(name: str, cfg) -> dict[str, Any]:
+    """Merge a vendor preset with the user's ``video.tts.http`` overrides.
+
+    Explicit wins: any field the user actually set in config takes precedence
+    over the preset's value, exactly like ``_PresetModel._apply_preset``.
+    """
+    preset = dict(TTS_PRESETS.get(name, {}))
+    spec: dict[str, Any] = {k: v for k, v in preset.items() if k in _SPEC_FIELDS}
+    spec["requires"] = list(preset.get("requires", []))
+    spec["docs"] = preset.get("docs")
+    for key, value in (preset.get("defaults") or {}).items():
+        spec.setdefault(key, value)
+
+    http = cfg.http
+    explicit = http.model_fields_set
+    overrides = {
+        "url": http.url,
+        "method": http.method,
+        "headers": http.headers,
+        "json": http.json_body,
+        "body": http.body,
+        "response": http.response,
+        "audio_path": http.audio_path,
+        "encoding": http.encoding,
+        "format": http.format,
+    }
+    for field_name, value in overrides.items():
+        # `json_body` carries the alias `json` on the model.
+        set_name = "json_body" if field_name == "json" else field_name
+        if set_name in explicit and value is not None:
+            spec[field_name] = value
+
+    # A user-set model/voice always beats the preset's default.
+    if cfg.model:
+        spec["model"] = cfg.model
+    if cfg.base_url:
+        spec["base_url"] = cfg.base_url
+    return spec
+
+
+def resolve(cfg) -> Resolved:
+    """Resolve ``video.tts.provider`` into something that can speak."""
+    name = (cfg.provider or "none").strip()
+
+    entry = _entry_point_providers().get(name)
+    if entry is not None:
+        try:
+            factory = entry.load()
+        except Exception as exc:
+            raise TtsError(f"TTS provider '{name}' is registered but failed to load: {exc}") from exc
+        try:
+            provider = factory(cfg)
+        except Exception as exc:
+            raise TtsError(f"TTS provider '{name}' failed to initialise: {exc}") from exc
+        return Resolved(provider=provider, name=name, source="entry_point", spec={})
+
+    if name in _BUILTINS:
+        return Resolved(provider=_build_builtin(name, cfg), name=name, source="builtin", spec=resolve_spec(name, cfg))
+
+    if name in TTS_PRESETS:
+        from .providers.http import build as build_http
+
+        spec = resolve_spec(name, cfg)
+        return Resolved(provider=build_http(name, spec, cfg), name=name, source="preset", spec=spec)
+
+    raise TtsError(
+        f"Unknown TTS provider '{name}'. Available: {', '.join(available_providers())}.\n"
+        "Set video.tts.provider to one of those, or describe an unsupported API "
+        "directly under video.tts.http (url / headers / json / response)."
+    )
+
+
+def _build_builtin(name: str, cfg):
+    if name == "none":
+        from .providers.null import build
+
+        return build(cfg)
+    if name == "http":
+        from .providers.http import build as build_http
+
+        return build_http("http", resolve_spec("http", cfg), cfg)
+    from .providers.local import build_espeak, build_piper
+
+    return build_piper(cfg) if name == "piper" else build_espeak(cfg)
+
+
+def describe(cfg) -> str:
+    """Human-readable one-liner for ``steppy video check``."""
+    try:
+        resolved = resolve(cfg)
+    except TtsError as exc:
+        return f"unusable — {exc}"
+    detail = {"entry_point": "third-party plugin", "builtin": "built in", "preset": "vendor preset"}[resolved.source]
+    if resolved.name == "none":
+        return "none (captions only, no audio)"
+    return f"{resolved.name} ({detail})"
+
+
+def readiness(cfg) -> Optional[str]:
+    """Return a problem description, or None when the provider looks usable."""
+    try:
+        resolved = resolve(cfg)
+    except TtsError as exc:
+        return str(exc)
+    if resolved.source == "builtin" and resolved.name in ("piper", "espeak"):
+        from .providers.local import probe
+
+        return probe(resolved.name, cfg)
+    if resolved.name != "none" and resolved.spec.get("requires"):
+        from .types import check_resolved
+
+        try:
+            check_resolved(cfg.api_key, "video.tts.api_key")
+        except TtsError as exc:
+            return str(exc)
+        if "api_key" in resolved.spec["requires"] and not cfg.api_key:
+            return f"video.tts.api_key is not set (required by '{resolved.name}')"
+    return None