### Install and Run Studio UI

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/guides/web-ui-api-server.md

Navigate to the UI directory, install dependencies, and start the development server. The UI will be accessible at http://localhost:3000.

```bash
cd mlx_audio/ui
npm install
npm run dev
```

--------------------------------

### Development Setup for mlx-audio Docs

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install mlx-audio in editable mode with development and documentation tooling dependencies.

```bash
pip install -e ".[dev,docs]"
```

--------------------------------

### Development Setup for mlx-audio

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Clone the repository and install mlx-audio in editable mode with development dependencies.

```bash
git clone https://github.com/Blaizzy/mlx-audio.git
cd mlx-audio
pip install -e ".[dev]"
```

--------------------------------

### ODE Solver Configuration Examples

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Examples of configuring ODE solver options for different quality and speed tradeoffs.

```python
# Maximum Quality - 32 midpoint steps (slowest, cleanest)
ode_opt = {"method": "midpoint", "step_size": 2/64}  # 32 midpoint steps
```

```python
# Official Default - 16 midpoint steps
ode_opt = {"method": "midpoint", "step_size": 2/32}  # 16 midpoint steps
```

```python
# Balanced - Good for separate_long()
ode_opt = {"method": "euler", "step_size": 2/64}     # 32 euler steps
```

```python
# Fastest - Real-time, may have artifacts
ode_opt = {"method": "euler", "step_size": 2/32}     # 16 euler steps
```

--------------------------------

### Start API Server Only

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/guides/web-ui-api-server.md

Launches the MLX Audio API server on all interfaces, port 8000. This is the basic command to get the server running.

```bash
mlx_audio.server --host 0.0.0.0 --port 8000
```

--------------------------------

### Install mlx-audio with Docs Extra

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install mlx-audio with the dependencies required for documentation tooling.

```bash
# Documentation tooling
pip install "mlx-audio[docs]"
```

--------------------------------

### Install mlx-audio CLI from Source with uv

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install the mlx-audio CLI tools from the latest source code on GitHub using uv.

```bash
# Latest code from GitHub
uv tool install --force git+https://github.com/Blaizzy/mlx-audio.git --prerelease=allow
```

--------------------------------

### Quick Install mlx-audio with pip

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Use this command for a standard installation of mlx-audio.

```bash
pip install mlx-audio
```

--------------------------------

### Install mlx-audio CLI with uv

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install the mlx-audio CLI tools globally using uv. This command installs the latest release from PyPI.

```bash
# Latest release from PyPI
uv tool install --force mlx-audio --prerelease=allow
```

--------------------------------

### Build Documentation

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/dev-setup.md

Install documentation dependencies, serve the documentation locally, or build the static documentation site.

```bash
# Install docs dependencies
pip install -e ".[docs]"
```

```bash
# Serve docs locally
mkdocs serve
```

```bash
# Build static site
mkdocs build
```

--------------------------------

### Install Kokoro Dependencies

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/tts/kokoro.md

Install the base 'misaki' dependency for text processing. Optionally install language-specific support for Japanese or Chinese.

```bash
pip install misaki

pip install misaki[ja]
pip install misaki[zh]
```

--------------------------------

### Install mlx-audio with All Extras

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install mlx-audio with all available optional dependencies, including TTS, STT, and STS.

```bash
# Everything
pip install "mlx-audio[all]"
```

--------------------------------

### Install MLX-Audio CLI tools with uv (latest release)

Source: https://github.com/blaizzy/mlx-audio/blob/main/README.md

Install only the command-line interface tools for MLX-Audio from the latest PyPI release using uv. Allows prerelease versions.

```bash
uv tool install --force mlx-audio --prerelease=allow
```

--------------------------------

### Run Local Server and UI

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/dev-setup.md

Start the MLX Audio API server locally and launch the web UI development server.

```bash
# API server
mlx_audio.server --host localhost --port 8000
```

```bash
# Web UI (separate terminal)
cd mlx_audio/ui
npm install
npm run dev
```

--------------------------------

### Start API Server with Studio UI

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/guides/web-ui-api-server.md

Starts the MLX Audio API server and the Next.js Studio UI. The API will be accessible at http://localhost:8000 and the UI at http://localhost:3000.

```bash
mlx_audio.server --host 0.0.0.0 --port 8000 --start-ui
```

--------------------------------

### Install mlx-audio with STT Extra

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install mlx-audio with only the speech-to-text dependencies.

```bash
# STT only
pip install "mlx-audio[stt]"
```

