sanotts 0.1.0__tar.gz

sanotts-0.1.0/.gitignore

@@ -0,0 +1,90 @@
+.DS_Store
+.playwright-mcp/
+**/__pycache__/
+*.pyc
+*.egg-info/
+/build/
+
+# Generated model/data artifacts. Keep reproducible scripts and docs in git.
+artifacts/
+*.ckpt
+*.gguf
+*.onnx
+*.onnx.data
+*.pt
+*.pth
+*.safetensors
+*.bin
+*.npz
+*.npy
+*.wav
+*.mp3
+*.flac
+*.m4a
+*.png
+!docs/assets/
+!docs/assets/*.png
+*.jpg
+*.jpeg
+*.webp
+
+# Small, immutable runtime fixtures are deliberately versioned for CI.
+!mcu/test/fixtures/**/*.bin
+
+# WASM demo build outputs (regenerate: bash mcu/ports/wasm/build.sh).
+# The browser demo is hosted on GitHub Pages, so its (small) prebuilt assets
+# and sample audio are deliberately versioned — the un-ignores below re-include
+# them past the global *.mp3 / web/* rules above.
+web/snt_tts.js
+web/snt_tts.wasm
+web/assets/
+!web/snt_tts.js
+!web/snt_tts.wasm
+!web/assets/
+!web/assets/*.bin
+!web/assets/mascots/
+!web/assets/mascots/*.png
+!web/samples/
+!web/samples/*.mp3
+!web/samples-release/
+!web/samples-release/*.mp3
+!web/samples-release/*.json
+!web/snt_g2p.js
+!web/snt_g2p.wasm
+!web/snt_g2p.data
+!web/snt_voice.js
+!web/snt_voice.wasm
+!web/voices/
+!web/voices/**
+
+# Scratch/runtime folders.
+.venv/
+dist/
+logs/
+runs/
+tmp/
+esp32c3/test/emu_out/
+
+# Host build products. Source files with similar names remain tracked.
+/mcu/snt_golden_test
+/mcu/snt_test_*
+/esp32c3/fsd/fsd_e2e_fast
+/esp32c3/fsd/fsd_e2e_frozen
+/esp32c3/fsd/fsd_e2e_full
+/esp32c3/fsd/fsd_e2e_test
+/esp32c3/fsd/fsd_q8_test
+/esp32c3/fsd/fsd_test
+
+# LaTeX build products. Submission PDFs belong in release assets.
+/paper/*.aux
+/paper/*.bbl
+/paper/*.blg
+/paper/*.log
+/paper/*.out
+/paper/*.pdf
+
+# Scratchpad host build outputs.
+scratchpad/**/test_u600_acoustic
+scratchpad/**/test_u600_decoder
+scratchpad/**/test_u600_whole
+scratchpad/**/test_u600_pipe

sanotts-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: sanotts
+Version: 0.1.0
+Summary: Self-contained, numpy-only inference runtime for saanoTTS voice packages.
+License: GPL-3.0-or-later
+Requires-Python: >=3.10
+Requires-Dist: espeakng-loader<1,>=0.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: phonemizer-fork<4,>=3.3
+Description-Content-Type: text/plain
+
+sanotts: pip-installable inference for saanoTTS raw-fp16 voice packages (duration + acoustic + piperlite decoder, numpy-only). Voices are downloaded on demand or loaded from a local directory produced by tools/export_roota_self_contained_package.py.

