### Quick Start Transcription with VoxtralCore

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Demonstrates the high-level API for transcribing audio using the VoxtralTranscriptionManager. It covers loading the model, performing transcription, and unloading the model. Ensure the VoxtralCore framework is imported.

```swift
import VoxtralCore

// High-level API
let manager = VoxtralTranscriptionManager()
try await manager.loadModel()
let result = try await manager.transcribe(audioURL: audioFile)
print(result.text)
manager.unloadModel()
```

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

### Install Dependencies and Convert Encoder to Core ML (Python)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/Scripts/CoreMLConversion/README.md

This script installs project dependencies using pip and then converts the Voxtral encoder model to the Core ML format, optimizing it for the Apple Neural Engine (ANE). It requires specifying the path to the downloaded model weights and the desired output path for the Core ML package.

```bash
cd Scripts/CoreMLConversion
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Convert encoder with ANE optimizations
python convert_to_coreml_ane.py \
    --model-path ./voxtral-mini-3b \
    --output ./output/VoxtralEncoderANE.mlpackage
```

```bash
pip install -r requirements.txt
```

```bash
python convert_to_coreml_ane.py \
    --model-path ./voxtral-mini-3b \
    --output ./output/VoxtralEncoderANE.mlpackage
```

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

### Integrate VoxtralCore into Swift Project

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

Shows how to add VoxtralCore as a dependency in a Swift project's Package.swift file and provides an example of using VoxtralPipeline for audio transcription.

```swift
// Package.swift
import PackageDescription

let package = Package(
    name: "MyApp",
    platforms: [
        .macOS(.v14)  // Requires macOS 14.0 (Sonoma) or later
    ],
    dependencies: [
        .package(
            url: "https://github.com/VincentGourbin/mlx-voxtral-swift",
            branch: "main"
        )
    ],
    targets: [
        .executableTarget(
            name: "MyApp",
            dependencies: [
                .product(name: "VoxtralCore", package: "mlx-voxtral-swift")
            ]
        )
    ]
)

// Usage in your code:
import VoxtralCore

@MainActor
class TranscriptionService {
    private var pipeline: VoxtralPipeline?

    func setup() async throws {
        pipeline = VoxtralPipeline(model: .mini3b8bit, backend: .auto)
        try await pipeline?.loadModel()
    }

    func transcribe(_ audioURL: URL) async throws -> String {
        guard let pipeline = pipeline else {
            throw NSError(domain: "NotLoaded", code: 1)
        }
        return try await pipeline.transcribe(audio: audioURL)
    }

    func cleanup() {
        pipeline?.unload()
        pipeline = nil
    }
}
```

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

### Enabling Hybrid Mode via Command Line Interface (CLI)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Provides examples of using the VoxtralCLI to transcribe audio files with different backend configurations. It shows how to use auto mode (recommended), force hybrid mode, or force pure MLX mode.

```bash
# Auto mode (recommended): uses Core ML if available
./.build/debug/VoxtralCLI transcribe /path/to/audio.mp3 --backend auto

# Force hybrid mode
./.build/debug/VoxtralCLI transcribe /path/to/audio.mp3 --backend hybrid

# Force pure MLX mode
./.build/debug/VoxtralCLI transcribe /path/to/audio.mp3 --backend mlx
```

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

### Swift Package Manager Installation

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Integrate the VoxtralCore library into your Swift project by adding the repository as a dependency in your Package.swift file. This allows you to easily use the Voxtral functionality within your own applications.

```swift
dependencies: [
    .package(url: "https://github.com/VincentGourbin/mlx-voxtral-swift", branch: "main")
]

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "VoxtralCore", package: "mlx-voxtral-swift")
    ]
)
```

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

### Swift Package Manager Installation for mlx-voxtral-swift

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Provides the Swift Package Manager dependency declaration required to integrate the mlx-voxtral-swift library into your project. Ensure your project meets the specified requirements (macOS 14.0+, Apple Silicon, Swift 6.0+).

```swift
dependencies: [
    .package(url: "https://github.com/VincentGourbin/mlx-voxtral-swift", from: "1.0.8")
]
```

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

### Transcribe Audio with VoxtralTranscriptionManager in Swift

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

