### Install FFmpeg on Linux

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Instructions for installing FFmpeg on Linux using apt-get.

```bash
sudo apt-get install ffmpeg
```

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

### FFmpeg Not Found Error Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Illustrates a `RuntimeError` indicating that FFmpeg is not installed, which is required for processing various audio formats.

```text
RuntimeError: ffmpeg not found
```

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

### Install mlx-voxtral from Source

Source: https://github.com/mzbac/mlx.voxtral/blob/main/README.md

Clone the repository and install mlx-voxtral in development mode.

```bash
# Clone the repository
git clone https://github.com/mzbac/mlx.voxtral
cd mlx.voxtral

# Install in development mode
pip install -e .
```

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

### Install Transformers Library

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Install the transformers library if it is missing, which is required for using the processor.

```bash
pip install transformers
```

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

### Install Soundfile for Faster Audio Loading

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Install the soundfile library for recommended and faster audio loading. If not available, the system falls back to ffmpeg-based loading.

```bash
pip install soundfile  # Recommended, faster loading
```

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

### Install mlx-voxtral from PyPI

Source: https://github.com/mzbac/mlx.voxtral/blob/main/README.md

Install the mlx-voxtral package and its required transformers dependency from PyPI.

```bash
# Install mlx-voxtral from PyPI
pip install mlx-voxtral

# Install transformers from GitHub (required)
pip install git+https://github.com/huggingface/transformers
```

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

### VoxtralTextConfig Initialization and Serialization Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Demonstrates how to initialize a VoxtralTextConfig with custom parameters, convert it to a dictionary, and then reconstruct a new config object from that dictionary.

```python
from mlx_voxtral import VoxtralTextConfig

config = VoxtralTextConfig(
    vocab_size=200000,
    hidden_size=4096,
    num_hidden_layers=40
)
config_dict = config.to_dict()

config2 = VoxtralTextConfig.from_dict(config_dict)
assert config2.vocab_size == 200000
```

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

### Install MLX Framework

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Install the MLX framework, which is required for the MLX Voxtral functionality. This framework is specific to Apple Silicon Macs. You can install from PyPI or directly from the source repository.

```bash
pip install mlx
# Or install from source for latest features
pip install git+https://github.com/ml-explore/mlx.git
```

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

### Install FFmpeg on macOS

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Instructions for installing FFmpeg on macOS using Homebrew or by manually adding it to the system's PATH.

```bash
# Using Homebrew
brew install ffmpeg

# Or manually add to path
export PATH="/usr/local/bin:$PATH"
```

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

### Create Fine-tuning Configuration

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Sets up a Voxtral configuration for fine-tuning. Includes examples of increasing dropout rates for regularization in both audio and text components.

```python
config = VoxtralConfig()

# Might increase dropout for regularization
config.audio_config.dropout = 0.1
config.audio_config.attention_dropout = 0.1
config.text_config.attention_dropout = 0.1
```

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

### VoxtralEncoderConfig from_dict() Class Method Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Demonstrates how to create a VoxtralEncoderConfig object from a dictionary. This is useful for loading configurations that have been previously serialized.

```python
from mlx_voxtral import VoxtralEncoderConfig

config = VoxtralEncoderConfig(hidden_size=2560, num_hidden_layers=48)
config_dict = config.to_dict()

# Later, recreate from dict
config2 = VoxtralEncoderConfig.from_dict(config_dict)
assert config2.hidden_size == 2560
```

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

### Example Usage of VoxtralConfig

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Demonstrates creating a VoxtralConfig instance with dictionary inputs for audio and text configurations, converting it to a dictionary, and then creating a new config from that dictionary.

```python
from mlx_voxtral import VoxtralConfig

config = VoxtralConfig(
    audio_config={
        "hidden_size": 1280,
        "num_hidden_layers": 32
    },
    text_config={
        "vocab_size": 131072,
        "hidden_size": 3072
    },
    audio_token_id=24
)

config_dict = config.to_dict()
config2 = VoxtralConfig.from_dict(config_dict)
```

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

### Install Soxr for High-Quality Resampling

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Install the soxr library for high-quality audio resampling. If not installed, the system will fall back to using librosa or ffmpeg.

```bash
pip install soxr  # High-quality resampling
```

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

### Quantization Configuration Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Illustrates the structure of a quantization configuration within a model's config.json. This includes details like group size, bits, and layer-specific quantization settings.

```json
{
    "model_type": "voxtral",
    "audio_config": {...},
    "text_config": {...},
    "quantization": {
        "group_size": 64,
        "bits": 4,
        "layer_name": {"bits": 8, "group_size": 128},
        ...
    }
}
```

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

### MLX Unsupported Hardware Error Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Shows a `RuntimeError` indicating that the MLX library is being used on hardware other than Apple Silicon, which is a requirement.

```text
RuntimeError: MLX only supports Apple Silicon
```

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

