Developer Environment Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page provides a comprehensive guide for setting up the development environment for the mlx-qwen3-asr project. The project is a ground-up MLX reimplementation of Qwen3-ASR specifically optimized for Apple Silicon, emphasizing a standalone package structure with zero external transformer dependencies at runtime.
The development environment is designed to support high-performance inference on Metal, rigorous quality gating through extensive automated testing, and various evaluation workflows including benchmarking and reference parity suites.
Sources: CLAUDE.md:1-15, pyproject.toml:1-15
Prerequisites and Core Dependencies
The project requires Python 3.10+ and is specifically targeted for macOS environments with Apple Silicon to leverage the Metal framework via MLX.
Hardware and OS Requirements
- Architecture: Apple Silicon (M-series chips).
- Operating System: macOS.
- Python Version: >= 3.10.
Base Dependencies
The core transcription pipeline relies on a minimal set of dependencies to ensure it remains lightweight and portable.
| Dependency | Version | Purpose |
|---|---|---|
mlx | >= 0.18.0 | Core machine learning framework for Apple Silicon. |
numpy | Latest | Numerical processing and audio array handling. |
regex | Latest | Advanced string matching for tokenization. |
huggingface-hub | >= 0.20.0 | Model weight and asset downloading. |
Sources: pyproject.toml:13-25, CLAUDE.md:100-110
Installation and Environment Setup
The recommended way to set up the development environment is using uv for package management within a virtual environment.
# Initialize development environment
uv pip install -e ".[dev]"
This installation mode installs the package in editable mode along with development-specific tools:
- pytest: For running the test suite.
- ruff: For linting and code formatting.
- mypy: For static type checking.
Sources: CLAUDE.md:160-170, pyproject.toml:32-35
Development Workflow and Quality Gates
The project maintains high standards for correctness and performance through a multi-tiered quality gate system.
Automated Testing
The test suite consists of over 440 tests. Developers should run these locally before proposing changes.
# Run full test suite
python -m pytest tests/
# Stop on first failure for debugging
python -m pytest tests/ -x -q
Quality Gate Modes
There are two primary modes for the quality gate script, which should be executed based on the scope of the changes.
| Mode | Description |
|---|---|
| Fast | Runs ruff linting and basic pytest suite. Used for routine development. |
| Release | Includes the fast suite plus reference parity checks (requires qwen-asr and PyTorch). |
# Fast quality gate
python scripts/quality_gate.py --mode fast
# Release quality gate (requires torch environment)
RUN_REFERENCE_PARITY=1 python scripts/quality_gate.py --mode release
Sources: CLAUDE.md:173-185, scripts/update_readme_stats.py:34-40
Optional Component Setup
Depending on the feature being developed, additional optional dependencies may be required. These are defined as extras in the project configuration.
# Example: Install server and evaluation extras
uv pip install -e ".[serve,eval]"
| Extra | Dependencies | Use Case |
|---|---|---|
aligner | nagisa, soynlp | Word-level timestamp generation (Korean support). |
diarize | pyannote.audio | Speaker identification in audio streams. |
mic | sounddevice | Real-time microphone transcription. |
serve | fastapi, uvicorn | Running the HTTP transcription server. |
eval | soundfile, pyarrow | Running benchmarks and manifest-based evaluations. |
Sources: pyproject.toml:27-35, CLAUDE.md:120-135
Development Architecture Overview
The following diagram illustrates the flow from environment setup to the verification of code quality within the local developer environment.
The diagram shows the iterative cycle a developer follows: installing dependencies, coding, linting, unit testing, and finally running the quality gate.
Sources: CLAUDE.md:160-190, scripts/README.md:1-15
Essential Development Utilities
The scripts/ directory contains various tools to assist in development and repository maintenance.
- README Statistics: Use
python scripts/update_readme_stats.pyto refresh line counts and test statistics in the documentation. - Model Conversion:
scripts/convert.pyis used to remap HuggingFace weights and apply Conv2d transposes for MLX compatibility. - Benchmarking: Evaluation scripts like
scripts/eval_manifest_quality.pymeasure WER/CER against standardized manifests.
Sources: scripts/README.md:5-25, scripts/update_readme_stats.py:75-85
Summary
The developer environment for mlx-qwen3-asr is optimized for high-velocity development on Apple Silicon. By utilizing uv for environment management and a structured quality gate system, developers can ensure that optimizations for Metal do not introduce regressions in transcription accuracy or system stability.
Sources: CLAUDE.md:195-210