Calliope

Voice-to-text for macOS — speak and type into any app.

Calliope sits in your menu bar, listens when you hold a hotkey, transcribes your speech with Whisper, and types the result into whatever app is focused. No cloud, no API keys — everything runs locally on your Mac.

Installation

git clone https://github.com/yourname/calliope.git
cd calliope
pip install -e .

Usage

# First run — launches the setup wizard, then starts the app
calliope

# Re-run the setup wizard
calliope setup

# Launch with overrides
calliope --device 2 --model openai/whisper-large-v3 --debug

# Print version
calliope --version

Hotkeys

Action	Default	Description
Push-to-talk	Ctrl+Shift (hold)	Records while held, transcribes on release
Toggle	Ctrl+Space	Start/stop recording

Hotkeys are configurable via the setup wizard or ~/.config/calliope/config.yaml.

Permissions

Calliope needs two macOS permissions:

• Accessibility — to type text into other apps (System Settings > Privacy & Security > Accessibility)
• Microphone — to record audio (System Settings > Privacy & Security > Microphone)

The setup wizard checks for these and can open System Settings for you.

Configuration

Config lives at ~/.config/calliope/config.yaml:

device: null          # sounddevice index; null = system default
model: distil-whisper/distil-large-v3
hotkeys:
  ptt: ctrl+shift
  toggle: ctrl+space
context: ""           # domain-specific terms to help Whisper
debug: false

CLI flags override config values for that session.

Troubleshooting

"Status: Model load failed" Check that you have enough disk space and RAM. The default model needs ~1.5 GB. Run with --debug for detailed logs.

No text appears after transcribing Make sure Accessibility permission is granted. Restart Calliope after granting it.

Wrong microphone Run calliope setup to pick a different input device, or set device in the config file. Use python -m sounddevice to list devices.

Hotkeys not working Ensure no other app is capturing the same key combo. Customize hotkeys via calliope setup.

Remaining TODOs

• LICENSE file
• Unit tests
• CI/CD pipeline
• Homebrew formula
• .app bundle for drag-and-drop install
• Changelog