This snippet demonstrates how to use VoxtralTranscriptionManager to transcribe audio files. It covers creating a manager instance, loading a model with progress updates, transcribing audio to get text and metadata, performing chat interactions with audio context, and managing the model lifecycle. Dependencies include the VoxtralCore framework.

```swift
import VoxtralCore

// Create manager with default model (mini-3b-8bit)
let manager = VoxtralTranscriptionManager()
// Or specify a model:
// let manager = VoxtralTranscriptionManager(model: .mini3b4bit)

// Load model with progress tracking
try await manager.loadModel { progress, status in
    print("[\(Int(progress * 100))%] (status)")
}

// Transcribe and get detailed result
let audioFile = URL(fileURLWithPath: "/path/to/audio.wav")
let result = try await manager.transcribe(audioURL: audioFile, language: "en")

print("Text: (result.text)")
print("Duration: (result.duration)s")
print("Tokens: (result.tokenCount)")
print("Speed: (result.tokensPerSecond) tok/s")
// Output:
// Text: "The quick brown fox jumps over the lazy dog..."
// Duration: 34.6s
// Tokens: 500
// Speed: 14.5 tok/s

// Chat with audio context
let chatResponse = try await manager.chat(
    audioURL: audioFile,
    prompt: "What language is being spoken?",
    language: "en"
)
print(chatResponse)
// Output: "English"

// Static convenience methods
let isDownloaded = VoxtralTranscriptionManager.isDefaultModelDownloaded()
let modelInfo = VoxtralTranscriptionManager.defaultModelInfo
print("Default model: (modelInfo.name), Size: (modelInfo.size)")

// Unload when done
manager.unloadModel()
```

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

### Command-Line Interface Usage for Voxtral

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Illustrates common commands for interacting with the Voxtral CLI. This includes downloading models, listing available models, performing transcription, engaging in chat, and enabling profiling for performance analysis.

```bash
# Download model
./VoxtralCLI download mini-3b-8bit

# List models
./VoxtralCLI list

# Transcribe
./VoxtralCLI transcribe audio.mp3
./VoxtralCLI transcribe audio.mp3 --backend hybrid

# Chat with audio
./VoxtralCLI chat audio.mp3 "Summarize this audio"

# With profiling
./VoxtralCLI transcribe audio.mp3 --profile
```

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

### Build and Use Voxtral CLI

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

Builds the Voxtral CLI tool using Swift Package Manager and demonstrates common commands for managing models and performing transcription and chat operations.

```bash
swift build --product VoxtralCLI
./.build/debug/VoxtralCLI list
./.build/debug/VoxtralCLI list --downloaded
./.build/debug/VoxtralCLI download mini-3b-8bit
./.build/debug/VoxtralCLI download mzbac/voxtral-mini-3b-8bit
./.build/debug/VoxtralCLI transcribe /path/to/audio.mp3 \
    --model mini-3b-8bit \
    --language en \
    --max-tokens 500 \
    --backend hybrid
./.build/debug/VoxtralCLI chat /path/to/audio.mp3 "Summarize this audio" \
    --model mini-3b-8bit \
    --temperature 0.7 \
    --max-tokens 500 \
    --backend mlx
```

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

### VoxtralPipeline.Configuration: Customize Generation Settings

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

Illustrates how to customize generation parameters for the VoxtralPipeline, including token limits, sampling temperature, and memory optimization presets. It also shows how to determine recommended models based on system RAM and list available models.

```swift
import VoxtralCore

// Create custom configuration
var config = VoxtralPipeline.Configuration.default
config.maxTokens = 1000              // Maximum tokens to generate
config.temperature = 0.0             // 0 = deterministic, higher = more random
config.topP = 0.95                   // Nucleus sampling parameter
config.repetitionPenalty = 1.2       // Avoid repetition (1.0 = no penalty)

// Memory optimization presets
config.memoryOptimization = .recommended()  // Auto-detect based on system RAM
// Other presets: .moderate, .aggressive, .ultra

// Create pipeline with custom configuration
let pipeline = VoxtralPipeline(
    model: .mini3b8bit,
    backend: .auto,
    configuration: config
)

// Recommended model based on system RAM
let recommendedModel = VoxtralPipeline.recommendedModel(forRAMGB: 16)
// Returns .mini3b8bit for 16-32GB systems

// List all available models
let allModels = VoxtralPipeline.availableModels
for model in allModels {
    print("\(model.rawValue): \(model.displayName)")
}
// Output:
// mini-3b: Voxtral Mini 3B (Full)
// mini-3b-8bit: Voxtral Mini 3B (8-bit)
// mini-3b-4bit: Voxtral Mini 3B (4-bit)
// ...
```

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