--------------------------------

### Install MLX-Audio for development

Source: https://github.com/blaizzy/mlx-audio/blob/main/README.md

Clone the repository and install MLX-Audio in editable mode with development and server dependencies. Recommended for contributing to the project or running the web interface.

```bash
git clone https://github.com/Blaizzy/mlx-audio.git
cd mlx-audio
pip install -e "[dev, server]"
```

--------------------------------

### Install mlx-audio with TTS Extra

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install mlx-audio with only the text-to-speech dependencies.

```bash
# TTS only
pip install "mlx-audio[tts]"
```

--------------------------------

### Install ffmpeg on Ubuntu/Debian

Source: https://github.com/blaizzy/mlx-audio/blob/main/README.md

Install ffmpeg on Ubuntu or Debian systems using apt. This is necessary for audio encoding in various formats.

```bash
# Ubuntu/Debian
sudo apt install ffmpeg
```

--------------------------------

### Example: Batch Processing with Different Anchors

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Shows how to apply different temporal anchors to multiple audio samples within a single batch processing operation.

```python
# Batch processing with different anchors per sample
batch = processor(
    descriptions=["speech", "music"],
    audios=["audio1.wav", "audio2.wav"],
    anchors=[
        [("+", 0.0, 2.0)],           # First sample
        [("+", 1.0, 4.0), ("-", 6.0, 8.0)],  # Second sample
    ],
)
```

--------------------------------

### Start MLX-Audio API Server

Source: https://github.com/blaizzy/mlx-audio/blob/main/README.md

Starts the MLX-Audio API server on the specified host and port. This server provides OpenAI-compatible API endpoints.

```bash
# Start API server
mlx_audio.server --host 0.0.0.0 --port 8000

# Start web UI (in another terminal)
cd mlx_audio/ui
npm install && npm run dev
```

--------------------------------

### Install MLX Audio Server Dependencies

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/guides/web-ui-api-server.md

Install the MLX Audio package with the 'server' optional dependency group to include FastAPI, Uvicorn, and python-multipart.

```bash
pip install "mlx-audio[server]"
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/dev-setup.md

Synchronize project dependencies using uv. Use --extra flag to include optional extras like 'docs'.

```bash
uv sync
```

```bash
uv sync --extra docs
```

```bash
uv sync --all-extras
```

--------------------------------

### Install Optional Dependencies

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/dev-setup.md

Install specific optional dependencies for TTS, STT, API server, or documentation tooling using pip.

```bash
pip install -e ".[tts]"
```

```bash
pip install -e ".[stt]"
```

```bash
pip install -e ".[server]"
```

```bash
pip install -e ".[docs]"
```

```bash
pip install -e ".[dev,docs,tts,stt,server]"
```

--------------------------------

### Load Moshi Model

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/moshi/README.md

Loads a quantized Moshi model from HuggingFace using the mlx_audio library. This is a quick way to get started with the model.

```python
from mlx_audio.sts import load

model = load("kyutai/moshiko-mlx-q4")
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/dev-setup.md

Install project dependencies in editable mode using pip. Include 'dev' extras for development, and 'docs' for documentation work.

```bash
pip install -e ".[dev]"
```

```bash
pip install -e ".[dev,docs]"
```

--------------------------------

### Load Model and Generate Audio Tasks in Python

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/stt/models/qwen2_audio/README.md

Load the Qwen2-Audio model and perform transcription, audio understanding, and translation. Ensure the 'mlx_audio' library is installed.

```python
from mlx_audio.stt.utils import load_model

model = load_model("mlx-community/Qwen2-Audio-7B-Instruct-4bit")

# Transcription
result = model.generate("audio.wav", prompt="Transcribe the audio.")
print(result.text)

# Audio understanding
result = model.generate("audio.wav", prompt="What emotion is the speaker expressing?")
print(result.text)

# Translation
result = model.generate("audio.wav", prompt="Translate the speech to French.")
print(result.text)
```

--------------------------------

### Install MLX-Audio Library

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/lfm_audio/README.md

The installation command for the mlx-audio package via pip.

```bash
pip install mlx-audio
```

--------------------------------

### Install ffmpeg on Ubuntu/Debian

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install the ffmpeg dependency on Ubuntu or Debian systems using apt. This is required for saving audio in MP3, FLAC, OGG, Opus, or Vorbis formats.

```bash
sudo apt install ffmpeg
```

--------------------------------

### Quick Start with Model-Specific Initializer

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/mossformer2_se/README.md

