wyoming-mlx-whisper 1.4.0
Wyoming Server for MLX whisper
Requires Python: <3.14,>=3.10
Keywords: mlx, rhasspy, stt, whisper, wyoming

# Wyoming MLX Whisper

[![PyPI](https://img.shields.io/pypi/v/wyoming-mlx-whisper)](https://pypi.org/project/wyoming-mlx-whisper/)
[![Python](https://img.shields.io/pypi/pyversions/wyoming-mlx-whisper)](https://pypi.org/project/wyoming-mlx-whisper/)
[![License](https://img.shields.io/github/license/basnijholt/wyoming-mlx-whisper)](https://github.com/basnijholt/wyoming-mlx-whisper/blob/main/LICENSE)
[![Pre-commit](https://github.com/basnijholt/wyoming-mlx-whisper/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/basnijholt/wyoming-mlx-whisper/actions/workflows/pre-commit.yml)

[Wyoming protocol](https://github.com/rhasspy/wyoming) server for [mlx-whisper](https://pypi.org/project/mlx-whisper) speech-to-text on Apple Silicon.

Uses [`mlx-community/whisper-large-v3-turbo`](https://huggingface.co/mlx-community/whisper-large-v3-turbo) by default, which runs near real-time on M1 Pro and newer.

### Available Models

| Model | Size | Speed | Quality |
|-------|------|-------|---------|
| [`mlx-community/whisper-tiny`](https://huggingface.co/mlx-community/whisper-tiny) | 75 MB | ⚡⚡⚡ Fastest | Basic |
| [`mlx-community/whisper-small-mlx`](https://huggingface.co/mlx-community/whisper-small-mlx) | 481 MB | ⚡⚡ Fast | Good |
| [`mlx-community/whisper-large-v3-turbo`](https://huggingface.co/mlx-community/whisper-large-v3-turbo) | 1.6 GB | ⚡⚡ Near real-time | **Best** (default) |
| [`mlx-community/whisper-large-v3-turbo-q4`](https://huggingface.co/mlx-community/whisper-large-v3-turbo-q4) | 464 MB | ⚡⚡ Near real-time | Near-best |

Use `--model <name>` to select a different model.

<details><summary><b><u>[ToC]</u></b> 📚</summary>

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Requirements](#requirements)
- [Installation](#installation)
  - [Using uvx (recommended, no install needed)](#using-uvx-recommended-no-install-needed)
  - [Using pip](#using-pip)
- [Usage](#usage)
  - [Run directly](#run-directly)
  - [Run as macOS service (launchd)](#run-as-macos-service-launchd)
- [Options](#options)
- [Home Assistant Integration](#home-assistant-integration)
- [Related Projects](#related-projects)
- [Development](#development)
- [Acknowledgements](#acknowledgements)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

</details>

## Requirements

- macOS with Apple Silicon (M1/M2/M3/M4)
- Python 3.10-3.13 (3.14 not yet supported by numba)
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

### Using uvx (recommended, no install needed)

```sh
uvx --python 3.12 wyoming-mlx-whisper
```

### Using pip

```sh
pip install wyoming-mlx-whisper
wyoming-mlx-whisper
```

## Usage

### Run directly

```sh
# 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:

```sh
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:

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

View logs:

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

## Options

<details>
<summary>See the output of <code>wyoming-mlx-whisper --help</code></summary>

<!-- CODE:BASH:START -->
<!-- echo '```' -->
<!-- uv run wyoming-mlx-whisper --help -->
<!-- echo '```' -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
```

 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]                                │
│ --version                           Print version and exit                             │
│ --help      -h                      Show this message and exit.                        │
╰────────────────────────────────────────────────────────────────────────────────────────╯

```

<!-- OUTPUT:END -->

</details>

## 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](https://github.com/basnijholt/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

```sh
uv sync
uv run pre-commit install
```

## Acknowledgements

- Forked from [vincent861223/wyoming-mlx-whisper](https://github.com/vincent861223/wyoming-mlx-whisper) by Vincent Lin
- Based on [wyoming-whisper-api-client](https://github.com/ser/wyoming-whisper-api-client) by Dr. Serge Victor