Skip to main content

🦜 Wordbird

CI PyPI

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 post-processes the transcription to fix errors, using project-specific context from a WORDBIRD.md file.

demo video

Getting started

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

# Run with uvx (no install needed)
uvx wordbird

# Or run in the background
uvx wordbird start
uvx wordbird stop
uvx wordbird status

Context-aware correction

You can improve transcription with a WORDBIRD.md file which lists project-specific terms that may be misheard.

Either create a standard template, or ask Claude to analyze your project and create the file for you.

uvx wordbird init
# or
uvx wordbird init --claude # uses haiku by default; you can specify model via --claude {haiku,sonnet,opus}

Context detection works with:

  • Terminal.app — detects the focused tab's shell working directory
  • VS Code / VS Code Insiders — via the Wordbird extension, which works with local and remote (SSH) workspaces
  • Zed - detects the focused window's project directory out of the box, no extension needed

Transcription and pasting work in any app.

A WORDBIRD.md file looks like this:

---
transcription_model: mlx-community/parakeet-tdt-0.6b-v2
fix_model: mlx-community/Qwen2.5-1.5B-Instruct-4bit
---

{# Your correction prompt and examples here #}

{# Key terms: MyApp, some_function, PostgreSQL #}
{# Names: Alice, Bob #}
{# Misheard words: "bird word" should be "Birdword" #}

Input: "{{ transcript }}"
Output:

The file is a Jinja template. {{ transcript }} is replaced with the raw transcription. The YAML front matter lets you override models per-project.

Hotkey

Action Default
Toggle recording Right ⌘ + Space
Transcribe and submit Right ⌘ + Return (opt-in)

The submit shortcut transcribes, pastes, and presses Return — useful for chat and terminal workflows. Enable it in the dashboard settings.

Configurable via CLI flags or the dashboard settings:

--modifier-key KEY   Modifier key (default: rcmd). Options: rcmd, lcmd, ralt, lalt, rshift, lshift, rctrl, lctrl, fn
--toggle-key KEY     Toggle key (default: space). Options: space, return, tab, escape

Options

--model MODEL        Transcription model (default: mlx-community/parakeet-tdt-0.6b-v2)
--fix-model MODEL    Post-processor model (default: mlx-community/Qwen2.5-1.5B-Instruct-4bit)
--no-fix             Disable LLM post-processing
--no-server          Don't spawn the API server (run it separately)

Dashboard

Wordbird runs a local web dashboard (default localhost:7870). Click the bird in the menu bar → Dashboard… to open it.

  • History — browse transcriptions with timestamps, app name, working directory, and duration. See both original and corrected text.
  • Settings — configure hotkey, models, and post-processing. Changes take effect within seconds.
  • Stats — words dictated, recording time, WPM, session count.
uvx wordbird history        # view history from the CLI
uvx wordbird config         # show or create the config file

Data

All data is stored in ~/.wordbird/:

File Purpose
wordbird.toml User configuration
wordbird.db Transcription history (SQLite)
server.json Server port discovery
wordbird.pid Singleton lock
wordbird.log Background mode logs

Menu bar

Wordbird shows a bird icon in the menu bar:

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

Permissions

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

  • 🎤 Microphone — to record your voice
  • 🔐 Accessibility — to paste text
  • ⌨️ Input Monitoring — to detect the global hotkey

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

Architecture

Wordbird runs as two sibling processes managed by a thin CLI:

  • Server (wordbird-server) — FastAPI app handling transcription, post-processing, history, config, and serving the React dashboard
  • Daemon (wordbird-daemon) — macOS-native process handling hotkeys, mic recording, overlay HUD, menu bar, and clipboard pasting

The daemon sends recorded audio to the server via HTTP. The server runs ML inference in a thread pool so the dashboard stays responsive during transcription.

uvx wordbird          # starts both (recommended)
uvx wordbird-server   # just the API server
uvx wordbird-daemon   # just the daemon (expects server running)

Development

make backend-dev      # API server with hot reload
make daemon-dev       # daemon only (expects server running)
make frontend-dev     # Vite dev server with API proxy
make dev              # backend + frontend + daemon (all three)
make wordbird         # build frontend + run everything
make backend-test     # run pytest

License

MIT

Metadata

Release files for wordbird 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wordbird 0.10.1
File Size Uploaded Provenance Actions
wordbird-0.10.1.tar.gz 713.5 kB With provenance Details for wordbird-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wordbird 0.10.1
File Interpreter ABI Platform Actions
wordbird-0.10.1-py3-none-any.whl Python 3 none any Details for wordbird-0.10.1-py3-none-any.whl

Total release size: 974.3 kB

Release files / wordbird-0.10.1.tar.gz

Download URL wordbird-0.10.1.tar.gz
Size 713.5 kB
Tags Source
SHA-256 checksum
How to use checksums
747eeec588431c841e6c1958fb9c7ba7205ef2f107ff4276b9f3ab694cb4c7cd
BLAKE2b-256 checksum
How to use checksums
89f1a068339a13c0c1c4df20406bf172e9425e9100bcc45cd84049c9a4dfa0e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.

Transparency log

Release files / wordbird-0.10.1-py3-none-any.whl

Download URL wordbird-0.10.1-py3-none-any.whl
Size 260.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
767f28d2c0ce3b4236f3846af560d7036e8773bd9dd1c3069e447adb3e3ae107
BLAKE2b-256 checksum
How to use checksums
cf038600c01dc634eb2c86c688856101b2c6a658c870514d509944bcbeeaea46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.

Transparency log

Security for wordbird 0.10.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for wordbird-0.10.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page