Load the MossFormer2 SE model directly using its specific initializer and enhance an audio file. Requires importing the model class and save_audio function.

```python
from mlx_audio.sts.models.mossformer2_se import (
    MossFormer2SEModel,
    save_audio,
)

# Load model
model = MossFormer2SEModel.from_pretrained("starkdmi/MossFormer2_SE_48K_MLX")

# Enhance audio
enhanced = model.enhance("noisy.wav")

# Save result
save_audio(enhanced, "enhanced.wav", 48000)
```

--------------------------------

### Load FSMN-VAD Model via Framework

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/vad/models/fsmn/README.md

Recommended way to load the FSMN-VAD model using the high-level load function. Ensure mlx_audio is installed.

```python
from mlx_audio.vad import load

model = load("mlx-community/fsmn-vad")
```

--------------------------------

### Quick Start with STS Loader

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/mossformer2_se/README.md

Load the MossFormer2 SE model using the standard STS loader and enhance an audio file. Requires importing load and save_audio functions.

```python
from mlx_audio.sts import load
from mlx_audio.sts.models.mossformer2_se import save_audio

# Standard STS loader
model = load("starkdmi/MossFormer2_SE_48K_MLX")

# Enhance audio
enhanced = model.enhance("noisy.wav")

# Save result
save_audio(enhanced, "enhanced.wav", 48000)
```

--------------------------------

### Generate Audio with MOSS-TTS (CLI)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/moss_tts/README.md

Provides an example of using the MOSS-TTS command-line interface to generate audio from text. Specify the model, text, and output path.

```bash
python -m mlx_audio.tts.generate \
  --model OpenMOSS-Team/MOSS-TTS-v1.5 \
  --text "Hello, this is MOSS-TTS running on MLX." \
  --output_path outputs
```

--------------------------------

### CLI Transcription with Context using VibeVoice-ASR

Source: https://github.com/blaizzy/mlx-audio/blob/main/README.md

Shows command-line usage for VibeVoice-ASR transcription with context (hotwords) to guide the model.

```bash
# With context/hotwords
python -m mlx_audio.stt.generate \
    --model mlx-community/VibeVoice-ASR-bf16 \
    --audio technical_talk.wav \
    --output-path output \
    --format json \
    --max-tokens 8192 \
    --context "MLX, Apple Silicon, PyTorch, Transformer" \
    --verbose
```

--------------------------------

### Example: Using Positive and Negative Anchors

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Illustrates the use of both positive ('+') and negative ('-') anchors to specify where the target sound is present and absent within specific time intervals.

```python
# Multiple anchors - target is here but NOT there
batch = processor(
    descriptions=["speech"],
    audios=["audio.wav"],
    anchors=[[("+", 1.5, 3.0), ("-", 5.0, 7.0)]],
)
```

--------------------------------

### Quick Start: Audio Separation with Temporal Anchors

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Perform audio separation using temporal anchors to specify a time range for the target sound. Anchors are passed directly with file paths.

```python
from mlx_audio.sts import SAMAudio, save_audio

model = SAMAudio.from_pretrained("facebook/sam-audio-large")

# Use anchors directly with file paths
result = model.separate(
    audios=["path/to/audio.mp3"],
    descriptions=["speech"],
    anchors=[[("+", 1.5, 3.0)]],  # Target speech from 1.5s to 3.0s
)

save_audio(result.target[0], "separated.wav", sample_rate=model.sample_rate)
```

--------------------------------

### Load Liquid2.5-Audio Model

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/sts/index.md

Load the Liquid2.5-Audio model, a multimodal foundation model for various voice tasks. This example loads a 4-bit quantized version.

```python
from mlx_audio.sts import load

model = load("mlx-community/LFM2.5-Audio-1.5B-4bit")
```

--------------------------------

### Saving Separated Audio

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Example of how to save the separated target and residual audio to WAV files using the `save_audio` utility function.

```python
from mlx_audio.sts import save_audio

save_audio(result.target[0], "target.wav", sample_rate=model.sample_rate)
save_audio(result.residual[0], "residual.wav", sample_rate=model.sample_rate)
```

--------------------------------

### Example: Extracting Speech within a Time Range

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Demonstrates using a positive anchor to extract speech occurring between 1.5 and 3.0 seconds.

```python
# Extract speech occurring between 1.5s and 3.0s
batch = processor(
    descriptions=["speech"],
    audios=["audio.wav"],
    anchors=[[("+", 1.5, 3.0)]],
)
```

--------------------------------

