87 lines
2.3 KiB
Markdown
87 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone https://github.com/yourname/calliope.git
|
|
cd calliope
|
|
pip install -e .
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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
|