sanotts-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sanotts"
+version = "0.1.0"
+description = "Self-contained, numpy-only inference runtime for saanoTTS voice packages."
+readme = { text = "sanotts: pip-installable inference for saanoTTS raw-fp16 voice packages (duration + acoustic + piperlite decoder, numpy-only). Voices are downloaded on demand or loaded from a local directory produced by tools/export_roota_self_contained_package.py.", content-type = "text/plain" }
+license = { text = "GPL-3.0-or-later" }
+requires-python = ">=3.10"
+dependencies = [
+  "numpy>=1.24",
+  "phonemizer-fork>=3.3,<4",
+  "espeakng-loader>=0.2,<1",
+]
+
+[project.scripts]
+sanotts = "sanotts.cli:main"
+
+# This directory is not (yet) committed to the parent repo's git tree, so we
+# cannot rely on hatchling's default VCS-tracked-files file selection --
+# without this, `sanotts/tables/*.json` (untracked) would silently be
+# dropped from the wheel. Explicit include instead.
+[tool.hatch.build]
+include = [
+  "sanotts/**/*.py",
+  "sanotts/tables/*.json",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["sanotts"]

sanotts-0.1.0/sanotts/__init__.py

@@ -0,0 +1,34 @@
+"""sanotts: a self-contained, numpy-only saanoTTS inference package.
+
+    import sanotts
+    result = sanotts.synthesize("Hello world", voice="amy")
+    # result.audio: float32 mono waveform in [-1, 1]
+    # result.sample_rate: int, e.g. 22050
+
+For repeated synthesis, reuse a Synthesizer instead of calling
+synthesize() (which reloads the voice pack every time):
+
+    synth = sanotts.Synthesizer(voice="amy")
+    a = synth.synthesize("First sentence.")
+    b = synth.synthesize("Second sentence.")
+
+Voices are resolved either from a local directory (--voice-dir / voice_dir=,
+a package produced by tools/export_roota_self_contained_package.py in the
+saanoTTS research repo) or downloaded by name into ~/.cache/sanotts/.
+"""
+
+from __future__ import annotations
+
+from .engine import SynthesisResult, Synthesizer, synthesize
+from .frontend import FrontendError
+from .voicepack import VoicePackError
+
+__all__ = [
+    "SynthesisResult",
+    "Synthesizer",
+    "synthesize",
+    "FrontendError",
+    "VoicePackError",
+]
+
+__version__ = "0.1.0"

sanotts-0.1.0/sanotts/cli.py

@@ -0,0 +1,81 @@
+"""sanotts command-line interface.
+
+    sanotts say "Hello world" --voice amy -o out.wav
+    sanotts say "Hello world" --voice-dir ./amy-en-1p46m -o out.wav
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import wave
+from pathlib import Path
+
+import numpy as np
+
+from .engine import Synthesizer
+from .frontend import FrontendError
+from .voicepack import VoicePackError
+
+
+def write_wav(path: Path, audio: np.ndarray, sample_rate: int) -> None:
+    audio = np.clip(np.asarray(audio, dtype=np.float32), -1.0, 1.0)
+    pcm16 = (audio * 32767.0).astype("<i2")
+    with wave.open(str(path), "wb") as handle:
+        handle.setnchannels(1)
+        handle.setsampwidth(2)
+        handle.setframerate(sample_rate)
+        handle.writeframes(pcm16.tobytes())
+
+
+def _add_say_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("text", help="Text to synthesize.")
+    voice_group = parser.add_mutually_exclusive_group(required=True)
+    voice_group.add_argument("--voice", help="Named voice to download/use from the cache, e.g. 'amy'.")
+    voice_group.add_argument("--voice-dir", type=Path, help="Local voice package directory (has manifest.json).")
+    parser.add_argument("-o", "--out", type=Path, default=Path("out.wav"), help="Output WAV path (default: out.wav).")
+    parser.add_argument("--cache-dir", type=Path, default=None, help="Override the voice download cache directory.")
+    parser.add_argument(
+        "--duration-length-scale",
+        type=float,
+        default=None,
+        help="Override the voice's default speaking-rate scale (>0; larger = slower).",
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="Enable info-level logging.")
+
+
+def _run_say(args: argparse.Namespace) -> int:
+    logging.basicConfig(level=logging.INFO if args.verbose else logging.WARNING, format="%(name)s: %(message)s")
+    try:
+        synth = Synthesizer(args.voice, voice_dir=args.voice_dir, cache_dir=args.cache_dir)
+        result = synth.synthesize(args.text, duration_length_scale=args.duration_length_scale)
+    except (FrontendError, VoicePackError, ValueError, RuntimeError, NotImplementedError) as exc:
+        print(f"sanotts: error: {exc}", file=sys.stderr)
+        return 1
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    write_wav(args.out, result.audio, result.sample_rate)
+    duration_s = result.audio.shape[-1] / float(result.sample_rate)
+    print(f"sanotts: wrote {args.out} ({duration_s:.2f}s at {result.sample_rate} Hz)")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="sanotts", description="Self-contained saanoTTS inference CLI.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    say_parser = subparsers.add_parser("say", help="Synthesize text to a WAV file.")
+    _add_say_args(say_parser)
+    say_parser.set_defaults(func=_run_say)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sanotts-0.1.0/sanotts/engine.py

@@ -0,0 +1,76 @@
+"""Ties the frontend, voice pack, and numpy models into one synthesizer."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from . import frontend, models, voicepack
+
+logger = logging.getLogger("sanotts.engine")
+
+
+@dataclass(frozen=True)
+class SynthesisResult:
+    audio: np.ndarray
+    sample_rate: int
+
+    def __array__(self, dtype=None) -> np.ndarray:  # convenience: np.asarray(result) just works
+        return self.audio if dtype is None else self.audio.astype(dtype)
+
+
+class Synthesizer:
+    """A loaded voice, ready to render text repeatedly without re-reading disk."""
+
+    def __init__(
+        self,
+        voice: str | None = None,
+        *,
+        voice_dir: str | Path | None = None,
+        cache_dir: str | Path | None = None,
+    ) -> None:
+        self.pack = voicepack.load_voice(voice, voice_dir=voice_dir, cache_dir=cache_dir)
+        self.phoneme_table = frontend.load_phoneme_table(self.pack.phoneme_config_path)
+
+        self._duration_tensors = self.pack.component_tensors("duration")
+        self._duration_config = self.pack.component_config("duration")
+        self._acoustic_tensors = self.pack.component_tensors("acoustic")
+        self._acoustic_config = self.pack.component_config("acoustic")
+        self._decoder_tensors = self.pack.component_tensors("decoder")
+        self._decoder_config = self.pack.component_config("decoder")
+
+    @property
+    def sample_rate(self) -> int:
+        return self.pack.sample_rate
+
+    def synthesize(self, text: str, *, duration_length_scale: float | None = None) -> SynthesisResult:
+        scale = float(duration_length_scale) if duration_length_scale is not None else self.pack.duration_length_scale
+        if scale <= 0.0:
+            raise ValueError(f"duration_length_scale must be positive, got {scale}")
+
+        ids = frontend.text_to_phoneme_ids(text, self.phoneme_table)
+        durations = models.duration_forward(
+            self._duration_tensors, self._duration_config, ids, length_scale=scale
+        )
+        latent = models.acoustic_forward(self._acoustic_tensors, self._acoustic_config, ids, durations)
+        audio = models.decoder_forward(self._decoder_tensors, self._decoder_config, latent)
+        audio = np.clip(audio, -1.0, 1.0).astype(np.float32)
+        return SynthesisResult(audio=audio, sample_rate=self.sample_rate)
+
+
+def synthesize(
+    text: str,
+    voice: str | None = None,
+    *,
+    voice_dir: str | Path | None = None,
+    cache_dir: str | Path | None = None,
+    duration_length_scale: float | None = None,
+) -> SynthesisResult:
+    """One-shot convenience wrapper. For synthesizing many strings with the
+    same voice, construct a `Synthesizer` once instead -- it amortizes the
+    (much slower) weight-loading and phonemizer-initialization cost."""
+    synth = Synthesizer(voice, voice_dir=voice_dir, cache_dir=cache_dir)
+    return synth.synthesize(text, duration_length_scale=duration_length_scale)

sanotts-0.1.0/sanotts/frontend.py

@@ -0,0 +1,284 @@
+"""Text -> Piper phoneme-id frontend.
+
+Mirrors the exact algorithm used by ``piper.phonemize_espeak`` /
+``piper.phoneme_ids`` (see the upstream piper1-gpl project) without
+depending on the ``piper-tts`` package itself (that package pulls in
+onnxruntime as a hard dependency and expects a full ONNX voice to be
+loaded before it will phonemize anything).
+
+Instead we drive the same underlying espeak-ng shared library through
+``phonemizer-fork`` + ``espeakng-loader``, then apply the exact
+NFD-decompose-to-codepoints and ``phonemes_to_ids`` framing rules that
+piper uses. This has been verified byte-for-byte against
+``piper.voice.PiperVoice.phonemize`` / ``.phonemes_to_ids`` for
+representative English sentences (see the package's gate test) -- the
+key ingredients are ``with_stress=True``, ``tie=False``,
+``preserve_punctuation=True`` (with piper's own punctuation set) and
+``language_switch="remove-flags"``, plus a final ``rstrip()`` before
+NFD decomposition (phonemizer emits a trailing space that piper does
+not).
+
+Known espeakng-loader pitfall (see project memory): some published
+``espeakng-loader`` wheels report a data path via
+``get_data_path()`` that looks valid on disk but the bundled dylib
+silently ignores it and falls back to a baked-in build-time path from
+the wheel's CI runner (e.g.
+``/Users/runner/work/espeakng-loader/.../espeak-ng-data``), which does
+not exist on the end user's machine. We defend against this by
+actually trying to construct a working backend for each data-path
+candidate (loader path, then common system install locations) instead
+of trusting ``os.path.exists`` alone.
+"""
+
+from __future__ import annotations
+
+import glob
+import logging
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+logger = logging.getLogger("sanotts.frontend")
+
+# Framing ids fixed by the Piper phoneme_id_map convention; every voice's
+# piper-phoneme-config.json must agree (checked in load_phoneme_table).
+PAD_ID = 0
+BOS_ID = 1
+EOS_ID = 2
+
+# Piper's own punctuation set (phoneme_id_map keys that are ASCII
+# punctuation rather than IPA symbols). Passed to phonemizer so
+# preserve_punctuation keeps exactly these and nothing extra.
+PUNCTUATION_MARKS = "!'(),-.:;?\""
+
+_DATA_PATH_CANDIDATES: list[str] = [
+    # Homebrew (macOS arm64/x86_64) -- versioned Cellar path, resolved via glob.
+    "/opt/homebrew/Cellar/espeak-ng/*/share/espeak-ng-data",
+    "/opt/homebrew/share/espeak-ng-data",
+    "/usr/local/share/espeak-ng-data",
+    "/usr/share/espeak-ng-data",
+    "/usr/lib/x86_64-linux-gnu/espeak-ng-data",
+]
+
+
+class FrontendError(RuntimeError):
+    """Raised when the espeak-ng backend cannot be initialized or used."""
+
+
+@dataclass(frozen=True)
+class PhonemeTable:
+    """A single voice's codepoint -> Piper phoneme-id map."""
+
+    espeak_voice: str
+    id_map: dict[str, int]
+
+
+def load_phoneme_table(piper_config_path: Path) -> PhonemeTable:
+    """Parse a Piper ``*.onnx.json`` / ``piper-phoneme-config.json`` file.
+
+    Raises FrontendError if the file does not have the exact shape we
+    depend on (single-codepoint keys, single-id values, and the
+    pad/bos/eos framing ids piper hardcodes).
+    """
+    import json
+
+    if not piper_config_path.is_file():
+        raise FrontendError(f"phoneme config not found: {piper_config_path}")
+    with piper_config_path.open("r", encoding="utf-8") as handle:
+        config = json.load(handle)
+
+    phoneme_type = config.get("phoneme_type", "espeak")
+    if phoneme_type not in (None, "espeak"):
+        raise FrontendError(f"{piper_config_path}: unsupported phoneme_type={phoneme_type!r}")
+
+    espeak_cfg = config.get("espeak") or {}
+    espeak_voice = espeak_cfg.get("voice")
+    if not espeak_voice:
+        raise FrontendError(f"{piper_config_path}: missing espeak.voice")
+
+    raw_map = config.get("phoneme_id_map")
+    if not isinstance(raw_map, dict) or not raw_map:
+        raise FrontendError(f"{piper_config_path}: missing/empty phoneme_id_map")
+
+    id_map: dict[str, int] = {}
+    for key, ids in raw_map.items():
+        if len(key) != 1:
+            raise FrontendError(f"{piper_config_path}: multi-codepoint map key {key!r}")
+        if not isinstance(ids, list) or len(ids) != 1:
+            raise FrontendError(f"{piper_config_path}: multi-id map value {key!r} -> {ids!r}")
+        id_map[key] = int(ids[0])
+
+    for sym, want in (("_", PAD_ID), ("^", BOS_ID), ("$", EOS_ID)):
+        got = id_map.get(sym)
+        if got != want:
+            raise FrontendError(
+                f"{piper_config_path}: framing symbol {sym!r} maps to {got}, expected {want}"
+            )
+
+    return PhonemeTable(espeak_voice=str(espeak_voice), id_map=id_map)
+
+
+class EspeakEngine:
+    """Lazily-initialized espeak-ng backend, shared across voices.
+
+    One process-wide instance is enough: phonemizer's EspeakBackend
+    takes the target espeak voice as a constructor argument, so we
+    cache one backend per requested espeak voice string.
+    """
+
+    def __init__(self) -> None:
+        self._configured = False
+        self._backends: dict[str, Any] = {}
+
+    def _configure_once(self) -> None:
+        if self._configured:
+            return
+        try:
+            import espeakng_loader
+        except ImportError as exc:  # pragma: no cover - dependency missing
+            raise FrontendError(
+                "the 'espeakng-loader' package is required for phonemization; "
+                "install it with `pip install espeakng-loader`"
+            ) from exc
+        try:
+            from phonemizer.backend import EspeakBackend
+            from phonemizer.backend.espeak.wrapper import EspeakWrapper
+        except ImportError as exc:  # pragma: no cover - dependency missing
+            raise FrontendError(
+                "the 'phonemizer-fork' package is required for phonemization; "
+                "install it with `pip install phonemizer-fork`"
+            ) from exc
+
+        library_path = espeakng_loader.get_library_path()
+        data_candidates = [espeakng_loader.get_data_path()]
+        for pattern in _DATA_PATH_CANDIDATES:
+            data_candidates.extend(sorted(glob.glob(pattern)))
+
+        last_error: Exception | None = None
+        for data_path in data_candidates:
+            if not data_path or not Path(data_path).is_dir():
+                continue
+            try:
+                EspeakWrapper.set_library(library_path)
+                EspeakWrapper.set_data_path(data_path)
+                # Constructing a throwaway backend exercises espeak_Initialize
+                # end to end; a bad data path raises here rather than later
+                # inside phonemize(), matching the documented loader pitfall.
+                probe = EspeakBackend(
+                    "en-us",
+                    preserve_punctuation=True,
+                    with_stress=True,
+                    tie=False,
+                    language_switch="remove-flags",
+                )
+                probe.phonemize(["a"], strip=False, separator=None)
+            except Exception as exc:  # noqa: BLE001 - probing many candidates on purpose
+                last_error = exc
+                logger.debug("espeak data path candidate failed: %s (%s)", data_path, exc)
+                continue
+            logger.info("sanotts: using espeak-ng data path %s", data_path)
+            self._configured = True
+            return
+
+        raise FrontendError(
+            "could not initialize espeak-ng: no working espeak-ng-data directory found. "
+            "Tried the espeakng-loader bundled path plus common system locations "
+            f"({', '.join(_DATA_PATH_CANDIDATES)}). This is a known espeakng-loader "
+            "packaging issue where the wheel's compiled-in default path does not match "
+            "the data it ships. Fix: `brew install espeak-ng` (macOS) or "
+            "`apt-get install espeak-ng` (Debian/Ubuntu), then retry."
+        ) from last_error
+
+    def backend(self, espeak_voice: str) -> Any:
+        self._configure_once()
+        cached = self._backends.get(espeak_voice)
+        if cached is not None:
+            return cached
+        from phonemizer.backend import EspeakBackend
+
+        # Some older voice packages (e.g. kristin) were trained against an
+        # espeak-ng version where a bare language code like "en" was a
+        # directly selectable voice. Newer espeak-ng only exposes regional
+        # variants (en-us, en-gb, ...) as primary voices -- "en" now only
+        # appears as a secondary/"other language" tag, so EspeakBackend("en")
+        # raises. Retry with a regional variant rather than failing outright;
+        # this is a voice-*selection* compatibility shim only (it changes
+        # which accent espeak uses), not a phoneme-table substitution.
+        candidates = [espeak_voice]
+        if "-" not in espeak_voice:
+            candidates += [f"{espeak_voice}-us", f"{espeak_voice}-gb"]
+
+        last_error: Exception | None = None
+        for candidate in candidates:
+            try:
+                backend = EspeakBackend(
+                    candidate,
+                    preserve_punctuation=True,
+                    punctuation_marks=PUNCTUATION_MARKS,
+                    with_stress=True,
+                    tie=False,
+                    language_switch="remove-flags",
+                )
+            except Exception as exc:  # noqa: BLE001 - trying multiple voice-name spellings
+                last_error = exc
+                continue
+            if candidate != espeak_voice:
+                logger.warning(
+                    "sanotts: espeak voice %r unavailable in this espeak-ng build, "
+                    "using %r instead (phoneme/accent may differ slightly from training)",
+                    espeak_voice, candidate,
+                )
+            self._backends[espeak_voice] = backend
+            return backend
+        raise FrontendError(
+            f"espeak-ng has no voice matching {espeak_voice!r} (tried {candidates})"
+        ) from last_error
+
+    def phonemize(self, text: str, espeak_voice: str) -> str:
+        backend = self.backend(espeak_voice)
+        out = backend.phonemize([text], strip=False, separator=None)
+        if not out or not out[0]:
+            raise FrontendError(f"espeak-ng produced no phonemes for text: {text!r}")
+        # phonemizer appends a trailing separator space that piper's own
+        # clause-based espeakbridge does not emit at true end-of-input.
+        return out[0].rstrip()
+
+
+_ENGINE = EspeakEngine()
+
+
+def phonemes_to_ids(phonemes: list[str], table: PhonemeTable) -> list[int]:
+    """Reproduce piper.phoneme_ids.phonemes_to_ids exactly:
+
+    bos, pad, then (id, pad) per phoneme, then eos. Phonemes missing from
+    the table are skipped with a warning, matching piper's behavior.
+    """
+    ids: list[int] = [BOS_ID, PAD_ID]
+    missing = 0
+    for phoneme in phonemes:
+        pid = table.id_map.get(phoneme)
+        if pid is None:
+            missing += 1
+            continue
+        ids.append(pid)
+        ids.append(PAD_ID)
+    if missing:
+        logger.warning("sanotts: %d phoneme(s) missing from the voice's phoneme_id_map, skipped", missing)
+    ids.append(EOS_ID)
+    return ids
+
+
+def text_to_phoneme_ids(text: str, table: PhonemeTable) -> np.ndarray:
+    """Full text -> Piper phoneme-id array, matching PiperVoice exactly."""
+    clean_text = text.strip()
+    if not clean_text:
+        raise FrontendError("text is empty")
+    phonemized = _ENGINE.phonemize(clean_text, table.espeak_voice)
+    phonemes = list(unicodedata.normalize("NFD", phonemized))
+    ids = phonemes_to_ids(phonemes, table)
+    if len(ids) <= 3:
+        raise FrontendError(f"phonemization produced no usable phonemes for: {text!r}")
+    return np.asarray(ids, dtype=np.int64)

sanotts-0.1.0/sanotts/models.py

@@ -0,0 +1,401 @@
+"""Pure-numpy forward passes for the saanoTTS Root-A student stack.
+
+These mirror the fp32 reference C runtime (mcu/src/snt_front_f32.c and
+mcu/src/snt_piperlite.c in the parent research repo), which itself was
+ported from the PyTorch training code (tools/train_roota_piper_duration_student.py,
+tools/train_roota_piper_latent_student.py, tools/train_roota_piper_decoder_student.py)
+and gated against it at correlation 1.0. Operation *order* here does not need to be
+bit-identical to either reference (numpy's BLAS-backed matmuls accumulate in a
+different order than the scalar C loops or PyTorch's cuDNN/MKL kernels), only
+numerically equivalent -- differences are float32-rounding-noise sized, far below
+the >0.99 waveform-correlation gate this package is held to.
+
+Only the subgraphs actually observed in the shipped voice packages
+(architecture="duration_conv" / "token_context", decoder variant="piperlite",
+stage*_branches=[0,1,2], no output adapter) are implemented. Anything else
+raises NotImplementedError rather than guessing at an unverified tensor layout.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import numpy as np
+
+logger = logging.getLogger("sanotts.models")
+
+# Fallback id used when a phoneme id from the frontend's (larger, shared)
+# codepoint table exceeds a specific component's trained vocab_size. Schwa
+# is a safe, neutral, always-in-vocab choice -- the same fallback used by
+# the ESP32/WASM ports for the analogous duration/acoustic vocab mismatch.
+_SCHWA_FALLBACK_ID = 59
+
+
+def clamp_ids_to_vocab(ids: np.ndarray, vocab_size: int, *, label: str) -> np.ndarray:
+    ids = np.asarray(ids, dtype=np.int64)
+    out_of_range = (ids < 0) | (ids >= vocab_size)
+    if np.any(out_of_range):
+        n = int(out_of_range.sum())
+        fallback = _SCHWA_FALLBACK_ID if _SCHWA_FALLBACK_ID < vocab_size else 0
+        logger.warning(
+            "sanotts: %d/%d %s ids fall outside vocab_size=%d, remapping to id=%d",
+            n, ids.size, label, vocab_size, fallback,
+        )
+        ids = np.where(out_of_range, fallback, ids)
+    return ids
+
+
+def silu(x: np.ndarray) -> np.ndarray:
+    return x / (1.0 + np.exp(-x))
+
+
+def leaky_relu(x: np.ndarray, slope: float) -> np.ndarray:
+    return np.where(x > 0.0, x, slope * x)
+
+
+def linspace01(n: int) -> np.ndarray:
+    if n <= 0:
+        return np.zeros((0,), dtype=np.float32)
+    if n == 1:
+        return np.zeros((1,), dtype=np.float32)
+    return np.linspace(0.0, 1.0, n, dtype=np.float64).astype(np.float32)
+
+
+def conv1d_same(
+    x: np.ndarray,
+    weight: np.ndarray,
+    bias: np.ndarray,
+    *,
+    dilation: int = 1,
+) -> np.ndarray:
+    """PyTorch Conv1d "same"-padding semantics: pad = dilation*(K//2).
+
+    x: [in_ch, T]; weight: [out_ch, in_ch, K]; bias: [out_ch].
+    Returns [out_ch, T].
+    """
+    in_ch, T = x.shape
+    out_ch, in_ch_w, K = weight.shape
+    if in_ch_w != in_ch:
+        raise ValueError(f"conv1d_same: channel mismatch {in_ch_w} != {in_ch}")
+    pad = dilation * (K // 2)
+    out = np.broadcast_to(bias[:, None].astype(np.float32), (out_ch, T)).copy()
+    for k in range(K):
+        off = k * dilation - pad
+        lo = max(0, -off)
+        hi = min(T, T - off)
+        if hi <= lo:
+            continue
+        # out[:, lo:hi] += weight[:, :, k] @ x[:, lo+off:hi+off]
+        out[:, lo:hi] += weight[:, :, k] @ x[:, lo + off:hi + off]
+    return out
+
+
+def conv1d_1x1(x: np.ndarray, weight: np.ndarray, bias: np.ndarray) -> np.ndarray:
+    """Conv1d with kernel_size=1: a plain per-timestep linear projection."""
+    w = weight[:, :, 0] if weight.ndim == 3 else weight
+    return w @ x + bias[:, None]
+
+
+def depthwise_conv1d_same(x: np.ndarray, weight: np.ndarray) -> np.ndarray:
+    """Depthwise Conv1d, no bias. x: [C, T]; weight: [C, K] (or [C,1,K])."""
+    if weight.ndim == 3:
+        weight = weight[:, 0, :]
+    C, T = x.shape
+    _, K = weight.shape
+    pad = K // 2
+    out = np.zeros_like(x)
+    for k in range(K):
+        off = k - pad
+        lo = max(0, -off)
+        hi = min(T, T - off)
+        if hi <= lo:
+            continue
+        out[:, lo:hi] += weight[:, k:k + 1] * x[:, lo + off:hi + off]
+    return out
+
+
+def conv_transpose1d(
+    x: np.ndarray,
+    weight: np.ndarray,
+    bias: np.ndarray,
+    *,
+    stride: int,
+    padding: int,
+) -> np.ndarray:
+    """PyTorch ConvTranspose1d. x: [in_ch, T]; weight: [in_ch, out_ch, K]; bias: [out_ch].
+
+    out[oc, t*stride + k - padding] += weight[ic, oc, k] * x[ic, t], summed over ic, k;
+    output length L = (T - 1) * stride - 2 * padding + K.
+    """
+    in_ch, T = x.shape
+    in_ch_w, out_ch, K = weight.shape
+    if in_ch_w != in_ch:
+        raise ValueError(f"conv_transpose1d: channel mismatch {in_ch_w} != {in_ch}")
+    L = (T - 1) * stride - 2 * padding + K
+    out = np.broadcast_to(bias[:, None].astype(np.float32), (out_ch, L)).copy()
+    for k in range(K):
+        shift = k - padding
+        if shift >= L:
+            continue
+        t_lo = 0
+        if shift < 0:
+            t_lo = (-shift + stride - 1) // stride
+        t_hi = (L - 1 - shift) // stride + 1
+        t_hi = min(t_hi, T)
+        if t_hi <= t_lo:
+            continue
+        count = t_hi - t_lo
+        j_start = t_lo * stride + shift
+        j_end = j_start + (count - 1) * stride + 1
+        contrib = weight[:, :, k].T @ x[:, t_lo:t_hi]  # [out_ch, count]
+        out[:, j_start:j_end:stride] += contrib
+    return out
+
+
+def residual_conv_block(
+    x: np.ndarray,
+    tensors: dict[str, np.ndarray],
+    prefix: str,
+) -> np.ndarray:
+    """One ResidualConvBlock: x + scale * conv2(silu(conv1(x))). Kernel/pad same as x.
+
+    Kernel size is read from the weight tensor itself (weight.shape[-1]), not
+    passed in, so this always matches whatever the checkpoint actually stored.
+    """
+    scale = float(tensors[f"{prefix}.scale"][0])
+    t = conv1d_same(x, tensors[f"{prefix}.net.0.weight"], tensors[f"{prefix}.net.0.bias"])
+    t = silu(t)
+    u = conv1d_same(t, tensors[f"{prefix}.net.2.weight"], tensors[f"{prefix}.net.2.bias"])
+    return x + scale * u
+
+
+# --------------------------------------------------------------------------
+# Duration student ("architecture": "duration_conv" in the manifest)
+# --------------------------------------------------------------------------
+
+def duration_forward(
+    tensors: dict[str, np.ndarray],
+    config: dict[str, Any],
+    ids: np.ndarray,
+    *,
+    length_scale: float,
+) -> np.ndarray:
+    architecture = str(config.get("architecture") or "")
+    if architecture != "duration_conv":
+        raise NotImplementedError(f"unsupported duration architecture: {architecture!r}")
+
+    vocab_size = int(config["vocab_size"])
+    hidden = int(config["hidden"])
+    depth = int(config["depth"])
+    max_tokens = int(config["max_tokens"])
+    max_duration = int(config["max_duration"])
+
+    ids = clamp_ids_to_vocab(ids, vocab_size, label="duration")
+    n = ids.shape[0]
+    if n <= 0:
+        raise ValueError("duration_forward: empty id sequence")
+
+    embed = tensors["embedding.weight"]  # [vocab, hidden]
+    if embed.shape != (vocab_size, hidden):
+        raise RuntimeError(f"duration embedding shape {embed.shape} != config ({vocab_size}, {hidden})")
+    token_x = embed[ids].T  # [hidden, n]
+
+    positions = linspace01(n)
+    length_hint = np.float32(np.log1p(np.float64(n)) / np.log1p(np.float64(max_tokens)))
+    valid_hint = np.ones((n,), dtype=np.float32)
+    features = np.stack([positions, np.full((n,), length_hint, dtype=np.float32), valid_hint], axis=0)
+
+    x = conv1d_1x1(
+        np.concatenate([token_x, features], axis=0),
+        tensors["input_proj.weight"],
+        tensors["input_proj.bias"],
+    )
+    for i in range(depth):
+        x = residual_conv_block(x, tensors, f"blocks.{i}")
+
+    log_duration = conv1d_1x1(x, tensors["output.weight"], tensors["output.bias"])[0]  # [n]
+
+    duration = np.exp(log_duration)
+    duration = np.clip(duration, 1.0, None)
+    duration = np.round(duration * float(length_scale))
+    duration = np.clip(duration, 1.0, float(max_duration))
+    return duration.astype(np.int64)
+
+
+# --------------------------------------------------------------------------
+# Acoustic student ("architecture": "token_context" in the manifest)
+# --------------------------------------------------------------------------
+
+def acoustic_forward(
+    tensors: dict[str, np.ndarray],
+    config: dict[str, Any],
+    ids: np.ndarray,
+    durations: np.ndarray,
+) -> np.ndarray:
+    architecture = str(config.get("architecture") or "")
+    if architecture != "token_context":
+        raise NotImplementedError(f"unsupported acoustic architecture: {architecture!r}")
+    unexpected_adapter_keys = [name for name in tensors if "adapter" in name]
+    if unexpected_adapter_keys:
+        raise NotImplementedError(
+            "acoustic checkpoint has an output adapter "
+            f"({unexpected_adapter_keys}); this package only implements the "
+            "adapter-free token_context path verified against the shipped voices"
+        )
+
+    vocab_size = int(config["vocab_size"])
+    hidden = int(config["hidden"])
+    depth = int(config["depth"])
+    token_depth = int(config["token_depth"])
+    out_channels = int(config["out_channels"])
+
+    ids = clamp_ids_to_vocab(ids, vocab_size, label="acoustic")
+    durations = np.asarray(durations, dtype=np.int64)
+    if durations.shape != ids.shape:
+        raise ValueError("acoustic_forward: id/duration shape mismatch")
+    if np.any(durations < 1):
+        raise ValueError("acoustic_forward: non-positive duration")
+
+    n = int(ids.shape[0])
+    frames = int(durations.sum())
+
+    # -- token stage --
+    embed = tensors["embedding.weight"]
+    if embed.shape != (vocab_size, hidden):
+        raise RuntimeError(f"acoustic embedding shape {embed.shape} != config ({vocab_size}, {hidden})")
+    token_x = embed[ids].T  # [hidden, n]
+    token_pos = linspace01(n)
+    durations_f = durations.astype(np.float64)
+    max_duration = max(float(durations_f.max()), 1.0)
+    duration_hint = (np.log1p(durations_f) / np.log1p(max_duration)).astype(np.float32)
+    token_features = np.stack([token_pos, duration_hint], axis=0)
+
+    token_x = conv1d_1x1(
+        np.concatenate([token_x, token_features], axis=0),
+        tensors["token_input_proj.weight"],
+        tensors["token_input_proj.bias"],
+    )
+    for i in range(token_depth):
+        token_x = residual_conv_block(token_x, tensors, f"token_blocks.{i}")
+
+    # -- expand token context to frames --
+    expanded = np.repeat(token_x, durations, axis=1)  # [hidden, frames]
+    if expanded.shape[1] != frames:
+        raise RuntimeError("acoustic_forward: context expansion length mismatch")
+
+    frame_pos = linspace01(frames)
+    token_count = max(n - 1, 1)
+    token_pos_frame = np.empty((frames,), dtype=np.float32)
+    duration_pos_frame = np.empty((frames,), dtype=np.float32)
+    pos = 0
+    for token_index in range(n):
+        d = int(durations[token_index])
+        if d <= 0:
+            continue
+        token_pos_frame[pos:pos + d] = np.float32(float(token_index) / float(token_count))
+        if d == 1:
+            duration_pos_frame[pos] = 0.0
+        else:
+            duration_pos_frame[pos:pos + d] = (
+                np.arange(d, dtype=np.float64) / np.float64(d - 1)
+            ).astype(np.float32)
+        pos += d
+
+    frame_features = np.stack([frame_pos, token_pos_frame, duration_pos_frame], axis=0)
+    x = conv1d_1x1(
+        np.concatenate([expanded, frame_features], axis=0),
+        tensors["frame_input_proj.weight"],
+        tensors["frame_input_proj.bias"],
+    )
+    for i in range(depth):
+        x = residual_conv_block(x, tensors, f"frame_blocks.{i}")
+
+    latent = conv1d_1x1(x, tensors["output.weight"], tensors["output.bias"])
+    if latent.shape[0] != out_channels:
+        raise RuntimeError("acoustic_forward: unexpected output channel count")
+    return latent.astype(np.float32)  # [out_channels, frames]
+
+
+# --------------------------------------------------------------------------
+# Decoder student ("variant": "piperlite" in the manifest)
+# --------------------------------------------------------------------------
+
+_BANK_KERNELS = (3, 5, 7)
+_BANK_DIL1 = (1, 2, 3)
+_BANK_DIL2 = (2, 6, 12)
+
+
+def _residual_bank(x: np.ndarray, tensors: dict[str, np.ndarray], prefix: str, branches: list[int]) -> np.ndarray:
+    """PiperResidualBank: mean over active branches of
+    y2 = conv2(lrelu(y1, 0.1)) + y1, y1 = conv1(lrelu(x, 0.1)) + x.
+    """
+    acc = np.zeros_like(x)
+    for branch in branches:
+        k = _BANK_KERNELS[branch]
+        d1 = _BANK_DIL1[branch]
+        d2 = _BANK_DIL2[branch]
+        t = leaky_relu(x, 0.1)
+        u = conv1d_same(t, tensors[f"{prefix}.blocks.{branch}.conv1.weight"], tensors[f"{prefix}.blocks.{branch}.conv1.bias"], dilation=d1)
+        y1 = u + x
+        t2 = leaky_relu(y1, 0.1)
+        u2 = conv1d_same(t2, tensors[f"{prefix}.blocks.{branch}.conv2.weight"], tensors[f"{prefix}.blocks.{branch}.conv2.bias"], dilation=d2)
+        y2 = u2 + y1
+        acc = acc + y2
+    return acc / float(len(branches))
+
+
+def _apply_post_filter(audio: np.ndarray, tensors: dict[str, np.ndarray], config: dict[str, Any]) -> np.ndarray:
+    channels = int(config.get("post_filter_channels") or 0)
+    layers = int(config.get("post_filter_layers") or 0)
+    kernel = int(config.get("post_filter_kernel") or 9)
+    scale = float(config.get("post_filter_scale") or 0.0)
+    if channels <= 0:
+        return audio
+
+    r = conv1d_same(audio[None, :], tensors["post_filter.in_conv.weight"], tensors["post_filter.in_conv.bias"])
+    for layer in range(layers):
+        unit_scale = float(tensors[f"post_filter.units.{layer}.scale"][0])
+        t = leaky_relu(r, 0.1)
+        u = conv1d_same(t, tensors[f"post_filter.units.{layer}.conv1.weight"], tensors[f"post_filter.units.{layer}.conv1.bias"], dilation=1 + layer)
+        t = leaky_relu(u, 0.1)
+        u2 = conv1d_same(t, tensors[f"post_filter.units.{layer}.conv2.weight"], tensors[f"post_filter.units.{layer}.conv2.bias"], dilation=1)
+        r = r + unit_scale * u2
+    out = conv1d_same(r, tensors["post_filter.out_conv.weight"], tensors["post_filter.out_conv.bias"])[0]
+    return np.tanh(audio + scale * out).astype(np.float32)
+
+
+def decoder_forward(tensors: dict[str, np.ndarray], config: dict[str, Any], latent: np.ndarray) -> np.ndarray:
+    variant = str(config.get("variant") or "")
+    if variant != "piperlite":
+        raise NotImplementedError(f"unsupported decoder variant: {variant!r}")
+    if str(config.get("activation") or "leaky_relu") != "leaky_relu":
+        raise NotImplementedError("only activation='leaky_relu' decoders are implemented")
+    if float(config.get("pre_tanh_repair_channels") or 0) > 0:
+        raise NotImplementedError("pre_tanh_repair is not implemented (no shipped voice uses it)")
+    res_layers = int(config.get("res_layers") or 1)
+    if res_layers != 1:
+        raise NotImplementedError(f"only res_layers=1 is implemented, got {res_layers}")
+
+    channels = config["channels"]
+    c0, c1, c2, c3 = (int(c) for c in channels[:4])
+
+    x = conv1d_same(latent, tensors["pre.weight"], tensors["pre.bias"])  # [c0, frames]
+
+    stage_specs = [
+        (c0, c1, 16, 8, 4, "up0", "res0.0", config.get("stage0_branches")),
+        (c1, c2, 16, 8, 4, "up1", "res1.0", config.get("stage1_branches")),
+        (c2, c3, 8, 4, 2, "up2", "res2.0", config.get("stage2_branches")),
+    ]
+    for in_c, out_c, up_k, up_s, up_p, up_name, bank_prefix, branches in stage_specs:
+        if branches is None:
+            branches = [0, 1, 2]
+        x = leaky_relu(x, 0.1)
+        x = conv_transpose1d(x, tensors[f"{up_name}.weight"], tensors[f"{up_name}.bias"], stride=up_s, padding=up_p)
+        x = _residual_bank(x, tensors, bank_prefix, list(branches))
+
+    x = leaky_relu(x, 0.01)
+    audio = conv1d_same(x, tensors["post.weight"], tensors["post.bias"])[0]
+    audio = np.tanh(audio).astype(np.float32)
+    audio = _apply_post_filter(audio, tensors, config)
+    return audio

sanotts-0.1.0/sanotts/tables/voices.json

@@ -0,0 +1,12 @@
+{
+  "_comment": "Alias -> release package name for VOICE_RELEASE_BASE_URL/<package>.tar.gz downloads. Package names match the directories under releases/multivoice-20260713 in the saanoTTS research repo, which is what tools/export_roota_self_contained_package.py produces per voice.",
+  "voices": {
+    "amy": { "package": "amy-en-1p46m", "language": "en_US", "sample_rate": 22050 },
+    "amy-1p1m": { "package": "amy-en-1p1m", "language": "en_US", "sample_rate": 22050 },
+    "amy-1p8m": { "package": "amy-en-1p8m", "language": "en_US", "sample_rate": 22050 },
+    "hfc": { "package": "hfc-en-1p8m", "language": "en_US", "sample_rate": 22050 },
+    "kristin": { "package": "kristin-en-1p4m", "language": "en_US", "sample_rate": 22050 },
+    "vi": { "package": "vi-vais1000-1p46m", "language": "vi_VN", "sample_rate": 22050 },
+    "id": { "package": "id-newstts-1p46m", "language": "id_ID", "sample_rate": 22050 }
+  }
+}

sanotts-0.1.0/sanotts/voicepack.py

@@ -0,0 +1,200 @@
+"""Voice package resolution: local directories or cached downloads.
+
+A voice package is a directory containing:
+  - manifest.json          (format "roota.raw-fp16.v1"; see
+                             tools/export_roota_self_contained_package.py
+                             in the saanoTTS research repo for the exporter)
+  - weights.fp16.bin        (flat fp16 blob, tensors addressed by
+                             manifest offset_bytes/nbytes)
+  - piper-phoneme-config.json (codepoint -> phoneme-id table + espeak voice)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import logging
+import tarfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+logger = logging.getLogger("sanotts.voicepack")
+
+# Placeholder release location -- change this constant to point at wherever
+# voice packages are actually published; everything else in this module is
+# indifferent to the exact hosting scheme as long as it serves a
+# `<name>.tar.gz` containing manifest.json + weights.fp16.bin + piper-phoneme-config.json
+# at its root.
+VOICE_RELEASE_BASE_URL = "https://github.com/Ampixa/sanoTTS/releases/download/voices-v1"
+
+DEFAULT_CACHE_DIR = Path.home() / ".cache" / "sanotts"
+
+# name -> package archive/dir basename, for the voices published alongside
+# this package (see releases/multivoice-20260713 in the research repo).
+KNOWN_VOICES_TABLE = Path(__file__).parent / "tables" / "voices.json"
+
+
+class VoicePackError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class VoicePack:
+    name: str
+    directory: Path
+    manifest: dict[str, Any]
+    weights: bytes
+
+    @property
+    def sample_rate(self) -> int:
+        return int(self.manifest["sample_rate"])
+
+    @property
+    def duration_length_scale(self) -> float:
+        return float(self.manifest.get("inference", {}).get("duration_length_scale", 1.0))
+
+    def component_tensors(self, component: str) -> dict[str, np.ndarray]:
+        """Materialize one component's tensors as float32 numpy arrays."""
+        comp = self.manifest["components"].get(component)
+        if comp is None:
+            raise VoicePackError(f"manifest has no component {component!r}")
+        out: dict[str, np.ndarray] = {}
+        for tensor in comp["tensors"]:
+            name = tensor["name"]
+            shape = tuple(tensor["shape"])
+            dtype = tensor["dtype"]
+            offset = int(tensor["offset_bytes"])
+            nbytes = int(tensor["nbytes"])
+            raw = self.weights[offset:offset + nbytes]
+            if len(raw) != nbytes:
+                raise VoicePackError(
+                    f"{component}.{name}: truncated weights blob "
+                    f"(wanted {nbytes} bytes at {offset}, got {len(raw)})"
+                )
+            if dtype == "float16":
+                array = np.frombuffer(raw, dtype="<f2").astype(np.float32)
+            elif dtype == "int64":
+                array = np.frombuffer(raw, dtype="<i8").astype(np.int64)
+            elif dtype == "int32":
+                array = np.frombuffer(raw, dtype="<i4").astype(np.int32)
+            else:
+                raise VoicePackError(f"{component}.{name}: unsupported dtype {dtype!r}")
+            out[name] = array.reshape(shape)
+        return out
+
+    def component_config(self, component: str) -> dict[str, Any]:
+        comp = self.manifest["components"].get(component)
+        if comp is None:
+            raise VoicePackError(f"manifest has no component {component!r}")
+        return comp["config"]
+
+    @property
+    def phoneme_config_path(self) -> Path:
+        included = self.manifest.get("frontend", {}).get("included_config") or "piper-phoneme-config.json"
+        path = self.directory / included
+        if not path.is_file():
+            raise VoicePackError(f"voice pack {self.name!r} is missing its phoneme config: {path}")
+        return path
+
+
+def _sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _load_from_directory(name: str, directory: Path) -> VoicePack:
+    manifest_path = directory / "manifest.json"
+    if not manifest_path.is_file():
+        raise VoicePackError(f"{directory}: missing manifest.json")
+    with manifest_path.open("r", encoding="utf-8") as handle:
+        manifest = json.load(handle)
+    if manifest.get("format") != "roota.raw-fp16.v1":
+        raise VoicePackError(
+            f"{directory}: unsupported manifest format {manifest.get('format')!r}, "
+            "expected 'roota.raw-fp16.v1'"
+        )
+    weights_path = directory / manifest["weights_file"]
+    if not weights_path.is_file():
+        raise VoicePackError(f"{directory}: missing weights file {weights_path}")
+    weights = weights_path.read_bytes()
+    expected_size = int(manifest.get("weights_size_bytes", -1))
+    if expected_size >= 0 and len(weights) != expected_size:
+        raise VoicePackError(
+            f"{weights_path}: size {len(weights)} != manifest weights_size_bytes {expected_size}"
+        )
+    expected_sha = manifest.get("weights_sha256")
+    if expected_sha:
+        actual_sha = _sha256_hex(weights)
+        if actual_sha != expected_sha:
+            raise VoicePackError(
+                f"{weights_path}: sha256 mismatch (manifest={expected_sha}, actual={actual_sha}); "
+                "the voice package is corrupt or was tampered with"
+            )
+    return VoicePack(name=name, directory=directory, manifest=manifest, weights=weights)
+
+
+def _known_voice_archive_name(voice: str) -> str:
+    if not KNOWN_VOICES_TABLE.is_file():
+        raise VoicePackError(f"missing bundled voice registry: {KNOWN_VOICES_TABLE}")
+    with KNOWN_VOICES_TABLE.open("r", encoding="utf-8") as handle:
+        registry = json.load(handle)
+    entry = registry.get("voices", {}).get(voice)
+    if entry is None:
+        available = ", ".join(sorted(registry.get("voices", {})))
+        raise VoicePackError(f"unknown voice {voice!r}; known voices: {available}")
+    return str(entry["package"])
+
+
+def _download_and_extract(voice: str, cache_dir: Path) -> Path:
+    package_name = _known_voice_archive_name(voice)
+    dest_dir = cache_dir / package_name
+    if (dest_dir / "manifest.json").is_file():
+        return dest_dir
+
+    url = f"{VOICE_RELEASE_BASE_URL}/{package_name}.tar.gz"
+    logger.info("sanotts: downloading voice %r from %s", voice, url)
+    try:
+        with urllib.request.urlopen(url, timeout=60) as response:  # noqa: S310 - fixed https host
+            archive_bytes = response.read()
+    except OSError as exc:
+        raise VoicePackError(
+            f"could not download voice {voice!r} from {url}: {exc}. "
+            f"Use --voice-dir to point at a local voice package instead, e.g. a directory "
+            "produced by tools/export_roota_self_contained_package.py."
+        ) from exc
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(fileobj=io.BytesIO(archive_bytes), mode="r:gz") as archive:
+        safe_root = dest_dir.resolve()
+        for member in archive.getmembers():
+            member_path = (dest_dir / member.name).resolve()
+            if safe_root not in member_path.parents and member_path != safe_root:
+                raise VoicePackError(f"refusing to extract unsafe archive member: {member.name}")
+        archive.extractall(dest_dir)  # noqa: S202 - paths validated above
+    return dest_dir
+
+
+def load_voice(
+    voice: str | None = None,
+    *,
+    voice_dir: str | Path | None = None,
+    cache_dir: str | Path | None = None,
+) -> VoicePack:
+    """Resolve a voice pack from an explicit directory, or by name (downloading
+    into `cache_dir` if it is not already cached there)."""
+    if voice_dir is not None:
+        directory = Path(voice_dir).expanduser().resolve()
+        if not directory.is_dir():
+            raise VoicePackError(f"--voice-dir {directory} is not a directory")
+        name = voice or directory.name
+        return _load_from_directory(name, directory)
+
+    if not voice:
+        raise VoicePackError("either voice or voice_dir must be given")
+    resolved_cache_dir = Path(cache_dir).expanduser() if cache_dir else DEFAULT_CACHE_DIR
+    directory = _download_and_extract(voice, resolved_cache_dir)
+    return _load_from_directory(voice, directory)