### TranscriptionInputs Usage Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/types.md

Shows how to generate transcription inputs using a processor and then pass these inputs to the model. The `apply_transcrition_request` method handles audio loading and preprocessing.

```python
inputs = processor.apply_transcrition_request(
    audio="speech.mp3",
    language="en"
)

# Access fields
model_output = model(
    input_ids=inputs.input_ids,
    input_features=inputs.input_features
)
```

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

### VoxtralModelOutput Usage Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/types.md

Demonstrates how to access the output attributes like logits and past_key_values from a model's output. The `return_dict=True` argument is necessary to get a structured output object.

```python
output = model(
    input_ids=input_ids,
    input_features=input_features,
    return_dict=True
)

logits = output.logits  # [1, seq_len, 131072]
cache = output.past_key_values  # For next generation step
```

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

### Streaming Transcription Output Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Shows the format of output when using the `--stream` flag, where tokens are displayed as they are generated, followed by final metrics.

```text
Here is the transcribed text from the audio...
(tokens printed as generated)

==================================================
Generated 156 tokens in 2.34 seconds (66.67 tokens/s)
==================================================
```

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

### Model Not Found Error Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Example of a `FileNotFoundError` that occurs if the specified model ID or path is incorrect or the model is not downloaded.

```text
FileNotFoundError: Model not found at path
```

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

### Verbose Transcription Output Example

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Illustrates the detailed output provided when the `--verbose` flag is used, including model loading times and generation metrics.

```text
Loading model: mistralai/Voxtral-Mini-3B-2507
Model loaded in 3.45 seconds
Model dtype: bfloat16

Processing audio: speech.mp3

Generating transcription...

==================================================
TRANSCRIPTION:
==================================================
Here is the transcribed text from the audio file...
==================================================

Generated 156 tokens in 2.34 seconds (66.67 tokens/s)
```

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

### Quantization output log

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Example log output from the quantization process, showing model loading, quantization parameters, saving progress, and final statistics on bits per weight and layer-specific quantization decisions.

```text
Loading model from mistralai/Voxtral-Mini-3B-2507
Model loaded with lazy evaluation
Quantizing model with 4 bits and group size 64
Using mixed precision quantization
Saving quantized model to ./voxtral-mini-4bit
Copying tokenizer and processor files...
Copied generation_config.json
Copied tekken.json
...

Quantized model to average 3.87 bits per weight

Quantization decisions for key layers:
  encoder.embed_positions: not quantized
  encoder.layers.0.self_attn.q_proj: 6 bits, group_size=64
  multi_modal_projector.linear_1: 6 bits, group_size=64
  language_model.layers.0.self_attn.q_proj: 4 bits, group_size=64
  language_model.layers.0.mlp.gate_proj: 4 bits, group_size=64
  lm_head: 6 bits, group_size=64

✅ Quantization complete! Model saved to: ./voxtral-mini-4bit
```

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

### Handle RuntimeError for Missing FFmpeg

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Catch and provide guidance when FFmpeg is not found, which is required for audio loading. This includes checking if the 'soundfile' library is installed and if the FFmpeg binary is in the system's PATH.

```python
from mlx_voxtral import load_audio

try:
    audio = load_audio("speech.mp3")
except RuntimeError as e:
    if "ffmpeg not found" in str(e):
        print("Install ffmpeg: brew install ffmpeg")
```

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

### VoxtralEncoder Example Usage

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/models.md

Demonstrates how to instantiate and use the VoxtralEncoder with random mel-spectrogram input. The output shape indicates the transformed embedding dimensions.

```python
from mlx_voxtral import VoxtralEncoder
from mlx_voxtral.configuration_voxtral import VoxtralEncoderConfig

config = VoxtralEncoderConfig()
encoder = VoxtralEncoder(config)

# Input: [1, 128, 3000] — one 30-second chunk
mel_features = mx.random.normal((1, 128, 3000))
output = encoder(mel_features)
print(output[0].shape)  # (1, 1500, 1280)
```

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

### Load and Use MLX Voxtral Model

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/utilities.md

Demonstrates the complete pipeline for loading a Voxtral model and processor, preparing inputs from audio, generating transcription, and decoding the output. Ensure you have the necessary libraries installed and audio files available.

```python
from mlx_voxtral import load_voxtral_model, VoxtralProcessor

# 1. Load model and config
model, config = load_voxtral_model(
    "mistralai/Voxtral-Mini-3B-2507",
    dtype=mx.float16
)

# 2. Load processor
processor = VoxtralProcessor.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)

# 3. Prepare inputs
inputs = processor.apply_transcrition_request(
    audio="speech.mp3",
    language="en"
)

# 4. Generate
outputs = model.generate(
    input_ids=inputs.input_ids,
    input_features=inputs.input_features,
    max_new_tokens=1024,
    temperature=0.0
)

# 5. Decode
transcription = processor.decode(
    outputs[0, inputs.input_ids.shape[1]:],
    skip_special_tokens=True
)
```

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

