🐦 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 post-processes the transcription to fix errors, using project-specific context from a BIRDWORD.md file.
Getting started
Requires macOS on Apple Silicon (M1+) and Python 3.10+.
# Run with uvx (no install needed)
uvx birdword
# Or run in the background
uvx birdword start
uvx birdword stop
uvx birdword status
Context-aware correction
The key idea behind birdword is contextual transcription correction. When dictating into Terminal.app, birdword detects the focused tab's working directory and looks for a BIRDWORD.md file up the directory tree. This lets you teach birdword your project's domain:
Context detection works with:
- Terminal.app — detects the focused tab's shell working directory
- VS Code / VS Code Insiders — via the Birdword extension, which works with local and remote (SSH) workspaces
Transcription and pasting work in any app.
uvx birdword init
This creates a BIRDWORD.md with the default prompt template. Edit it to add your project's terms, names, and jargon:
---
transcription_model: mlx-community/parakeet-tdt-0.6b-v2
fix_model: mlx-community/Qwen2.5-1.5B-Instruct-4bit
---
Fix transcription errors. Output only the corrected text.
Example 1:
Input: "the java script function isnt working"
Output: "The JavaScript function isn't working."
Example 2:
Input: "check the get ignore file for the repo"
Output: "Check the .gitignore file for the repo."
Example 3:
Input: "we need to refactor the a p i endpoint"
Output: "We need to refactor the API endpoint."
Key terms: MyClass, some_function, PostgreSQL
Names: Alice, Bob
Input: "{{ transcript }}"
Output:
The file is a Jinja template. {{ transcript }} is replaced with the raw transcription. If omitted, the transcript is appended automatically.
The YAML front matter lets you override models per-project. When you dictate into a Terminal tab whose shell is in that directory (or a child), birdword picks up the nearest BIRDWORD.md and uses it.
Hotkeys
| Action | Default |
|---|---|
| Toggle recording | Right ⌘ + Space |
| Hold to record | Hold Right ⌘ for >1s, release to transcribe |
Hotkeys are configurable:
--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
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
Dashboard
Birdword runs a local web dashboard at localhost:7870. Click the bird in the menu bar → Dashboard… to open it.
- 📝 History — browse all your transcriptions with timestamps, app name, working directory, and duration. See both the original and corrected text.
- ⚙️ Settings — configure hotkeys, models, and post-processing. Changes take effect immediately without restarting.
You can also view history from the command line:
uvx birdword history
Menu bar
Birdword shows a bird icon in the menu bar:
- ⚪ White — idle
- 🟡 Yellow — connecting mic
- 🔴 Red — listening
- ✨ Sparkles — transcribing
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.
License
MIT
Metadata
Release files for birdword 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| birdword-0.3.2.tar.gz | 415.3 kB | With provenance | Details for birdword-0.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| birdword-0.3.2-py3-none-any.whl | Python 3 | none | any | Details for birdword-0.3.2-py3-none-any.whl |
Total release size: 449.6 kB
Release files / birdword-0.3.2.tar.gz
| Download URL | birdword-0.3.2.tar.gz |
|---|---|
| Size | 415.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e38ff9295e2d48e57c03dcd8fdb2c06d6245a3106a5ab125bb78d0cd8d252f9
|
|
BLAKE2b-256 checksum How to use checksums |
e609cfe5dbf7f3f1b533515390b71bfd0e4763a72f99b6f15a83fa166131b7af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Mar 14, 2026.
Transparency logRelease files / birdword-0.3.2-py3-none-any.whl
| Download URL | birdword-0.3.2-py3-none-any.whl |
|---|---|
| Size | 34.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1282d66b94e1bb67c5fa41167c066b6f072337ce148c6965af350ed1a807728c
|
|
BLAKE2b-256 checksum How to use checksums |
a27f0eb86d323bea2f4c854493305bca10a0b228c18c722ad81886adb1e70e3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Mar 14, 2026.
Transparency logSecurity for birdword 0.3.2
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.
Attestation for birdword-0.3.2.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 Mar 14, 2026.
Transparency logA 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.