### Correct VoxtralPipeline Usage for Transcription (Swift)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

This snippet shows the recommended way to use VoxtralPipeline for audio transcription. It initializes the pipeline, loads the model, transcribes audio from a URL, and then unloads the model. It also contrasts this with incorrect usage that accesses internal components, which can lead to unexpected behavior.

```swift
// ✅ CORRECT - Use VoxtralPipeline
let pipeline = VoxtralPipeline(model: .mini3b8bit)
try await pipeline.loadModel()
let text = try await pipeline.transcribe(audio: audioURL)
pipeline.unload()

// ❌ WRONG - Don't access internals
// let model = try loadVoxtralModel(...)  // Internal function
// let params = model.parameters()         // Will have wrong keys
```

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

### Download Voxtral Model Weights (Bash)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/Scripts/CoreMLConversion/README.md

This command downloads the official Mistral Voxtral model weights from Hugging Face to a specified local directory. This is a prerequisite step before converting the model to Core ML format.

```bash
# The official Mistral model is recommended
huggingface-cli download mistralai/Voxtral-Mini-3B-2507 --local-dir ./voxtral-mini-3b
```

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

### Initialize Voxtral Generator with Hybrid Backend (Swift)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/Scripts/CoreMLConversion/README.md

This Swift code snippet demonstrates how to initialize the VoxtralGenerator. By setting the backend configuration to `.hybrid`, the generator will utilize the Core ML audio encoder on the Apple Neural Engine (ANE) and the MLX decoder on the GPU, optimizing performance and power consumption.

```swift
// In VoxtralGenerator
let config = VoxtralConfiguration(
    backend: .hybrid  // or .mlx for GPU-only
)
let generator = try VoxtralGenerator(configuration: config)
```

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

### Memory Optimization Configuration in Swift

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Demonstrates how to configure memory optimization for the Voxtral pipeline using predefined presets or custom settings. These configurations help manage GPU memory usage, balancing performance and resource consumption.

```swift
// Presets
MemoryOptimizationConfig.recommended()  // Auto-detect based on system RAM
MemoryOptimizationConfig.moderate       // Balanced
MemoryOptimizationConfig.aggressive     // Lower memory, slower
MemoryOptimizationConfig.ultra          // Minimum memory

// Custom
let config = MemoryOptimizationConfig(
    maxKVCacheSize: 8192,
    clearCacheInterval: 50,
    useAggressiveCleanup: true
)
```

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

### VoxtralCLI: Command Line Interface Usage

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

Provides command-line access to all features of the Voxtral library. This section outlines the general usage of the CLI tool.

```bash
# Example usage (specific commands would follow)
# VoxtralCLI --transcribe audio.mp3 --output transcript.txt
# VoxtralCLI --chat --model /path/to/model
```

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

### Enable Profiling Mode for CLI (Bash)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

This command demonstrates how to run the VoxtralCLI in profiling mode to gather detailed performance metrics. The `--profile` flag provides insights into Time To First Token (TTFT) and memory usage during transcription.

```bash
VoxtralCLI transcribe audio.mp3 --backend hybrid --profile
```

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

### VoxtralPipeline: Transcribe and Chat with Audio

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

Demonstrates the main high-level API for transcribing audio files and engaging in chat-based interactions with the transcribed content. It handles model loading, transcription, and chat prompts, with options for language selection and automatic model downloading.