### Provide valid audio content fields

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

When using audio content in messages, ensure one of the required fields ('path', 'url', 'audio', 'base64') is present. This example shows valid formats.

```python
{"type": "audio", "path": "speech.mp3"}
{"type": "audio", "url": "https://example.com/audio.mp3"}
{"type": "audio", "audio": audio_array}
```

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

### Generate from quantized model via command line

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Shows how to use a quantized model for generation directly from the command line, specifying the path to the quantized model and the audio input file.

```bash
mlx-voxtral.generate \
  --model ./voxtral-mini-4bit \
  --audio speech.mp3
```

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

### VoxtralTextConfig Initialization and Methods

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Demonstrates how to initialize VoxtralTextConfig with custom parameters and use its `to_dict` and `from_dict` methods.

```APIDOC
## VoxtralTextConfig

Configuration for the text decoder (Llama-like language model).

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `vocab_size` | `int` | 131072 | Text vocabulary size (token count) |
| `hidden_size` | `int` | 3072 | LM hidden dimension |
| `intermediate_size` | `int` | 8192 | FFN intermediate size |
| `num_hidden_layers` | `int` | 30 | Number of decoder layers |
| `num_attention_heads` | `int` | 32 | Number of attention heads |
| `num_key_value_heads` | `int` | 8 | Number of KV heads (GQA) |
| `max_position_embeddings` | `int` | 131072 | Maximum sequence length |
| `rms_norm_eps` | `float` | 1e-05 | RMSNorm epsilon |
| `rope_theta` | `float` | 100000000.0 | RoPE theta parameter |
| `rope_scaling` | `Dict | None` | None | RoPE scaling configuration |
| `tie_word_embeddings` | `bool` | False | Share embeddings with output layer |
| `use_cache` | `bool` | True | Use KV cache for generation |
| `hidden_act` | `str` | "silu" | Activation function (silu or gelu) |
| `initializer_range` | `float` | 0.02 | Weight initialization std |
| `attention_bias` | `bool` | False | Include bias in attention |
| `attention_dropout` | `float` | 0.0 | Attention dropout |
| `mlp_bias` | `bool` | False | Include bias in MLP |
| `head_dim` | `int` | 128 | Dimension per attention head |
| `model_type` | `str` | "llama" | Model type (for compatibility) |
| `pretraining_tp` | `int` | 1 | Tensor parallel size (unused) |
| `sliding_window` | `int | None` | None | Sliding window attention size |

### Methods

#### to_dict()

```python
def to_dict(self) -> Dict
```

**Returns**: Dictionary with all non-None fields

#### from_dict() (Class Method)

```python
@classmethod
def from_dict(cls, config_dict: Dict) -> VoxtralTextConfig
```

Only includes known fields, filtering out extra keys.

**Example**:
```python
from mlx_voxtral import VoxtralTextConfig

config = VoxtralTextConfig(
    vocab_size=200000,
    hidden_size=4096,
    num_hidden_layers=40
)
config_dict = config.to_dict()

config2 = VoxtralTextConfig.from_dict(config_dict)
assert config2.vocab_size == 200000
```
```

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

### Create mx.array

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/types.md

Demonstrates creating mx.array from lists, random initialization, and zero initialization. Requires importing mlx.core.

```python
import mlx.core as mx

arr = mx.array([1, 2, 3])  # From list
arr = mx.random.normal((3, 4))  # Random
arr = mx.zeros((2, 3))  # Zeros
```

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

### Integrate Quantization Script with Python

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Shows how to invoke the quantization script from within a Python script by manipulating sys.argv.

```python
from mlx_voxtral.scripts.quantize_voxtral import main as quantize

sys.argv = [
    "mlx-voxtral.quantize",
    "mistralai/Voxtral-Mini-3B-2507",
    "--output-dir", "./voxtral-mini-4bit",
    "--bits", "4"
]
quantize()
```

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

### Get Cached Mel Filters

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/audio-processing.md

Retrieves mel filters using lazy evaluation and caching to optimize performance for repeated calls.

```python
def get_mel_filters(n_mels: int = N_MELS) -> mx.array
```

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

### Load processor with tokenizer

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Initialize the VoxtralProcessor by loading a pre-trained model which includes the tokenizer. This is the recommended way to ensure all components are correctly set up.

```python
# Load processor with tokenizer
processor = VoxtralProcessor.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)

# Or initialize with tokenizer
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained(model_id)
processor = VoxtralProcessor(tokenizer=tokenizer)
```

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

### CLI Entry Points

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/INDEX.md

Command-line interface entry points for MLX Voxtral.

```APIDOC
## mlx-voxtral.generate

### Description
CLI command for generating content with Voxtral.

### Method
CLI command

### Endpoint
Not applicable

### Parameters
None specified in source.

### Request Example
```bash
mlx-voxtral generate --prompt "Your prompt here"
```

### Response
None specified in source.
```

