43 lines
2.2 KiB
Markdown
43 lines
2.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What is Calliope?
|
|
|
|
A macOS menu bar app for local voice-to-text. Users press a hotkey, speak, and transcribed text is typed into the focused app. Runs entirely offline using Whisper models via `mlx-whisper`, natively accelerated on Apple Silicon.
|
|
|
|
## Setup & Running
|
|
|
|
```bash
|
|
pip install -e . # Install in dev mode
|
|
calliope # Launch (runs setup wizard on first run)
|
|
calliope setup # Re-run setup wizard
|
|
calliope --debug # Launch with debug logging
|
|
calliope --device 2 --model mlx-community/whisper-large-v3 # Override config
|
|
```
|
|
|
|
No test suite or linter is configured yet.
|
|
|
|
## Architecture
|
|
|
|
**Entry point:** `calliope/cli.py` → Click CLI → `calliope/app.py:main()`
|
|
|
|
**Data flow:** Hotkey press → Record audio → Transcribe with Whisper → Type into focused app
|
|
|
|
Key modules in `calliope/`:
|
|
|
|
- **app.py** — `CalliopeApp(rumps.App)`: main orchestrator, manages menu bar UI and coordinates all components; includes auto-stop-on-silence logic (background thread monitors RMS energy and stops recording after `silence_timeout_seconds` of quiet)
|
|
- **recorder.py** — Audio capture via `sounddevice` at 16kHz mono float32, with chunk consolidation
|
|
- **transcriber.py** — Whisper STT using `mlx-whisper` (`mlx_whisper.transcribe`); default model `mlx-community/whisper-large-v3-turbo`
|
|
- **hotkeys.py** — `HotkeyListener` using `pynput`: supports push-to-talk (Ctrl+Shift hold) and toggle (Ctrl+Space) modes
|
|
- **typer.py** — Outputs text via Quartz CGEvents (character mode) or clipboard paste (Cmd+V)
|
|
- **overlay.py** — `WaveformOverlay`: floating NSPanel with scrolling waveform during recording, pulsing dots during transcription
|
|
- **setup_wizard.py** — Rich-based interactive first-run config (mic, hotkeys, model download)
|
|
- **config.py** — Loads/saves YAML config at `~/.config/calliope/config.yaml`
|
|
|
|
## Platform Constraints
|
|
|
|
- **macOS only** — uses `pyobjc` bindings (Quartz, AppKit, AVFoundation, ApplicationServices)
|
|
- **Apple Silicon required** — `mlx-whisper` uses the MLX framework, which only runs on Apple Silicon (M1 or later)
|
|
- Requires Accessibility and Microphone permissions in macOS System Settings
|