Transcription Pipeline & CLI

Relevant source files

The following files were used as context for generating this wiki page:

• mlx_qwen3_asr/transcribe.py
• mlx_qwen3_asr/cli.py
• mlx_qwen3_asr/server.py
• CLAUDE.md
• pyproject.toml
• examples/real-world/README.md

The Transcription Pipeline & CLI serves as the primary interface for users to interact with the MLX-optimized Qwen3-ASR model. It provides a high-level API for converting audio to text, supporting features like word-level timestamps, speaker diarization, and speculative decoding. The system is designed specifically for Apple Silicon, leveraging MLX for Metal-optimized inference to achieve low-latency performance.

Sources: CLAUDE.md:6-14, mlx_qwen3_asr/transcribe.py:165-172

Pipeline Architecture

The transcription process follows a structured sequence that converts raw audio input into structured text and metadata. For long audio files (typically >1200s), the system automatically splits the input into manageable chunks before processing them through the encoder-decoder architecture.

Data Flow Overview

The diagram above illustrates the logical flow from raw audio to the final result, highlighting the optional alignment and diarization stages.
Sources: mlx_qwen3_asr/transcribe.py:174-180, CLAUDE.md:67-73

High-Level API Functions

Function	Description	Async Support
transcribe()	Main entry point for single audio source transcription.	No
transcribe_async()	Async wrapper for transcribe using asyncio.to_thread.	Yes
transcribe_batch()	Processes multiple audio inputs while reusing the loaded model/tokenizer.	No
transcribe_batch_async()	Async version of batch transcription for non-blocking execution.	Yes

Sources: mlx_qwen3_asr/transcribe.py:165, mlx_qwen3_asr/transcribe.py:270, mlx_qwen3_asr/transcribe.py:306, mlx_qwen3_asr/transcribe.py:382

Command-Line Interface (CLI)

The package provides a comprehensive CLI utility named mlx-qwen3-asr. It allows users to perform offline transcriptions, run experimental streaming/microphone captures, or launch a built-in HTTP server.

Core CLI Commands and Options

The CLI supports various flags to tune the transcription behavior, including model selection and output formatting.

Flag	Type	Default	Description
--model	string	Qwen/Qwen3-ASR-0.6B	HF Model ID or local path.
--context	string	""	Space-separated terms to bias the decoder.
--output-format	choice	txt	Formats: txt, json, srt, vtt, tsv, all.
--timestamps	flag	False	Enables word-level timestamps via native MLX aligner.
--diarize	flag	False	Attaches speaker labels (requires pyannote.audio).
--streaming	flag	False	Experimental chunked streaming decode.

Sources: mlx_qwen3_asr/cli.py:539-650, pyproject.toml:44

Environment Diagnostics

The CLI includes a doctor mode to verify the runtime environment, checking for essential binaries like ffmpeg and optional dependencies for diarization.

Real-World Workflows

The system is optimized for several common transcription tasks through specific CLI configurations.

Subtitles and Meetings

• Subtitles: When -f srt or -f vtt is specified, the CLI automatically enables word-level timestamps to generate valid subtitle files.
• Meeting Diarization: Using --diarize allows speaker attribution. The system supports specifying --num-speakers or using --min-speakers and --max-speakers for auto-estimation.

Sources: examples/real-world/README.md:7-25, mlx_qwen3_asr/cli.py:734-745

Speculative Decoding

Speculative decoding can be enabled by providing a smaller --draft-model alongside the primary --model. This uses the smaller model to generate token hypotheses that the larger model verifies, potentially increasing throughput.

Sources: mlx_qwen3_asr/transcribe.py:488-511, mlx_qwen3_asr/cli.py:615-625

Server Integration

The CLI includes a serve subcommand that exposes the transcription pipeline as an OpenAI-compatible HTTP API.

Endpoint	Method	Description
/v1/audio/transcriptions	POST	Synchronous OpenAI-compatible transcription.
/transcribe	POST	Asynchronous job submission (returns job_id).
/jobs/{job_id}	GET	Polls the status and retrieves results for async jobs.
/health	GET	Returns server uptime, model ID, and queue depth.

Sources: mlx_qwen3_asr/server.py:206, mlx_qwen3_asr/server.py:255, mlx_qwen3_asr/server.py:318, mlx_qwen3_asr/server.py:343

Technical Constraints & Invariants

To ensure transcription accuracy, the pipeline maintains several "correctness invariants":

• Audio Loading: All audio is downmixed to mono and resampled to 16kHz before processing.
• Memory Management: The pipeline explicitly calls mx.clear_cache() (or mx.metal.clear_cache()) between chunks to prevent unbounded GPU memory growth during long-form transcription.
• Language Detection: If a language is forced via the API/CLI, it is canonicalized (e.g., zh-cn to Chinese) and passed to the tokenizer for prompt construction.

Sources: CLAUDE.md:76-85, mlx_qwen3_asr/transcribe.py:108-117, mlx_qwen3_asr/transcribe.py:614-618

The Transcription Pipeline & CLI provides a robust, production-grade interface for Qwen3-ASR on Apple hardware, bridging the gap between raw MLX model execution and usable transcription outputs.