```APIDOC
## mlx-voxtral.quantize

### Description
CLI command for quantizing Voxtral models.

### Method
CLI command

### Endpoint
Not applicable

### Parameters
None specified in source.

### Request Example
```bash
mlx-voxtral quantize --model-path "path/to/model"
```

### Response
None specified in source.
```

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

### Handle Audio Loading Errors from URL

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Demonstrates how to catch and handle ValueError when attempting to load audio from a URL that may be invalid, inaccessible, or return an error. This includes checking for connection timeouts, invalid URLs, server errors, and corrupted data.

```python
extractor = VoxtralFeatureExtractor()

try:
    features = extractor("https://invalid-domain.xyz/audio.mp3")
except ValueError as e:
    print(f"Error loading: {e}")
```

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

### Initializing VoxtralForConditionalGeneration Model

Source: https://github.com/mzbac/mlx.voxtral/blob/main/README.md

Load the VoxtralForConditionalGeneration model from a pre-trained checkpoint. Optionally specify the data type for the model weights.

```python
model = VoxtralForConditionalGeneration.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507",
    dtype=mx.bfloat16  # Optional: specify dtype
)

# Generate transcription
outputs = model.generate(
    **inputs,
    max_new_tokens=1024,
    temperature=0.0,
    do_sample=False
)
```

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

### Initialize VoxtralMultiModalProjector

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/models.md

Initializes the VoxtralMultiModalProjector module. This class projects audio embeddings from encoder space to language model space.

```python
class VoxtralMultiModalProjector(nn.Module):
    def __init__(self, config: VoxtralConfig)
```

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

### Loading Pre-quantized Models

Source: https://github.com/mzbac/mlx.voxtral/blob/main/README.md

Access pre-quantized models for convenience. These models offer reduced memory footprints, making them suitable for environments with limited resources.

```python
models = {
    "mzbac/voxtral-mini-3b-4bit-mixed": "3.2GB model with mixed precision",
    "mzbac/voxtral-mini-3b-8bit": "5.3GB model with 8-bit quantization"
}
```

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

### Create Default Transcription Configuration

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Initializes a standard Voxtral configuration suitable for transcription tasks. Shows how to adjust parameters like hidden size for faster inference with lower precision.

```python
from mlx_voxtral import VoxtralConfig

# Standard transcription config
config = VoxtralConfig()

# Adjust for faster inference (lower precision)
config.audio_config.hidden_size = 640
config.text_config.hidden_size = 1536
config.text_config.num_hidden_layers = 15
```

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

### Generated files for quantized model

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Lists the files generated in the output directory after quantization, including model weights, configuration files, tokenizer, and processor settings. These files are necessary for inference.

```text
voxtral-mini-4bit/
├── config.json                    # Full config with quantization info
├── model-00001-of-00004.safetensors
├── model-00002-of-00004.safetensors
├── model-00003-of-00004.safetensors
├── model-00004-of-00004.safetensors
├── model.safetensors.index.json   # Weight mapping
├── generation_config.json         # Generation defaults
├── tekken.json                    # Mistral tokenizer
├── preprocessor_config.json       # Audio preprocessing
└── special_tokens_map.json        # Special token definitions
```

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

### Quantize Model with MLX Voxtral

Source: https://github.com/mzbac/mlx.voxtral/blob/main/README.md

Use the mlx-voxtral.quantize command-line tool to quantize models. Basic 4-bit quantization is recommended for a balance of size and quality. Mixed precision offers the best quality, while custom settings allow for specific bit depths and group sizes.

```bash
# Basic 4-bit quantization (recommended)
mlx-voxtral.quantize mistralai/Voxtral-Mini-3B-2507 -o ./voxtral-mini-4bit
```

```bash
# Mixed precision quantization (best quality)
mlx-voxtral.quantize mistralai/Voxtral-Mini-3B-2507 --output-dir ./voxtral-mini-mixed --mixed
```

```bash
# Custom quantization settings
mlx-voxtral.quantize mistralai/Voxtral-Mini-3B-2507 \
    --output-dir ./voxtral-mini-8bit \
    --bits 8 \
    --group-size 32
```

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

### Handle Quantization Output Directory Error

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

When quantizing, ensure the output directory does not already exist. Remove or specify a different directory if it does.

```bash
mlx-voxtral.quantize mistralai/Voxtral-Mini-3B-2507 \
  --output-dir ./existing_dir
```

```text
ValueError: Output directory ./existing_dir already exists
```

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

### Programmatic Transcription with Voxtral

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Illustrates direct programmatic transcription using Voxtral models and processors in Python, including loading the model and generating text from audio.

