# m4x — local, private audio transcription

Turn voice memos and podcasts into text **entirely on your own machine**. `m4x` is a thin, fast wrapper around [whisper.cpp](https://github.com/ggml-org/whisper.cpp) that ships as both a **command-line tool** and an **MCP server** for AI agents.

Think of it as a tiny, local-first alternative to cloud transcription products (Plaud, Otter, etc.) — with one big difference: **your audio never leaves your computer.** No account, no upload, no API key, no per-minute fee. It runs beautifully on Apple-silicon Macs (Metal-accelerated) but works anywhere whisper.cpp does.

> ⚡ On an Apple M-series machine, the `large-v3-turbo` model transcribes roughly an hour of audio in a couple of minutes, fully offline.

## Why local?

| | m4x (local) | Typical cloud transcriber |
|---|---|---|
| Where your audio goes | Stays on your machine | Uploaded to a third party |
| Account / API key | None | Required |
| Cost | Free | Per-minute or subscription |
| Works offline | Yes | No |
| Summaries | Bring your own LLM (see below) | Built-in (cloud) |

## Requirements

- **Python 3.10+**
- **whisper.cpp** (`whisper-cli`) — install via Homebrew: `brew install whisper-cpp`
- **A ggml model** — download once (see below)

## Install

```bash
# 1. the transcription engine
brew install whisper-cpp

# 2. a model (large-v3-turbo: great quality/speed; ~1.5 GB)
mkdir -p ~/whisper-models
curl -L -o ~/whisper-models/ggml-large-v3-turbo.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin

# 3. m4x itself
pipx install .        # or: pip install .
```

## CLI usage

```bash
# a single voice memo
m4x transcribe ~/Downloads/memo.m4a
# -> writes ~/Downloads/memo.txt

# a whole folder of podcasts, German
m4x transcribe ~/Podcasts --lang de

# print to stdout and pipe straight into your own LLM for a summary
m4x transcribe interview.mp3 --stdout | llm "summarise this into 5 bullet points and action items"
```

Options: `--lang` (e.g. `en`, `de`, or `auto`), `--model <path>`, `--out <dir>`, `--stdout`.

## MCP usage (Claude Desktop & other agents)

`m4x` also runs as an MCP server so an agent can transcribe for you. Long files run as a background job — start, then poll.

Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "m4x": {
      "command": "m4x-mcp"
    }
  }
}
```

Tools exposed: `transcribe_start(file_path, language)` → `job_id`, `transcribe_result(job_id)`, `transcribe_list_jobs()`.

## "Mini-Plaud" pattern: transcribe → summarise

`m4x` deliberately does **transcription only** and stays out of the AI-summary business, so you keep full control (and privacy) over that step. Pair it with any LLM you like:

```bash
m4x transcribe standup.m4a --stdout | llm "Extract decisions, owners, and due dates as a table"
```

Or, in an agent: call `transcribe_start`, poll `transcribe_result`, then ask the model to summarise the returned text.

## Configuration

Everything has sensible defaults; override via environment variables:

| Variable | Default | Meaning |
|---|---|---|
| `M4X_WHISPER_BIN` | `whisper-cli` on PATH, else `/opt/homebrew/bin/whisper-cli` | Path to the whisper.cpp binary |
| `M4X_MODEL` | `~/whisper-models/ggml-large-v3-turbo.bin` | Path to the ggml model |

## How it works

`m4x` shells out to `whisper-cli` with your chosen model and language, writes a `.txt` transcript next to the audio (or to `--out`), and returns the text. The CLI and the MCP server share one small `core` module — no duplicated logic. That's the whole thing: ~200 lines, no magic.

## License

MIT — see [LICENSE](LICENSE). Contributions welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).