```swift
import VoxtralCore

// Create pipeline with recommended settings
let pipeline = VoxtralPipeline(
    model: .mini3b8bit,      // .mini3b, .mini3b8bit, .mini3b4bit, .small24b, .small24b8bit, .small4bit
    backend: .auto           // .mlx (pure GPU), .hybrid (Core ML + MLX), .auto
)

// Load model with progress tracking (downloads from HuggingFace if needed)
try await pipeline.loadModel { progress, status in
    print("[\(Int(progress * 100))%] \(status)")
}

// Transcribe audio file
let audioURL = URL(fileURLWithPath: "/path/to/audio.mp3")
let transcription = try await pipeline.transcribe(audio: audioURL, language: "en")
print(transcription)
// Output: "Hello and welcome to this recording..."

// Chat mode - ask questions about audio content
let response = try await pipeline.chat(
    audio: audioURL,
    prompt: "Summarize what is being said in this audio",
    language: "en"
)
print(response)
// Output: "The speaker discusses the importance of..."

// Check encoder status and memory usage
print("Encoder: \(pipeline.encoderStatus)")   // "Core ML available: true"
print("Memory: \(pipeline.memorySummary)")    // "Active: 4.0 GB, Peak: 10.05 GB"

// Release resources when done
pipeline.unload()
```

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

### Automatic Core ML Download and Hybrid Mode in Swift

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Demonstrates how to initialize the VoxtralPipeline in automatic or hybrid backend modes. The pipeline automatically downloads the Core ML encoder model from HuggingFace when using `.auto` or `.hybrid` backends. It also shows how to check the encoder status.

```swift
// Auto mode: downloads Core ML if available, uses it automatically
let pipeline = VoxtralPipeline(model: .mini3b8bit, backend: .auto)
try await pipeline.loadModel()  // Downloads Core ML encoder to ~/Library/Caches/models/

// Force hybrid mode
let pipeline = VoxtralPipeline(model: .mini3b8bit, backend: .hybrid)

// Check encoder status
print(pipeline.encoderStatus)  // "Core ML available: true" or "MLX encoder (GPU)"
```

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

### Clone and Build Project

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Clone the MLX Voxtral Swift repository from GitHub and build the project using the Swift Package Manager. This method is suitable for development or if you prefer not to use SPM for integration.

```bash
git clone https://github.com/VincentGourbin/mlx-voxtral-swift.git
cd mlx-voxtral-swift
swift build
```

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

### Configure VoxtralPipeline Options (Swift)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

This code illustrates how to customize the VoxtralPipeline's behavior by adjusting configuration parameters. Options include setting maximum tokens, temperature for randomness, top-P for nucleus sampling, repetition penalty, and memory optimization presets.

```swift
var config = VoxtralPipeline.Configuration.default
config.maxTokens = 1000          // Maximum tokens to generate
config.temperature = 0.0         // 0 = deterministic, higher = more random
config.topP = 0.95               // Nucleus sampling
config.repetitionPenalty = 1.2   // Avoid repetition

// Memory optimization
config.memoryOptimization = .recommended()  // Auto-detect based on RAM
// Other presets: .moderate, .aggressive, .ultra

let pipeline = VoxtralPipeline(
    model: .mini3b8bit,
    backend: .auto,
    configuration: config
)
```

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

### Build and Run SwiftUI Application

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Compile and launch the included SwiftUI macOS application for Voxtral. This provides a user-friendly interface for audio transcription and chat functionalities with drag-and-drop support.

```bash
swift build --product VoxtralApp
./create_app_bundle.sh
open Voxtral.app
```

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

### ModelDownloader Utility for Voxtral Models

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Utility functions for managing Voxtral speech-to-text models. This includes checking if the default model is downloaded, initiating downloads with progress tracking, deleting models, and resolving model URLs. It also allows listing and deleting downloaded models.

```swift
ModelDownloader.isDefaultModelDownloaded() -> Bool
ModelDownloader.downloadDefaultModel(progress:) async throws -> URL
ModelDownloader.deleteDefaultModel() throws
ModelDownloader.defaultModel -> VoxtralModelInfo
ModelDownloader.resolveModel(_ identifier: String) async throws -> URL
ModelDownloader.listDownloadedModels() -> [VoxtralModelInfo]
ModelDownloader.deleteModel(_ model: VoxtralModelInfo) throws
```

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