### Load STT Model and Generate Transcription

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/api-reference/stt.md

Demonstrates how to load a pre-trained STT model and generate a transcription from audio data. Ensure the 'mlx_audio' library is installed and the audio data is available.

```python
from mlx_audio.stt import load

model = load("mlx-community/whisper-tiny-asr-fp16")
result = model.generate(audio)
```

--------------------------------

### Quick Start: Basic Audio Separation

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Load the SAMAudio model and perform basic audio separation using file paths and text descriptions. Saves the separated audio to a WAV file and prints peak memory usage.

```python
from mlx_audio.sts import SAMAudio, save_audio

# Load model
model = SAMAudio.from_pretrained("facebook/sam-audio-large")

# Separate audio - pass file paths directly!
result = model.separate(
    audios=["path/to/audio.mp3"],  # File paths or mx.array
    descriptions=["speech"],
)

# Save output
save_audio(result.target[0], "separated.wav", sample_rate=model.sample_rate)
print(f"Peak memory: {result.peak_memory:.2f} GB")
```

--------------------------------

### Sway Sampling for Faster Inference (Python)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/irodori_tts/README.md

Example of using Sway Sampling with fewer Euler steps for faster inference. Configure `num_steps` and `t_schedule_mode`.

```python
generate_audio(
    model="mlx-community/Irodori-TTS-500M-v3-fp16",
    text="今日はいい天気ですね。",
    ref_audio="speaker.wav",
    file_prefix="output",
    num_steps=6,
    t_schedule_mode="sway",
    sway_coeff=-1.0,
)
```

--------------------------------

### Load and Generate Speech with MOSS-TTS v1.5

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/tts/moss-tts.md

Quick start for loading the MOSS-TTS v1.5 model and generating speech from text. Requires `mlx_audio` library. The generated audio is saved to 'moss_tts.wav'.

```python
from mlx_audio.audio_io import write as audio_write
from mlx_audio.tts import load

model = load("OpenMOSS-Team/MOSS-TTS-v1.5", lazy=True)

result = next(model.generate(
    text="Hello, this is MOSS-TTS running on MLX.",
    max_tokens=120,
))
audio_write("moss_tts.wav", result.audio, result.sample_rate)
```

--------------------------------

### Real-time Speech-to-Speech Generation with Moshi

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/moshi/README.md

Demonstrates real-time speech-to-speech generation using the Moshi model. It loads a quantized model, streams audio output to speakers, and prints the generated inner monologue. This example requires the `sounddevice` and `numpy` libraries.

```python
from mlx_audio.sts.models.moshi import MoshiSTSModel
import sounddevice as sd
import numpy as np

# Load quantized model directly from HuggingFace
model = MoshiSTSModel.from_pretrained("kyutai/moshiko-mlx-q4", quantized=4)

# Open audio output stream
stream = sd.OutputStream(samplerate=24000, channels=1, dtype=np.float32)
stream.start()

print("Generating...")
# Generate 150 steps (~12 seconds of audio)
for word, pcm_frame in model.generate(steps=150):
    if word:
        # Print inner monologue as it generates
        print(word, end="", flush=True)
        
    if pcm_frame is not None:
        # Stream audio directly to speakers
        stream.write(np.array(pcm_frame))

stream.stop()
stream.close()
```

--------------------------------

### Zero-Shot Generation (Chinese) with AudioDiT

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/longcat_audiodit/README.md

Generate speech in Chinese using the AudioDiT model. This example demonstrates zero-shot generation without specific voice cloning parameters.

```python
result = next(model.generate(
    text="今天晴暖转阴雨，空气质量优至良，空气相对湿度较低。",
    steps=16,
    cfg_strength=4.0,
))
```

--------------------------------

### Sortformer v1 RTTM Output Format Example

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/vad/index.md

Example of the RTTM (Rich Transcription Time Marked) format for speaker diarization output. It specifies speaker segments with start and end times.

```text
SPEAKER audio 1 0.000 3.200 <NA> <NA> speaker_0 <NA> <NA>
SPEAKER audio 1 3.520 5.120 <NA> <NA> speaker_1 <NA> <NA>
```

--------------------------------

### Get Sentence and Word Timestamps

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/stt/parakeet.md

After transcribing audio, iterate through the 'sentences' attribute of the result object to access sentence-level start and end times along with the transcribed text.

```python
result = model.generate("audio.wav")
for sentence in result.sentences:
    print(f"[{sentence.start:.2f}s - {sentence.end:.2f}s] {sentence.text}")
```

