verbalcoding 0.2.12 → 0.2.13

package/integrations/fireredtts2/mlx_llm.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import numpy as np
+import mlx.core as mx
+import mlx.nn as nn
+from mlx.utils import tree_unflatten
+from mlx_lm.models.cache import KVCache
+from mlx_lm.models.qwen2 import ModelArgs as Qwen2Args, TransformerBlock, create_attention_mask
+
+
+@dataclass
+class FireRedMLXArgs:
+    text_vocab_size: int = 151936
+    audio_vocab_size: int = 2051
+    audio_num_codebooks: int = 16
+    hidden_size: int = 1536
+    backbone_layers: int = 28
+    decoder_layers: int = 4
+    num_attention_heads: int = 12
+    num_key_value_heads: int = 2
+    intermediate_size: int = 8960
+    rms_norm_eps: float = 1e-6
+    max_position_embeddings: int = 4096
+    rope_theta: float = 1000000.0
+
+
+def _qwen_args(num_layers: int, args: FireRedMLXArgs) -> Qwen2Args:
+    return Qwen2Args(
+        model_type="qwen2",
+        hidden_size=args.hidden_size,
+        num_hidden_layers=num_layers,
+        intermediate_size=args.intermediate_size,
+        num_attention_heads=args.num_attention_heads,
+        num_key_value_heads=args.num_key_value_heads,
+        rms_norm_eps=args.rms_norm_eps,
+        vocab_size=args.text_vocab_size,
+        max_position_embeddings=args.max_position_embeddings,
+        rope_theta=args.rope_theta,
+        tie_word_embeddings=True,
+    )
+
+
+class QwenStack(nn.Module):
+    def __init__(self, num_layers: int, args: FireRedMLXArgs):
+        super().__init__()
+        qargs = _qwen_args(num_layers, args)
+        self.layers = [TransformerBlock(qargs) for _ in range(num_layers)]
+        self.norm = nn.RMSNorm(args.hidden_size, eps=args.rms_norm_eps)
+
+    def __call__(self, h: mx.array, cache: Optional[list[Any]] = None) -> mx.array:
+        if cache is None:
+            cache = [None] * len(self.layers)
+        mask = create_attention_mask(h, cache[0])
+        for layer, c in zip(self.layers, cache):
+            h = layer(h, mask, c)
+        return self.norm(h)
+
+
+class FireRedMLXLLM(nn.Module):
+    def __init__(self, args: FireRedMLXArgs | None = None):
+        super().__init__()
+        self.args = args or FireRedMLXArgs()
+        a = self.args
+        self.backbone = QwenStack(a.backbone_layers, a)
+        self.decoder = QwenStack(a.decoder_layers, a)
+        self.text_embeddings = nn.Embedding(a.text_vocab_size, a.hidden_size)
+        self.audio_embeddings = nn.Embedding(a.audio_vocab_size * a.audio_num_codebooks, a.hidden_size)
+        self.projection = nn.Linear(a.hidden_size, a.hidden_size, bias=False)
+        self.text_head = nn.Linear(a.hidden_size, a.text_vocab_size, bias=False)
+        self.codebook0_head = nn.Linear(a.hidden_size, a.audio_vocab_size, bias=False)
+        self.audio_head = mx.zeros((a.audio_num_codebooks - 1, a.hidden_size, a.audio_vocab_size))
+        self.backbone_cache: list[KVCache] | None = None
+        self.decoder_cache: list[KVCache] | None = None
+
+    def reset_caches(self) -> None:
+        self.backbone_cache = [KVCache() for _ in range(self.args.backbone_layers)]
+        self.decoder_cache = [KVCache() for _ in range(self.args.decoder_layers)]
+
+    def _embed_audio(self, codebook: int, tokens: mx.array) -> mx.array:
+        return self.audio_embeddings(tokens + codebook * self.args.audio_vocab_size)
+
+    def _embed_tokens(self, tokens: mx.array) -> mx.array:
+        text_embeds = mx.expand_dims(self.text_embeddings(tokens[:, :, -1]), -2)
+        offsets = self.args.audio_vocab_size * mx.arange(self.args.audio_num_codebooks)
+        audio_tokens = tokens[:, :, :-1] + offsets
+        flat = audio_tokens.reshape((-1,))
+        audio_embeds = self.audio_embeddings(flat).reshape(
+            (tokens.shape[0], tokens.shape[1], self.args.audio_num_codebooks, -1)
+        )
+        return mx.concatenate([audio_embeds, text_embeds], axis=-2)
+
+    @staticmethod
+    def _sample_topk(logits: mx.array, topk: int, temperature: float) -> mx.array:
+        # Logits are tiny here (audio vocab ~2k). Move to CPU for robust sampling while
+        # the rest of the heavy transformer math stays on MLX/Metal.
+        arr = np.array(logits / temperature, dtype=np.float64)
+        out = []
+        for row in arr:
+            k = min(topk, row.shape[-1])
+            idx = np.argpartition(row, -k)[-k:]
+            vals = row[idx]
+            vals = vals - vals.max()
+            probs = np.exp(vals)
+            probs = probs / probs.sum()
+            out.append(np.random.choice(idx, p=probs))
+        return mx.array(np.array(out, dtype=np.int32).reshape((-1, 1)))
+
+    def generate_frame(
+        self,
+        tokens: mx.array,
+        tokens_mask: mx.array,
+        temperature: float,
+        topk: int,
+    ) -> mx.array:
+        embeds = self._embed_tokens(tokens)
+        h = mx.sum(embeds * mx.expand_dims(tokens_mask, -1), axis=2)
+        h = self.backbone(h, self.backbone_cache)
+        last_h = h[:, -1, :]
+        c0_logits = self.codebook0_head(last_h)
+        c0_sample = self._sample_topk(c0_logits, topk, temperature)
+        c0_embed = self._embed_audio(0, c0_sample)
+        curr_h = mx.concatenate([mx.expand_dims(last_h, 1), c0_embed], axis=1)
+        curr_sample = c0_sample
+
+        # Decoder cache is per generated frame, matching the Torch implementation.
+        self.decoder_cache = [KVCache() for _ in range(self.args.decoder_layers)]
+        for i in range(1, self.args.audio_num_codebooks):
+            decoder_h = self.decoder(self.projection(curr_h), self.decoder_cache)
+            ci_logits = decoder_h[:, -1, :] @ self.audio_head[i - 1]
+            ci_sample = self._sample_topk(ci_logits, 10, 0.75)
+            ci_embed = self._embed_audio(i, ci_sample)
+            curr_h = ci_embed
+            curr_sample = mx.concatenate([curr_sample, ci_sample], axis=1)
+        mx.eval(curr_sample)
+        return curr_sample
+
+
+def _map_qwen_key(prefix: str, key: str) -> str | None:
+    if not key.startswith(prefix + "."):
+        return None
+    rest = key[len(prefix) + 1 :]
+    rest = rest.replace("attn.output_proj.", "self_attn.o_proj.")
+    if ".attn." in rest:
+        rest = rest.replace(".attn.", ".self_attn.")
+    rest = rest.replace("mlp.w1.", "mlp.gate_proj.")
+    rest = rest.replace("mlp.w2.", "mlp.down_proj.")
+    rest = rest.replace("mlp.w3.", "mlp.up_proj.")
+    rest = rest.replace("sa_norm.scale", "input_layernorm.weight")
+    rest = rest.replace("mlp_norm.scale", "post_attention_layernorm.weight")
+    rest = rest.replace("norm.scale", "norm.weight")
+    return rest
+
+
+def load_firered_mlx_from_state_dict(state_dict: dict[str, Any]) -> FireRedMLXLLM:
+    model = FireRedMLXLLM()
+    flat: list[tuple[str, mx.array]] = []
+    for key, value in state_dict.items():
+        if hasattr(value, "detach"):
+            value = value.detach().cpu().numpy()
+        arr = mx.array(value)
+        if key.startswith("backbone."):
+            mapped = _map_qwen_key("backbone", key)
+            if mapped:
+                flat.append(("backbone." + mapped, arr))
+        elif key.startswith("decoder."):
+            mapped = _map_qwen_key("decoder", key)
+            if mapped:
+                flat.append(("decoder." + mapped, arr))
+        elif key in {
+            "text_embeddings.weight",
+            "audio_embeddings.weight",
+            "projection.weight",
+            "text_head.weight",
+            "codebook0_head.weight",
+            "audio_head",
+        }:
+            flat.append((key, arr))
+    model.update(tree_unflatten(flat))
+    mx.eval(model.parameters())
+    return model