### Download Models via CLI

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Utilize the provided Command Line Interface (CLI) tool to manage Voxtral models. You can list available models, download specific models by their ID or HuggingFace repository, and manage model files.

```bash
# List available models
./.build/debug/VoxtralCLI list

# Download the recommended model
./.build/debug/VoxtralCLI download mini-3b-8bit

# Download by HuggingFace repo ID
./.build/debug/VoxtralCLI download mzbac/voxtral-mini-3b-8bit
```

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

### Manage Voxtral Models with ModelDownloader in Swift

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

This code demonstrates how to use ModelDownloader to manage Voxtral models. It covers checking if a model is downloaded, downloading specific models with progress updates, resolving model paths by ID or repository, and listing or deleting downloaded models. This functionality requires the VoxtralCore framework.

```swift
import VoxtralCore

// Check if default model is downloaded
if ModelDownloader.isDefaultModelDownloaded() {
    print("Default model ready")
}

// Download a specific model with progress
let modelInfo = ModelRegistry.model(withId: "mini-3b-8bit")!
let modelPath = try await ModelDownloader.download(modelInfo) { progress, status in
    print("[\(Int(progress * 100))%] (status)")
}
print("Downloaded to: (modelPath.path)")
// Output: Downloaded to: ~/Library/Caches/models/mzbac/voxtral-mini-3b-8bit

// Resolve model by ID, repo ID, or local path (downloads if needed)
let path = try await ModelDownloader.resolveModel("mini-3b-8bit") { progress, status in
    print(status)
}

// Or by HuggingFace repo ID directly
let repoPath = try await ModelDownloader.downloadByRepoId("mzbac/voxtral-mini-3b-8bit")

// List downloaded models
let downloaded = ModelDownloader.listDownloadedModels()
for model in downloaded {
    if let size = ModelDownloader.modelSize(for: model) {
        print("\(model.name): \(ModelDownloader.formatSize(size))")
    }
}
// Output:
// Voxtral Mini 3B (8-bit): 3.5 GB

// Delete a model
try ModelDownloader.deleteModel(modelInfo)
```

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

### Command Line Interface Usage

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Interact with the Voxtral model using the command-line interface. This allows for quick transcription of audio files, engaging in chat mode with audio content, and accessing help information.

```bash
# List available models
./.build/debug/VoxtralCLI list

# Download a model
./.build/debug/VoxtralCLI download mini-3b-8bit

# Transcribe audio
./.build/debug/VoxtralCLI transcribe /path/to/audio.mp3 --model mini-3b-8bit

# Chat mode - ask questions about audio
./.build/debug/VoxtralCLI chat /path/to/audio.mp3 "What language is being spoken?"

# Get help
./.build/debug/VoxtralCLI --help
```

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

### Manual Core ML Encoder Conversion Script

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Details the steps to manually convert the Core ML encoder using a provided shell script. This process generates a `VoxtralEncoderFull.mlmodelc` file, which can then be uploaded to HuggingFace or utilized locally.

```bash
cd Scripts/CoreMLConversion
chmod +x convert.sh
./convert.sh
```

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

### Chat Mode: Ask Questions About Audio (Swift)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

This snippet demonstrates how to use the VoxtralPipeline to process audio and ask questions about its content. It requires loading the model, providing an audio URL, a prompt, and optionally a language. The pipeline should be unloaded after use.

```swift
import VoxtralCore

let pipeline = VoxtralPipeline(model: .mini3b8bit, backend: .auto)
try await pipeline.loadModel()

// Ask questions about audio content
let response = try await pipeline.chat(
    audio: audioURL,
    prompt: "Summarize what is being said in this audio",
    language: "en"
)
print(response)

pipeline.unload()
```

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

### VoxtralPipeline API for Advanced Speech-to-Text Control

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Offers granular control over speech-to-text processing using VoxtralPipeline. This API allows specifying models and backends, handling model loading with progress updates, and performing transcription or chat operations. It also provides status checks for the audio encoder and memory management.

