Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
chore: cleanup md file blank spaces
Felipe Afonso49ffd64a4beb
diff --git a/CLAUDE.md b/CLAUDE.mdindex 7406c97b9..b556ee40a 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -9,7 +9,6 @@ OpenWhispr is an Electron-based desktop dictation application that uses whisper.## Architecture Overview### Core Technologies-- **Frontend**: React 19, TypeScript, Tailwind CSS v4, Vite- **Desktop Framework**: Electron 39 with context isolation- **Database**: better-sqlite3 for local transcription history@@ -186,7 +185,6 @@ OpenWhispr is an Electron-based desktop dictation application that uses whisper.### 1. FFmpeg IntegrationFFmpeg is bundled with the app and doesn't require system installation:-```javascript// FFmpeg is unpacked from ASAR to app.asar.unpacked/node_modules/ffmpeg-static/```@@ -205,7 +203,6 @@ FFmpeg is bundled with the app and doesn't require system installation:### 3. Local Whisper Models (GGML format)Models stored in `~/.cache/openwhispr/whisper-models/`:-- tiny: ~75MB (fastest, lowest quality)- base: ~142MB (recommended balance)- small: ~466MB (better quality)@@ -231,7 +228,6 @@ CREATE TABLE transcriptions (### 5. Settings StorageSettings stored in localStorage with these keys:-- `whisperModel`: Selected Whisper model- `useLocalWhisper`: Boolean for local vs cloud- `openaiApiKey`: Encrypted API key@@ -246,14 +242,12 @@ Settings stored in localStorage with these keys:- `customDictionary`: JSON array of words/phrases for improved transcription accuracyEnvironment variables persisted to `.env` (via `saveAllKeysToEnvFile()`):-- `LOCAL_TRANSCRIPTION_PROVIDER`: Transcription engine (`nvidia` for Parakeet)- `PARAKEET_MODEL`: Selected Parakeet model name (e.g., `parakeet-tdt-0.6b-v3`)### 6. Language Support58 languages supported (see src/utils/languages.ts):-- Each language has a two-letter code and label- "auto" for automatic detection- Passed to whisper.cpp via -l parameter@@ -283,7 +277,6 @@ Environment variables persisted to `.env` (via `saveAllKeysToEnvFile()`):### 8. Model Registry ArchitectureAll AI model definitions are centralized in `src/models/modelRegistryData.json` as the single source of truth:-```json{"cloudProviders": [...], // OpenAI, Anthropic, Gemini API models@@ -292,7 +285,6 @@ All AI model definitions are centralized in `src/models/modelRegistryData.json````**Key files:**-- `src/models/modelRegistryData.json` - Single source of truth for all models- `src/models/ModelRegistry.ts` - TypeScript wrapper with helper methods- `src/config/aiProvidersConfig.ts` - Derives AI_MODES from registry@@ -300,7 +292,6 @@ All AI model definitions are centralized in `src/models/modelRegistryData.json`- `src/helpers/modelManagerBridge.js` - Handles local model downloads**Local model features:**-- Each model has `hfRepo` for direct HuggingFace download URLs- `promptTemplate` defines the chat format (ChatML, Llama, Mistral)- Download URLs constructed as: `{baseUrl}/{hfRepo}/resolve/main/{fileName}`@@ -308,7 +299,6 @@ All AI model definitions are centralized in `src/models/modelRegistryData.json`### 9. API Integrations and Updates**OpenAI Responses API (September 2025)**:-- Migrated from Chat Completions to new Responses API- Endpoint: `https://api.openai.com/v1/responses`- Simplified request format with `input` array instead of `messages`@@ -317,20 +307,17 @@ All AI model definitions are centralized in `src/models/modelRegistryData.json`- No temperature parameter for newer models (GPT-5, o-series)**Anthropic Integration**:-- Routes through IPC handler to avoid CORS issues in renderer process- Uses main process for API calls with proper error handling- Model IDs use alias format (e.g., `claude-sonnet-4-6` not date-suffixed versions)**Gemini Integration**:-- Direct API calls from renderer process- Increased token limits for Gemini 3.1 Pro (2000 minimum)- Proper handling of thinking process in responses- Error handling for MAX_TOKENS finish reason**API Key Persistence**:-- All API keys now properly persist to `.env` file- Keys stored in environment variables and reloaded on app start- Centralized `saveAllKeysToEnvFile()` method ensures consistency@@ -340,7 +327,6 @@ All AI model definitions are centralized in `src/models/modelRegistryData.json`The app can open OS-level settings for microphone permissions, sound input selection, and accessibility:**IPC Handlers** (in `ipcHandlers.js`):-- `open-microphone-settings`: Opens microphone privacy settings- `open-sound-input-settings`: Opens sound/audio input device settings- `open-accessibility-settings`: Opens accessibility privacy settings (macOS only)@@ -353,7 +339,6 @@ The app can open OS-level settings for microphone permissions, sound input selec| Linux | Manual (no URL scheme) | Manual (e.g., pavucontrol) | N/A |**UI Component** (`MicPermissionWarning.tsx`):-- Shows platform-appropriate buttons and messages- Linux only shows "Open Sound Settings" (no separate privacy settings)- macOS/Windows show both sound and privacy buttons@@ -361,7 +346,6 @@ The app can open OS-level settings for microphone permissions, sound input selec### 11. Debug ModeEnable with `--log-level=debug` or `OPENWHISPR_LOG_LEVEL=debug` (can be set in `.env`):-- Logs saved to platform-specific app data directory- Comprehensive logging of audio pipeline- FFmpeg path resolution details@@ -373,26 +357,22 @@ Enable with `--log-level=debug` or `OPENWHISPR_LOG_LEVEL=debug` (can be set in `Native Windows support for true push-to-talk functionality using low-level keyboard hooks:**Architecture**:-- `resources/windows-key-listener.c`: Native C program using Windows `SetWindowsHookEx` for keyboard hooks- `src/helpers/windowsKeyManager.js`: Node.js wrapper that spawns and manages the native binary- Binary outputs `KEY_DOWN` and `KEY_UP` to stdout when target key is pressed/released**Compound Hotkey Support**:-- Parses hotkey strings like `CommandOrControl+Shift+F11`- Maps modifiers: `CommandOrControl`/`Ctrl` → VK_CONTROL, `Alt`/`Option` → VK_MENU, `Shift` → VK_SHIFT- Verifies all required modifiers are held before emitting key events**Binary Distribution**:-- Prebuilt binary downloaded from GitHub releases (`windows-key-listener-v*` tags)- Download script: `scripts/download-windows-key-listener.js`- CI workflow: `.github/workflows/build-windows-key-listener.yml`- Fallback to tap mode if binary unavailable**IPC Events**:-- `windows-key-listener:key-down`: Fired when hotkey pressed (start recording)- `windows-key-listener:key-up`: Fired when hotkey released (stop recording)@@ -401,21 +381,18 @@ Native Windows support for true push-to-talk functionality using low-level keyboImprove transcription accuracy for specific words, names, or technical terms:**How it works**:-- User adds words/phrases through Settings → Custom Dictionary- Words stored as JSON array in localStorage (`customDictionary` key)- On transcription, words are joined and passed as `prompt` parameter to Whisper- Works with both local whisper.cpp and cloud OpenAI Whisper API**Implementation**:-- `src/hooks/useSettings.ts`: Manages `customDictionary` state- `src/components/SettingsPage.tsx`: UI for adding/removing dictionary words- `src/helpers/audioManager.js`: Reads dictionary and adds to transcription options- `src/helpers/whisperServer.js`: Includes dictionary as `prompt` in API request**Whisper Prompt Parameter**:-- Whisper uses the prompt as context/hints for transcription- Words in the prompt are more likely to be recognized correctly- Useful for: uncommon names, technical jargon, brand names, domain-specific terms@@ -425,7 +402,6 @@ Improve transcription accuracy for specific words, names, or technical terms:On GNOME Wayland, Electron's `globalShortcut` API doesn't work due to Wayland's security model. OpenWhispr uses native GNOME shortcuts:**Architecture**:-1. `main.js` enables `GlobalShortcutsPortal` feature flag for Wayland2. `hotkeyManager.js` detects GNOME + Wayland and initializes `GnomeShortcutManager`3. `gnomeShortcut.js` creates D-Bus service at `com.openwhispr.App`@@ -433,19 +409,16 @@ On GNOME Wayland, Electron's `globalShortcut` API doesn't work due to Wayland's5. GNOME triggers `dbus-send` command which calls the D-Bus `Toggle()` method**Key Constants**:-- D-Bus service: `com.openwhispr.App`- D-Bus path: `/com/openwhispr/App`- gsettings path: `/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr/`**IPC Integration**:-- `get-hotkey-mode-info`: Returns `{ isUsingGnome, isUsingHyprland, isUsingNativeShortcut }` to renderer- UI hides activation mode selector when `isUsingNativeShortcut` is true- Forces tap-to-talk mode (push-to-talk not supported)**Hotkey Format Conversion**:-- Electron format: `Alt+R`, `CommandOrControl+Shift+Space`- GNOME format: `<Alt>r`, `<Control><Shift>space`- Backtick (`) → `grave` in GNOME keysym format@@ -455,7 +428,6 @@ On GNOME Wayland, Electron's `globalShortcut` API doesn't work due to Wayland'sOn Hyprland (wlroots Wayland compositor), Electron's `globalShortcut` API and the `GlobalShortcutsPortal` feature don't work reliably. OpenWhispr uses native Hyprland keybindings:**Architecture**:-1. `main.js` enables `GlobalShortcutsPortal` feature flag for Wayland (fallback)2. `hotkeyManager.js` detects Hyprland + Wayland and initializes `HyprlandShortcutManager`3. `hyprlandShortcut.js` creates D-Bus service at `com.openwhispr.App` (same as GNOME)@@ -463,24 +435,20 @@ On Hyprland (wlroots Wayland compositor), Electron's `globalShortcut` API and th5. Hyprland triggers `dbus-send` command which calls the D-Bus `Toggle()` method**Detection**:-- Primary: `HYPRLAND_INSTANCE_SIGNATURE` environment variable (set by Hyprland)- Fallback: `XDG_CURRENT_DESKTOP` contains "hyprland"**Hotkey Format Conversion**:-- Electron format: `Alt+R`, `CommandOrControl+Shift+Space`- Hyprland format: `ALT, R`, `CTRL SHIFT, space`- Modifier-only combos (e.g., `Control+Super`) → `CTRL, Super_L`**Bind/Unbind Commands**:-- Register: `hyprctl keyword bind "ALT, R, exec, dbus-send --session ..."`- Unregister: `hyprctl keyword unbind "ALT, R"`- Bindings are ephemeral (don't survive Hyprland restart) but re-registered on app startup**Limitations**:-- Push-to-talk not supported (Hyprland `bind` fires a single exec, not key-down/key-up)- Requires `hyprctl` on PATH (ships with Hyprland)@@ -489,25 +457,21 @@ On Hyprland (wlroots Wayland compositor), Electron's `globalShortcut` API and thDetects meetings via three independent sources, orchestrated by `MeetingDetectionEngine`:**Architecture**:-- `MeetingDetectionEngine` listens to events from `MeetingProcessDetector` and `AudioActivityDetector`- `GoogleCalendarManager` provides calendar context (imminent events, active meetings)- All three sources feed into a unified notification pipeline**Process Detection** (known meeting apps — Zoom, Teams, Webex, FaceTime):-- macOS: `systemPreferences.subscribeWorkspaceNotification` — zero CPU, instant detection- Windows/Linux: `processListCache` shared polling (30s interval, `ps-list` npm)**Microphone Detection** (unscheduled/browser meetings like Google Meet):-- macOS: `macos-mic-listener` binary — CoreAudio `kAudioDevicePropertyDeviceIsRunningSomewhere` property listeners with hot-plug support- Windows: `windows-mic-listener.exe` — WASAPI `IAudioSessionManager2` session monitoring, `--exclude-pid` for self-mic exclusion- Linux: `pactl subscribe` — PulseAudio source-output events- All platforms: Graceful fallback to polling if native binary/command unavailable**UX Rules**:-- During recording (tap-to-talk or push-to-talk): ALL notifications suppressed- After recording: 2.5s cooldown before showing queued notifications- Multiple signals coalesced: process > audio priority, one notification shown@@ -515,13 +479,11 @@ Detects meetings via three independent sources, orchestrated by `MeetingDetectio- Active calendar meeting recording: all detections suppressed**Binary Distribution**:-- macOS: Compiled from Swift source via `scripts/build-macos-mic-listener.js` during `compile:native`- Windows: Prebuilt binary downloaded via `scripts/download-windows-mic-listener.js` during `prebuild:win`- CI workflow: `.github/workflows/build-windows-mic-listener.yml` auto-builds on push to main**Calendar Sync Resilience**:-- 10s socket timeout on all Google Calendar API requests- Exponential backoff on consecutive failures: 2min → 4min → 8min → cap 30min- Reset to normal 2min interval on any successful sync@@ -537,7 +499,6 @@ All user-facing strings **must** use the i18n system. Never hardcode UI text in**Supported languages**: en, es, fr, de, pt, it, ru, zh-CN, zh-TW**How to use**:-```tsximport { useTranslation } from "react-i18next";@@ -547,7 +508,6 @@ const { t } = useTranslation();```**Rules**:-1. Every new UI string must have a translation key in `en/translation.json` and all other language files2. Use `useTranslation()` hook in components and hooks3. Keep `{{variable}}` interpolation syntax for dynamic values@@ -626,7 +586,6 @@ const { t } = useTranslation();### Platform-Specific Notes**macOS**:-- Requires accessibility permissions for clipboard (auto-paste)- Requires microphone permission (prompted by system)- Uses AppleScript for reliable pasting@@ -636,7 +595,6 @@ const { t } = useTranslation();- System settings accessible via `x-apple.systempreferences:` URL scheme**Windows**:-- No special accessibility permissions needed- Microphone privacy settings at `ms-settings:privacy-microphone`- Sound settings at `ms-settings:sound`@@ -649,7 +607,6 @@ const { t } = useTranslation();- Falls back to tap mode if unavailable**Linux**:-- Multiple package manager support- Standard XDG directories- AppImage for distribution