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: bump version + doc update
Gabriel Steinfa4e67726b60
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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### Addeddiff --git a/DEBUG.md b/DEBUG.mdindex 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 FailsLook 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 FailsLook 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 IssuesLook 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 LogsWhen 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.mdindex 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.mdindex 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 supportdiff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.mdindex 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 reproducediff --git a/WINDOWS_TROUBLESHOOTING.md b/WINDOWS_TROUBLESHOOTING.mdindex 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 loggingOpenWhispr.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\.envOPENWHISPR_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 reproducediff --git a/package-lock.json b/package-lock.jsonindex 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.jsonindex 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,