From 46d9136b2f0effd48926b6f30422681285d5e1b8 Mon Sep 17 00:00:00 2001 From: syntaxbullet Date: Wed, 18 Feb 2026 16:46:36 +0100 Subject: [PATCH] chore: update claude.md --- CLAUDE.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a48fe58..ea180ca 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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