Installation and Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides the necessary steps to install, configure, and begin using mlx-qwen3-asr, a high-performance speech recognition package optimized for Apple Silicon. The system is a ground-up MLX reimplementation of Qwen3-ASR, providing Metal-optimized inference with zero dependencies on PyTorch or HuggingFace transformers at runtime.
The scope of this document covers basic environment setup, dependency management via pip or uv, and various methods of execution including the Command Line Interface (CLI) and the built-in HTTP transcription server.
Sources: CLAUDE.md:7-14, pyproject.toml:1-15
Installation
mlx-qwen3-asr requires Python 3.10 or later and is specifically designed for macOS systems with Apple Silicon.
Base Installation
The primary package can be installed directly from PyPI. Using uv is recommended for faster dependency resolution.
# Using pip
pip install mlx-qwen3-asr
# Using uv
uv pip install mlx-qwen3-asr
Sources: CLAUDE.md:7, pyproject.toml:11-15, CLAUDE.md:144-145
Optional Dependencies
The project uses optional "extras" for specialized functionality such as diarization, microphone support, or serving the API.
| Extra | Description | Dependencies |
|---|---|---|
serve | Built-in HTTP server | fastapi, uvicorn, python-multipart |
diarize | Speaker labeling | pyannote.audio |
aligner | Word-level timestamps | nagisa, soynlp |
mic | Live microphone capture | sounddevice |
dev | Development tools | pytest, ruff, mypy |
Sources: pyproject.toml:27-32, mlx_qwen3_asr/cli.py:539-548
System Requirements: ffmpeg
While the core MLX pipeline avoids many heavy dependencies, ffmpeg is required for decoding various media formats (e.g., .mp3, .m4a, .mp4).
# macOS (Recommended)
brew install ffmpeg
Sources: mlx_qwen3_asr/cli.py:100-112
Environment Validation
The system includes a "doctor" utility to verify that the environment, dependencies, and necessary binaries (like ffmpeg) are correctly configured.
mlx-qwen3-asr --doctor
This command checks for the presence of mlx, ffmpeg, and optional modules for diarization, and validates the presence of authentication tokens (e.g., PYANNOTE_AUTH_TOKEN) if required.
Sources: mlx_qwen3_asr/cli.py:126-175
Quick Start: CLI Usage
The CLI is the primary entry point for transcribing audio files locally.
Basic Transcription
To transcribe a single audio file into a text file:
mlx-qwen3-asr audio.wav
Advanced Workflows
The CLI supports multiple formats, model sizes (0.6B default or 1.7B), and features like diarization or word-level timestamps.
# Generate SRT subtitles with word-level timestamps
mlx-qwen3-asr video.mp4 -f srt -o subtitles/
# Transcribe with speaker labels (requires [diarize] extra)
export PYANNOTE_AUTH_TOKEN=hf_...
mlx-qwen3-asr meeting.m4a --diarize --num-speakers 2
Sources: examples/real-world/README.md:9-32, mlx_qwen3_asr/cli.py:328-360
Quick Start: Transcription Server
The package includes a built-in FastAPI-based server that provides an OpenAI-compatible transcription endpoint.
Starting the Server
export MLX_ASR_API_KEY="$(openssl rand -hex 16)"
mlx-qwen3-asr serve --api-key "$MLX_ASR_API_KEY"
Server Architecture
The server manages an internal job queue and an inference lock to handle requests sequentially on the Metal backend.
The server maintains a multi-slot model cache and uses a sequential job processor to manage resource contention on the GPU.
Sources: mlx_qwen3_asr/server.py:112-160, mlx_qwen3_asr/server.py:276-320, CLAUDE.md:63-68
API Consumption
Once the server is running, it can be targeted using standard OpenAI SDKs or curl.
from openai import OpenAI
client = OpenAI(api_key="YOUR_KEY", base_url="http://localhost:8765/v1")
result = client.audio.transcriptions.create(
model="Qwen/Qwen3-ASR-0.6B",
file=open("recording.wav", "rb"),
)
Sources: examples/openai-server/README.md:14-28
Summary
mlx-qwen3-asr offers a streamlined installation path for Apple Silicon users, providing both high-level CLI tools and a production-grade HTTP server. By leveraging MLX, it achieves low-latency inference without the overhead of the PyTorch ecosystem. Users should begin with a base installation and add optional extras based on their specific needs for diarization or API serving.
Sources: CLAUDE.md:1-20