--------------------------------

### Get Segment-Level Timestamps (Python)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/stt/models/whisper/README.md

Generates speech-to-text transcription with segment-level timestamps enabled by default. It iterates through the 'segments' in the result to print the start time, end time, and transcribed text for each segment. Requires a loaded Whisper model.

```python
result = model.generate("audio.wav")
for segment in result.segments:
    print(f"[{segment['start']:.2f} -> {segment['end']:.2f}] {segment['text']}")
```

--------------------------------

### Load and Use Qwen2-Audio Model in Python

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/stt/qwen2-audio.md

Load the Qwen2-Audio model using `mlx_audio.stt.utils.load_model` and generate text from an audio file with a given prompt. The result's text attribute contains the output.

```python
from mlx_audio.stt.utils import load_model

model = load_model("mlx-community/Qwen2-Audio-7B-Instruct-4bit")

result = model.generate("audio.wav", prompt="Transcribe the audio.")
print(result.text)
```

--------------------------------

### Run Qwen2-Audio Transcription via CLI

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/stt/qwen2-audio.md

Use this command-line interface to transcribe audio files using a specified Qwen2-Audio model. Ensure the model and audio file path are correctly provided.

```bash
python -m mlx_audio.stt.generate \
    --model mlx-community/Qwen2-Audio-7B-Instruct-4bit \
    --audio audio.wav \
    --prompt "Transcribe the audio."
```

--------------------------------

### Load Mel-Band-RoFormer Model with Presets

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/mel_roformer/README.md

Demonstrates how to load a Mel-Band-RoFormer model using predefined configuration presets or a custom configuration. Ensure the chosen preset matches the checkpoint family.

```python
from mlx_audio.sts.models.mel_roformer import MelRoFormer, MelRoFormerConfig

# Pick the config preset matching your checkpoint family
config = MelRoFormerConfig.kim_vocal_2()           # depth=6
# or:
config = MelRoFormerConfig.viperx_vocals()         # depth=12
# or:
config = MelRoFormerConfig.zfturbo_bs_roformer()   # depth=12
# or for non-standard variants:
config = MelRoFormerConfig.custom(depth=8, num_bands=48)

# Load from a local directory (must contain a matching safetensors file)
model = MelRoFormer.from_pretrained("./my_weights_dir", config=config)

# Or from a HuggingFace repo ID (if the repo contains a compatible
# `<name>.config.json` produced by convert.py, the config is loaded from there)
model = MelRoFormer.from_pretrained("your-org/mel-band-roformer-mlx")
```

--------------------------------

### Install ffmpeg on macOS

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/installation.md

Install the ffmpeg dependency on macOS using Homebrew. This is required for saving audio in MP3, FLAC, OGG, Opus, or Vorbis formats.

```bash
brew install ffmpeg
```

--------------------------------

### Get Segment-Level Timestamps

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/stt/whisper.md

Retrieve segment-level timestamps for the transcription. This is enabled by default.

```python
result = model.generate("audio.wav")
for segment in result.segments:
    print(f"[{segment['start']:.2f} -> {segment['end']:.2f}] {segment['text']}")
```

--------------------------------

### STT Output Format Example

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/stt/models/cohere_asr/README.md

Illustrates the structure of the output from the transcription model, including the full text, segmented results, and metadata.

```python
STTOutput(
    text="Full transcription text",
    segments=[
        {"text": "segment text", "start": 0.0, "end": 12.3},
        ...
    ],
    language="en",
    prompt_tokens=9,
    generation_tokens=42,
    total_tokens=51,
    total_time=1.8,
    prompt_tps=5.0,
    generation_tps=23.3,
)
```

--------------------------------

### Load and Generate Audio with MOSS-TTS (Python API)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/moss_tts/README.md

Demonstrates loading a MOSS-TTS model and generating audio from text using the Python API. Ensure the model is loaded with lazy=True for efficient memory usage.

```python
from mlx_audio.audio_io import write as audio_write
from mlx_audio.tts import load

model = load("OpenMOSS-Team/MOSS-TTS-v1.5", lazy=True)

result = next(model.generate(
    text="Hello, this is MOSS-TTS running on MLX.",
    max_tokens=120,
))
audio_write("output.wav", result.audio, result.sample_rate)
```

--------------------------------

### CLI Transcription with VibeVoice-ASR

Source: https://github.com/blaizzy/mlx-audio/blob/main/README.md

Demonstrates basic command-line usage for VibeVoice-ASR transcription, including specifying the model, audio file, and output format.

