wyoming-mlx-whisper 1.1.0

Wyoming Server for MLX whisper

Wyoming MLX Whisper

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

Uses mlx-community/whisper-large-v3-turbo by default (~1.6GB download, ~1.7GB memory), which runs near real-time on M1 Pro and newer. For lower memory usage, try the quantized version with --model mlx-community/whisper-large-v3-turbo-q4.

[ToC] 📚

• Requirements
• Installation
  • Using uvx (recommended, no install needed)
  • Using pip
• Usage
  • Run directly
  • Run as macOS service (launchd)
• Home Assistant Integration
• Options
• Development
• Acknowledgements

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/*.out ~/Library/Logs/wyoming-mlx-whisper/*.err

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.

Options

See the output of wyoming-mlx-whisper --help

 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]            │
│ --debug           --no-debug          Log DEBUG messages                     │
│                                       [env var: WHISPER_DEBUG]               │
│                                       [default: no-debug]                    │
│ --log-format                    TEXT  Format for log messages                │
│                                       [default:                              │
│                                       %(levelname)s:%(name)s:%(message)s]    │
│ --version                             Print version and exit                 │
│ --help        -h                      Show this message and exit.            │
╰──────────────────────────────────────────────────────────────────────────────╯

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