voxx 0.1.0__py3-none-any.whl

voxx/__init__.py

@@ -0,0 +1 @@
+"""voxx: a local text-to-speech CLI for agents."""

voxx/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from voxx.cli import main
+
+sys.exit(main())

voxx/audio.py

@@ -0,0 +1,102 @@
+"""Finishing and writing a Line's audio and a Reference Recording. Worker-side only."""
+
+import math
+import warnings
+import wave
+
+import numpy as np
+import pyloudnorm
+from scipy.ndimage import minimum_filter1d, uniform_filter1d
+from scipy.signal import resample_poly
+
+from voxx.files import replacing
+from voxx.output import USAGE, VoxxError
+
+LOUDNESS = -18.0  # LUFS, integrated
+TOLERANCE = 0.5  # LU a Line may fall short of LOUDNESS before it warns
+SILENCE = 0.05  # seconds of silence left before and after the speech
+QUIET = 10 ** (-50 / 20)  # a sample this far below the Line's peak counts as silence
+BLOCK = 0.4  # seconds: the loudness meter's gating block
+CEILING = 10 ** (-1 / 20)  # the highest peak a Line may reach, a little below full scale so it never clips
+REACH = 0.01  # seconds either side of a peak over which the limiter turns the Line down and back up
+# Every Reference Recording is stored at one rate: as high as any cloning Model hears (Qwen3-TTS Base hears 24 kHz,
+# VoxCPM2 16 kHz), so storing more would keep nothing a Model uses.
+REFERENCE_SAMPLE_RATE = 24_000
+
+
+def finish(samples, sample_rate):
+    """The same loudness and the same short silences for every Line, at the Engine's native sample rate.
+    Returns the samples and the Line's warnings."""
+    samples = _trim(samples.astype(np.float64), round(sample_rate * SILENCE))
+    loudness = _loudness(samples, sample_rate)
+    if not np.isfinite(loudness):
+        return samples, [{"code": "silent", "message": "The Model read the Line as silence."}]
+    samples = _limit(samples * 10 ** ((LOUDNESS - loudness) / 20), round(sample_rate * REACH))
+    reached = _loudness(samples, sample_rate)
+    if reached >= LOUDNESS - TOLERANCE:
+        return samples, []
+    return samples, [{"code": "loudness_below_target",
+                      "message": f"The Line peaks too often to reach {LOUDNESS:g} LUFS without clipping; it is {reached:.1f} LUFS."}]
+
+
+def prepare_reference(source, path):
+    """Normalizes the Reference Recording at `source` into a WAV at `path`, as a Line is finished: mono, at
+    REFERENCE_SAMPLE_RATE, at the same loudness and with the same short silences. Returns its warnings."""
+    # mlx-audio's reader decodes WAV, MP3 and FLAC itself, and M4A, Ogg, AIFF and more through ffmpeg if installed.
+    from mlx_audio.audio_io import read
+
+    try:
+        samples, sample_rate = read(str(source), always_2d=True, dtype="float64")
+    except Exception as e:
+        raise VoxxError("unreadable_reference", f"Cannot decode {source}: {type(e).__name__}: {e}",
+                        "Pass a WAV, MP3 or FLAC file to --ref, or install ffmpeg for other formats.",
+                        {"ref": str(source)}, USAGE)
+    samples = samples.mean(axis=1)
+    if not len(samples):
+        raise VoxxError("silent_reference", f"{source} has no audio.", "Pass a recording of the voice to --ref.",
+                        {"ref": str(source)}, USAGE)
+    gcd = math.gcd(REFERENCE_SAMPLE_RATE, sample_rate)
+    samples, found = finish(resample_poly(samples, REFERENCE_SAMPLE_RATE // gcd, sample_rate // gcd), REFERENCE_SAMPLE_RATE)
+    if any(w["code"] == "silent" for w in found):
+        raise VoxxError("silent_reference", f"{source} is silent.", "Pass a recording of the voice to --ref.",
+                        {"ref": str(source)}, USAGE)
+    write_wav(path, samples, REFERENCE_SAMPLE_RATE)
+    return found
+
+
+def _loudness(samples, sample_rate):
+    """Integrated loudness in LUFS; -inf for a Line too quiet to measure."""
+    # A Line shorter than one block is measured as one block; a sample short of its length, so rounding never makes it longer.
+    meter = pyloudnorm.Meter(sample_rate, block_size=min(BLOCK, (len(samples) - 1) / sample_rate))
+    with warnings.catch_warnings(), np.errstate(divide="ignore"):
+        warnings.simplefilter("ignore", RuntimeWarning)
+        return meter.integrated_loudness(samples)
+
+
+def _limit(samples, reach):
+    """Turns down only the moments that would peak above CEILING, ramping in and out over `reach` samples."""
+    needed = CEILING / np.maximum(np.abs(samples), CEILING)
+    width = 2 * reach + 1
+    # Each over-ceiling sample holds its gain across every window it falls in, so averaging those windows never lets it
+    # through; the final minimum only absorbs rounding.
+    gain = uniform_filter1d(minimum_filter1d(needed, width, mode="nearest"), width, mode="nearest")
+    return samples * np.minimum(gain, needed)
+
+
+def _trim(samples, margin):
+    """Keeps `margin` samples around the speech: the Engine's own where it left that many, silence where it did not."""
+    level = np.abs(samples)
+    loud = np.flatnonzero(level >= level.max() * QUIET)
+    start, end = loud[0], loud[-1] + 1
+    kept = samples[max(0, start - margin):end + margin]
+    return np.pad(kept, (margin - min(start, margin), margin - min(len(samples) - end, margin)))
+
+
+def write_wav(path, samples, sample_rate):
+    """Mono 16-bit PCM at the Engine's native sample rate."""
+    pcm = (np.clip(samples, -1.0, 1.0) * 32767).astype("<i2")
+    with replacing(path) as partial, wave.open(str(partial), "wb") as f:
+        f.setnchannels(1)
+        f.setsampwidth(2)
+        f.setframerate(sample_rate)
+        f.writeframes(pcm.tobytes())

voxx/cli.py

@@ -0,0 +1,89 @@
+"""The `voxx` command. Never imports an inference library: synthesis runs in the worker (ADR 0002)."""
+
+import argparse
+import io
+import sys
+import traceback
+from typing import cast
+
+from voxx.models import CAPABILITIES, list_models
+from voxx.output import BUG_HINT, INTERNAL, OK, USAGE, VoxxError, print_error, print_result
+
+ARGS_HINT = "Run `voxx schema` to see every command's arguments."
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise VoxxError("invalid_arguments", message, ARGS_HINT, {}, USAGE)
+
+
+def _parser():
+    # No --help: stdout carries only JSON, and `voxx schema` describes every command.
+    parser = _Parser(prog="voxx", add_help=False)
+    commands = parser.add_subparsers(dest="command", required=True, parser_class=_Parser)
+    narrate = commands.add_parser("narrate", add_help=False)
+    narrate.add_argument("narration")
+    narrate.add_argument("--out", required=True)
+    narrate.add_argument("--model")
+    narrate.add_argument("--line", dest="lines", action="append", default=[])
+    narrate.add_argument("--voices-dir")
+    models = commands.add_parser("models", add_help=False)
+    models.add_argument("--capability", choices=CAPABILITIES)
+    installed = models.add_mutually_exclusive_group()
+    installed.add_argument("--installed", dest="installed", action="store_const", const=True)
+    installed.add_argument("--not-installed", dest="installed", action="store_const", const=False)
+    commands.add_parser("voices", add_help=False).add_argument("--voices-dir")
+    voice = commands.add_parser("voice", add_help=False).add_subparsers(dest="voice_command", required=True,
+                                                                         parser_class=_Parser)
+    add = voice.add_parser("add", add_help=False)
+    add.add_argument("name")
+    add.add_argument("--ref", required=True)
+    add.add_argument("--ref-text")
+    add.add_argument("--model")
+    add.add_argument("--voices-dir")
+    add.add_argument("--overwrite", action="store_true")
+    install = commands.add_parser("install", add_help=False)
+    install.add_argument("model")
+    commands.add_parser("doctor", add_help=False)
+    schema = commands.add_parser("schema", add_help=False)
+    # Words, so `voxx schema voice add` names a command of two.
+    schema.add_argument("name", nargs="*")
+    return parser
+
+
+def main(argv=None):
+    for stream in (sys.stdout, sys.stderr):
+        cast(io.TextIOWrapper, stream).reconfigure(encoding="utf-8")
+    try:
+        args = _parser().parse_args(argv)
+        if args.command == "narrate":
+            from voxx.narrate import narrate
+            data = narrate(args.narration, args.out, args.model, args.lines, args.voices_dir)
+        elif args.command == "install":
+            from voxx.install import install
+            data = install(args.model)
+        elif args.command == "doctor":
+            from voxx.doctor import doctor
+            data = doctor()
+        elif args.command == "models":
+            data = list_models(args.capability, args.installed)
+        elif args.command == "voices":
+            from voxx.voices import list_voices
+            data = list_voices(args.voices_dir)
+        elif args.command == "voice":
+            from voxx.voices import add_voice
+            data = add_voice(args.name, args.ref, args.ref_text, args.model, args.voices_dir, args.overwrite)
+        else:
+            from voxx.schema import schema
+            data = schema(" ".join(args.name) or None)
+        print_result(data)
+    except VoxxError as e:
+        print_error(e)
+        return e.exit_code
+    except KeyboardInterrupt:
+        print_error(VoxxError("interrupted", "voxx was interrupted.", "Run the command again.", {}, INTERNAL))
+        return INTERNAL
+    except Exception as e:
+        print_error(VoxxError("internal_error", f"{type(e).__name__}: {e}", BUG_HINT, {"traceback": traceback.format_exc()}, INTERNAL))
+        return INTERNAL
+    return OK

voxx/doctor.py

@@ -0,0 +1,49 @@
+"""`voxx doctor`: what an agent checks before narrating. Reports, never fails, and caches nothing."""
+
+import os
+import platform
+import shutil
+import subprocess
+
+from voxx.files import nearest_existing
+from voxx.models import is_installed, models, voxx_home
+
+# Test-only: "<system> <machine>[ rosetta]" stands in for the real platform.
+PLATFORM_ENV = "VOXX_TEST_PLATFORM"
+
+
+def doctor():
+    home = voxx_home()
+    disk = nearest_existing(home)
+    installed = {m: is_installed(m) for m in models()}
+    return {
+        "platform": _platform(),
+        "home": str(home),
+        "disk": {"path": str(disk), "free_bytes": shutil.disk_usage(disk).free},
+        "models": {"installed": [m.id for m, yes in installed.items() if yes],
+                   "not_installed": [m.install_summary() for m, yes in installed.items() if not yes]},
+    }
+
+
+def _platform():
+    if PLATFORM_ENV in os.environ:
+        system, machine, *rest = os.environ[PLATFORM_ENV].split()
+        translated = rest == ["rosetta"]
+    else:
+        system, machine = platform.system(), platform.machine()
+        translated = system == "Darwin" and _sysctl("sysctl.proc_translated") == "1"
+    reported = {"system": system, "machine": machine}
+    if system == "Darwin" and machine == "arm64":
+        return {**reported, "apple_silicon": True, "supported": True}
+    if translated:
+        return {**reported, "apple_silicon": True, "supported": False,
+                "reason": "This Mac has Apple Silicon, but Python runs as x86_64 under Rosetta. Use an arm64 Python."}
+    return {**reported, "apple_silicon": False, "supported": False,
+            "reason": "voxx v0.1 runs only on Apple Silicon Macs (M1 or later)."}
+
+
+def _sysctl(name):
+    try:
+        return subprocess.run(["sysctl", "-n", name], capture_output=True, text=True, timeout=5).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return ""

voxx/engines/__init__.py

@@ -0,0 +1,47 @@
+"""Engine adapters. Worker-side only: an Engine may import heavy inference libraries."""
+
+from pathlib import Path
+from typing import Protocol
+
+import numpy as np
+
+from voxx.models import fake_engine_enabled
+from voxx.output import BUG_HINT, VoxxError
+
+
+class Engine(Protocol):
+    def load(self, path: Path, capability: str) -> None:
+        """Load the Model installed at path, to use it for capability. Called once per Model per worker; never
+        downloads (ADR 0003)."""
+        ...
+
+    def synthesize(self, text: str, *, model: str, voice: str, style: str | None, language: str, seed: int) -> tuple[np.ndarray, int]:
+        """Read one whole Line in one pass, the same way every time for the same seed. language is a BCP 47 tag.
+        Returns mono float32 samples in [-1, 1] and the native sample rate."""
+        ...
+
+    def clone(self, text: str, *, model: str, reference: Path, reference_text: str, language: str,
+              seed: int) -> tuple[np.ndarray, int]:
+        """Read one whole Line in one pass in the voice of the Reference Recording, a WAV at reference whose words are
+        reference_text; otherwise as synthesize does."""
+        ...
+
+    def transcribe(self, path: Path, *, model: str, language: str | None) -> str:
+        """The words spoken in the WAV at path, in language, a BCP 47 tag; None means whatever language is heard."""
+        ...
+
+    def align(self, path: Path, *, model: str, text: str, language: str) -> list[tuple[str, float, float]]:
+        """Each word of text, in order and without punctuation, with the seconds into the WAV at path where it starts
+        and ends. Each Chinese character counts as a word. language is a BCP 47 tag. Raises if it cannot align text
+        with the WAV."""
+        ...
+
+
+def load_engine(name) -> Engine:
+    if name == "fake" and fake_engine_enabled():
+        from voxx.engines.fake import FakeEngine
+        return FakeEngine()
+    if name == "mlx-audio":
+        from voxx.engines.mlx_audio import MlxAudioEngine
+        return MlxAudioEngine()
+    raise VoxxError("unknown_engine", f"No Engine named {name!r}.", BUG_HINT, {"engine": name})

voxx/engines/fake.py

@@ -0,0 +1,122 @@
+"""Test-only Engine: deterministic tones and no model files. Registered only when VOXX_TEST_FAKE_ENGINE=1."""
+
+import json
+import os
+import signal
+import unicodedata
+import wave
+import zlib
+from collections import Counter
+from typing import NamedTuple
+
+import numpy as np
+
+from voxx.models import find_model
+
+SAMPLE_RATE = 24_000
+SECONDS_PER_CHAR = 0.06
+# "load", "synthesize", "transcribe" or "align": the worker is killed at that step, as the OS does when memory runs out.
+# "synthesize:2" kills it the second time it reaches that step, such as at the second Line it reads.
+CRASH_ENV = "VOXX_TEST_FAKE_CRASH"
+# A JSON object from a Line's text to what the fake Engine transcribes instead; any other Line is transcribed as written.
+HEARD_ENV = "VOXX_TEST_FAKE_HEARD"
+# What the fake Engine hears in a recording it did not read itself, such as a Reference Recording; HEARD_ENV can map it
+# to something else too.
+REFERENCE_HEARD = "这是我自己的声音。"
+# A JSON object from a Line's text to the [word, start, end] list the fake Engine aligns it to instead, or to the
+# error it fails with; any other Line's words are spread evenly over the sound in its WAV.
+ALIGNED_ENV = "VOXX_TEST_FAKE_ALIGNED"
+
+
+class Shape(NamedTuple):
+    amplitude: float
+    lead: float  # seconds of silence before the tone
+    tail: float  # seconds of silence after it
+    spike: float = 0  # height of one-sample spikes spread evenly through the tone
+    spikes: int = 1
+
+
+# Seeds 0-6 read in these shapes, so tests can hand the postprocessing different audio; every other seed reads in the first.
+SHAPES = [Shape(0.2, 0.25, 0.35), Shape(0.01, 0.0, 0.8), Shape(0.7, 0.6, 0.0), Shape(0.05, 1.2, 0.02),
+          Shape(0.01, 0.1, 0.1, spike=0.1), Shape(1e-5, 0.1, 0.1), Shape(0.01, 0.1, 0.1, spike=0.9, spikes=60)]
+
+
+class FakeEngine:
+    # A tone carries no words, so the fake Engine transcribes the text it last read in this worker.
+    last_read = None
+
+    def load(self, path, capability):
+        _crash_if("load")
+
+    def synthesize(self, text, *, model, voice, style, language, seed):
+        return _tone(text, seed, SAMPLE_RATE, voice.encode(), (style or "").encode())
+
+    def clone(self, text, *, model, reference, reference_text, language, seed):
+        # The pitch follows the Reference Recording and its words, and the sample rate the Model's registry entry.
+        return _tone(text, seed, find_model(model).sample_rate or SAMPLE_RATE, reference.read_bytes(), reference_text.encode())
+
+    def transcribe(self, path, *, model, language):
+        _crash_if("transcribe")
+        with wave.open(str(path)) as audio:
+            if not any(audio.readframes(audio.getnframes())):
+                return ""
+        heard = REFERENCE_HEARD if FakeEngine.last_read is None else FakeEngine.last_read
+        return json.loads(os.environ.get(HEARD_ENV, "{}")).get(heard, heard)
+
+    def align(self, path, *, model, text, language):
+        _crash_if("align")
+        aligned = json.loads(os.environ.get(ALIGNED_ENV, "{}")).get(text)
+        if isinstance(aligned, str):
+            raise RuntimeError(aligned)
+        if aligned is not None:
+            return [tuple(word) for word in aligned]
+        with wave.open(str(path)) as audio:
+            rate = audio.getframerate()
+            samples = np.frombuffer(audio.readframes(audio.getnframes()), "<i2")
+        sound = np.flatnonzero(samples)
+        start, end = (sound[0], sound[-1] + 1) if len(sound) else (0, len(samples))
+        words = _words(text)
+        step = (end - start) / rate / max(len(words), 1)
+        return [(word, start / rate + i * step, start / rate + (i + 1) * step) for i, word in enumerate(words)]
+
+
+def _tone(text, seed, sample_rate, *voice):
+    """A Line read as a tone whose pitch follows the seed and every part of `voice`, so tests can tell what reached
+    the Engine."""
+    _crash_if("synthesize")
+    FakeEngine.last_read = text
+    frequency = 200 + np.random.default_rng([seed, *map(zlib.crc32, voice)]).integers(0, 2000)
+    shape = SHAPES[seed] if seed < len(SHAPES) else SHAPES[0]
+    t = np.arange(int(sample_rate * len(text) * SECONDS_PER_CHAR)) / sample_rate
+    tone = shape.amplitude * np.sin(2 * np.pi * frequency * t)
+    if shape.spike:
+        tone[(2 * np.arange(shape.spikes) + 1) * len(tone) // (2 * shape.spikes)] = shape.spike
+    lead, tail = np.zeros(int(sample_rate * shape.lead)), np.zeros(int(sample_rate * shape.tail))
+    return np.concatenate([lead, tone, tail]).astype(np.float32), sample_rate
+
+
+def _words(text):
+    """As the real aligner splits a Chinese Line: each Chinese character, and each run of other letters, digits and
+    apostrophes."""
+    words, word = [], ""
+    for c in text:
+        if unicodedata.name(c, "").startswith("CJK UNIFIED"):
+            words += [word, c] if word else [c]
+            word = ""
+        elif c == "'" or unicodedata.category(c)[0] in "LN":
+            word += c
+        elif word:
+            words.append(word)
+            word = ""
+    return words + [word] if word else words
+
+
+# How many times this worker has reached each step.
+_reached = Counter()
+
+
+def _crash_if(step):
+    _reached[step] += 1
+    crash_step, _, nth = os.environ.get(CRASH_ENV, "").partition(":")
+    if crash_step == step and _reached[step] == int(nth or 1):
+        os.kill(os.getpid(), signal.SIGKILL)

voxx/engines/mlx_audio.py

@@ -0,0 +1,57 @@
+"""Runs Models through mlx-audio on Apple Silicon. Imported only inside the worker (ADR 0002)."""
+
+from typing import Any
+
+import mlx.core as mx
+import numpy as np
+from mlx_audio.stt.utils import load as load_stt
+from mlx_audio.tts.utils import load as load_tts
+
+from voxx.output import BUG_HINT, VoxxError
+
+# Narrations name languages by BCP 47 tag; mlx-audio names them in English.
+LANGUAGE_NAMES = {"zh": "chinese", "en": "english", "ja": "japanese", "ko": "korean", "fr": "french", "de": "german",
+                  "it": "italian", "pt": "portuguese", "ru": "russian", "es": "spanish", "ar": "arabic", "id": "indonesian",
+                  "th": "thai", "vi": "vietnamese", "tr": "turkish", "hi": "hindi", "ms": "malay", "nl": "dutch",
+                  "sv": "swedish", "da": "danish", "fi": "finnish", "pl": "polish", "cs": "czech", "fa": "persian",
+                  "el": "greek", "ro": "romanian", "hu": "hungarian", "mk": "macedonian", "yue": "cantonese",
+                  "fil": "filipino"}
+
+
+class MlxAudioEngine:
+    # mlx-audio's Models share no typed interface.
+    model: Any
+
+    def load(self, path, capability):
+        # mlx-audio loads Models that speak and Models that listen through different loaders.
+        self.model = load_stt(path) if capability in ("transcribe", "align") else load_tts(path)
+
+    def synthesize(self, text, *, model, voice, style, language, seed):
+        return self._read(model, seed, text=text, voice=voice, instruct=style, lang_code=LANGUAGE_NAMES[language])
+
+    def clone(self, text, *, model, reference, reference_text, language, seed):
+        # Qwen3-TTS Base clones from ref_audio and ref_text. VoxCPM2 takes ref_audio for the voice and continues
+        # prompt_audio, read as prompt_text, for its closest likeness (upstream's "ultimate cloning"). Each Model's
+        # generate ignores the other's arguments.
+        return self._read(model, seed, text=text, ref_audio=str(reference), ref_text=reference_text,
+                          prompt_audio=str(reference), prompt_text=reference_text, lang_code=LANGUAGE_NAMES[language])
+
+    def _read(self, model, seed, **arguments):
+        # mlx samples from one global generator, so seeding it before each Line makes the Line independent of the others.
+        mx.random.seed(seed)
+        # CustomVoice Models never split a Line; an empty split_pattern keeps the Base ones from splitting it at newlines.
+        results = list(self.model.generate(**arguments, split_pattern="", verbose=False))
+        if len(results) != 1:
+            raise VoxxError("engine_split_line", f"mlx-audio read the Line in {len(results)} parts instead of one.",
+                            BUG_HINT, {"model": model, "parts": len(results)})
+        return np.asarray(results[0].audio, dtype=np.float32), results[0].sample_rate
+
+    def transcribe(self, path, *, model, language):
+        # Greedy decoding, so the same Line is always heard the same way; the path lets mlx-audio resample to 16 kHz.
+        # No language lets Qwen3-ASR detect it.
+        return self.model.generate(str(path), language=language and LANGUAGE_NAMES[language], verbose=False).text
+
+    def align(self, path, *, model, text, language):
+        # The aligner splits the text into words itself: by character for Chinese, by space for English.
+        result = self.model.generate(str(path), text=text, language=LANGUAGE_NAMES[language])
+        return [(item.text, item.start_time, item.end_time) for item in result]

voxx/files.py

@@ -0,0 +1,34 @@
+"""Files and directories: writing so a reader never sees a half-written file, and finding where a path would live."""
+
+import shutil
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def replacing(path):
+    """Yields a temporary path next to `path`; on success it replaces `path`, on failure it is removed."""
+    partial = path.with_name(path.name + ".partial")
+    try:
+        yield partial
+    except BaseException:
+        partial.unlink(missing_ok=True)
+        raise
+    partial.replace(path)
+
+
+@contextmanager
+def staging(directory):
+    """Yields a new hidden directory inside `directory`, so a file written there moves into `directory` with one atomic
+    rename; on the way out it is removed with whatever is still in it."""
+    stage = Path(tempfile.mkdtemp(prefix=".voxx-staging-", dir=directory))
+    try:
+        yield stage
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)
+
+
+def nearest_existing(path):
+    """`path` if it exists, else its closest existing parent: where its disk space would come from."""
+    return next(p for p in (path, *path.parents) if p.exists())