Skip to main content

🐦 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)

Source distribution for birdword 0.3.2
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)

Table of built distributions (wheels) for birdword 0.3.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 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