```bash
# Basic transcription
python -m mlx_audio.stt.generate \
    --model mlx-community/VibeVoice-ASR-bf16 \
    --audio meeting.wav \
    --output-path output \
    --format json \
    --max-tokens 8192 \
    --verbose
```

--------------------------------

### load

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/api-reference/stt.md

Loads an STT model from a specified path or HuggingFace repository. This function is used to get a model object that can then be used for transcription.

```APIDOC
## load

### Description
Loads an STT model from a specified path or HuggingFace repository.

### Method
```python
load(model_path: str, device=None, dtype=None)
```

### Parameters
#### Path Parameters
- **model_path** (str) - Required - Path to the model or HuggingFace repo.
- **device** (Optional) - The device to load the model on.
- **dtype** (Optional) - The data type to use for the model weights.

### Response
Returns a model object that can be used for transcription.
```

--------------------------------

### Get Word-Level Timestamps

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/stt/whisper.md

Enable word-level timestamps using cross-attention alignment heads via DTW for detailed transcription timing.

```python
result = model.generate("audio.wav", word_timestamps=True)
for segment in result.segments:
    for word in segment["words"]:
        print(f"[{word['start']:.2f} -> {word['end']:.2f}] {word['word']} (p={word['probability']:.3f})")
```

--------------------------------

### Generate Audio with Style-Controlled Voice Cloning (CLI)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/irodori_tts/README.md

Use the command-line to generate audio with style-controlled voice cloning. Provide the model, text, reference audio, and a detailed instruction for the voice style.

```bash
python -m mlx_audio.tts.generate \
  --model mlx-community/Irodori-TTS-600M-v3-VoiceDesign-fp16 \
  --text "今日はいい天気ですね。" \
  --ref_audio speaker.wav \
  --instruct "深く傷つき、今にも泣き出しそうな様子。声が震えており、悲痛なトーンで弱々しく話す。"
```

--------------------------------

### Generate Speech with MoshiSTSModel

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/sts/index.md

Generates speech using the Moshi STS model and streams the output audio. Ensure sounddevice and numpy are installed.

```python
from mlx_audio.sts.models.moshi import MoshiSTSModel
import sounddevice as sd
import numpy as np

model = MoshiSTSModel.from_pretrained("kyutai/moshiko-mlx-q4", quantized=4)

stream = sd.OutputStream(samplerate=24000, channels=1, dtype=np.float32)
stream.start()

for word, pcm_frame in model.generate(steps=150):
    if word:
        print(word, end="", flush=True)
    if pcm_frame is not None:
        stream.write(np.array(pcm_frame))

stream.stop()
stream.close()
```

--------------------------------

### Python API for Text-to-Speech

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/higgs_audio_v3/README.md

Use the Python API to load the model and generate speech from text. Ensure mlx_audio is installed and the model is available.

```python
from mlx_audio.audio_io import write as audio_write
from mlx_audio.tts import load

model = load("bosonai/higgs-audio-v3-tts-4b")

result = next(model.generate(
    text="Hello from Higgs Audio v3 on MLX.",
    temperature=1.0,
    max_new_tokens=2048,
))
audio_write("output.wav", result.audio, result.sample_rate)
```

--------------------------------

### Voice Design with VoxCPM2 (Python API)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/voxcpm2/README.md

Shows how to create a voice from a text description using the 'instruct' parameter in the model.generate method. This allows for generating speech with specific voice characteristics without reference audio.

```python
result = next(model.generate(
    text="Hello, welcome to VoxCPM2.",
    instruct="A young woman, warm and gentle voice",
))
```

--------------------------------

### Python API for Text-to-Speech

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/omnivoice/README.md

Load the OmniVoice model and tokenizers, then generate speech from text using the Python API. Ensure necessary libraries are installed.

```python
from transformers import AutoTokenizer
from mlx_audio.codec.models.higgs_audio.higgs_audio import HiggsAudioTokenizer
from mlx_audio.tts.models.omnivoice.omnivoice import Model, OmniVoiceConfig
from mlx_audio.audio_io import write as audio_write
import mlx.core as mx, json, numpy as np

model_path = "path/to/OmniVoice"

# Load model
with open(f"{model_path}/config.json") as f:
    raw = json.load(f)
config = OmniVoiceConfig.from_dict(raw)
model = Model(config)
weights = model.sanitize(dict(mx.load(f"{model_path}/model.safetensors")))
model.load_weights(list(weights.items()))
mx.eval(model.parameters())

# Load tokenizers
tokenizer = HiggsAudioTokenizer.from_pretrained(model_path)
text_tokenizer = AutoTokenizer.from_pretrained(f"{model_path}/tokenizer")

# Generate speech
result = next(model.generate(
    text="Hello, this is OmniVoice running on Apple Silicon.",
    language="en",
    duration_s=5.0,
    tokenizer=tokenizer,
    text_tokenizer=text_tokenizer,
))
audio_write("output.wav", np.array(result.audio), result.sample_rate)
```

