Wyoming MLX Whisper

Wyoming protocol server for mlx-whisper speech-to-text on Apple Silicon.

Uses mlx-community/whisper-large-v3-turbo by default, which runs near real-time on M1 Pro and newer.

Available Models

Use --model <name> to select a different model. Use --initial-prompt <text> to guide recognition with custom vocabulary.

Requirements

• macOS with Apple Silicon (M1/M2/M3/M4)
• Python 3.10-3.13 (3.14 not yet supported by numba)
• uv (recommended) or pip

Installation

Using uvx (recommended, no install needed)

uvx --python 3.12 wyoming-mlx-whisper

Using pip

pip install wyoming-mlx-whisper
wyoming-mlx-whisper

Usage

Run directly

# With uvx (no install needed)
uvx --python 3.12 wyoming-mlx-whisper

# Or if installed with pip
wyoming-mlx-whisper

Run as macOS service (launchd)

Download and run the install script:

curl -fsSL https://raw.githubusercontent.com/basnijholt/wyoming-mlx-whisper/main/scripts/install_service.sh | bash

The server runs at tcp://localhost:10300 by default.

Uninstall the service:

curl -fsSL https://raw.githubusercontent.com/basnijholt/wyoming-mlx-whisper/main/scripts/uninstall_service.sh | bash

View logs:

tail -f ~/Library/Logs/wyoming-mlx-whisper/*.log

Options

 Usage: wyoming-mlx-whisper [OPTIONS]

 Run the Wyoming MLX Whisper server.

╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
│ --uri                               TEXT  unix:// or tcp://                            │
│                                           [env var: WHISPER_URI]                       │
│                                           [default: tcp://0.0.0.0:10300]               │
│ --model                             TEXT  Name of MLX Whisper model to use             │
│                                           [env var: WHISPER_MODEL]                     │
│                                           [default:                                    │
│                                           mlx-community/whisper-large-v3-turbo]        │
│ --language                          TEXT  Language code (e.g., 'en')                   │
│                                           [env var: WHISPER_LANGUAGE]                  │
│ --initial-prompt                    TEXT  Initial prompt to guide Whisper recognition  │
│                                           [env var: WHISPER_INITIAL_PROMPT]            │
│ --debug               --no-debug          Log DEBUG messages  [env var: WHISPER_DEBUG] │
│                                           [default: no-debug]                          │
│ --version                                 Print version and exit                       │
│ --help            -h                      Show this message and exit.                  │
╰────────────────────────────────────────────────────────────────────────────────────────╯

Home Assistant Integration

1. Start the server (using any method above)
2. In Home Assistant, go to Settings → Devices & Services → Add Integration
3. Search for "Wyoming Protocol"
4. Enter localhost (or your Mac's IP) and port 10300

The Whisper STT service will now be available for voice assistants.

Related Projects

• agent-cli - Local-first AI-powered CLI agents for voice transcription, autocorrect, voice editing, and more. Uses wyoming-mlx-whisper as its default ASR backend on Apple Silicon.

Development

uv sync
uv run pre-commit install

Acknowledgements

• Forked from vincent861223/wyoming-mlx-whisper by Vincent Lin
• Based on wyoming-whisper-api-client by Dr. Serge Victor