```swift
// Available models: .mini3b, .mini3b8bit, .mini3b4bit, .small24b, .small24b8bit, .small4bit
// Available backends: .mlx (pure GPU), .hybrid (Core ML encoder + MLX decoder), .auto

let pipeline = VoxtralPipeline(model: .mini3b8bit, backend: .auto)
try await pipeline.loadModel { progress, status in
    // Downloads MLX model + Core ML encoder automatically from HuggingFace
    print("\(Int(progress * 100))% - \(status)")
}

// Transcribe
let text = try await pipeline.transcribe(audio: audioURL, language: "en")

// Chat (ask questions about audio)
let response = try await pipeline.chat(audio: audioURL, prompt: "Summarize this", language: "en")

// Check encoder status
print(pipeline.encoderStatus)  // "Core ML available: true" or "MLX encoder (GPU)"

// Release memory
pipeline.unload()

// Configuration (before loadModel)
var config = VoxtralPipeline.Configuration.default
config.maxTokens = 500
config.temperature = 0.0
config.memoryOptimization = .recommended()
let pipeline = VoxtralPipeline(model: .mini3b8bit, configuration: config)
```

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

### Access Voxtral Model Information with ModelRegistry in Swift

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

This Swift code snippet shows how to interact with the ModelRegistry to access information about available Voxtral models. It covers retrieving all models, the default/recommended model, filtering models by category (mini, small, official), finding models by ID or repository ID, and printing a formatted list of available models. This requires the VoxtralCore framework.

```swift
import VoxtralCore

// Get all available models
let allModels = ModelRegistry.models
for model in allModels {
    let rec = model.recommended ? " [RECOMMENDED]" : ""
    print("\(model.id)\(rec)")
    print("  Repo: \(model.repoId)")
    print("  Size: \(model.size), Quantization: \(model.quantization)")
    print("  Parameters: \(model.parameters)")
}
// Output:
// mini-3b
//   Repo: mistralai/Voxtral-Mini-3B-2507
//   Size: ~6 GB, Quantization: float16
//   Parameters: 3B
// mini-3b-8bit [RECOMMENDED]
//   Repo: mzbac/voxtral-mini-3b-8bit
//   Size: ~3.5 GB, Quantization: 8-bit
//   Parameters: 3B
// ...

// Get default/recommended model
let defaultModel = ModelRegistry.defaultModel
print("Recommended: \(defaultModel.name)")
// Output: Recommended: Voxtral Mini 3B (8-bit)

// Filter models by category
let miniModels = ModelRegistry.miniModels      // 3B parameter models (quantized)
let smallModels = ModelRegistry.smallModels    // 24B parameter models (quantized)
let official = ModelRegistry.officialModels    // Full precision Mistral models

// Find by ID or repo
if let model = ModelRegistry.model(withId: "mini-3b-4bit") {
    print("Found: \(model.description)")
}
if let model = ModelRegistry.model(withRepoId: "VincentGOURBIN/voxtral-small-4bit-mixed") {
    print("Found: \(model.name)")
}

// Print formatted model list
ModelRegistry.printAvailableModels()
```

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

### VoxtralProcessor: Audio and Text Processing in Swift

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

Handles audio features, tokenization, and chat template formatting. It can be initialized from a pretrained model directory and used for transcription requests, applying chat templates, and decoding token IDs back to text. Dependencies include VoxtralCore.

```swift
import VoxtralCore

// Create processor from pretrained model directory
let processor = try VoxtralProcessor.fromPretrained("/path/to/model") { progress, status in
    print("[\(Int(progress * 100))%] \(status)")
}

// Process transcription request
let audioPath = "/path/to/audio.mp3"
let inputs = try processor.applyTranscritionRequest(
    audio: audioPath,
    language: "en",
    samplingRate: 16000
)
// inputs.inputIds: MLXArray [1, seqLen] - token IDs with audio placeholders
// inputs.inputFeatures: MLXArray [numChunks, 128, 3000] - mel spectrogram

// Apply chat template for conversation
let conversation: [[String: Any]] = [
    [
        "role": "user",
        "content": [
            ["type": "audio", "audio": audioPath],
            ["type": "text", "text": "What is being discussed?"]
        ]
    ]
]

let chatInputs = try processor.applyChatTemplate(
    conversation: conversation,
    tokenize: true,
    returnTensors: "mlx"
) as! [String: MLXArray]

let inputIds = chatInputs["input_ids"]!         // Token IDs
let inputFeatures = chatInputs["input_features"]! // Audio features

// Decode token IDs back to text
let tokenIds = [1, 3, 25, 24, 24, ..., 4, 34]  // Example token sequence
let text = try processor.decode(tokenIds, skipSpecialTokens: true)
print(text)
// Output: "This is the transcribed text..."

// Batch decode multiple sequences
let batchTokenIds = [[1, 3, 25, ...], [1, 3, 26, ...]]
let texts = try processor.batchDecode(batchTokenIds, skipSpecialTokens: true)
```

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