```python
from mlx_voxtral import (
    VoxtralForConditionalGeneration,
    VoxtralProcessor,
    load_voxtral_model
)
import mlx.core as mx

# Programmatic transcription
model = VoxtralForConditionalGeneration.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507",
    dtype=mx.float16
)
processor = VoxtralProcessor.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)

inputs = processor.apply_transcrition_request(
    audio="speech.mp3",
    language="en"
)

for token, _ in model.generate_stream(**inputs):
    text = processor.decode([token], skip_special_tokens=True)
    print(text, end='', flush=True)
```

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

### Troubleshooting: Insufficient disk space

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

This error indicates that there is not enough disk space to complete the quantization process. Quantized models are temporary, so ensure you have at least twice the expected final size of free disk space available.

```text
Error: No space left on device
```

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

### Integrate Transcription Script with Python

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Demonstrates how to use the transcription script programmatically within a Python script by setting sys.argv.

```python
from mlx_voxtral.scripts.generate import main as transcribe
import sys

sys.argv = [
    "mlx-voxtral.generate",
    "--model", "mistralai/Voxtral-Mini-3B-2507",
    "--audio", "speech.mp3",
    "--language", "en"
]
transcribe()
```

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

### Initializing VoxtralProcessor

Source: https://github.com/mzbac/mlx.voxtral/blob/main/README.md

Load the VoxtralProcessor from a pre-trained checkpoint. This processor is used for preparing audio inputs and decoding model outputs.

```python
processor = VoxtralProcessor.from_pretrained("mistralai/Voxtral-Mini-3B-2507")

# Apply transcription formatting
inputs = processor.apply_transcrition_request(
    language="en",  # or "fr", "de", etc.
    audio="path/to/audio.mp3",
    task="transcribe",  # or "translate"
)

# Decode model outputs
text = processor.decode(token_ids, skip_special_tokens=True)
```

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

### Load and use quantized model in Python

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Demonstrates how to load a quantized Voxtral model and its processor using the same API as the full model. This code snippet shows the typical workflow for applying transcription requests and generating output.

```python
from mlx_voxtral import (
    VoxtralForConditionalGeneration,
    VoxtralProcessor
)

# Load quantized model (identical API)
model = VoxtralForConditionalGeneration.from_pretrained(
    "./voxtral-mini-4bit"
)
processor = VoxtralProcessor.from_pretrained(
    "./voxtral-mini-4bit"
)

# Use exactly the same as full model
inputs = processor.apply_transcrition_request(
    audio="speech.mp3",
    language="en"
)
outputs = model.generate(**inputs)
```

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

### Simple Audio Transcription with Voxtral

Source: https://github.com/mzbac/mlx.voxtral/blob/main/README.md

Load the Voxtral model and processor to transcribe an audio file. Ensure the audio file and model are accessible.

```python
from mlx_voxtral import VoxtralForConditionalGeneration, VoxtralProcessor

# Load model and processor
model = VoxtralForConditionalGeneration.from_pretrained("mistralai/Voxtral-Mini-3B-2507")
processor = VoxtralProcessor.from_pretrained("mistralai/Voxtral-Mini-3B-2507")

# Transcribe audio
inputs = processor.apply_transcrition_request(
    language="en",
    audio="speech.mp3"
)
outputs = model.generate(**inputs, max_new_tokens=1024, temperature=0.0)
transcription = processor.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(transcription)
```

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

### Basic Transcription

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/API-OVERVIEW.md

Demonstrates how to perform basic audio transcription using VoxtralForConditionalGeneration and VoxtralProcessor. It loads a pre-trained model, processes an audio file, generates a transcription, and decodes the output.

```APIDOC
## Basic Transcription

### Description
This example shows how to transcribe an audio file using the `VoxtralForConditionalGeneration` model and `VoxtralProcessor`. It covers loading the model and processor, applying a transcription request, generating output, and decoding the transcription.

### Code
```python
from mlx_voxtral import VoxtralForConditionalGeneration, VoxtralProcessor

model = VoxtralForConditionalGeneration.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)
processor = VoxtralProcessor.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)

inputs = processor.apply_transcrition_request(
    language="en",
    audio="speech.mp3"
)
outputs = model.generate(**inputs, max_new_tokens=1024, temperature=0.0)
transcription = processor.decode(
    outputs[0][inputs.input_ids.shape[1]:],
    skip_special_tokens=True
)
print(transcription)
```
```

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

### Load Voxtral Model Configuration from Hub

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Automatically loads the configuration file (config.json) from a specified HuggingFace model repository. Accesses audio and text configuration parameters after loading.

```python
from mlx_voxtral import VoxtralForConditionalGeneration

# Automatically loads config.json from HuggingFace
model = VoxtralForConditionalGeneration.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)

# Access loaded config
print(model.config.audio_config.hidden_size)  # 1280
print(model.config.text_config.vocab_size)    # 131072
```

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

