steppy-dev 0.3.0__py3-none-any.whl

steppy/tts/__init__.py

@@ -0,0 +1,280 @@
+"""Text-to-speech for video narration — provider-agnostic by construction.
+
+The whole point of this package is that ``video.tts.provider`` is the only thing
+that has to change to swap engines: ``none`` (the default: captions, no audio),
+``piper`` or ``espeak`` (free, offline), a vendor preset (``elevenlabs``,
+``openai``, ``azure``, ``google``), a hand-written REST shape under
+``video.tts.http``, or a third-party plugin registered through the
+``steppy.tts_providers`` entry point. No code path branches on vendor.
+
+Narration is synthesized **before** the browser opens, because the video
+timeline needs each clip's duration to know how long to hold its step. So this
+package never imports ``steppy.video``, and ``steppy.video`` never imports this
+one — they meet at a dict of durations and a finished WAV.
+
+Synthesis is **per step**, and the cache is keyed on the text rather than on the
+step's position, so editing one sentence re-voices one sentence: unchanged steps
+hit, reordered steps hit, and the same sentence in two guides shares one clip.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional, Sequence
+
+from .cache import ClipCache, cache_key
+from .registry import available_providers, describe, readiness, resolve
+from .types import SpeechClip, SpeechRequest, TtsError, TtsProvider
+
+__all__ = [
+    "ClipCache",
+    "SpeechClip",
+    "SpeechRequest",
+    "TtsError",
+    "TtsProvider",
+    "Utterance",
+    "Narration",
+    "assemble_track",
+    "available_providers",
+    "cache_key",
+    "describe",
+    "normalize_narration",
+    "readiness",
+    "resolve",
+    "synthesize_steps",
+    "voice_jobs",
+]
+
+
+@dataclass(frozen=True)
+class Utterance:
+    """One step's narration."""
+
+    step_id: str
+    text: str
+
+
+@dataclass(frozen=True)
+class Narration:
+    """Per-step clips and durations, ready for the timeline and the muxer."""
+
+    durations_ms: dict[str, int]
+    clips: dict[str, Path]
+    provider: str
+
+    @property
+    def silent(self) -> bool:
+        return not self.clips
+
+
+def normalize_narration(text: Optional[str]) -> str:
+    """Collapse authoring whitespace, so re-wrapping a line is not a re-bill.
+
+    ``guide-text`` is YAML, and a hard wrap moved by one word changes the string
+    without changing a syllable of the audio. Normalizing the *request* rather
+    than the *key* is deliberate: were only the key normalized, two differently
+    wrapped texts would collide on whichever clip synthesized first, and the
+    audio would no longer correspond to the text that was sent.
+    """
+    return " ".join((text or "").split())
+
+
+def synthesize_steps(
+    utterances: Sequence[Utterance],
+    cfg,
+    *,
+    locale: str,
+    work_dir: Path,
+    ffmpeg: str,
+    cache_root: Optional[Path] = None,
+    memo: Optional[dict[str, tuple[Path, int]]] = None,
+    on_warning: Optional[Callable[[str], None]] = None,
+) -> Narration:
+    """Synthesize every step's narration for one locale.
+
+    Returns durations keyed by step id — which is what the video timeline needs
+    up front, to stretch each step so its voiceover is never cut off.
+
+    ``cache_root`` overrides ``cfg.cache_dir`` and should be an **absolute**
+    path resolved against the project root; the bare config value is relative to
+    the CWD, so a build launched from a subdirectory would otherwise miss a warm
+    cache and re-bill for it. ``memo`` is a process-local key→path map shared
+    across a batch, so N layouts of one guide synthesize once even when the
+    on-disk cache is disabled.
+
+    A provider failure is reported and downgraded to silence rather than raised:
+    losing the voiceover is a bad outcome, losing the release is a worse one.
+    """
+    from .track import normalize, wav_duration_ms
+
+    resolved = resolve(cfg)
+    if resolved.name == "none":
+        return Narration(durations_ms={}, clips={}, provider="none")
+
+    cache = ClipCache(Path(cache_root or cfg.cache_dir), enabled=cfg.cache)
+    version = _safe_version(resolved.provider)
+    durations: dict[str, int] = {}
+    clips: dict[str, Path] = {}
+
+    for utterance in utterances:
+        text = normalize_narration(utterance.text)
+        if not text:
+            continue
+        request = SpeechRequest(
+            text=text,
+            locale=locale,
+            voice=cfg.voice_for(locale),
+            model=cfg.model,
+            speed=cfg.speed,
+            fmt=cfg.format,
+            options=dict(cfg.options or {}),
+        )
+        key = cache_key(request, resolved.name, version)
+        try:
+            wav, duration = _clip_for(request, key, cache, resolved, work_dir, ffmpeg, normalize, memo)
+        except TtsError as exc:
+            if on_warning:
+                on_warning(f"narration for '{utterance.step_id}' ({locale}) failed: {exc}")
+            continue
+        if wav is None:
+            continue
+        if duration is None:
+            try:
+                duration = wav_duration_ms(wav)
+            except Exception as exc:  # a clip we just produced and cannot read
+                if on_warning:
+                    on_warning(f"narration for '{utterance.step_id}' ({locale}) is unreadable: {exc}")
+                continue
+            cache.set_duration(key, "wav", duration)
+        durations[utterance.step_id] = duration
+        clips[utterance.step_id] = wav
+        if memo is not None:
+            memo[key] = (wav, duration)
+
+    return Narration(durations_ms=durations, clips=clips, provider=resolved.name)
+
+
+def _clip_for(request, key, cache, resolved, work_dir, ffmpeg, normalize, memo) -> tuple[Optional[Path], Optional[int]]:
+    """Fetch from the memo, then the cache, else synthesize.
+
+    Always returns normalized WAV, plus the clip's duration when it was already
+    known. A cached clip that will not open is treated as a **miss**: the entry
+    is dropped and re-synthesized, because a truncated WAV left by a killed run
+    is otherwise a permanent hit whose duration no longer matches the timeline
+    the video was rendered against.
+    """
+    from .track import is_intact_wav, wav_duration_ms
+
+    if memo is not None:
+        remembered = memo.get(key)
+        if remembered is not None and remembered[0].is_file():
+            return remembered
+
+    hit = cache.get(key, "wav")
+    if hit is not None:
+        if is_intact_wav(hit.path):
+            return hit.path, hit.duration_ms or wav_duration_ms(hit.path)
+        cache.discard(key, "wav")
+
+    clip = resolved.provider.synthesize(request)
+    if clip.empty:
+        return None, None
+
+    # ``.raw.`` keeps the pre-transcode container from ever colliding with the
+    # normalized artifact, which matters when the provider already returned WAV.
+    work_dir.mkdir(parents=True, exist_ok=True)
+    raw = work_dir / f"{key}.raw.{clip.fmt}"
+    raw.write_bytes(clip.audio)
+    try:
+        if not cache.enabled:
+            return normalize(raw, work_dir / f"{key}.wav", ffmpeg), None
+        staging = cache.staging_path(key, "wav")
+        try:
+            normalize(raw, staging, ffmpeg)
+            return cache.commit(key, staging, "wav"), None
+        except BaseException:
+            staging.unlink(missing_ok=True)
+            raise
+    finally:
+        # The normalized WAV is the artifact; the raw container is scratch, and
+        # leaving it behind is what made ``tts-cache/work/`` grow forever.
+        raw.unlink(missing_ok=True)
+
+
+def _safe_version(provider) -> str:
+    try:
+        return str(provider.version())
+    except Exception:  # pragma: no cover - a provider must not break on this
+        return "?"
+
+
+# ── Job-level helpers, shared by ``steppy build`` and ``steppy guide`` ───────
+
+
+def voice_jobs(
+    jobs: Sequence,
+    cfg,
+    *,
+    ffmpeg: str,
+    cache_root: Path,
+    work_dir: Path,
+    on_warning: Optional[Callable[[str], None]] = None,
+) -> list:
+    """Voice every job's steps before any browser opens.
+
+    The timeline needs each clip's *duration* up front, to stretch its step so
+    the voiceover is never cut off — which is why this cannot wait until render
+    time. Where each clip is *placed* is a separate question, decided by the
+    timeline and answered by :func:`assemble_track`.
+
+    One home for both entry points: ``steppy build --video`` and
+    ``steppy guide --video`` had byte-identical copies of this, and they had
+    already drifted apart on cache-path resolution. The batch shares one memo,
+    so the desktop and mobile jobs of one guide voice its steps once.
+
+    With ``tts.provider: none`` (the shipped default) this is a no-op.
+    """
+    from dataclasses import replace
+
+    if cfg.provider == "none":
+        return list(jobs)
+
+    memo: dict[str, tuple[Path, int]] = {}
+    voiced: list = []
+    for job in jobs:
+        narration = synthesize_steps(
+            [
+                Utterance(step_id=step["id"], text=(step.get("text") or {}).get(job.locale) or "")
+                for step in job.manifest["steps"]
+            ],
+            cfg,
+            locale=job.locale,
+            work_dir=work_dir,
+            ffmpeg=ffmpeg,
+            cache_root=cache_root,
+            memo=memo,
+            on_warning=on_warning,
+        )
+        voiced.append(
+            job
+            if narration.silent
+            else replace(job, narration_ms=narration.durations_ms, narration_clips=narration.clips)
+        )
+    return voiced
+
+
+def assemble_track(job, cues: list, total_ms: int, dest: Path) -> Optional[Path]:
+    """Lay each step's clip at the offset the timeline gave that step.
+
+    Injected into ``render_videos`` rather than called from it: ``video.py`` is a
+    leaf module that must not import ``steppy.tts``, and the placement rule
+    genuinely belongs to whoever owns the narration.
+    """
+    if not job.narration_clips:
+        return None
+
+    from .track import assemble
+
+    placed = [(int(cue["startMs"]), job.narration_clips.get(cue["stepId"])) for cue in cues]
+    return assemble(placed, total_ms=total_ms, dest=dest)

