# 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