birdword 0.1.0

Voice dictation daemon using NVIDIA Parakeet on Apple Silicon

🐦 Birdword

Contextual voice dictation for macOS. Powered by NVIDIA Parakeet running locally on Apple Silicon via MLX.

Press a hotkey, speak, and your words are transcribed and pasted into whatever app is focused. A small LLM (Qwen2.5-0.5B) post-processes the transcription to fix errors, optionally using project-specific context from a BIRDWORD.md file.

Install

pip install birdword

Or run without installing:

uvx birdword

Requires macOS on Apple Silicon (M1+) and Python 3.10+.

Usage

# Run in the foreground
birdword

# Run in the background
birdword start
birdword stop
birdword status

Hotkeys

Action	Default
Toggle recording	Right ⌘ + Space
Hold to record	Hold Right ⌘ for >1s, release to transcribe

Options

--model MODEL        Transcription model (default: mlx-community/parakeet-tdt-0.6b-v2)
--fix-model MODEL    Post-processor model (default: mlx-community/Qwen2.5-0.5B-Instruct-4bit)
--no-fix             Disable LLM post-processing
--hold-key KEY       Hold key (default: rcmd). Options: rcmd, lcmd, ralt, lalt, rshift, lshift, rctrl, lctrl
--toggle-key KEY     Toggle key (default: space). Options: space, return, tab, escape

Permissions

Birdword needs three macOS permissions, granted to your terminal app:

• Microphone — to record your voice
• Accessibility — to paste text and intercept the hotkey
• Input Monitoring — to detect the global hotkey

Birdword checks these on startup and tells you what's missing.

Context-aware correction

Drop a BIRDWORD.md file in your project directory with domain-specific terms, names, and jargon:

This is a Rust networking project using tokio and hyper.

Key terms: epoll, mio, AsyncRead, TcpListener
Names: Till

When you dictate into a Terminal tab whose shell is in that directory (or a child), birdword feeds this context to the post-processor so it knows not to "correct" your domain terms.

Menu bar

Birdword shows a bird icon in the menu bar:

• White — idle
• Yellow — connecting mic
• Red — listening
• ✨ Sparkles — transcribing

License

MIT