--------------------------------

### Default ODE Solver Options

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Reference default ODE solver options from the official SAM-Audio implementation.

```python
DFLT_ODE_OPT = {"method": "midpoint", "step_size": 2/32}  # 16 midpoint steps
```

--------------------------------

### Speech Continuation with VoxCPM2 (Python API)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/voxcpm2/README.md

Demonstrates how to continue generating speech seamlessly from a previous audio clip using the 'prompt_text' and 'prompt_audio' parameters. This is useful for generating long-form content like audiobooks.

```python
result = next(model.generate(
    text=" and this continues seamlessly from the previous sentence.",
    prompt_text="The previous sentence spoken aloud",
    prompt_audio="previous.wav",
))
```

--------------------------------

### Load and Generate Audio with KugelAudio (Python)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/kugelaudio/README.md

Use this Python API to load the KugelAudio model and generate speech from text. Requires the mlx_audio library. Adjust `cfg_scale` and `ddpm_steps` for guidance strength and quality.

```python
from mlx_audio.tts import load

model = load("kugelaudio/kugelaudio-0-open")

result = next(model.generate(
    text="Hello, this is KugelAudio running on Apple Silicon.",
    cfg_scale=3.0,
    ddpm_steps=10,
))
audio = result.audio  # mx.array, 24kHz
```

--------------------------------

### API Request for Text-to-Speech

Source: https://github.com/blaizzy/mlx-audio/blob/main/README.md

Example cURL command to make a Text-to-Speech request to the MLX-Audio API server. Specify model, input text, and voice.

```bash
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "mlx-community/Kokoro-82M-bf16", "input": "Hello!", "voice": "af_heart"}' \
  --output speech.wav
```

--------------------------------

### Load and Generate with Sortformer v1

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/vad/models/sortformer/README.md

Demonstrates how to load the Sortformer v1 model directly from HuggingFace and perform offline diarization on an audio file. Requires the 'mlx-audio' library.

```python
from mlx_audio.vad import load

model = load("mlx-community/diar_sortformer_4spk-v1-fp32")
result = model.generate("audio.wav", threshold=0.5, verbose=True)
print(result.text)
```

--------------------------------

### Qwen3-ForcedAligner Word-Level Alignment

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/getting-started/quickstart-python.md

Aligns spoken words in an audio file to a given text using the Qwen3-ForcedAligner. Provides start and end times for each word.

```python
from mlx_audio.stt import load

aligner = load("mlx-community/Qwen3-ForcedAligner-0.6B-8bit")
result = aligner.generate("audio.wav", text="I have a dream", language="English")

for item in result:
    print(f"[{item.start_time:.2f}s - {item.end_time:.2f}s] {item.text}")
```

--------------------------------

### CLI for MOSS-TTS-Nano

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/tts/models/moss_tts_nano/README.md

This command-line interface command generates audio with a cloned voice using the MOSS-TTS-Nano model. Provide the model name, text, and a reference audio file.

```bash
python -m mlx_audio.tts.generate \
  --model mlx-community/MOSS-TTS-Nano-100M \
  --text "Hello, this is a cloned voice." \
  --ref_audio speaker.wav
```

--------------------------------

### Separate Method Parameters

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/sam_audio/README.md

Demonstrates the parameters for the `separate()` method, including audio sources, text descriptions, optional temporal anchors, ODE solver options, and chunked decoding size.

```python
result = model.separate(
    audios=["audio.mp3"],             # File paths or (B, 1, T) tensor
    descriptions=["speech"],          # List of text prompts
    anchors=[[("+", 1.0, 5.0)]],      # Optional: temporal anchors (with file paths)
    ode_opt=None,                     # ODE solver options (see below)
    ode_decode_chunk_size=50,         # Chunked decoding (reduces memory)
)
```

--------------------------------

### STT Generation Pattern Example

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/architecture.md

STT models expose a `generate()` method that returns a result object with a `.text` attribute. Some models also support streaming.