steppy/tts/cache.py

@@ -0,0 +1,185 @@
+"""Content-addressed clip cache.
+
+Not an optimisation — a correctness-of-cost feature. A cloud provider bills per
+character, and a guide corpus re-synthesized on every CI run would bill for
+text that has not changed since the last release. With the cache, only edited
+narration costs anything.
+
+Lives under ``.steppy/``, never ``output/``, for the same reason ``coverage.db``
+and ``history.jsonl`` do: ``steppy build`` wipes its output directory on every
+run, so a cache there would never survive to be a hit.
+
+**Every write lands atomically.** A clip is written to a sibling temp file and
+``os.replace``d into position, because the failure mode otherwise is permanent:
+a Ctrl-C or a full disk leaves a truncated WAV *at the final key path*, and a
+lookup that only asks ``is_file()`` will serve it forever.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .types import SpeechClip, SpeechRequest
+
+
+@dataclass(frozen=True)
+class CachedClip:
+    path: Path
+    fmt: str
+    duration_ms: Optional[int]
+
+
+def cache_key(request: SpeechRequest, provider: str, version: str) -> str:
+    """Everything that can change the audio, and nothing that cannot.
+
+    ``version`` is load-bearing for the local engines: espeak-ng and Piper
+    produce different audio across builds, so an unversioned key would serve a
+    stale clip whose duration no longer matches the timeline the video was
+    rendered against. For the HTTP engine it also carries a hash of the request
+    shape, so editing ``video.tts.http`` re-synthesizes rather than serving
+    audio the old body produced.
+
+    ``request.text`` is already whitespace-normalized by ``synthesize_steps``,
+    so re-wrapping a YAML block scalar is not a cache miss.
+    """
+    payload = {
+        "provider": provider,
+        "version": version,
+        "text": request.text,
+        "locale": request.locale,
+        "voice": request.voice or "",
+        "model": request.model or "",
+        "speed": round(float(request.speed), 4),
+        "fmt": request.fmt or "",
+        "options": request.options or {},
+    }
+    blob = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+def atomic_replace(source: Path, dest: Path) -> Path:
+    """Move *source* onto *dest* in one indivisible step.
+
+    ``os.replace`` is atomic on NTFS and POSIX alike **as long as both paths sit
+    on the same filesystem** — which is why callers stage their temp file in
+    ``dest.parent`` rather than the system temp dir.
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    os.replace(str(source), str(dest))
+    return dest
+
+
+def atomic_write_bytes(dest: Path, data: bytes) -> Path:
+    return _atomic_write(dest, lambda handle: handle.write(data))
+
+
+def atomic_write_text(dest: Path, text: str) -> Path:
+    return _atomic_write(dest, lambda handle: handle.write(text.encode("utf-8")))
+
+
+def _atomic_write(dest: Path, write) -> Path:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    fd, name = tempfile.mkstemp(dir=str(dest.parent), prefix=f".{dest.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            write(handle)
+        return atomic_replace(Path(name), dest)
+    except BaseException:
+        Path(name).unlink(missing_ok=True)
+        raise
+
+
+def _touch(path: Path) -> None:
+    """Mark an entry as used, so LRU eviction means what it says.
+
+    Without this a clip reused daily for a year looks exactly as stale as one
+    abandoned on day two. Best-effort: a read-only cache is still a usable one.
+    """
+    try:
+        path.touch()
+    except OSError:
+        pass
+
+
+class ClipCache:
+    def __init__(self, root: Path, enabled: bool = True) -> None:
+        self.root = Path(root)
+        self.enabled = enabled
+
+    def _paths(self, key: str, fmt: str) -> tuple[Path, Path]:
+        return self.root / f"{key}.{fmt}", self.root / f"{key}.json"
+
+    def get(self, key: str, fmt: str) -> Optional[CachedClip]:
+        if not self.enabled:
+            return None
+        audio, meta = self._paths(key, fmt)
+        if not audio.is_file():
+            return None
+        duration = None
+        if meta.is_file():
+            try:
+                duration = json.loads(meta.read_text(encoding="utf-8")).get("duration_ms")
+            except (ValueError, OSError):
+                # A torn sidecar just means we re-measure; the audio is still good.
+                duration = None
+            _touch(meta)
+        _touch(audio)
+        return CachedClip(path=audio, fmt=fmt, duration_ms=duration)
+
+    def put(self, key: str, clip: SpeechClip, duration_ms: Optional[int] = None) -> Optional[CachedClip]:
+        """Store raw provider bytes. Returns None when the cache is disabled —
+        there is no path to hand back, because nothing was written."""
+        if not self.enabled:
+            return None
+        audio, _ = self._paths(key, clip.fmt)
+        atomic_write_bytes(audio, clip.audio)
+        self.set_duration(key, clip.fmt, duration_ms)
+        return CachedClip(path=audio, fmt=clip.fmt, duration_ms=duration_ms)
+
+    def commit(self, key: str, source: Path, fmt: str = "wav") -> Path:
+        """Adopt an already-produced file as this key's cache entry.
+
+        The normalize step writes into the cache directory directly (so the
+        transcode is not paid twice), then hands the temp file here to be moved
+        into position — the move being the only moment the entry becomes
+        visible to a lookup.
+        """
+        if not self.enabled:
+            return source
+        audio, _ = self._paths(key, fmt)
+        if source == audio:
+            return audio
+        return atomic_replace(source, audio)
+
+    def set_duration(self, key: str, fmt: str, duration_ms: Optional[int]) -> None:
+        if not self.enabled:
+            return
+        _, meta = self._paths(key, fmt)
+        atomic_write_text(
+            meta,
+            json.dumps({"duration_ms": duration_ms, "format": fmt}, ensure_ascii=False) + "\n",
+        )
+
+    def discard(self, key: str, fmt: str) -> None:
+        """Drop a poisoned entry so the next lookup is an honest miss."""
+        for path in self._paths(key, fmt):
+            try:
+                path.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+    def staging_path(self, key: str, fmt: str) -> Path:
+        """Where a producer should write before calling :meth:`commit`.
+
+        Same directory as the final entry, so ``os.replace`` stays atomic; and
+        pid-suffixed, so two concurrent builds sharing one cache stage into
+        different files and the loser's replace is merely redundant.
+        """
+        self.root.mkdir(parents=True, exist_ok=True)
+        return self.root / f".{key}.{fmt}.{os.getpid()}.tmp"

steppy/tts/presets.py

@@ -0,0 +1,125 @@
+"""Vendor TTS presets — pure data, no logic.
+
+Every cloud text-to-speech API is the same shape: POST some JSON, get audio
+back. So Steppy has one generic HTTP provider and this table of vendor shapes,
+rather than a class per vendor. Adding ElevenLabs' next competitor is a dict
+entry; adding one Steppy has never heard of needs no code at all, just
+``video.tts.http`` filled in directly. That is what makes the promise —
+"change the provider by changing config" — literally true.
+
+Mirrors ``steppy/presets.py`` (the UI-kit selector packs) in both spirit and
+mechanics: a data registry plus a resolver that lets explicitly-set fields win.
+
+**Keep this module free of ``httpx``.** It sits on an import path that reaches
+the default CLI path, and the negative-import guard enforces it.
+
+Placeholders available in any string leaf of ``headers`` / ``json`` / ``body``:
+
+    {text} {voice} {locale} {model} {speed} {api_key} {region}
+
+plus every key of ``video.tts.options``. Substitution happens on the parsed
+structure, never on serialized JSON, so narration containing a brace is safe.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# ``format`` is what the provider returns, not what the user asks for; the audio
+# assembler transcodes to WAV as needed. ``defaults`` fills fields the user left
+# unset — an explicit ``video.tts.model`` always wins.
+TTS_PRESETS: dict[str, dict[str, Any]] = {
+    "elevenlabs": {
+        "url": "https://api.elevenlabs.io/v1/text-to-speech/{voice}",
+        "method": "POST",
+        "headers": {
+            "xi-api-key": "{api_key}",
+            "accept": "audio/mpeg",
+            "content-type": "application/json",
+        },
+        "json": {
+            "text": "{text}",
+            "model_id": "{model}",
+        },
+        "response": "binary",
+        "encoding": "raw",
+        "format": "mp3",
+        "defaults": {
+            # Multilingual by default: a per-locale guide is the normal case here.
+            "model": "eleven_multilingual_v2",
+        },
+        "requires": ["api_key", "voice"],
+        "docs": "https://elevenlabs.io/docs/api-reference/text-to-speech",
+    },
+    "openai": {
+        "url": "{base_url}/audio/speech",
+        "method": "POST",
+        "headers": {
+            "Authorization": "Bearer {api_key}",
+            "content-type": "application/json",
+        },
+        "json": {
+            "model": "{model}",
+            "input": "{text}",
+            "voice": "{voice}",
+            "speed": "{speed}",
+            # WAV keeps the assembler on the stdlib path (no transcode).
+            "response_format": "wav",
+        },
+        "response": "binary",
+        "encoding": "raw",
+        "format": "wav",
+        "defaults": {
+            "model": "gpt-4o-mini-tts",
+            "voice": "alloy",
+            "base_url": "https://api.openai.com/v1",
+        },
+        "requires": ["api_key"],
+        "docs": "https://platform.openai.com/docs/api-reference/audio/createSpeech",
+    },
+    "azure": {
+        "url": "https://{region}.tts.speech.microsoft.com/cognitiveservices/v1",
+        "method": "POST",
+        "headers": {
+            "Ocp-Apim-Subscription-Key": "{api_key}",
+            "Content-Type": "application/ssml+xml",
+            "X-Microsoft-OutputFormat": "riff-24khz-16bit-mono-pcm",
+        },
+        # Azure speaks SSML, not JSON — which is exactly why the engine supports
+        # a raw body as well as a JSON one.
+        "body": (
+            "<speak version='1.0' xml:lang='{locale}'>"
+            "<voice xml:lang='{locale}' name='{voice}'>"
+            "<prosody rate='{speed}'>{text}</prosody>"
+            "</voice></speak>"
+        ),
+        "response": "binary",
+        "encoding": "raw",
+        "format": "wav",
+        "defaults": {},
+        "requires": ["api_key", "region", "voice"],
+        "docs": "https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech",
+    },
+    "google": {
+        "url": "https://texttospeech.googleapis.com/v1/text:synthesize?key={api_key}",
+        "method": "POST",
+        "headers": {"content-type": "application/json"},
+        "json": {
+            "input": {"text": "{text}"},
+            "voice": {"languageCode": "{locale}", "name": "{voice}"},
+            "audioConfig": {"audioEncoding": "LINEAR16", "speakingRate": "{speed}"},
+        },
+        # Google wraps the audio in JSON as base64 rather than returning it raw.
+        "response": "json",
+        "audio_path": "audioContent",
+        "encoding": "base64",
+        "format": "wav",
+        "defaults": {},
+        "requires": ["api_key", "voice"],
+        "docs": "https://cloud.google.com/text-to-speech/docs/reference/rest/v1/text/synthesize",
+    },
+}
+
+
+def available_presets() -> list[str]:
+    return sorted(TTS_PRESETS)

steppy/tts/providers/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in TTS provider implementations.
+
+Imported lazily by ``registry._build_builtin`` so that naming a provider in
+config costs nothing until a video is actually rendered — and so ``httpx`` stays
+off the default CLI path.
+"""