package/integrations/fireredtts2/synth.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""VerbalCoding FireRedTTS-2 synthesis wrapper.
+
+This wrapper gives the Node bridge a stable CLI even though upstream FireRedTTS-2
+is primarily documented as a Python API.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _resolve(root: Path, value: str | None) -> str | None:
+    if not value:
+        return None
+    p = Path(value).expanduser()
+    if not p.is_absolute():
+        p = root / p
+    return str(p)
+
+
+def _auto_device(requested: str) -> str:
+    requested = (requested or "auto").lower()
+    if requested != "auto":
+        return requested
+    try:
+        import torch
+        if torch.cuda.is_available():
+            return "cuda"
+        if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
+            return "mps"
+    except Exception:
+        pass
+    return "cpu"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Synthesize speech with FireRedTTS-2")
+    parser.add_argument("--text", required=True, help="Text to synthesize")
+    parser.add_argument("--output", required=True, help="Output WAV path")
+    parser.add_argument("--pretrained-dir", default="pretrained_models/FireRedTTS2")
+    parser.add_argument("--device", default="auto", help="auto | cuda | mps | cpu")
+    parser.add_argument("--gen-type", default="monologue", choices=["monologue", "dialogue"])
+    parser.add_argument("--speaker", default="S1", help="Speaker tag for monologue text; empty for raw text")
+    parser.add_argument("--prompt-audio", default="", help="Optional zero-shot prompt audio")
+    parser.add_argument("--prompt-text", default="", help="Transcript for prompt audio")
+    parser.add_argument("--temperature", type=float, default=0.9)
+    parser.add_argument("--topk", type=int, default=30)
+    parser.add_argument("--bf16", action="store_true", help="Use bfloat16 when upstream supports it")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    root = _repo_root()
+    vendor = root / "vendor" / "FireRedTTS2"
+    if vendor.exists():
+        sys.path.insert(0, str(vendor))
+
+    try:
+        import torch
+        import soundfile as sf
+        from fireredtts2.fireredtts2 import FireRedTTS2
+    except Exception as exc:
+        print(
+            "FireRedTTS-2 Python dependencies are missing. Run `vc doctor` or "
+            "`scripts/install_fireredtts2.sh --yes` first.\n"
+            f"Import error: {exc}",
+            file=sys.stderr,
+        )
+        return 127
+
+    pretrained_dir = _resolve(root, args.pretrained_dir)
+    if not pretrained_dir or not Path(pretrained_dir).exists():
+        print(
+            f"FireRedTTS-2 pretrained model not found: {pretrained_dir}. "
+            "Run `vc doctor` to download it.",
+            file=sys.stderr,
+        )
+        return 66
+
+    prompt_audio = _resolve(root, args.prompt_audio)
+    prompt_text = args.prompt_text or None
+    if prompt_audio and not Path(prompt_audio).exists():
+        # Do not fail hard for a missing reference sample; random speaker mode is useful
+        # for first-run smoke tests and package installs.
+        prompt_audio = None
+        prompt_text = None
+
+    device = _auto_device(args.device)
+    output = Path(args.output).expanduser()
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    text = args.text.strip()
+    if args.gen_type == "monologue" and args.speaker and not text.startswith("["):
+        text = f"[{args.speaker}]{text}"
+
+    try:
+        if not torch.cuda.is_available():
+            original_torch_load = torch.load
+
+            def torch_load_with_map_location(*load_args, **load_kwargs):
+                load_kwargs.setdefault("map_location", torch.device(device))
+                return original_torch_load(*load_args, **load_kwargs)
+
+            torch.load = torch_load_with_map_location
+
+        model_kwargs = {
+            "pretrained_dir": pretrained_dir,
+            "gen_type": args.gen_type,
+            "device": device,
+        }
+        # Upstream added bf16 later; pass only if accepted.
+        if args.bf16:
+            model_kwargs["use_bf16"] = True
+        try:
+            tts = FireRedTTS2(**model_kwargs)
+        except TypeError:
+            model_kwargs.pop("use_bf16", None)
+            tts = FireRedTTS2(**model_kwargs)
+
+        generate_kwargs = {"text": text, "temperature": args.temperature, "topk": args.topk}
+        if prompt_audio:
+            generate_kwargs["prompt_wav"] = prompt_audio
+            if prompt_text:
+                generate_kwargs["prompt_text"] = prompt_text
+        try:
+            audio = tts.generate_monologue(**generate_kwargs)
+        except TypeError:
+            generate_kwargs.pop("temperature", None)
+            generate_kwargs.pop("topk", None)
+            audio = tts.generate_monologue(**generate_kwargs)
+
+        if hasattr(audio, "detach"):
+            audio = audio.detach().cpu()
+        if hasattr(audio, "numpy"):
+            audio_np = audio.numpy()
+        else:
+            audio_np = audio
+        if getattr(audio_np, "ndim", 1) == 2 and audio_np.shape[0] <= 8:
+            audio_np = audio_np.T
+        sf.write(str(output), audio_np, 24000)
+    except Exception as exc:
+        print(f"FireRedTTS-2 synthesis failed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/integrations/fireredtts2/synth_mlx.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Experimental MLX FireRedTTS-2 synthesis wrapper.
+
+This ports the FireRedTTS-2 LLM token generator to MLX/Metal while keeping the
+RedCodec encode/decode path in Torch. It is intended for Apple Silicon where the
+upstream Torch Qwen generation path can hang or be unusably slow.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _resolve(root: Path, value: str | None) -> str | None:
+    if not value:
+        return None
+    p = Path(value).expanduser()
+    if not p.is_absolute():
+        p = root / p
+    return str(p)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Synthesize speech with FireRedTTS-2 MLX LLM")
+    parser.add_argument("--text", required=True)
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--pretrained-dir", default="pretrained_models/FireRedTTS2")
+    parser.add_argument("--device", default="mlx", help="accepted for compatibility; MLX chooses Metal automatically")
+    parser.add_argument("--gen-type", default="monologue", choices=["monologue", "dialogue"])
+    parser.add_argument("--speaker", default="S1")
+    parser.add_argument("--prompt-audio", default="")
+    parser.add_argument("--prompt-text", default="")
+    parser.add_argument("--temperature", type=float, default=0.9)
+    parser.add_argument("--topk", type=int, default=30)
+    parser.add_argument("--max-audio-ms", type=float, default=12_000)
+    parser.add_argument("--bf16", action="store_true", help="ignored; compatibility with torch wrapper")
+    return parser.parse_args()
+
+
+def log(msg: str) -> None:
+    print(f"[firered-mlx] {msg}", file=sys.stderr, flush=True)
+
+
+def main() -> int:
+    args = parse_args()
+    root = _repo_root()
+    vendor = root / "vendor" / "FireRedTTS2"
+    if vendor.exists():
+        sys.path.insert(0, str(vendor))
+    sys.path.insert(0, str(root))
+
+    try:
+        import numpy as np
+        import mlx.core as mx
+        import torch
+        import torchaudio
+        import soundfile as sf
+        from transformers import AutoTokenizer
+        from fireredtts2.codec import RedCodecInfer
+        from integrations.fireredtts2.mlx_llm import load_firered_mlx_from_state_dict
+    except Exception as exc:
+        print(f"FireRedTTS-2 MLX dependencies missing: {exc}", file=sys.stderr, flush=True)
+        return 127
+
+    pretrained_dir = Path(_resolve(root, args.pretrained_dir) or "")
+    if not pretrained_dir.exists():
+        print(f"FireRedTTS-2 pretrained model not found: {pretrained_dir}", file=sys.stderr, flush=True)
+        return 66
+
+    llm_ckpt = pretrained_dir / ("llm_pretrain.pt" if args.gen_type == "monologue" else "llm_posttrain.pt")
+    codec_config = pretrained_dir / "config_codec.json"
+    codec_ckpt = pretrained_dir / "codec.pt"
+    qwen_path = pretrained_dir / "Qwen2.5-1.5B"
+    output = Path(args.output).expanduser()
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    text = args.text.strip()
+    if args.gen_type == "monologue" and args.speaker and not text.startswith("["):
+        text = f"[{args.speaker}]{text}"
+
+    try:
+        log("loading MLX LLM checkpoint")
+        ckpt = torch.load(str(llm_ckpt), map_location="cpu", weights_only=False)["model"]
+        model = load_firered_mlx_from_state_dict(ckpt)
+        model.reset_caches()
+        del ckpt
+        log("MLX LLM loaded")
+
+        log("loading tokenizer")
+        tokenizer = AutoTokenizer.from_pretrained(str(qwen_path))
+
+        log("loading Torch codec")
+        original_torch_load = torch.load
+        def torch_load_with_map_location(*load_args, **load_kwargs):
+            load_kwargs.setdefault("map_location", torch.device("cpu"))
+            return original_torch_load(*load_args, **load_kwargs)
+        torch.load = torch_load_with_map_location
+        codec = RedCodecInfer.from_pretrained(str(codec_config), str(codec_ckpt)).eval()
+        torch.load = original_torch_load
+        # Keep codec on MPS if possible for decode/optional prompt encode.
+        codec_device = "mps" if torch.backends.mps.is_available() else "cpu"
+        codec = codec.to(codec_device)
+        log(f"codec loaded on {codec_device}")
+
+        frame_tokens = []
+        frame_masks = []
+        prompt_audio = _resolve(root, args.prompt_audio)
+        prompt_text = args.prompt_text or ""
+        if prompt_audio and Path(prompt_audio).exists():
+            log("encoding prompt audio with Torch codec")
+            audio, sr = torchaudio.load(prompt_audio)
+            if audio.shape[0] > 1:
+                audio = audio[0, :].unsqueeze(0)
+            audio16k = torchaudio.functional.resample(audio, sr, 16000)
+            audio_len = torch.tensor([audio16k.shape[1]], dtype=torch.long, device=codec_device)
+            audio_tokens, _ = codec.encode(audio16k.to(codec_device), audio_len, batch_size=24)
+            audio_tokens = audio_tokens.squeeze(0).detach().cpu().numpy()
+
+            speaker = f"[{args.speaker}]" if args.speaker and not args.speaker.startswith("[") else args.speaker
+            ptext = speaker + "<|text_start|>" + prompt_text + "<|text_end|>" if prompt_text else speaker + "<|text_start|><|text_end|>"
+            ids = tokenizer.encode(ptext)
+            tframe = mx.zeros((len(ids), 17), dtype=mx.int32)
+            tmask = mx.zeros((len(ids), 17), dtype=mx.bool_)
+            tframe[:, -1] = mx.array(ids, dtype=mx.int32)
+            tmask[:, -1] = True
+            frame_tokens.append(tframe)
+            frame_masks.append(tmask)
+
+            # add EOS frame after prompt audio
+            eos = np.zeros((audio_tokens.shape[0], 1), dtype=audio_tokens.dtype)
+            audio_tokens = np.concatenate([audio_tokens, eos], axis=1)
+            aframe = mx.zeros((audio_tokens.shape[1], 17), dtype=mx.int32)
+            amask = mx.zeros((audio_tokens.shape[1], 17), dtype=mx.bool_)
+            aframe[:, :-1] = mx.array(audio_tokens.T, dtype=mx.int32)
+            amask[:, :-1] = True
+            frame_tokens.append(aframe)
+            frame_masks.append(amask)
+
+        log("tokenizing target text")
+        speaker = ""
+        target = text
+        if text.startswith("[") and "]" in text:
+            speaker = text[: text.index("]") + 1]
+            target = text[text.index("]") + 1 :]
+        ids = tokenizer.encode(speaker + "<|text_start|>" + target + "<|text_end|>")
+        tframe = mx.zeros((len(ids), 17), dtype=mx.int32)
+        tmask = mx.zeros((len(ids), 17), dtype=mx.bool_)
+        tframe[:, -1] = mx.array(ids, dtype=mx.int32)
+        tmask[:, -1] = True
+        frame_tokens.append(tframe)
+        frame_masks.append(tmask)
+
+        curr_tokens = mx.expand_dims(mx.concatenate(frame_tokens, axis=0), 0)
+        curr_mask = mx.expand_dims(mx.concatenate(frame_masks, axis=0), 0)
+        mx.eval(curr_tokens, curr_mask)
+        log(f"prompt frames={curr_tokens.shape[1]}")
+
+        max_generation_len = max(1, int(args.max_audio_ms / 80))
+        samples = []
+        for i in range(max_generation_len):
+            sample = model.generate_frame(curr_tokens, curr_mask, args.temperature, args.topk)
+            mx.eval(sample)
+            if bool(mx.all(sample == 0).item()):
+                log(f"eos at frame {i}")
+                break
+            samples.append(sample)
+            zero = mx.zeros((1, 1), dtype=mx.int32)
+            curr_tokens = mx.expand_dims(mx.concatenate([sample, zero], axis=1), 1)
+            curr_mask = mx.expand_dims(mx.concatenate([mx.ones(sample.shape, dtype=mx.bool_), mx.zeros((1, 1), dtype=mx.bool_)], axis=1), 1)
+            if i == 0 or (i + 1) % 20 == 0:
+                log(f"generated frames={i+1}")
+        if not samples:
+            raise RuntimeError("MLX LLM produced no audio frames")
+
+        log("decoding audio tokens with Torch codec")
+        toks_np = mx.concatenate([mx.expand_dims(s, 0) for s in samples], axis=0)
+        toks_np = np.array(toks_np).transpose(1, 2, 0)
+        toks = torch.from_numpy(toks_np).long().to(codec_device)
+        audio = codec.decode(toks).squeeze(0).squeeze(0).detach().cpu().numpy()
+        sf.write(str(output), audio, 24000)
+        log(f"wrote {output}")
+        return 0
+    except Exception as exc:
+        print(f"FireRedTTS-2 MLX synthesis failed: {exc}", file=sys.stderr, flush=True)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/integrations/mlxaudio/synth.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""VerbalCoding mlx-audio synthesis wrapper."""
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Synthesize speech with mlx-audio")
+    parser.add_argument("--text", required=True)
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--model", default="mlx-community/Qwen3-TTS-12Hz-1.7B-Base-8bit")
+    parser.add_argument("--voice", default="Chelsie")
+    parser.add_argument("--lang-code", default="ko")
+    parser.add_argument("--stream", action="store_true")
+    return parser.parse_args()
+
+
+def newest_audio_file(directory: Path) -> Path | None:
+    candidates = []
+    for pattern in ("*.wav", "*.mp3", "*.flac", "*.m4a"):
+        candidates.extend(directory.glob(pattern))
+    if not candidates:
+        return None
+    return max(candidates, key=lambda p: p.stat().st_mtime)
+
+
+def main() -> int:
+    args = parse_args()
+    output = Path(args.output).expanduser()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="verbalcoding-mlxaudio-") as tmp:
+        out_dir = Path(tmp)
+        cmd = [
+            sys.executable,
+            "-m",
+            "mlx_audio.tts.generate",
+            "--model",
+            args.model,
+            "--text",
+            args.text,
+            "--voice",
+            args.voice,
+            "--lang_code",
+            args.lang_code,
+            "--output_path",
+            str(out_dir),
+            "--join_audio",
+        ]
+        if args.stream:
+            cmd.extend(["--stream", "--save"])
+        try:
+            subprocess.run(cmd, check=True, text=True, timeout=None)
+        except ModuleNotFoundError:
+            print("mlx-audio is not installed. Run scripts/install_mlxaudio.sh --yes first.", file=sys.stderr)
+            return 127
+        except subprocess.CalledProcessError as exc:
+            print(f"mlx-audio synthesis failed with exit {exc.returncode}", file=sys.stderr)
+            return exc.returncode or 1
+        audio = newest_audio_file(out_dir)
+        if not audio:
+            print("mlx-audio did not produce an audio file", file=sys.stderr)
+            return 66
+        shutil.copyfile(audio, output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())