```python
result = model.generate("audio.wav")
print(result.text)
```

--------------------------------

### TTS Generation Pattern Example

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/architecture.md

TTS models implement a generator function for `generate()` that yields `GenerationResult` objects. This supports both non-streaming and streaming audio generation.

```python
for result in model.generate(text="Hello!", voice="af_heart"):
    # result.audio is an mx.array waveform
    # result.sample_rate, result.audio_duration, etc.
```

--------------------------------

### Upload Converted Model to Hugging Face Hub CLI

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/guides/quantization.md

Convert a model and upload it directly to the Hugging Face Hub by adding the `--upload-repo` flag with your desired repository path.

```bash
python -m mlx_audio.convert \
    --hf-path prince-canuma/Kokoro-82M \
    --mlx-path ./Kokoro-82M-4bit \
    --quantize \
    --q-bits 4 \
    --upload-repo username/Kokoro-82M-4bit
```

--------------------------------

### Separate Audio with SAM-Audio

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/sts/index.md

Use SAM-Audio to separate a mixed audio file based on a text description. This example shows how to save the separated target and residual audio.

```python
from mlx_audio.sts import SAMAudio, save_audio

# Load model
model = SAMAudio.from_pretrained("facebook/sam-audio-large")

# Separate audio using a text prompt
result = model.separate(
    audios=["mixed_audio.wav"],
    descriptions=["A person speaking"],
)

# Save separated audio
save_audio(result.target[0], "voice.wav", sample_rate=model.sample_rate)
save_audio(result.residual[0], "background.wav", sample_rate=model.sample_rate)
```

--------------------------------

### Load Pretrained LFM2AudioModel (Python)

Source: https://github.com/blaizzy/mlx-audio/blob/main/mlx_audio/sts/models/lfm_audio/README.md

Shows how to load a pretrained LFM2AudioModel from the HuggingFace Hub. This is the initial step for utilizing the model's capabilities for audio and text generation.

```python
class LFM2AudioModel:
    @classmethod
    def from_pretrained(cls, model_name: str) -> "LFM2AudioModel":
        """Load pretrained model from HuggingFace Hub."""

```

--------------------------------

### BaseModelArgs Dataclass Example

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/contributing/architecture.md

A dataclass base with a `from_dict()` class method that filters unknown keys, allowing `config.json` files to contain extra fields without errors.

```python
@dataclass
class MyModelConfig(BaseModelArgs):
    hidden_size: int = 512
```

--------------------------------

### Import audio I/O functions

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/api-reference/index.md

Import functions for reading and writing audio files.

```python
from mlx_audio.audio_io import read, write
```

--------------------------------

### Configure CORS Allowed Origins

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/guides/web-ui-api-server.md

Starts the server with specific allowed origins for CORS, restricting access to the specified URLs. Alternatively, set the MLX_AUDIO_ALLOWED_ORIGINS environment variable.

```bash
mlx_audio.server --allowed-origins http://localhost:3000 https://myapp.example.com
```

--------------------------------

### Generate Audio with Reference Voice

Source: https://github.com/blaizzy/mlx-audio/blob/main/examples/voice_prompts/README.md

Demonstrates how to use a reference audio file and its corresponding transcript to generate new audio with a cloned voice using HiggsAudioServer.

```python
from mlx_audio.tts.models.higgs_audio import HiggsAudioServer
from pathlib import Path

voice_dir = Path("examples/voice_prompts")
ref_wav = voice_dir / "en_woman.wav"
ref_txt = (voice_dir / "en_woman.txt").read_text().strip()

server = HiggsAudioServer.from_pretrained(
    model_path="mlx-community/higgs-audio-v2-3B-mlx-q8",
    codec_path="mlx-community/higgs-audio-v2-tokenizer",
)

result = server.generate(
    target_text="Anything you want cloned in the chosen voice.",
    reference_audio_path=str(ref_wav),
    reference_text=ref_txt,
    temperature=0.7,
    top_p=0.95,
    max_new_frames=1200,
    fade_in_ms=30.0,
)

```

--------------------------------

### Load and Use Silero VAD Model

Source: https://github.com/blaizzy/mlx-audio/blob/main/docs/models/vad/index.md

Load the Silero VAD model and get speech timestamps from an audio file. The `return_seconds=True` argument provides timestamps in seconds.

```python
from mlx_audio.vad import load

model = load("mlx-community/silero-vad")
timestamps = model.get_speech_timestamps("audio.wav", return_seconds=True)
print(timestamps)
```