### Basic Transcription with mlx-voxtral.generate

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Performs audio transcription using default model and parameters. Requires an audio file path.

```bash
mlx-voxtral.generate --audio speech.mp3
```

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

### load_config()

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/utilities.md

Loads the model configuration from a specified directory. It reads the `config.json` file.

```APIDOC
## load_config()

### Description
Loads the model configuration from a specified directory. It reads the `config.json` file.

### Method
`load_config(model_path: Path) -> Dict`

### Parameters
#### Path Parameters
- **model_path** (Path) - Required - Directory containing `config.json`

### Returns
- **Dict** - Dictionary with configuration

### Raises
- **FileNotFoundError** - if config.json not found

### Example
```python
from pathlib import Path
from mlx_voxtral.utils.model_loading import load_config

model_path = Path("/path/to/voxtral-mini")
config = load_config(model_path)
print(config["audio_config"]["hidden_size"])  # 1280
```
```

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

### VoxtralProcessor.from_pretrained()

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/processing.md

Loads a VoxtralProcessor from a pretrained model on HuggingFace Hub. This method initializes the processor with a tokenizer and feature extractor.

```APIDOC
## VoxtralProcessor.from_pretrained() (Class Method)

Load processor from a pretrained model on HuggingFace Hub.

```python
@classmethod
def from_pretrained(
    cls,
    pretrained_model_name_or_path,
    **kwargs,
) -> VoxtralProcessor
```

**Returns**: Initialized VoxtralProcessor with loaded tokenizer and feature extractor

**Example**:
```python
from mlx_voxtral import VoxtralProcessor

processor = VoxtralProcessor.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)
```
```

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

### Load Model Configuration

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/utilities.md

Loads the model configuration from a specified directory. Expects a `config.json` file within the directory. Raises `FileNotFoundError` if `config.json` is not found.

```python
from pathlib import Path
from mlx_voxtral.utils.model_loading import load_config

model_path = Path("/path/to/voxtral-mini")
config = load_config(model_path)
print(config["audio_config"]["hidden_size"])  # 1280
```

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

### Complete Voxtral Transcription Pipeline

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/processing.md

This snippet demonstrates the full pipeline for transcribing audio using the Voxtral processor and model. It covers loading the processor and model, applying a transcription request, passing inputs to the model for generation, and decoding the output transcription. Ensure audio files and model IDs are correctly specified.

```python
# Complete pipeline
processor = VoxtralProcessor.from_pretrained(model_id)
model = VoxtralForConditionalGeneration.from_pretrained(model_id)

inputs = processor.apply_transcrition_request(
    audio="speech.mp3",
    language="en"
)

# Pass to model
outputs = model.generate(
    input_ids=inputs.input_ids,
    input_features=inputs.input_features,
    max_new_tokens=1024,
    temperature=0.0
)

# Decode output
generated_ids = outputs[0, inputs.input_ids.shape[1]:]
transcription = processor.decode(generated_ids, skip_special_tokens=True)
```

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

### VoxtralConfig Initialization

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Initializes the VoxtralConfig with various parameters for audio and text components, including special token IDs and activation functions.

```APIDOC
## VoxtralConfig

Complete configuration for the full model combining encoder and decoder.

```python
class VoxtralConfig:
    def __init__(
        self,
        audio_config: Optional[Union[VoxtralEncoderConfig, Dict]] = None,
        text_config: Optional[Union[VoxtralTextConfig, Dict]] = None,
        audio_token_id: Optional[int] = 24,
        projector_hidden_act: str = "gelu",
        pad_token_id: int = 11,
        bos_token_id: int = 1,
        eos_token_id: int = 2,
        **kwargs,
    )
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `audio_config` | `VoxtralEncoderConfig | Dict | None` | Audio encoder config |
| `text_config` | `VoxtralTextConfig | Dict | None` | Text decoder config |
| `audio_token_id` | `int` | 24 | Special token ID for audio placeholder |
| `projector_hidden_act` | `str` | "gelu" | Activation in multi-modal projector |
| `pad_token_id` | `int` | 11 | Padding token ID |
| `bos_token_id` | `int` | 1 | Beginning of sequence token ID |
| `eos_token_id` | `int` | 2 | End of sequence token ID |
| `**kwargs` | — | — | Additional attributes (dynamic) |

### Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `audio_config` | `VoxtralEncoderConfig` | Audio encoder configuration |
| `text_config` | `VoxtralTextConfig` | Text decoder configuration |
| `audio_token_id` | `int` | Audio placeholder token |
| `projector_hidden_act` | `str` | Projector activation |
| `model_type` | `str` | Always "voxtral" |
| `vocab_size` | `int` | From text_config.vocab_size |
| `hidden_size` | `int` | From text_config.hidden_size |

