Metadata-Version: 2.4
Name: blurt
Version: 0.9.1
Summary: Talk to your coding agents. On-device voice-to-text for macOS Apple Silicon. No cloud, no API keys.
Author: Satya Borgohain
License-Expression: MIT
Project-URL: Homepage, https://github.com/satyaborg/blurt
Keywords: speech-to-text,qwen,mlx,apple-silicon,macos,voice,transcription
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mlx-audio>=0.4.0
Requires-Dist: sounddevice
Requires-Dist: pynput
Requires-Dist: numpy
Requires-Dist: rich
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

<p align="center">
  <pre align="center">
░█▀▄░█░░░█░█░█▀▄░▀█▀
░█▀▄░█░░░█░█░█▀▄░░█░
░▀▀░░▀▀▀░▀▀▀░▀░▀░░▀░
  </pre>
  <p align="center">Talk to your coding agents.</p>
  <p align="center">
    <a href="https://pypi.org/project/blurt/"><img src="https://img.shields.io/pypi/v/blurt?color=blue" alt="PyPI"></a>
    <a href="https://pepy.tech/project/blurt"><img src="https://img.shields.io/pepy/dt/blurt?color=green" alt="Downloads"></a>
    <a href="https://github.com/satyaborg/blurt/blob/main/LICENSE"><img src="https://img.shields.io/github/license/satyaborg/blurt" alt="License"></a>
  </p>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/satyaborg/blurt/main/demo.gif" alt="demo" width="600">
</p>

On-device voice-to-text for macOS. Press right **⌘**, speak, then press it again - your words go straight into Claude Code, Codex, Cursor, OpenCode or any other agent, wherever your cursor is.

## Install

```bash
brew tap satyaborg/blurt
brew install blurt
```

Or via [pipx](https://pipx.pypa.io/):

```bash
pipx install blurt
```

> Requires macOS with Apple Silicon.

First run downloads the selected transcription model once. macOS will prompt for **Microphone** and **Accessibility** access (System Settings → Privacy & Security).

## Usage

| Action | Description |
|---|---|
| Press right **⌘** | Start recording |
| Press right **⌘** again | Stop, transcribe, paste at cursor |
| **Ctrl + C** | Quit |

## Models

| Mode | Model | Use case |
|---|---|---|
| `fast` | Qwen3-ASR 0.6B 8-bit | Default, lowest latency |
| `accurate` | Qwen3-ASR 1.7B 8-bit | Higher accuracy |

```bash
blurt mode fast       # use the default 0.6B model
blurt mode accurate   # use the higher-accuracy 1.7B model
```

The fast mode downloads an approximately 1 GB [MLX checkpoint](https://huggingface.co/mlx-community/Qwen3-ASR-0.6B-8bit), while accurate mode downloads an approximately 2.5 GB [MLX checkpoint](https://huggingface.co/mlx-community/Qwen3-ASR-1.7B-8bit). Custom words and filename-shaped repository terms are passed to Qwen as transcription context.

## Transcript Casing

```bash
blurt case original     # preserve the model's casing
blurt case lowercase    # convert every transcription to lowercase
```

## Custom Words

Teach Blurt words it gets wrong (names, jargon, acronyms):

```bash
blurt add "Claude Code"   # add a word
blurt vocab               # list all
blurt rm "Claude Code"    # remove
```

Words are stored in `~/.blurt/vocab.txt` (one per line).

## @-mentions

Run Blurt from a git repo and spoken filenames automatically resolve to `@path/to/file` references that coding agents understand. For example, saying _"check init.py for the bug"_ becomes `check @blurt/__init__.py for the bug`.

## Transcript History

```bash
blurt log                 # view recent transcripts
```

Logs are stored in `~/.blurt/log.txt`.

## Update

```bash
blurt upgrade
```

## Troubleshooting

| Issue | Fix |
|---|---|
| "Microphone access" prompt doesn't appear | System Settings → Privacy & Security → Microphone → enable your terminal |
| "Accessibility" error | System Settings → Privacy & Security → Accessibility → enable your terminal |
| No audio / recording fails | `brew install portaudio` then restart your terminal |
| Model download stalls | Check available space in `~/.cache/huggingface/` for the selected model |

## Contributing

```bash
git clone https://github.com/satyaborg/blurt.git
cd blurt
uv pip install -e ".[dev]"
pytest
```

## Privacy

Everything runs on your Mac. No network calls, no telemetry, no data collection. Audio files are saved locally to `~/.blurt/audio/` and never leave your device.

## License

[MIT](LICENSE)
