zerotts 0.1.0__py3-none-any.whl

zerotts/__init__.py

@@ -0,0 +1,26 @@
+"""ZeroTTS — Vietnamese zero-shot text-to-speech, ONNX runtime, no PyTorch.
+
+    from zerotts import ZeroTTS
+
+    tts = ZeroTTS.from_pretrained("zeroweight-ai/ZeroTTS")
+    audio = tts.synthesize("Xin chào các bạn.", voice="maichi")
+    tts.save_audio(audio, "out.wav")
+"""
+
+from .hub import DEFAULT_REPO_ID, resolve_model_dir
+from .synthesizer import ZeroTTS
+from .text_norm import normalize_vi_text
+from .voices import Voice, list_voices, load_voice
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ZeroTTS",
+    "normalize_vi_text",
+    "Voice",
+    "list_voices",
+    "load_voice",
+    "resolve_model_dir",
+    "DEFAULT_REPO_ID",
+    "__version__",
+]

zerotts/audio.py

@@ -0,0 +1,57 @@
+"""Audio I/O helpers — plain numpy + soundfile/scipy, no torch."""
+
+from __future__ import annotations
+
+from math import gcd
+
+import numpy as np
+
+SAMPLE_RATE = 48_000
+
+
+def load_wav_mono(path: str, target_sr: int = SAMPLE_RATE) -> np.ndarray:
+    """Load a wav, downmix to mono, resample to ``target_sr``. Returns (T,) float32."""
+    import soundfile as sf
+
+    wav, sr = sf.read(path, always_2d=True)
+    wav = wav.mean(axis=1).astype(np.float32)
+    if sr != target_sr:
+        from scipy.signal import resample_poly
+
+        g = gcd(target_sr, sr)
+        wav = resample_poly(wav, target_sr // g, sr // g)
+    return wav.astype(np.float32)
+
+
+def resample_wav(wav: np.ndarray, sr_from: int, sr_to: int) -> np.ndarray:
+    """Resample a 1-D float32 array, matching load_wav_mono's resampler."""
+    if sr_from == sr_to:
+        return wav.astype(np.float32)
+    from scipy.signal import resample_poly
+
+    g = gcd(sr_from, sr_to)
+    return resample_poly(wav, sr_to // g, sr_from // g).astype(np.float32)
+
+
+def save_wav(audio: np.ndarray, path: str, sample_rate: int = SAMPLE_RATE) -> None:
+    """Save a (..., T) float array (leading dims squeezed) as 16-bit PCM wav."""
+    import soundfile as sf
+
+    sf.write(path, np.asarray(audio).squeeze(), sample_rate, subtype="PCM_16")
+
+
+def concat_with_silence(chunks: list[np.ndarray], silence_sec: float,
+                        sample_rate: int = SAMPLE_RATE) -> np.ndarray:
+    """Join (1, T) or (T,) chunks with ``silence_sec`` of silence between them."""
+    parts = [np.asarray(c).reshape(-1) for c in chunks if np.asarray(c).size]
+    if not parts:
+        return np.zeros((1, 0), dtype=np.float32)
+    if silence_sec > 0 and len(parts) > 1:
+        gap = np.zeros(int(silence_sec * sample_rate), dtype=np.float32)
+        joined: list = []
+        for i, p in enumerate(parts):
+            if i:
+                joined.append(gap)
+            joined.append(p)
+        parts = joined
+    return np.concatenate(parts).astype(np.float32)[None, :]

zerotts/chunking.py

@@ -0,0 +1,270 @@
+"""Punctuation normalization + sentence segmentation/chunking for long-form
+text-to-speech input.
+
+No sentence-boundary-detection library is a project dependency (no nltk/
+spacy/pysbd), so this uses a regex-based splitter, then greedily packs
+sentences into chunks bounded by an estimated speaking duration.
+
+Splitting falls back through a hierarchy so no single chunk ever exceeds
+the character budget, however the user punctuates (or doesn't):
+    1. sentence-ending punctuation (. ! ? …)
+    2. commas, if a "sentence" is still too long
+    3. word boundaries, if a comma-separated piece is still too long
+    4. raw character slicing, as a last resort (e.g. one giant run-on word)
+"""
+
+from __future__ import annotations
+
+import re
+
+# Split after ., !, ?, or … followed by whitespace (or end of string), but
+# not on a run of digits/abbreviation-like single letters (e.g. "3.5" or
+# "Mr.") immediately before the dot — kept intentionally simple/heuristic.
+_SENTENCE_END_RE = re.compile(r"(?<=[.!?…])\s+")
+
+# Split after a comma followed by whitespace, keeping the comma with the
+# preceding text (used only when a whole "sentence" is over budget).
+_COMMA_RE = re.compile(r"(?<=,)\s+")
+
+# Rough average speaking rate used to size chunks by estimated duration
+# rather than raw character count (TTS speaking rate varies by language,
+# so this is a coarse heuristic, not a precise duration predictor).
+_CHARS_PER_SEC = 15.0
+
+# ── punctuation normalization ────────────────────────────────────────────────
+# Written text carries breaks the model was never trained to voice. The BPE
+# vocab has a token for ';', but the training corpus is transcribed speech,
+# where a semicolon is rare — the model has no reliable prosody for it, and at
+# inference it tends to read as a hard stop or as nothing at all. A comma is
+# the break it actually stands for out loud, so it is rewritten to one. ':' is
+# left as-is (kept, not folded to a comma). Newlines are worse: the BPE
+# normalizer collapses all whitespace to a single space
+# (zerotts.tokenizer.normalize_text), so a line break vanishes entirely
+# and two unrelated lines run together as one breath. Turning it into a
+# sentence stop preserves the pause the layout meant — unless the line already
+# ends in punctuation, which already carries it.
+
+_PAUSE_PUNCT_RE = re.compile(r"[;]")
+
+# A newline (plus any surrounding horizontal whitespace, and any run of blank
+# lines) with what immediately precedes it captured, so the replacement can look
+# at whether that character is already punctuation.
+_NEWLINE_RE = re.compile(r"(.?)[ \t]*(?:\r?\n[ \t]*)+")
+
+# Characters that already terminate or pause a clause — a line ending in one of
+# these needs no added '.'.
+_EXISTING_PUNCT = set(".!?…,;:—–-\"')]}")
+
+
+def normalize_punctuation(text: str) -> str:
+    """Rewrite written-only punctuation into the breaks the model can voice.
+
+        ';' -> ','
+        newline -> '. ' when the line does not already end in punctuation,
+                   otherwise just a space.
+
+    Semicolons are converted FIRST, so a line ending in one counts as
+    already-punctuated when the newline rule runs (it ends in ',' by then)
+    and does not also collect a '.'. ':' is untouched by this step, but is
+    already in _EXISTING_PUNCT so a line ending in one is also treated as
+    already-punctuated.
+    """
+    if not text:
+        return text
+
+    text = _PAUSE_PUNCT_RE.sub(",", text)
+
+    def _repl(m: re.Match) -> str:
+        prev = m.group(1)
+        if not prev:  # leading newline(s) — nothing before them to punctuate
+            return ""
+        if prev in _EXISTING_PUNCT:
+            return f"{prev} "
+        return f"{prev}. "
+
+    text = _NEWLINE_RE.sub(_repl, text)
+    return text.strip()
+
+
+def split_sentences(text: str) -> list[str]:
+    text = text.strip()
+    if not text:
+        return []
+    # Split paragraphs first so blank lines always force a break, then
+    # sentence-split within each paragraph.
+    sentences: list[str] = []
+    for para in re.split(r"\n\s*\n", text):
+        para = para.strip()
+        if not para:
+            continue
+        for sent in _SENTENCE_END_RE.split(para):
+            sent = sent.strip()
+            if sent:
+                sentences.append(sent)
+    return sentences
+
+
+def _pack_pieces(pieces: list[str], max_chars: int) -> list[str]:
+    """Greedily join `pieces` (each already <= max_chars) with a single
+    space, filling each output chunk as close to max_chars as possible
+    without exceeding it."""
+    chunks: list[str] = []
+    current: list[str] = []
+    current_len = 0
+    for piece in pieces:
+        piece_len = len(piece) + (1 if current else 0)
+        if current and current_len + piece_len > max_chars:
+            chunks.append(" ".join(current))
+            current, current_len = [], 0
+            piece_len = len(piece)
+        current.append(piece)
+        current_len += piece_len
+    if current:
+        chunks.append(" ".join(current))
+    return chunks
+
+
+def _split_by_chars(text: str, max_chars: int) -> list[str]:
+    return [text[i:i + max_chars] for i in range(0, len(text), max_chars)]
+
+
+def _split_by_words(text: str, max_chars: int) -> list[str]:
+    words = text.split()
+    pieces = _pack_pieces(words, max_chars)
+    # A single word longer than max_chars (e.g. a spammed run of characters
+    # with no spaces) still needs a hard character split.
+    out: list[str] = []
+    for piece in pieces:
+        if len(piece) <= max_chars:
+            out.append(piece)
+        else:
+            out.extend(_split_by_chars(piece, max_chars))
+    return out
+
+
+def _atomize(text: str, max_chars: int) -> list[str]:
+    """Break `text` down until every returned piece is <= max_chars,
+    preferring the least disruptive split available (comma > word >
+    character)."""
+    text = text.strip()
+    if not text:
+        return []
+    if len(text) <= max_chars:
+        return [text]
+
+    comma_parts = [p.strip() for p in _COMMA_RE.split(text) if p.strip()]
+    if len(comma_parts) > 1:
+        out: list[str] = []
+        for part in comma_parts:
+            out.extend(_atomize(part, max_chars))
+        return out
+
+    if " " in text.strip():
+        return _split_by_words(text, max_chars)
+
+    return _split_by_chars(text, max_chars)
+
+
+def chunk_text(text: str, max_chunk_sec: float = 15.0) -> list[str]:
+    """Split `text` into speakable chunks whose estimated duration stays
+    near `max_chunk_sec`, preferring to break on sentence-ending
+    punctuation, then commas, then words, then raw characters as a last
+    resort — so a single chunk never balloons past the budget no matter how
+    the input is (or isn't) punctuated.
+    """
+    max_chars = max(1, int(max_chunk_sec * _CHARS_PER_SEC))
+    sentences = split_sentences(text)
+
+    atoms: list[str] = []
+    for sent in sentences:
+        atoms.extend(_atomize(sent, max_chars))
+
+    return _pack_pieces(atoms, max_chars)
+
+
+# ── per-segment punctuation cleanup ──────────────────────────────────────────
+# Chunking (above) can cut a sentence mid-flow, leaving a segment that ends on
+# a comma or nothing at all, and/or a stray '.'/'!'/'?'/other symbol stranded
+# in the middle of what is now a shorter, standalone utterance. Interior
+# punctuation reads as a hard stop (or gets silently dropped by the tokenizer)
+# where only a pause belongs, so every mid-segment punctuation mark other than
+# a hyphen — word-joining ('twenty-one') or otherwise —, a slash, or a dot is
+# downgraded to a comma-pause. The segment's own end is where a real stop belongs: whatever
+# terminal mark it already had is kept if it's one of '.', '!', '?' (that's
+# real, meaningful prosody), and anything else trailing there — comma, dash,
+# stray symbol, nothing — is normalized to a single '.'.
+
+# Trailing run of whitespace/punctuation, i.e. everything after the last
+# alphanumeric character in the segment.
+_TRAILING_RE = re.compile(r"[^\w]+$", re.UNICODE)
+
+# Any mid-segment character that is not a word char, whitespace, hyphen,
+# slash, dot, colon, question mark, exclamation mark, quote (single or
+# double), percent sign, or comma itself gets folded into a comma-pause.
+_MID_PUNCT_RE = re.compile(r"[^\w\s\-/.,:?@!\"'%]", re.UNICODE)
+
+# Collapse runs of commas (possibly separated by spaces) into a single
+# ', ' — also fixes the missing space left when a punctuation mark abutting
+# a word (e.g. the '"' in 'Hello"world') is folded straight into a comma.
+_REPEAT_COMMA_RE = re.compile(r"\s*(?:,\s*)+")
+
+_END_PUNCT = {".", "!", "?"}
+
+
+def clean_segment_punctuation(text: str) -> str:
+    """Normalize a single chunked segment's punctuation for TTS:
+
+        1. every mid-segment punctuation mark other than
+           '-', '/', '.', ':', '?', '!', '"', "'", '%' becomes a ',' pause
+        2. terminal mark: kept as-is if it's '.', '!', or '?', otherwise
+           whatever trails (comma, dash, stray symbol, nothing) -> '.'
+    """
+    text = text.strip()
+    if not text:
+        return text
+
+    m = _TRAILING_RE.search(text)
+    core = text[:m.start()] if m else text
+    trailing = text[m.start():].rstrip() if m else ""
+
+    end_punct = trailing[-1] if trailing and trailing[-1] in _END_PUNCT else "."
+
+    core = _MID_PUNCT_RE.sub(",", core)
+    core = _REPEAT_COMMA_RE.sub(", ", core).strip(" ,")
+
+    if not core:
+        return ""
+    return core + end_punct
+
+
+# ── sample text file loading ─────────────────────────────────────────────────
+# Used by the Gradio demo's "Sample texts" picker.
+
+def load_text_samples(path) -> dict[str, str]:
+    """Parse a "### name" delimited sample-text file (see webui/test_samples.txt's
+    header for the format) into {name: text}. Missing file -> {}."""
+    from pathlib import Path
+
+    path = Path(path)
+    if not path.is_file():
+        return {}
+
+    samples: dict[str, str] = {}
+    name = None
+    lines: list[str] = []
+
+    def flush():
+        if name is not None:
+            samples[name] = "\n".join(lines).strip()
+
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        if raw_line.startswith("### "):
+            flush()
+            name = raw_line[4:].strip()
+            lines = []
+        elif raw_line.startswith("#"):
+            continue
+        else:
+            lines.append(raw_line)
+    flush()
+    return samples

zerotts/cli.py

@@ -0,0 +1,162 @@
+"""Command-line interface: ``zerotts say`` / ``zerotts voices`` / ``zerotts bench``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+import numpy as np
+
+from . import hub
+from .audio import concat_with_silence
+from .chunking import chunk_text, clean_segment_punctuation, normalize_punctuation
+from .synthesizer import ZeroTTS
+from .text_norm import normalize_vi_text
+
+
+def _add_model_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--model", default=hub.DEFAULT_REPO_ID,
+                   help="HF repo id or local model directory.")
+    p.add_argument("--revision", default=None, help="HF revision to pin.")
+    p.add_argument("--threads", type=int, default=4, help="onnxruntime intra-op threads.")
+
+
+def _add_sampling_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--cfg_scale", type=float, default=1.0,
+                   help=">1 guides toward the voice, at 2x the per-frame cost.")
+    p.add_argument("--audio_temperature", type=float, default=0.8)
+    p.add_argument("--audio_topk", type=int, default=25)
+    p.add_argument("--audio_topp", type=float, default=0.95)
+    p.add_argument("--audio_repetition_penalty", type=float, default=1.2,
+                   help="1.2 is the benchmarked default; 1.0 raises WER.")
+    p.add_argument("--seed", type=int, default=None, help="Seed the sampler.")
+
+
+def _sampling_kwargs(a: argparse.Namespace) -> dict:
+    return {
+        "cfg_scale": a.cfg_scale,
+        "audio_temperature": a.audio_temperature,
+        "audio_topk": a.audio_topk,
+        "audio_topp": a.audio_topp,
+        "audio_repetition_penalty": a.audio_repetition_penalty,
+    }
+
+
+def cmd_say(a: argparse.Namespace) -> int:
+    if a.seed is not None:
+        np.random.seed(a.seed)
+    tts = ZeroTTS.from_pretrained(a.model, revision=a.revision,
+                                  intra_op_num_threads=a.threads)
+
+    text = a.text if a.text != "-" else sys.stdin.read()
+    # Before chunking: an expansion is several times longer than what it
+    # replaces, and the chunk budget has to size the text the model receives.
+    if not a.no_text_norm:
+        text = normalize_vi_text(text)
+    segments = [text]
+    if a.chunk:
+        segments = [clean_segment_punctuation(s)
+                    for s in chunk_text(normalize_punctuation(text),
+                                        max_chunk_sec=a.max_chunk_sec)]
+        segments = [s for s in segments if s]
+
+    t0 = time.perf_counter()
+    chunks = []
+    for i, seg in enumerate(segments, 1):
+        if len(segments) > 1:
+            print(f"[{i}/{len(segments)}] {seg[:70]}{'…' if len(seg) > 70 else ''}",
+                  file=sys.stderr)
+        chunks.append(tts.synthesize(seg, voice=a.voice, **_sampling_kwargs(a)))
+    audio = concat_with_silence(chunks, a.gap_sec, tts.sample_rate)
+    elapsed = time.perf_counter() - t0
+
+    tts.save_audio(audio, a.out)
+    dur = audio.shape[-1] / tts.sample_rate
+    speed = dur / elapsed if elapsed > 0 else float("inf")
+    print(f"{a.out}  {dur:.2f}s audio in {elapsed:.2f}s ({speed:.1f}x realtime)")
+    return 0
+
+
+def cmd_voices(a: argparse.Namespace) -> int:
+    tts = ZeroTTS.from_pretrained(a.model, revision=a.revision, warmup=False)
+    names = tts.list_voices()
+    if not names:
+        print("No voice packs in this model directory.")
+        print("This build cannot create voices from audio — see the README "
+              "(voice cloning).")
+        return 1
+    for name in names:
+        v = tts.load_voice(name)
+        desc = f"  {v.description}" if v.description else ""
+        print(f"{name:20s} {v.language:4s} {v.n_voice_queries} queries{desc}")
+    return 0
+
+
+def cmd_bench(a: argparse.Namespace) -> int:
+    if a.seed is not None:
+        np.random.seed(a.seed)
+    tts = ZeroTTS.from_pretrained(a.model, revision=a.revision,
+                                  intra_op_num_threads=a.threads)
+    text = a.text
+    timings = []
+    for i in range(a.runs):
+        timing: dict = {}
+        audio = tts.synthesize(text, voice=a.voice, timing=timing,
+                               **_sampling_kwargs(a))
+        dur = audio.shape[-1] / tts.sample_rate
+        timings.append((timing, dur))
+        print(f"run {i + 1}: {dur:.2f}s audio, {timing['total_time']:.2f}s wall, "
+              f"TTFF {timing['time_to_first_frame'] * 1000:.0f}ms, "
+              f"{timing['n_frames']} frames, {dur / timing['total_time']:.1f}x realtime")
+
+    wall = float(np.median([t["total_time"] for t, _ in timings]))
+    dur = float(np.median([d for _, d in timings]))
+    ttff = float(np.median([t["time_to_first_frame"] for t, _ in timings]))
+    print(f"\nmedian over {a.runs}: {dur / wall:.1f}x realtime, TTFF {ttff * 1000:.0f}ms, "
+          f"{a.threads} threads")
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="zerotts", description="ZeroTTS command line.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    say = sub.add_parser("say", help="Synthesize text to a wav file.")
+    say.add_argument("text", help="Text to speak, or '-' to read stdin.")
+    say.add_argument("-o", "--out", default="out.wav")
+    say.add_argument("-v", "--voice", default=None,
+                     help="Voice name. Omit for the model's unconditional voice.")
+    say.add_argument("--chunk", action="store_true",
+                     help="Split long text into segments and join the audio.")
+    say.add_argument("--max_chunk_sec", type=float, default=15.0)
+    say.add_argument("--gap_sec", type=float, default=0.15,
+                     help="Silence inserted between chunks.")
+    say.add_argument("--no_text_norm", action="store_true",
+                     help="Skip Vietnamese normalization of dates/times/numbers. "
+                          "Use for non-Vietnamese text — the expansions are "
+                          "Vietnamese words.")
+    _add_model_args(say)
+    _add_sampling_args(say)
+    say.set_defaults(func=cmd_say)
+
+    voices = sub.add_parser("voices", help="List available voices.")
+    _add_model_args(voices)
+    voices.set_defaults(func=cmd_voices)
+
+    bench = sub.add_parser("bench", help="Measure realtime factor and TTFF.")
+    bench.add_argument(
+        "--text",
+        default="Xin chào, đây là một bài kiểm tra tốc độ tổng hợp giọng nói.")
+    bench.add_argument("-v", "--voice", default=None)
+    bench.add_argument("--runs", type=int, default=3)
+    _add_model_args(bench)
+    _add_sampling_args(bench)
+    bench.set_defaults(func=cmd_bench)
+
+    a = p.parse_args(argv)
+    return a.func(a)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

zerotts/codec.py

@@ -0,0 +1,154 @@
+"""onnxruntime-only MOSS-Audio-Tokenizer-Nano **decoder** — codes -> waveform.
+
+Vendored, not downloaded. The decoder graphs ship inside the ZeroTTS weights
+repo (``onnx/codec/``) so a ZeroTTS install has no runtime dependency on any
+third-party model repo staying up or unchanged.
+
+Decoder only. The upstream export also has an encoder graph (waveform -> codes),
+used solely to turn reference audio into voice latents. That is voice cloning,
+which this release does not do (see zerotts.voices), so the encoder is neither
+shipped nor wrapped — it would be ~45MB of weights nothing here can call.
+
+Conventions worth knowing before touching this:
+  * native sample rate 48 kHz; the codec is stereo internally, the public
+    interface is mono (decode averages the two channels).
+  * this export uses (batch, T, K) — TIME-major, codebook-LAST — for
+    ``audio_codes``. ZeroTTS's AR loop produces (B, K, T), so decode transposes.
+  * every integer tensor here is **int32**, not int64. This is verified against
+    the graphs; do not "fix" it to int64 out of PyTorch habit.
+
+Credit: MOSS-Audio-Tokenizer-Nano by the OpenMOSS team, Apache-2.0. See
+https://github.com/OpenMOSS/MOSS-Audio-Tokenizer and the NOTICE file.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+
+class MossCodecDecoder:
+    """Args:
+        codec_dir: directory holding the decoder graphs and
+            ``codec_browser_onnx_meta.json``.
+        providers: onnxruntime execution providers.
+        intra_op_num_threads: per-session thread count.
+    """
+
+    def __init__(
+        self,
+        codec_dir: str | Path,
+        providers: list[str] | None = None,
+        intra_op_num_threads: int = 4,
+    ):
+        import onnxruntime as ort
+
+        codec_dir = Path(codec_dir)
+        meta_path = codec_dir / "codec_browser_onnx_meta.json"
+        if not meta_path.exists():
+            raise FileNotFoundError(
+                f"{codec_dir} has no codec_browser_onnx_meta.json — the vendored "
+                f"codec is missing from this model directory.")
+        meta = json.loads(meta_path.read_text())
+        self._meta = meta
+
+        cfg = meta["codec_config"]
+        self.sample_rate = int(cfg["sample_rate"])
+        self.num_channels = int(cfg["channels"])
+        self.frame_size = int(cfg["downsample_rate"])
+        self.frame_rate = self.sample_rate / self.frame_size
+        self.num_codebooks = int(cfg["num_quantizers"])
+
+        sess_options = ort.SessionOptions()
+        sess_options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL
+        sess_options.intra_op_num_threads = intra_op_num_threads
+        sess_options.inter_op_num_threads = 1
+        resolved = providers or ["CPUExecutionProvider"]
+
+        def _session(key: str):
+            return ort.InferenceSession(
+                str(codec_dir / meta["files"][key]),
+                sess_options=sess_options,
+                providers=resolved,
+            )
+
+        self._decode_full_sess = _session("decode_full")
+        self._decode_step_sess = _session("decode_step")
+
+    def decode(self, codes_bkt: np.ndarray) -> np.ndarray:
+        """(B, K, T) int codes -> (B, T_audio) float32 mono at sample_rate."""
+        codes = np.asarray(codes_bkt)
+        if codes.ndim == 2:  # (K, T) -> (1, K, T)
+            codes = codes[None, :, :]
+        codes_btk = codes.transpose(0, 2, 1).astype(np.int32)  # -> (B, T, K)
+        lengths = np.array([codes_btk.shape[1]], dtype=np.int32)
+        audio, audio_lengths = self._decode_full_sess.run(
+            None, {"audio_codes": codes_btk, "audio_code_lengths": lengths}
+        )
+        n = int(audio_lengths.reshape(-1)[0])
+        return audio[:, :, :n].mean(axis=1).astype(np.float32)
+
+    def streaming_decoder(self) -> MossStreamingDecoder:
+        """Open a stateful streaming decoder (keeps the causal decoder KV cache
+        across chunks). Call decode_chunk per chunk, then close."""
+        return MossStreamingDecoder(self)
+
+
+class MossStreamingDecoder:
+    """KV-cached streaming decode over decode_step.onnx, driven by the state
+    layout ``codec_browser_onnx_meta.json``'s "streaming_decode" section
+    describes: per-decoder transformer offsets plus per-layer attention caches
+    (key/value/position ring buffers). Use via
+    ``MossCodecDecoder.streaming_decoder()``."""
+
+    def __init__(self, codec: MossCodecDecoder):
+        self._codec = codec
+        self._session = codec._decode_step_sess
+        streaming = codec._meta.get("streaming_decode", {})
+        self._transformer_specs = list(streaming.get("transformer_offsets", []))
+        self._attention_specs = list(streaming.get("attention_caches", []))
+        self._output_names = [o.name for o in self._session.get_outputs()]
+        self._state: dict = {}
+        self._reset_state()
+
+    def _reset_state(self) -> None:
+        self._state = {}
+        for spec in self._transformer_specs:
+            self._state[str(spec["input_name"])] = np.zeros(tuple(spec["shape"]), dtype=np.int32)
+        for spec in self._attention_specs:
+            self._state[str(spec["offset_input_name"])] = np.zeros(
+                tuple(spec["offset_shape"]), dtype=np.int32)
+            self._state[str(spec["cached_keys_input_name"])] = np.zeros(
+                tuple(spec["cache_shape"]), dtype=np.float32)
+            self._state[str(spec["cached_values_input_name"])] = np.zeros(
+                tuple(spec["cache_shape"]), dtype=np.float32)
+            # -1, not 0: position 0 is a real position, so a zero-filled ring
+            # buffer would read as "every slot holds frame 0".
+            self._state[str(spec["cached_positions_input_name"])] = np.full(
+                tuple(spec["positions_shape"]), -1, dtype=np.int32)
+
+    def decode_chunk(self, codes_bkt: np.ndarray) -> np.ndarray:
+        """(1, K, n) int codes -> (1, chunk_samples) float32 mono."""
+        codes = np.asarray(codes_bkt)
+        if codes.ndim == 2:
+            codes = codes[None, :, :]
+        codes_btk = codes.transpose(0, 2, 1).astype(np.int32)  # -> (1, n, K)
+        feeds = {
+            "audio_codes": codes_btk,
+            "audio_code_lengths": np.array([codes_btk.shape[1]], dtype=np.int32),
+            **self._state,
+        }
+        outputs = self._session.run(None, feeds)
+        named = dict(zip(self._output_names, outputs))
+        for spec in self._transformer_specs:
+            self._state[str(spec["input_name"])] = named[str(spec["output_name"])]
+        for spec in self._attention_specs:
+            for key in ("offset", "cached_keys", "cached_values", "cached_positions"):
+                self._state[str(spec[f"{key}_input_name"])] = named[str(spec[f"{key}_output_name"])]
+        n = int(named["audio_lengths"].reshape(-1)[0])
+        return named["audio"][:, :, :n].mean(axis=1).astype(np.float32)
+
+    def close(self) -> None:
+        self._reset_state()