**Auto-conversion**: If `audio_config` or `text_config` are dicts, they are automatically converted to config objects.
```

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

### Handle NotImplementedError: Base64 audio not supported

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Catch this error when attempting to use base64-encoded audio in `apply_chat_template`. Base64 audio is not yet supported; convert to a file or URL, or pass as an array.

```python
content = [
    {"type": "audio", "base64": "..."}
]

try:
    processor.apply_chat_template([{"role": "user", "content": content}])
except NotImplementedError:
    print("Base64 audio not yet supported")
```

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

### Streaming Transcription with Verbose Metrics

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/cli-tools.md

Enables real-time streaming of transcription output and displays detailed performance metrics during processing. Useful for monitoring transcription progress and performance.

```bash
mlx-voxtral.generate \
  --audio speech.mp3 \
  --stream \
  --verbose
```

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

### KVCache Usage for Efficient Generation

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/types.md

Illustrates initializing and updating KVCache for efficient tensor caching during model generation. Requires importing KVCache from mlx_lm.models.cache.

```python
from mlx_lm.models.cache import KVCache

cache = [KVCache() for _ in range(num_layers)]

# During generation:
output = model(
    input_ids=token,
    past_key_values=cache
)
```

```python
cache.update_and_fetch(keys, values)  # Update cache and get all values
cache.offset  # Current position in sequence
```

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

### VoxtralTextConfig from_dict() Class Method

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Creates a VoxtralTextConfig object from a dictionary. It filters out any unknown keys, ensuring only valid configuration parameters are used.

```python
@classmethod
def from_dict(cls, config_dict: Dict) -> VoxtralTextConfig
```

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

### Handle FileNotFoundError for Audio Loading

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Use this snippet to catch and report errors when the specified audio file path does not exist. Verify the file path, consider using an absolute path, and check file permissions.

```python
from mlx_voxtral import load_audio

try:
    audio = load_audio("nonexistent.mp3")
except FileNotFoundError as e:
    print(f"Audio file error: {e}")
```

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

### Basic Transcription with Voxtral

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/API-OVERVIEW.md

Perform basic speech transcription using `VoxtralForConditionalGeneration` and `VoxtralProcessor`. Load the model and processor, apply a transcription request, generate output, and decode the transcription. Ensure the audio file exists.

```python
from mlx_voxtral import VoxtralForConditionalGeneration, VoxtralProcessor

model = VoxtralForConditionalGeneration.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)
processor = VoxtralProcessor.from_pretrained(
    "mistralai/Voxtral-Mini-3B-2507"
)

inputs = processor.apply_transcrition_request(
    language="en",
    audio="speech.mp3"
)
outputs = model.generate(**inputs, max_new_tokens=1024, temperature=0.0)
transcription = processor.decode(
    outputs[0][inputs.input_ids.shape[1]:],
    skip_special_tokens=True
)
print(transcription)
```

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

### Initialize VoxtralAttention Layer

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/models.md

Initializes the multi-head attention layer for the audio encoder. Configure embedding dimension, number of heads, and bias inclusion.

```python
class VoxtralAttention(nn.Module):
    def __init__(
        self,
        embed_dim: int,
        num_heads: int,
        bias: bool = True,
    )
```

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

### Robust Audio Loading with Retry Logic

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Implement retry logic for loading audio files, specifically handling `RuntimeError` that might indicate FFmpeg issues. `FileNotFoundError` is not retried.

```python
from mlx_voxtral import load_audio

def safe_load_audio(path, retry_count=3):
    """Load audio with retry logic."""
    for attempt in range(retry_count):
        try:
            return load_audio(path)
        except FileNotFoundError:
            raise  # Don't retry for missing files
        except RuntimeError as e:
            if "ffmpeg" in str(e).lower():
                raise RuntimeError("FFmpeg required: brew install ffmpeg")
            if attempt == retry_count - 1:
                raise
            continue
    return None
```

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

### download_model()

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/utilities.md

Downloads a specified model from the HuggingFace Hub. It returns the path to the downloaded model directory.

```APIDOC
## download_model()

### Description
Downloads a specified model from the HuggingFace Hub. It returns the path to the downloaded model directory.

### Method
`download_model(
    model_id: str,
    revision: Optional[str] = None
) -> Path`

### Parameters
#### Path Parameters
- **model_id** (str) - Required - HuggingFace model ID (e.g., "mistralai/Voxtral-Mini-3B-2507")
- **revision** (str | None) - Optional - Branch, tag, or commit hash. Defaults to None.

### Returns
- **Path** - Path to downloaded model directory

### Example
```python
from mlx_voxtral.utils.model_loading import download_model

model_path = download_model("mistralai/Voxtral-Mini-3B-2507")
print(model_path)  # /home/user/.cache/huggingface/hub/mistralai--Voxtral-Mini-3B-2507/...
```
```

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

### generate()

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/models.md

Performs non-streaming audio generation to produce a sequence of token IDs. It supports various sampling strategies like greedy, temperature, top-k, and top-p.

```APIDOC
## generate()