### VoxtralTranscriptionManager API for Speech-to-Text

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Provides detailed usage of the VoxtralTranscriptionManager for speech-to-text tasks. This includes checking and downloading models, performing transcription and chat operations, and accessing result properties. The manager can be initialized with a default or specific model.

```swift
// Check/download model
VoxtralTranscriptionManager.isDefaultModelDownloaded() -> Bool
VoxtralTranscriptionManager.isModelDownloaded(_ model: VoxtralPipeline.Model) -> Bool
VoxtralTranscriptionManager.downloadDefaultModel(progress:) async throws -> URL
VoxtralTranscriptionManager.deleteDefaultModel() throws

// Transcription
let manager = VoxtralTranscriptionManager()  // Uses default model (mini-3b-8bit)
let manager = VoxtralTranscriptionManager(model: .mini3b4bit)  // Specific model
try await manager.loadModel()
let result = try await manager.transcribe(audioURL: URL)
let response = try await manager.chat(audioURL: URL, prompt: String)
manager.unloadModel()

// Result properties
result.text          // Transcribed text
result.tokenCount    // Number of tokens generated
result.duration      // Generation time in seconds
result.tokensPerSecond  // Performance metric
```

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

### Library Integration with VoxtralPipeline

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

Integrate the Voxtral functionality into your Swift projects using the `VoxtralPipeline` class. This provides a programmatic interface for loading models, transcribing audio, and managing the pipeline's lifecycle.

```swift
import VoxtralCore

// Create pipeline with desired model and backend
let pipeline = VoxtralPipeline(
    model: .mini3b8bit,      // .mini3b, .mini3b8bit, .mini3b4bit, .small24b, .small24b8bit, .small4bit
    backend: .auto           // .mlx (pure GPU), .hybrid (Core ML + MLX), .auto
)

// Load model (downloads automatically from HuggingFace if needed)
try await pipeline.loadModel { progress, status in
    print("[\(Int(progress * 100))%] \(status)")
}

// Transcribe audio
let text = try await pipeline.transcribe(audio: audioURL, language: "en")
print(text)

// When done, release memory
pipeline.unload()
```

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

### ModelRegistry API for Voxtral Model Information

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/llms.txt

Provides access to information about available Voxtral speech-to-text models. The ModelRegistry allows querying all available models, the default model, specific models by ID or repository ID, and filtering models by size (mini or small).

```swift
ModelRegistry.models -> [VoxtralModelInfo]
ModelRegistry.defaultModel -> VoxtralModelInfo  // mini-3b-8bit (recommended)
ModelRegistry.model(withId: String) -> VoxtralModelInfo?
ModelRegistry.model(withRepoId: String) -> VoxtralModelInfo?
ModelRegistry.miniModels -> [VoxtralModelInfo]  // 3B models
ModelRegistry.smallModels -> [VoxtralModelInfo]  // 24B models
```

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

### VoxtralForConditionalGeneration: Core Model in Swift

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

The main model class for conditional generation, combining an audio encoder and a language model. It can be loaded from a standard model path and supports generating audio embeddings, performing a full forward pass, and streaming token generation with or without pre-computed audio embeddings. Dependencies include VoxtralCore and MLX.

