Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

chore: bump version + doc update

Gabriel Steinfa4e67726b60
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0176581f5..6b3c19735 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.1.0] - 2026-01-10
+
+### Added
+- **Compound Hotkey Support**: Use multi-key combinations like `Cmd+Shift+K` or `Ctrl+Alt+D` for dictation
+- **Groq API Integration**: Ultra-fast AI inference with Groq's cloud API
+- **Auto-Update UI**: Download progress bars and install button in settings
+- **Recording Cancellation**: Cancel an in-progress recording without transcribing
+- **Release Notes Viewer**: Markdown-rendered release notes in settings
+
+### Changed
+- **Major Hotkey Refactor**: Complete rewrite of hotkey selection with improved reliability and validation
+- **Consolidated Model Registry**: Single source of truth for all AI models (`modelRegistryData.json`)
+- **Unified Model Picker**: Reusable component for both transcription and reasoning model selection
+- **Improved Latency Logging**: Numbered stage logs for recording, transcription, reasoning, and paste timing
+- **Reduced Paste Delay**: Lowered from 100ms to 50ms for faster text insertion
+- **Code Quality**: Added ESLint, Prettier for JS/TS, and Ruff for Python
+
+### Fixed
+- **Windows 11 Compatibility**: Fixed PATH separator, cache directories, and process termination
+- **Python Virtual Environment**: Fixed race condition and added Arch Linux venv support
+- **Microphone Detection**: Improved onboarding flow for missing inputs with deep-linking to system settings
+- **Recording State Alignment**: Recording now aligns to MediaRecorder's actual start/stop events
+- **Caching Optimizations**: Cached accessibility, paste tool, and FFmpeg checks to reduce process spawns
+- **Window Titles**: Electron window titles now set correctly after page load
+
## [1.0.15] - 2026-01-05
### Added
diff --git a/DEBUG.md b/DEBUG.md
index 260556c16..e026237e7 100644
--- a/DEBUG.md
+++ b/DEBUG.md
@@ -1,11 +1,10 @@
-# OpenWhispr Debug Mode
+# Debug Mode
-## Enabling Debug Logging
+Enable verbose logging to diagnose issues like "no audio detected" or transcription failures.
-When experiencing issues like "no audio detected", you can enable verbose debug logging to help diagnose the problem.
+## Enable Debug Logging
-### Method 1: Command Line Flag
-Run the app with the `--log-level=debug` flag:
+### Option 1: Command Line
```bash
# macOS
/Applications/OpenWhispr.app/Contents/MacOS/OpenWhispr --log-level=debug
@@ -14,173 +13,61 @@ Run the app with the `--log-level=debug` flag:
OpenWhispr.exe --log-level=debug
```
-### Method 2: Environment Variable
-Set the `OPENWHISPR_LOG_LEVEL=debug` environment variable:
-```bash
-# macOS/Linux
-export OPENWHISPR_LOG_LEVEL=debug
-open /Applications/OpenWhispr.app
-
-# Windows
-set OPENWHISPR_LOG_LEVEL=debug
-OpenWhispr.exe
+### Option 2: Environment File
+Add to your `.env` file and restart:
+```
+OPENWHISPR_LOG_LEVEL=debug
```
-You can also put `OPENWHISPR_LOG_LEVEL=debug` in the app's `.env` file and restart:
-
-- **macOS**: `~/Library/Application Support/OpenWhispr/.env`
-- **Windows**: `%APPDATA%\OpenWhispr\.env`
-- **Linux**: `~/.config/OpenWhispr/.env`
-
-## Finding the Debug Logs
-
-When debug mode is enabled, logs are saved to:
-
-- **macOS**: `~/Library/Application Support/OpenWhispr/logs/debug-[timestamp].log`
-- **Windows**: `%APPDATA%\OpenWhispr\logs\debug-[timestamp].log`
-- **Linux**: `~/.config/OpenWhispr/logs/debug-[timestamp].log`
-
-## Log Levels (Quick Guide)
-
-Log levels control how verbose logging is. Setting `--log-level=debug` means you'll see everything at `debug` and above.
-
-- `trace`: very detailed, internal flow (most verbose)
-- `debug`: detailed diagnostics for troubleshooting
-- `info`: normal operational events
-- `warn`: something unexpected, but the app can continue
-- `error`: a failure occurred
-- `fatal`: the app can't continue
-
-## What the Logs Include
-
-The debug logs capture comprehensive information about the audio pipeline:
-1. **๐ŸŽฌ FFmpeg Detection**
- - All paths checked for FFmpeg (bundled and system)
- - File existence, permissions, and executable status
- - ASAR unpacking verification
- - Environment variable configuration
- - Final FFmpeg path resolution
+**Env file locations:**
+- macOS: `~/Library/Application Support/OpenWhispr/.env`
+- Windows: `%APPDATA%\OpenWhispr\.env`
+- Linux: `~/.config/OpenWhispr/.env`
-2. **๐ŸŽ™๏ธ Audio Recording**
- - Microphone permission requests and grants
- - Audio track details (enabled, muted, label, settings)
- - Real-time audio chunk reception (size and count)
- - Audio level analysis (average, max, silence detection)
- - Recording duration and blob creation
+## Log File Locations
-3. **๐Ÿ”Š Audio Processing**
- - Audio data types and conversion
- - Temporary file creation and permissions
- - File sizes at each stage
- - First bytes of audio data (hex)
- - Whisper command construction
- - Python process environment setup
+- **macOS**: `~/Library/Application Support/OpenWhispr/logs/debug-*.log`
+- **Windows**: `%APPDATA%\OpenWhispr\logs\debug-*.log`
+- **Linux**: `~/.config/OpenWhispr/logs/debug-*.log`
-4. **๐Ÿ“ก Process Communication**
- - IPC messages between renderer and main process
- - Audio blob transfer details
- - Whisper process stdout/stderr
- - Process exit codes
- - Error propagation
+## What Gets Logged
-5. **๐ŸŽฏ Pipeline Stages**
- - Each stage is clearly marked with descriptive labels
- - Timing information for performance analysis
- - Success/failure status at each step
+| Stage | Details |
+|-------|---------|
+| FFmpeg | Path resolution, permissions, ASAR unpacking |
+| Audio Recording | Permission requests, chunk sizes, audio levels |
+| Audio Processing | File creation, Whisper command, process output |
+| IPC | Messages between renderer and main process |
-## Common Issues and What to Look For
+## Common Issues
### "No Audio Detected"
-Look for these specific log entries:
-- `Audio appears to be silent` - Check `maxLevel` value (should be > 0.01)
-- `Audio chunk received, size: 0` - MediaRecorder not capturing data
-- `FFmpeg not available` - FFmpeg path resolution failed
-- `Bundled FFmpeg not found` - ASAR unpacking issue
-- `FFmpeg exists but is not executable` - Permission problem
-- `No audio chunks received after 3 seconds` - Microphone not working
-- `Whisper reported no audio detected` - FFmpeg processing failed
-
-### Transcription Fails
Look for:
-- `Whisper stderr:` - Check for Python errors or FFmpeg issues
-- `Failed to parse Whisper output` - Invalid JSON response
-- `Process closed with code: [non-zero]` - Process failure
-- `Audio file is empty after writing` - File I/O issue
-- `Unsupported audio data type` - Audio format problem
+- `maxLevel < 0.01` โ†’ Audio too quiet
+- `Audio appears to be silent` โ†’ Microphone issue
+- `FFmpeg not available` โ†’ Path resolution failed
-### Slow Performance
+### Transcription Fails
Look for:
-- Large `blobSize` values (> 10MB) - Consider audio optimization
-- Multiple `Checking alternative path` entries - FFmpeg search overhead
-- `Whisper process closed` with long delays - Model processing time
+- `Whisper stderr:` โ†’ Python/FFmpeg errors
+- `Process closed with code: [non-zero]` โ†’ Process failure
+- `Failed to parse Whisper output` โ†’ Invalid JSON
### Permission Issues
Look for:
-- `Microphone Access Denied` - System permission required
-- `dirReadable: false` - Directory access problems
-- `permissions: [number]` - Check file permission octals
+- `Microphone Access Denied`
+- `isExecutable: false` โ†’ FFmpeg permission issue
-## Interpreting Key Debug Messages
-
-### FFmpeg Path Resolution
-```
-๐ŸŽฌ FFmpeg Debug - Initial ffmpeg-static path {
- "ffmpegPath": "/path/to/ffmpeg",
- "exists": true,
- "fileInfo": {
- "size": 74750976,
- "isFile": true,
- "isExecutable": true,
- "permissions": "100755"
- }
-}
-```
-- `exists: false` - Path resolution failed
-- `isExecutable: false` - Permission issue
-- `permissions` - Should be executable (755 or similar)
-
-### Audio Level Analysis
-```
-๐Ÿ”Š Audio level analysis {
- "duration": "3.45s",
- "samples": 165888,
- "averageLevel": "0.002134",
- "maxLevel": "0.045632",
- "isSilent": false
-}
-```
-- `maxLevel < 0.01` - Audio too quiet/silent
-- `samples: 0` - No audio data captured
-- `isSilent: true` - Definite silence detected
-
-### Whisper Process Environment
-```
-๐Ÿš€ Starting process {
- "command": "python3",
- "args": ["whisper_bridge.py", "/tmp/whisper_audio.wav", "--model", "base"],
- "env": {
- "FFMPEG_PATH": "/path/to/ffmpeg",
- "FFMPEG_EXECUTABLE": "/path/to/ffmpeg",
- "FFMPEG_BINARY": "/path/to/ffmpeg"
- }
-}
-```
-- All three FFmpeg env vars should point to valid path
-- Empty env vars indicate FFmpeg not found
-
-## Sharing Debug Logs
+## Sharing Logs
When reporting issues:
-
1. Enable debug mode and reproduce the issue
-2. Find the debug log file (path is shown at startup)
-3. Look for any sensitive information and redact if needed
-4. Share the relevant portions of the log file
-5. Include the error message shown to the user
-6. Note your system configuration (macOS version, mic type)
+2. Locate the log file
+3. Redact any sensitive information
+4. Include relevant log sections in your issue report
-## Disabling Debug Mode
+## Disable Debug Mode
-Debug mode is disabled by default. To ensure it's off:
-- Don't use `--log-level=debug`
-- Unset the environment variable: `unset OPENWHISPR_LOG_LEVEL`
+Debug mode is off by default. To ensure it's disabled:
+- Remove `--log-level=debug` from command
+- Remove `OPENWHISPR_LOG_LEVEL` from `.env`
diff --git a/LOCAL_WHISPER_SETUP.md b/LOCAL_WHISPER_SETUP.md
index 8945af088..b8fdf735e 100644
--- a/LOCAL_WHISPER_SETUP.md
+++ b/LOCAL_WHISPER_SETUP.md
@@ -1,205 +1,83 @@
-# Local Whisper Integration Guide
+# Local Whisper Setup
-## โœ… What We've Accomplished
+OpenWhispr supports local speech-to-text processing using OpenAI's Whisper models. This keeps your audio completely privateโ€”nothing leaves your device.
-Your OpenWhispr app has been successfully refactored to support **local Whisper models** in addition to the OpenAI API. Here's what's been implemented:
+## Quick Start
-### ๐Ÿ”ง Technical Implementation
+1. Open the **Control Panel** (right-click tray icon or click the overlay)
+2. Go to **Settings** โ†’ **Speech to Text Processing**
+3. Enable **Use Local Whisper**
+4. Select a model (recommended: `base`)
+5. Click **Save**
-1. **Python Bridge Script** (`whisper_bridge.py`)
- - Handles local audio transcription using OpenAI's Whisper models
- - Supports all Whisper models: tiny, base, small, medium, large, turbo
- - JSON output for integration with Electron app
- - Proper error handling and cleanup
+The first transcription will download the model automatically.
-2. **Enhanced Main Process** (`main.js`)
- - New IPC handlers for local Whisper transcription
- - Python executable detection across different systems
- - Whisper installation checking
- - Temporary file management with cleanup
- - 30-second timeout protection
+## Model Selection
-3. **Updated Preload Script** (`preload.js`)
- - New IPC methods exposed to renderer
- - Type-safe interfaces for TypeScript
+| Model | Size | Speed | Quality | RAM | Best For |
+|--------|--------|----------|---------|--------|-----------------------|
+| tiny | 39MB | Fastest | Basic | ~1GB | Quick notes |
+| base | 74MB | Fast | Good | ~1GB | **Recommended** |
+| small | 244MB | Medium | Better | ~2GB | Professional use |
+| medium | 769MB | Slow | High | ~5GB | High accuracy |
+| large | 1.5GB | Slowest | Best | ~10GB | Maximum quality |
+| turbo | 809MB | Fast | High | ~6GB | Best speed/quality |
-4. **Enhanced React App** (`src/App.jsx`)
- - Automatic fallback from local to OpenAI API
- - User preference storage in localStorage
- - Model selection support
- - Smart error handling
+## How It Works
-5. **Advanced Control Panel** (`src/components/ControlPanel.tsx`)
- - Complete UI for Whisper engine selection
- - Model selection dropdown with descriptions
- - Installation status checking
- - Privacy information display
- - Settings persistence
+OpenWhispr automatically:
+1. Creates an isolated Python virtual environment (no system modifications)
+2. Installs Whisper and dependencies into that environment
+3. Downloads the selected model on first use
+4. Processes audio locally using FFmpeg (bundled with the app)
-## ๐Ÿš€ How to Use Local Whisper
+## Requirements
-### Step 1: Open the Control Panel
-- Right-click the app tray icon (macOS) or use the overlay
-- Navigate to "Whisper Engine Settings"
-
-### Step 2: Enable Local Whisper
-- Check the "Use Local Whisper (Privacy Mode)" checkbox
-- Select your desired model:
- - **Tiny**: Fastest, lowest quality (39M params)
- - **Base**: Balanced speed/quality (74M params) - Recommended
- - **Small**: Better quality, slower (244M params)
- - **Medium**: High quality, much slower (769M params)
- - **Large**: Best quality, very slow (1550M params)
- - **Turbo**: Fast with good quality (809M params)
+- **Disk Space**: 39MBโ€“1.5GB depending on model
+- **RAM**: 1GBโ€“10GB depending on model
+- **Python**: System Python 3.7+ (used only to create the venv)
-### Step 3: Save Settings
-- Click "Save Whisper Settings"
-- The app will now use local processing for all new transcriptions
+## File Locations
-## ๐Ÿ”’ Privacy Benefits
+| Data | macOS | Windows | Linux |
+|-------------------|----------------------------------------------|--------------------------------------|---------------------------------|
+| Virtual Env | `~/Library/Application Support/OpenWhispr/python/venv` | `%APPDATA%\OpenWhispr\python\venv` | `~/.config/OpenWhispr/python/venv` |
+| Models | `~/.cache/whisper/` | `%USERPROFILE%\.cache\whisper\` | `~/.cache/whisper/` |
-### Local Whisper Mode
-- โœ… **Complete Privacy**: Audio never leaves your device
-- โœ… **No Internet Required**: Works offline (after model download)
-- โœ… **No API Costs**: Free to use after initial setup
-- โœ… **Faster Response**: No network latency
-- โš ๏ธ **Higher Resource Usage**: Uses CPU/memory for processing
+## Advanced: Custom Python
-### OpenAI API Mode
-- โš ๏ธ **Audio Sent to OpenAI**: Audio data transmitted to servers
-- โš ๏ธ **Internet Required**: Needs active connection
-- โš ๏ธ **API Costs**: Charges per minute of audio
-- โœ… **Fast & Efficient**: Minimal local resource usage
-- โœ… **Always Latest Model**: OpenAI's most advanced model
+To use a specific Python interpreter instead of the managed venv:
-## ๐Ÿ“ฆ Requirements
+```bash
+# macOS/Linux
+export OPENWHISPR_PYTHON=/usr/local/bin/python3.11
-### โœ… Bundled Dependencies (No Installation Required)
+# Windows (permanent)
+setx OPENWHISPR_PYTHON "C:\Python311\python.exe"
+```
-The following are now **bundled with the app** and require no user installation:
+When set, OpenWhispr uses this interpreter directly. Ensure Whisper is installed in that environment.
-- โœ… **FFmpeg**: Bundled with the app (no system installation needed)
-- โœ… **Python Bridge Script**: Included in the app bundle
-- โœ… **App Integration**: Fully implemented
+## Troubleshooting
-### ๐Ÿ”ง Isolated Python Environment (Default)
-
-For **local Whisper processing**, OpenWhispr now:
-
-- โœ… Creates a per-user virtual environment automatically
-- โœ… Installs OpenAI Whisper inside that environment
-- โœ… Avoids modifying system Python (no global `pip install`)
-
-If you want to force a specific interpreter, set `OPENWHISPR_PYTHON` to a Python 3.x path before launching the app.
-
-**Note**: FFmpeg is bundled, so users no longer need to install it separately.
-
-## ๐Ÿงช Testing Your Setup
-
-### Test 1: Check Installation Status
-1. Open the Control Panel
-2. Look at the "Whisper Engine Settings" card
-3. You should see "โœ… Installed" next to the Local Whisper checkbox
-
-### Test 2: Test Local Transcription
-1. Enable "Use Local Whisper" in Control Panel
-2. Select "base" model (recommended for testing)
-3. Save settings
-4. Press your hotkey (default: backtick `) to start dictation
-5. Speak clearly for 2-3 seconds
-6. Press your hotkey again to stop
-7. The transcription should appear and paste automatically
-
-### Test 3: Model Download (First Time)
-- The first time you use a model, Whisper will download it automatically
-- This may take a few minutes depending on your internet speed
-- Subsequent uses will be much faster
-
-## ๐Ÿ”„ Fallback Behavior
-
-The app is configured with intelligent fallback:
-
-1. **Primary**: Use local Whisper if enabled and working
-2. **Fallback**: Automatically switch to OpenAI API if local fails
-3. **Error Handling**: Clear messages about what's happening
-4. **Hotkey Control**: All recording is controlled via customizable hotkey (no clicking required)
-
-## ๐Ÿ“Š Model Performance Guide
-
-| Model | Size | Speed | Quality | Memory | Best For |
-|--------|-------|----------|---------|--------|----------|
-| Tiny | 39M | Fastest | Basic | ~1GB | Quick notes |
-| Base | 74M | Fast | Good | ~1GB | **Recommended** |
-| Small | 244M | Medium | Better | ~2GB | Professional use |
-| Medium | 769M | Slow | High | ~5GB | High accuracy needed |
-| Large | 1550M | Slowest | Best | ~10GB | Maximum quality |
-| Turbo | 809M | Fast | High | ~6GB | Best balance |
-
-## ๐Ÿ›  Troubleshooting
-
-### "โŒ Not Found" Status
-If you see this status:
-1. Click "Recheck Installation" button
-2. Restart the app completely
-3. Check Console logs for Python/Whisper errors
+### "Not Found" Status
+1. Click **Recheck Installation** in Control Panel
+2. Restart the app
+3. Check console logs for Python/Whisper errors
### Transcription Fails
-1. Check your microphone permissions
-2. Verify the model downloaded successfully
-3. Try switching to a smaller model (tiny/base)
-4. Check Console logs for detailed error messages
+1. Verify microphone permissions
+2. Try a smaller model (tiny/base)
+3. Check disk space for model downloads
### Slow Performance
-1. Use smaller models (tiny, base)
-2. Close other resource-intensive apps
-3. Check your system's available memory
-
-### Model Download Issues
-1. Ensure stable internet connection
-2. Check available disk space (~2-15GB depending on model)
-3. Try smaller model first
-
-## ๐Ÿ”ง Advanced Configuration
-
-### Custom Python Path
-If you need to force a specific interpreter, set the `OPENWHISPR_PYTHON` environment variable before launching the app (e.g. `setx OPENWHISPR_PYTHON "C:\\Python312\\python.exe"` on Windows or `export OPENWHISPR_PYTHON=/opt/homebrew/bin/python3.12` on macOS).
-When this is set, OpenWhispr will use that interpreter directly instead of its managed virtual environment, so ensure Whisper is installed in that environment.
-
-### Managed Python Environment Location
-The isolated environment lives under your app data directory:
-- macOS: `~/Library/Application Support/OpenWhispr/python/venv`
-- Windows: `%APPDATA%\\OpenWhispr\\python\\venv`
-- Linux: `~/.config/OpenWhispr/python/venv`
-
-### Model Storage Location
-Models are downloaded to `~/.cache/whisper/` by default.
-You can change this by modifying the bridge script.
-
-### Timeout Settings
-Current timeout is 30 seconds. To change:
-1. Edit `main.js`
-2. Find the `setTimeout` in the `transcribe-local-whisper` handler
-3. Adjust the value (in milliseconds)
-
-## ๐ŸŽฏ Next Steps
-
-Your app now supports both local and cloud transcription! You can:
-
-1. **Switch modes anytime** via Control Panel
-2. **Test different models** to find your preference
-3. **Enjoy complete privacy** with local processing
-4. **Keep API access** as a backup option
-5. **Customize your hotkey** to any key you prefer
-6. **Drag the panel** to position it anywhere on your screen
-
-The integration is complete and ready for production use. All files have been modified and the Python bridge is fully functional.
-
-## ๐Ÿ“ Files Modified
+1. Use smaller models (tiny or base)
+2. Close resource-intensive apps
+3. Consider using cloud mode for large files
-- โœ… `whisper_bridge.py` - New Python bridge script
-- โœ… `main.js` - Added local Whisper IPC handlers
-- โœ… `preload.js` - Added new IPC method exports
-- โœ… `src/App.jsx` - Enhanced with local/API switching
-- โœ… `src/components/ControlPanel.tsx` - New Whisper settings UI
+## Privacy Comparison
-Everything is ready to use! ๐ŸŽ‰
+| Mode | Audio Leaves Device | Internet Required | Cost |
+|-------|---------------------|-------------------|-----------|
+| Local | No | Only for model download | Free |
+| Cloud | Yes (to OpenAI) | Yes | API usage |
diff --git a/README.md b/README.md
index a14aa964a..1db478ace 100644
--- a/README.md
+++ b/README.md
@@ -11,10 +11,11 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
- ๐ŸŽค **Global Hotkey**: Customizable hotkey to start/stop dictation from anywhere (default: backtick `)
- ๐Ÿค– **Multi-Provider AI Processing**: Choose between OpenAI, Anthropic Claude, Google Gemini, or local models
- ๐ŸŽฏ **Agent Naming**: Personalize your AI assistant with a custom name for natural interactions
-- ๐Ÿง  **Latest AI Models** (September 2025):
- - **OpenAI**: GPT-5 Series, GPT-4.1 Series, o-series reasoning models (o3/o4-mini)
- - **Anthropic**: Claude Opus 4.1, Claude Sonnet 4, Claude 3.5 Sonnet/Haiku
- - **Google**: Gemini 2.5 Pro/Flash/Flash-Lite with thinking capability, Gemini 2.0 Flash
+- ๐Ÿง  **Multi-Provider AI**:
+ - **OpenAI**: GPT-5, GPT-4.1, o-series reasoning models
+ - **Anthropic**: Claude Opus 4.5, Claude Sonnet 4.5
+ - **Google**: Gemini 2.5 Pro/Flash/Flash-Lite
+ - **Groq**: Ultra-fast inference with Llama and Mixtral models
- **Local**: Qwen, LLaMA, Mistral models via llama.cpp
- ๐Ÿ”’ **Privacy-First**: Local processing keeps your voice data completely private
- ๐ŸŽจ **Modern UI**: Built with React 19, TypeScript, and Tailwind CSS v4
@@ -28,6 +29,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
- ๐Ÿ–ฑ๏ธ **Draggable Interface**: Move the dictation panel anywhere on your screen
- ๐Ÿ”„ **OpenAI Responses API**: Using the latest Responses API for improved performance
- ๐ŸŒ **Globe Key Toggle (macOS)**: Optional Fn/Globe key listener for a hardware-level dictation trigger
+- โŒจ๏ธ **Compound Hotkeys**: Support for multi-key combinations like `Cmd+Shift+K`
## Prerequisites
@@ -249,13 +251,11 @@ Once you've named your agent during setup, you can interact with it using multip
- "Hey [AgentName], convert this to bullet points"
**๐Ÿค– AI Provider Options**:
-- **OpenAI**:
- - GPT-5 Series (Nano/Mini/Full) - Latest generation with deep reasoning
- - GPT-4.1 Series - Enhanced coding with 1M token context
- - o3/o4 Series - Advanced reasoning models with longer thinking
-- **Anthropic**: Claude Opus 4.1, Sonnet 4 - Frontier intelligence models
-- **Google**: Gemini 2.5 Pro/Flash - Advanced multi-modal capabilities
-- **Local**: Community models for complete privacy
+- **OpenAI**: GPT-5, GPT-4.1, o-series reasoning models
+- **Anthropic**: Claude Opus 4.5, Sonnet 4.5, Haiku 4.5
+- **Google**: Gemini 2.5 Pro/Flash/Flash-Lite
+- **Groq**: Ultra-fast Llama and Mixtral inference
+- **Local**: Qwen, LLaMA, Mistral via llama.cpp
**๐Ÿ“ Regular Dictation** (for normal text):
- "This is just normal text I want transcribed"
@@ -523,12 +523,10 @@ A: OpenWhispr supports 58 languages including English, Spanish, French, German,
## Project Status
-OpenWhispr is actively maintained and ready for production use. Current version: 1.0.4
+OpenWhispr is actively maintained and ready for production use. Current version: 1.1.0
- โœ… Core functionality complete
-- โœ… Cross-platform support
+- โœ… Cross-platform support (macOS, Windows, Linux)
- โœ… Local and cloud processing
-- โœ… Automatic Python/Whisper installation
-- โœ… Agent naming system
-- โœ… Draggable interface
-- ๐Ÿšง Continuous improvements and bug fixes
+- โœ… Multi-provider AI (OpenAI, Anthropic, Gemini, Groq, Local)
+- โœ… Compound hotkey support
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index 643e4ac1e..12b71077e 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -1,74 +1,77 @@
-# OpenWhispr Troubleshooting
+# Troubleshooting
## Quick Diagnostics
| Check | Command |
-| --- | --- |
+|-------|---------|
| Host architecture | `uname -m` |
| Node architecture | `node -p "process.arch"` |
-| Native module arch | `file node_modules/better-sqlite3/build/Release/better_sqlite3.node` |
-| FFmpeg availability | `ffmpeg -version` or `node -e "console.log(require('ffmpeg-static'))"` |
| Python install | `python3 --version && which python3` |
-| Whisper cache size | `du -sh ~/Library/Application\ Support/whisper ~/.cache/whisper 2>/dev/null` |
-
-If any of these look wrong (e.g., `x86_64` binaries on an Apple Silicon host), run `scripts/complete-uninstall.sh`, then reinstall dependencies.
+| FFmpeg availability | `ffmpeg -version` |
## Common Issues
-### 1. Architecture mismatch (arm64 vs x86_64)
-**Symptoms:** the renderer crashes on launch, or `better_sqlite3.node` throws โ€œwrong architectureโ€ errors.
-
-**Resolution:**
-1. Run the diagnostics above. If `uname -m` reports `arm64` but `node -p "process.arch"` or `file โ€ฆbetter_sqlite3.node` shows `x86_64`, Node was installed with Rosetta.
-2. Uninstall the mismatched Node build (`brew uninstall node` or remove `/usr/local/bin/node`).
-3. Reinstall an ARM build: `arch -arm64 brew install node@20` or download the arm64 pkg from nodejs.org.
-4. Remove residual artifacts: run `scripts/complete-uninstall.sh` and allow it to delete caches.
-5. Recreate dependencies: `rm -rf node_modules package-lock.json && npm ci`.
-6. Rebuild (`npm run dev` or `npm run build`) and confirm onboarding starts normally.
-
-### 2. โ€œyouโ€ transcription bug
-**Symptoms:** every transcription history entry shows the word โ€œyouโ€, even when you speak full sentences.
-
-**Cause:** Whisper produced an empty/near-empty result and the legacy fallback string (`"you"`) is being saved. This usually happens when:
-- the microphone permission was revoked mid-session,
-- stale local Whisper caches contain zero-byte clips,
-- or a hotkey collision triggers dictation without audio input.
-
-**Resolution:**
-1. Confirm microphone + accessibility permissions via macOS Settings, then re-run onboarding step 3 to re-test.
-2. Clear SQLite history and caches: `scripts/complete-uninstall.sh` (answer โ€œyโ€ to Whisper model removal) or manually delete the folders listed in `CLEANUP_INSTRUCTIONS.md`.
-3. Reinstall Whisper models from the Control Panel or rerun onboardingโ€™s model picker.
-4. Try a different dictation hotkeyโ€”reserved accelerators are now blocked in step 4 and settings.
-5. If you rely on cloud transcription, verify your OpenAI key is valid (link in the UI now opens `https://platform.openai.com`).
-
-### 3. FFmpeg missing
-**Symptoms:** Local transcription fails immediately with โ€œFFmpeg not foundโ€ or `ffmpeg-static` resolves to `null`.
-
-**Resolution:**
-1. Run `ffmpeg -version`. If the command is missing, install via `brew install ffmpeg` (Apple Silicon) or add it to your PATH.
-2. Ensure npm dependencies pulled the static binary: `rm -rf node_modules package-lock.json && npm ci`.
-3. Execute `npm run setup` so the bridge verifies FFmpeg before launching Electron.
-4. If the packaged app still cannot find FFmpeg, run `scripts/complete-uninstall.sh` to clear frozen binaries, then rebuild via `npm run build:mac`.
-
-### 4. Python install issues
-**Symptoms:** Local Whisper install fails, or `window.electronAPI.installPython` never completes.
-
-**Resolution:**
-1. Verify you have a working Python 3: `python3 --version` and `which python3`. Apple Silicon should point to `/usr/bin/python3` or a Homebrew arm64 path.
-2. OpenWhispr creates an isolated virtual environment under your user data directory. If it fails, delete the appโ€™s `python/venv` folder and retry.
-3. From the running app, open Settings โ†’ Whisper Models and click โ€œInstall Pythonโ€ (uses the IPC bridge) or install Python manually from python.org.
-4. If you see a โ€œexternally managed environment / PEP 668โ€ error, you are trying to install into system Python. Use the appโ€™s install button or unset `OPENWHISPR_PYTHON`.
-5. Delete `~/Library/Application Support/whisper` if partially downloaded models exist, then try again.
-6. As a last resort, run `scripts/complete-uninstall.sh`, reboot, and rerun onboarding so the installer can download a clean toolchain.
-
-### 5. Local Whisper can't find Python on Windows
-**Symptoms:** The toast shows `Whisper process error: spawn python ENOENT` as soon as transcription starts.
-
-**Resolution:**
-1. Update to the latest desktop buildโ€”recent releases probe the Windows `py` launcher plus the common `Python312`/`Python311` folders instead of relying on `python.exe` being on PATH.
-2. Open `cmd` and run `py --version`. If this command fails, reinstall Python 3.11+ from [python.org](https://www.python.org/downloads/windows/) and keep the โ€œInstall launcherโ€ checkbox ticked.
-3. If you installed Python to a custom directory, set `OPENWHISPR_PYTHON` to the full path (e.g. `setx OPENWHISPR_PYTHON "D:\\Tools\\Python312\\python.exe"`) and restart the app so the bridge can pick it up.
-4. Re-run the Local Whisper onboarding check or use the Control Panel โ†’ Whisper Engine card to verify detection succeeds.
-5. If you would rather stay on cloud transcription, open the Control Panel, toggle off โ€œUse Local Whisperโ€, or enable โ€œAllow OpenAI fallbackโ€ so the app automatically switches to the API whenever Python is missing.
-
-Need deeper help? Capture the diagnostic command output and attach it to an issue so we can see which stage failed.
+### Architecture Mismatch (Apple Silicon)
+
+**Symptoms:** Crashes on launch, "wrong architecture" errors
+
+**Fix:**
+1. Check if Node is x86_64 on arm64: `node -p "process.arch"` vs `uname -m`
+2. Uninstall mismatched Node and reinstall native build
+3. Run `rm -rf node_modules package-lock.json && npm ci`
+4. Rebuild the app
+
+### Empty Transcriptions
+
+**Symptoms:** History shows "you" or empty entries
+
+**Causes:**
+- Microphone permission revoked mid-session
+- Stale Whisper cache with corrupted clips
+- Hotkey triggering without audio input
+
+**Fix:**
+1. Check microphone permissions in System Settings
+2. Clear caches: `rm -rf ~/.cache/whisper`
+3. Try a different hotkey
+4. Re-run onboarding
+
+### FFmpeg Not Found
+
+**Symptoms:** "FFmpeg not found" error, transcription fails immediately
+
+**Fix:**
+1. Reinstall dependencies: `rm -rf node_modules && npm ci`
+2. Run `npm run setup` to verify FFmpeg
+3. If using packaged app, try reinstalling
+
+### Python/Whisper Issues
+
+**Symptoms:** Local transcription fails, "spawn python ENOENT"
+
+**Fix:**
+1. OpenWhispr creates an isolated venv automatically
+2. If failing, delete the venv folder and retry (see [LOCAL_WHISPER_SETUP.md](LOCAL_WHISPER_SETUP.md))
+3. Check if `python3 --version` works in terminal
+4. Try cloud transcription as fallback
+
+### Windows-Specific Issues
+
+See [WINDOWS_TROUBLESHOOTING.md](WINDOWS_TROUBLESHOOTING.md) for:
+- Window visibility issues
+- Python path detection
+- FFmpeg permission problems
+
+## Enable Debug Mode
+
+For detailed diagnostics, see [DEBUG.md](DEBUG.md).
+
+## Getting Help
+
+1. Enable debug mode and reproduce the issue
+2. Collect diagnostic output from commands above
+3. Open an issue at https://github.com/HeroTools/open-whispr/issues with:
+ - OS version
+ - OpenWhispr version
+ - Relevant log sections
+ - Steps to reproduce
diff --git a/WINDOWS_TROUBLESHOOTING.md b/WINDOWS_TROUBLESHOOTING.md
index 872acf00e..e66bbbb08 100644
--- a/WINDOWS_TROUBLESHOOTING.md
+++ b/WINDOWS_TROUBLESHOOTING.md
@@ -1,259 +1,78 @@
-# Windows Troubleshooting Guide
-
-This guide addresses common Windows-specific issues in OpenWhispr.
+# Windows Troubleshooting
## Quick Fixes
-### Issue: "App starts but no window appears"
+### No Window Appears
-**Symptoms:**
-- OpenWhispr.exe runs in Task Manager, but no window shows up
-- You only see background processes or a tray icon
+**Symptoms:** OpenWhispr runs in Task Manager but no window shows
**Solutions:**
+1. Check system tray (click ^ caret) for OpenWhispr icon
+2. Run with debug: `OpenWhispr.exe --log-level=debug`
+3. Try disabling GPU: `OpenWhispr.exe --disable-gpu`
-1. **Check the system tray**
- - Click the ^ caret in the Windows tray
- - Look for the OpenWhispr icon
- - Click it to open the Control Panel
-
-2. **Start with debug logging**
- - Open Command Prompt in the install directory
- - Run: `OpenWhispr.exe --log-level=debug`
- - Check logs in: `%APPDATA%\OpenWhispr\logs`
-
-3. **Disable GPU acceleration**
- - Some Windows 11 builds have GPU/driver issues with Electron
- - Run: `OpenWhispr.exe --disable-gpu`
- - If that works, keep using the flag and report your GPU model
+### No Transcriptions
-### Issue: "No transcriptions" or "Audio file is empty"
-
-**Symptoms:**
-- Recording indicator shows, but no text appears
-- Error: "Audio file is empty"
-- Error: "Audio data too small"
+**Symptoms:** Recording works but no text appears
**Solutions:**
+1. Check microphone permissions: Settings โ†’ Privacy โ†’ Microphone
+2. Verify mic is selected: Sound settings โ†’ Input
+3. Test recording in Windows Voice Recorder first
-1. **Check Microphone Permissions**
- - Open Windows Settings โ†’ Privacy & Security โ†’ Microphone
- - Ensure "Microphone access" is ON
- - Ensure "Let apps access your microphone" is ON
- - Restart OpenWhispr
-
-2. **Verify Microphone Selection**
- - Right-click speaker icon in system tray
- - Select "Sound settings"
- - Under "Input", select your microphone
- - Test by speaking - the volume bar should move
- - Set volume to 70-100%
-
-3. **Test Recording**
- - Open Windows Voice Recorder
- - Record a short clip
- - If Voice Recorder works but OpenWhispr doesn't, enable debug mode (see below)
+### Python Not Found
-### Issue: "Python not found" or ENOENT error
-
-**Symptoms:**
-- Error: "spawn python ENOENT"
-- Error: "Python 3.x not found"
-- Transcription fails immediately
+**Symptoms:** "spawn python ENOENT" error
**Solutions:**
+1. Use OpenWhispr's built-in Python installer (Control Panel โ†’ Settings)
+2. Or install Python 3.11+ from [python.org](https://python.org) with "Add to PATH" checked
+3. Verify: `python --version` in Command Prompt
+4. Set custom path: `setx OPENWHISPR_PYTHON "C:\Path\To\python.exe"`
-1. **Install Python via OpenWhispr**
- - Open Control Panel (click OpenWhispr icon โ†’ Control Panel)
- - Go to Settings tab
- - Click "Install Python" button
- - Wait for installation to complete
- - Restart OpenWhispr
-
-2. **Use the isolated environment (recommended)**
- - OpenWhispr installs Whisper into a per-user virtual environment automatically
- - If you set `OPENWHISPR_PYTHON`, unset it and restart so the app can manage its own environment
-
-3. **Manual Python Installation**
- - Download Python 3.11+ from [python.org](https://www.python.org/downloads/)
- - **IMPORTANT**: Check "Add Python to PATH" during installation
- - Choose "Install for all users" if you have admin rights
- - After installation, restart your computer
- - Restart OpenWhispr
-
-4. **Verify Python Installation**
- - Open Command Prompt (Win + R, type `cmd`)
- - Type: `python --version`
- - Should show: `Python 3.x.x`
- - Type: `where python`
- - Should show path to python.exe
-
-5. **Set Python Path Manually**
- - Find your Python installation (usually `C:\Users\YourName\AppData\Local\Programs\Python\Python311\python.exe`)
- - Create/edit `.env` file in OpenWhispr directory
- - Add: `OPENWHISPR_PYTHON=C:\Path\To\Your\python.exe`
- - Restart OpenWhispr
-
-### Issue: "FFmpeg not found" or transcription fails silently
+### FFmpeg Issues
-**Symptoms:**
-- Recording completes but never transcribes
-- Error mentions FFmpeg
-- Local Whisper mode doesn't work
+**Symptoms:** Transcription fails silently
**Solutions:**
+1. Reinstall OpenWhispr (FFmpeg is bundled)
+2. Check antivirus isn't quarantining FFmpeg
+3. Install system FFmpeg and add to PATH if needed
-1. **Reinstall OpenWhispr**
- - Uninstall OpenWhispr completely
- - Download latest version
- - Install to default location
- - FFmpeg is bundled and should work automatically
+## Debug Mode
-2. **Install System FFmpeg** (if bundled version fails)
- - Download FFmpeg from [ffmpeg.org](https://ffmpeg.org/download.html#build-windows)
- - Extract to `C:\ffmpeg`
- - Add to PATH:
- - Open System Properties โ†’ Environment Variables
- - Edit "Path" variable
- - Add: `C:\ffmpeg\bin`
- - Restart OpenWhispr
-
-3. **Verify FFmpeg**
- - Open Command Prompt
- - Type: `ffmpeg -version`
- - Should show FFmpeg version info
-
-## Enable Debug Mode
-
-Debug mode creates detailed logs for troubleshooting:
-
-### Method 1: Command Line
```batch
-cd "C:\Users\YourName\AppData\Local\Programs\OpenWhispr"
+# Run with debug logging
OpenWhispr.exe --log-level=debug
-```
-### Method 2: Environment Variable
-```batch
-set OPENWHISPR_LOG_LEVEL=debug
-"C:\Users\YourName\AppData\Local\Programs\OpenWhispr\OpenWhispr.exe"
-```
-You can also set it in `%APPDATA%\OpenWhispr\.env`:
-```
+# Or set in .env file at %APPDATA%\OpenWhispr\.env
OPENWHISPR_LOG_LEVEL=debug
```
-Then restart OpenWhispr.
-
-### Find Debug Logs
-Logs are saved to: `%APPDATA%\OpenWhispr\logs\`
-
-To open:
-1. Press Win + R
-2. Type: `%APPDATA%\OpenWhispr\logs`
-3. Press Enter
-4. Open the most recent `debug-*.log` file
-
-## Common Error Messages Explained
-### "Audio buffer is empty - no audio data received"
-**Meaning:** The microphone didn't capture any audio data.
+Logs saved to: `%APPDATA%\OpenWhispr\logs\`
-**Fix:**
-- Check microphone is not muted
-- Check microphone permissions
-- Try a different microphone
-- Ensure no other app is blocking microphone access
+## Common Errors
-### "Python version check failed"
-**Meaning:** Python is installed but not responding correctly.
+| Error | Meaning | Fix |
+|-------|---------|-----|
+| Audio buffer empty | Mic not capturing | Check permissions, try different mic |
+| Python version check failed | Python not responding | Reinstall Python, check PATH |
+| FFmpeg not found | Can't find FFmpeg | Reinstall app, check antivirus |
+| Whisper installation failed | Can't install Whisper | Check Python, internet; try cloud mode |
-**Fix:**
-- Reinstall Python
-- Ensure Python is in PATH
-- Check Windows Defender isn't blocking Python
-- Run OpenWhispr as Administrator (temporarily)
+## Windows-Specific Tips
-### "FFmpeg not found at any location"
-**Meaning:** Cannot find FFmpeg executable.
+### Windows Defender
+Add OpenWhispr to exclusions if blocked:
+Settings โ†’ Virus & threat protection โ†’ Exclusions
-**Fix:**
-- Reinstall OpenWhispr to get bundled FFmpeg
-- Install FFmpeg separately (see above)
-- Check antivirus isn't quarantining FFmpeg
-
-### "Whisper installation failed"
-**Meaning:** Cannot install the Whisper AI package.
-
-**Fix:**
-- Ensure Python is installed correctly
-- Check internet connection
-- Install Microsoft Visual C++ Redistributable
-- Try Cloud mode instead (requires OpenAI API key)
-
-## Performance Tips
-
-### Slow Transcription
-- Use smaller Whisper model (tiny or base)
-- Enable GPU acceleration if you have NVIDIA GPU
-- Use Cloud mode for faster results
-- Close other apps while transcribing
-
-### High CPU Usage
-- Use "tiny" or "base" model instead of "large"
-- Enable Cloud mode
-- Reduce recording length
-
-## Windows-Specific Issues
-
-### Windows Defender Blocks
-If Windows Defender blocks OpenWhispr:
-1. Open Windows Security
-2. Go to Virus & threat protection
-3. Click "Manage settings"
-4. Add OpenWhispr to exclusions
-
-### Firewall Issues (Cloud Mode)
-If Cloud transcription fails:
-1. Open Windows Firewall settings
-2. Allow OpenWhispr through firewall
-3. Check your antivirus isn't blocking internet access
+### Firewall (Cloud Mode)
+Allow OpenWhispr through firewall for cloud transcription
### Permission Errors
-If you see "Access denied" errors:
-1. Right-click OpenWhispr shortcut
-2. Choose "Run as administrator"
-3. If it works, add permanent admin rights:
- - Right-click โ†’ Properties โ†’ Compatibility
- - Check "Run this program as administrator"
-
-## Getting Help
-
-If none of these solutions work:
+Right-click โ†’ Run as administrator (or set in Properties โ†’ Compatibility)
-1. **Collect Debug Logs**
- - Enable debug mode (see above)
- - Reproduce the issue
- - Locate log file in `%APPDATA%\OpenWhispr\logs`
-
-2. **Report Issue**
- - Go to: https://github.com/HeroTools/open-whispr/issues
- - Create new issue
- - Include:
- - Windows version (Win + R โ†’ `winver`)
- - OpenWhispr version (Help โ†’ About)
- - Debug log contents
- - Steps to reproduce
-
-3. **System Information**
- Helpful to include:
- - Python version: `python --version`
- - FFmpeg installed: `ffmpeg -version`
- - Microphone working: Test in Voice Recorder
- - Other dictation apps working: Try Windows built-in dictation
-
-## Registry Cleanup (Advanced)
-
-If you want to completely uninstall and start fresh:
+## Complete Reset
```batch
# Uninstall OpenWhispr first, then:
@@ -263,36 +82,10 @@ rd /s /q "%LOCALAPPDATA%\OpenWhispr"
Then reinstall.
-## Success Indicators
-
-OpenWhispr is working correctly when:
-- โœ“ Microphone indicator shows activity when speaking
-- โœ“ Recording stops cleanly when hotkey pressed
-- โœ“ Transcribed text appears within 5-10 seconds
-- โœ“ Text is pasted into active application
-- โœ“ No error messages appear
-
-## Notes for IT Administrators
-
-If deploying OpenWhispr in enterprise environment:
-
-1. **Python Installation**
- - Deploy Python 3.11+ system-wide
- - Add to system PATH
- - Install for all users
-
-2. **FFmpeg**
- - Include in application deployment
- - Whitelist in antivirus
- - Ensure ASAR unpacking works
-
-3. **Permissions**
- - Microphone access required
- - Internet access for Cloud mode
- - File write access to %APPDATA%
- - Registry read access for Python detection
+## Getting Help
-4. **Group Policy**
- - Allow microphone access
- - Don't block Python/FFmpeg executables
- - Allow network access if using Cloud mode
+Report issues at https://github.com/HeroTools/open-whispr/issues with:
+- Windows version (`winver`)
+- OpenWhispr version
+- Debug log contents
+- Steps to reproduce
diff --git a/package-lock.json b/package-lock.json
index b57955d19..d4149d6fc 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "open-whispr",
- "version": "1.0.15",
+ "version": "1.1.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "open-whispr",
- "version": "1.0.15",
+ "version": "1.1.0",
"hasInstallScript": true,
"license": "MIT",
"dependencies": {
diff --git a/package.json b/package.json
index bf1a42d98..d3223efb0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-whispr",
- "version": "1.0.15",
+ "version": "1.1.0",
"description": "A desktop dictation application using OpenAI Whisper for speech-to-text transcription",
"main": "main.js",
"private": true,