### Description
Non-streaming generation from audio.

### Method Signature
```python
def generate(
    self,
    input_ids: Optional[mx.array] = None,
    input_features: Optional[mx.array] = None,
    attention_mask: Optional[mx.array] = None,
    max_new_tokens: int = 128,
    temperature: float = 0.0,
    top_p: float = 0.95,
    top_k: int = 0,
    min_p: float = 0.0,
    repetition_penalty: float = 1.2,
    logit_bias: Optional[Dict[int, float]] = None,
    stop_tokens: Optional[List[int]] = None,
    **kwargs,
) -> mx.array
```

### Parameters

- **input_ids** (`mx.array`) - Optional - Token IDs with audio placeholders
- **input_features** (`mx.array`) - Optional - Mel spectrograms
- **attention_mask** (`mx.array | None`) - Optional - Attention mask
- **max_new_tokens** (`int`) - Optional - Default: 128 - Maximum tokens to generate
- **temperature** (`float`) - Optional - Default: 0.0 - Sampling temperature (0 = greedy)
- **top_p** (`float`) - Optional - Default: 0.95 - Nucleus sampling probability
- **top_k** (`int`) - Optional - Default: 0 - Top-k sampling (0 = disabled)
- **min_p** (`float`) - Optional - Default: 0.0 - Minimum probability threshold
- **repetition_penalty** (`float`) - Optional - Default: 1.2 - Penalty for token repetition
- **logit_bias** (`Dict[int, float] | None`) - Optional - Default: None - Token ID → bias values
- **stop_tokens** (`List[int] | None`) - Optional - Default: [2, 4, 32000] - Stop generation at these tokens

### Returns
- `mx.array` — Generated token sequence [batch, input_len + output_len]

### Sampling Strategies
1. **Greedy** (temperature=0) — Select highest logit
2. **Temperature Sampling** — Scale logits by temperature
3. **Top-K** — Sample from top-K highest probability tokens
4. **Top-P (Nucleus)** — Sample from smallest set of tokens with cumulative probability ≥ top_p
5. **Min-P** — Filter tokens below min_p × max(logits)

### Example
```python
inputs = processor.apply_transcrition_request(
    audio="speech.mp3",
    language="en"
)

# Greedy (deterministic)
outputs = model.generate(
    **inputs,
    max_new_tokens=1024,
    temperature=0.0
)

# Nucleus sampling (diverse but coherent)
outputs = model.generate(
    **inputs,
    max_new_tokens=1024,
    temperature=0.7,
    top_p=0.9
)

# Extract and decode new tokens
new_tokens = outputs[0, inputs.input_ids.shape[1]:]
transcription = processor.decode(new_tokens, skip_special_tokens=True)
print(transcription)
```
```

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

### Load and Resample Audio

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/audio-processing.md

Loads an audio file and resamples it to a specified sample rate (default 16kHz) and converts it to mono. Supports normalization to a [-1, 1] range. Falls back to ffmpeg if soundfile is unavailable.

```python
from mlx_voxtral import load_audio

# Load from file
audio = load_audio("speech.mp3")
print(audio.shape)  # (480000,) for 30 seconds at 16kHz

# Load and normalize
audio = load_audio("speech.mp3", normalize=True)
```

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

### Handle FileNotFoundError: Config file not found

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/errors.md

Occurs when the `config.json` file is missing from the specified model directory. Verify the model path and ensure the full model has been downloaded.

```python
from mlx_voxtral.utils.model_loading import load_config
from pathlib import Path

try:
    config = load_config(Path("/invalid/path"))
except FileNotFoundError:
    print("config.json not found")
```

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

### Configuration Types Imports

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/types.md

Imports configuration classes for the Voxtral model and its components.

```python
from mlx_voxtral.configuration_voxtral import (
    VoxtralConfig,
    VoxtralEncoderConfig,
    VoxtralTextConfig,
)
```

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

### Create Hanning Window

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/audio-processing.md

Generates a Hanning (Hann) window of a specified size, commonly used in Short-Time Fourier Transform (STFT) computations.

```python
def hanning(size: int) -> mx.array
```

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

### from_dict() Class Method

Source: https://github.com/mzbac/mlx.voxtral/blob/main/_autodocs/configuration.md

Creates a VoxtralConfig object from a dictionary.

```APIDOC
#### from_dict() (Class Method)

```python
@classmethod
def from_dict(cls, config_dict: Dict) -> VoxtralConfig
```

**Example**:
```python
from mlx_voxtral import VoxtralConfig

config = VoxtralConfig(
    audio_config={
        "hidden_size": 1280,
        "num_hidden_layers": 32
    },
    text_config={
        "vocab_size": 131072,
        "hidden_size": 3072
    },
    audio_token_id=24
)

config_dict = config.to_dict()
config2 = VoxtralConfig.from_dict(config_dict)
```
```