MLX Whisper

Local speech-to-text transcription using MLX Whisper with Apple Silicon GPU acceleration.

Features

• 🚀 GPU-accelerated transcription on Apple Silicon (M1/M2/M3)
• 📦 Lightweight MLX implementation of OpenAI Whisper
• 🌍 Multi-language support
• 📁 CLI interface for easy use

Requirements

• macOS with Apple Silicon (M1/M2/M3)
• Python 3.10+
• FFmpeg (brew install ffmpeg)

Installation

1. Clone the repository

git clone https://github.com/orchidsun/mlx-whisper.git
cd mlx-whisper

2. Create virtual environment

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install mlx-whisper

4. (Optional) Download models

Models auto-download on first use. To pre-download:

# Install openai-whisper for PyTorch weights
pip install openai-whisper

# Convert small model (244 MB)
python3 -c "from mlx_whisper import convert; convert.convert_and_save('small')"

Usage

CLI

# Activate virtual environment
source venv/bin/activate

# Basic transcription
python3 mlx-transcribe.py audio.mp3

# Specify language
python3 mlx-transcribe.py audio.mp3 --lang zh

# Use specific model
python3 mlx-transcribe.py audio.mp3 --model medium

# Output to specific directory
python3 mlx-transcribe.py audio.mp3 --output ~/Documents/transcripts

# List available models
python3 mlx-transcribe.py --list-models

CLI Options

Option	Description	Default
--model	Model size: tiny, small, medium	small
--lang	Language code (e.g., en, zh, ja)	auto-detect
--output	Output directory	same as audio
--list-models	List available models	-

Python API

from mlx_whisper import transcribe

# Basic transcription
result = transcribe("audio.mp3")
print(result["text"])

# Specify language
result = transcribe("audio.mp3", language="zh")

# Use specific model
result = transcribe("audio.mp3", path_or_hf_repo="medium")

Full Example

from mlx_whisper import transcribe
from pathlib import Path

def transcribe_audio(audio_path, model="small", language=None, output_dir="."):
    """Transcribe audio file and save transcript to .txt"""
    result = transcribe(
        audio_path,
        path_or_hf_repo=model,
        language=language,
        word_timestamps=False,
        verbose=False
    )
    
    # Save transcript
    txt_path = Path(output_dir) / f"{Path(audio_path).stem}.txt"
    with open(txt_path, "w", encoding="utf-8") as f:
        f.write(result["text"])
    
    return txt_path

# Usage
transcript = transcribe_audio("podcast.mp3", language="zh")
print(f"Saved to: {transcript}")

Models

Model	Size	Speed	Best For
tiny	76 MB	Fastest	Quick tests, short audio
small	244 MB	Fast	Daily use (default)
medium	756 MB	Slower	High accuracy needs

Supported Formats

• MP3, M4A, WAV, FLAC, OGG, WEBM, MKV
• Any FFmpeg-supported audio format

Troubleshooting

"No module named 'mlx'"

source venv/bin/activate
pip install mlx

Slow transcription

• Use smaller model (tiny/small vs medium)
• Ensure Apple Silicon GPU is being used

Model conversion fails

# Install PyTorch version first
pip install openai-whisper

# Then convert
python3 -c "from mlx_whisper import convert; convert.convert_and_save('small')"

License

MIT

Links

• MLX Whisper
• MLX