syntaxbullet/calliope
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update claude.md

Browse Source
This commit is contained in:
syntaxbullet
2026-02-18 16:46:36 +01:00
parent 4441f4046f
commit 46d9136b2f
1 changed files with 5 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
CLAUDE.md
View File

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## 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 Hugging Face Transformers + PyTorch.
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
@@ -13,7 +13,7 @@ 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 openai/whisper-large-v3 # Override config
calliope --device 2 --model mlx-community/whisper-large-v3 # Override config
```
No test suite or linter is configured yet.
@@ -26,9 +26,9 @@ No test suite or linter is configured yet.
Key modules in `calliope/`:
- **app.py** — `CalliopeApp(rumps.App)`: main orchestrator, manages menu bar UI and coordinates all components
- **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 HF `transformers.pipeline("automatic-speech-recognition")`
- **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
@@ -38,5 +38,5 @@ Key modules in `calliope/`:
## Platform Constraints
- **macOS only** — uses `pyobjc` bindings (Quartz, AppKit, AVFoundation, ApplicationServices)
- **MPS (Apple Silicon):** must use float32, not float16 (causes garbled Whisper output)
- **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