```swift
import VoxtralCore
import MLX

// Load model using standard loader
let modelPath = "/path/to/model"
let (standardModel, _) = try loadVoxtralStandardModel(
    modelPath: modelPath,
    dtype: .float16
)
let model = VoxtralForConditionalGeneration(standardModel: standardModel)

// Generate audio embeddings
let inputFeatures: MLXArray = ...  // [numChunks, 128, 3000]
let audioEmbeds = model.getAudioEmbeds(inputFeatures)
print("Audio embeddings: \(audioEmbeds.shape)")
// Output: Audio embeddings: [1, numChunks * 375, hiddenSize]

// Full forward pass
let output = model.callAsFunction(
    inputIds: inputIds,           // [batch, seqLen]
    attentionMask: nil,
    inputFeatures: inputFeatures, // [numChunks, 128, 3000]
    inputsEmbeds: nil,
    pastKeyValues: nil
)
let logits = output.logits  // [batch, seqLen, vocabSize]

// Generate tokens with streaming
let tokenIds = try model.generateStream(
    inputIds: inputIds,
    inputFeatures: inputFeatures,
    maxNewTokens: 500,
    temperature: 0.0,
    topP: 0.95,
    repetitionPenalty: 1.2,
    contextSize: 4096  // KV cache limit (nil = unlimited)
)
print("Generated \(tokenIds.count) tokens")

// Generate with pre-computed audio embeddings (for hybrid mode)
let hybridTokenIds = try model.generateStreamWithAudioEmbeds(
    inputIds: inputIds,
    audioEmbeds: audioEmbeds,  // Pre-computed via Core ML
    maxNewTokens: 500,
    temperature: 0.0,
    topP: 0.95,
    repetitionPenalty: 1.2
)
```

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

### High-Level Manager API for Transcription (Swift)

Source: https://github.com/vincentgourbin/mlx-voxtral-swift/blob/main/README.md

This snippet shows the simplest way to integrate transcription using the VoxtralTranscriptionManager. It automatically selects the recommended model and provides a straightforward interface for loading the model, transcribing audio, and accessing results like text, token count, and speed.

```swift
import VoxtralCore

let manager = VoxtralTranscriptionManager()
try await manager.loadModel()

let result = try await manager.transcribe(audioURL: audioFile)
print(result.text)
print("Generated (result.tokenCount) tokens in (result.duration)s")
print("Speed: (result.tokensPerSecond) tok/s")

manager.unloadModel()
```

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

### VoxtralFeatureExtractor: Audio Feature Extraction in Swift

Source: https://context7.com/vincentgourbin/mlx-voxtral-swift/llms.txt

Extracts mel-spectrogram features from audio files. It can be initialized with custom settings for feature size, sampling rate, hop length, chunk length, and FFT size. It processes audio file paths or raw audio arrays and can also perform low-level audio loading and spectrogram computation. Dependencies include VoxtralCore.

```swift
import VoxtralCore

// Create feature extractor with default settings
let featureExtractor = VoxtralFeatureExtractor(
    featureSize: 128,       // Number of mel bins
    samplingRate: 16000,    // Target sample rate
    hopLength: 160,         // STFT hop length
    chunkLength: 30,        // Chunk length in seconds
    nFft: 400               // FFT size
)

// Extract features from audio file path
let audioPath = "/path/to/audio.mp3"
let features = try featureExtractor.callAsFunction(
    rawSpeech: audioPath,
    samplingRate: 16000,
    returnTensors: "mlx"
)

let inputFeatures = features["input_features"] as! MLXArray
print("Feature shape: \(inputFeatures.shape)")
// Output: Feature shape: [numChunks, 128, 3000]
// Shape breakdown: [number of 30-second chunks, mel bins, time frames]

// Process raw audio array
let audioData: [Float] = [...]  // Audio samples at 16kHz
let rawFeatures = try featureExtractor.callAsFunction(
    rawSpeech: audioData,
    samplingRate: 16000,
    returnTensors: "mlx"
)

// Low-level function: load and resample audio
let audio = try loadAudio("/path/to/audio.wav")  // Returns MLXArray
// Automatically resamples to 16kHz, converts stereo to mono

// Compute log-mel spectrogram directly
let (logMelSpec, logMax) = logMelSpectrogram(
    audio,
    nMels: 128,
    nFft: 400,
    hopLength: 160
)
print("Spectrogram shape: \(logMelSpec.shape)")
// Output: Spectrogram shape: [3000, 128]
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.