Skip to content

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

chore: docs update

Gabriel Stein1c49b43b311b
diff --git a/CLAUDE.md b/CLAUDE.md
index 9ceb4bbbf..a18b72030 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -307,7 +307,8 @@ Enable with `--log-level=debug` or `OPENWHISPR_LOG_LEVEL=debug` (can be set in `
- Use `npm run pack` for unsigned builds (CSC_IDENTITY_AUTO_DISCOVERY=false)
- Signing requires Apple Developer account
- ASAR unpacking needed for FFmpeg
- - Run `npm run download:whisper-cpp` before packaging
+ - Run `npm run download:whisper-cpp` before packaging (current platform)
+ - Use `npm run download:whisper-cpp:all` for multi-platform packaging
- afterSign.js automatically skips signing when CSC_IDENTITY_AUTO_DISCOVERY=false
### Platform-Specific Notes
diff --git a/LOCAL_WHISPER_SETUP.md b/LOCAL_WHISPER_SETUP.md
index e2ebb62c0..fe59acb0e 100644
--- a/LOCAL_WHISPER_SETUP.md
+++ b/LOCAL_WHISPER_SETUP.md
@@ -34,7 +34,21 @@ OpenWhispr uses whisper.cpp, a high-performance C++ implementation of OpenAI's W
- **Disk Space**: 75MB–3GB depending on model
- **RAM**: 1GB–10GB depending on model
-- **No additional dependencies required** - whisper.cpp is bundled
+- **No additional dependencies required** - whisper.cpp is bundled in packaged builds
+
+## Running From Source
+
+If you're running OpenWhispr locally from a git checkout (not a packaged app), download the whisper.cpp binary for your current platform:
+
+```bash
+npm run download:whisper-cpp
+```
+
+This puts the binary in `resources/bin/`. For multi-platform packaging from a single machine, use:
+
+```bash
+npm run download:whisper-cpp:all
+```
## File Locations
diff --git a/README.md b/README.md
index d205965e6..f1b0d26d0 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,12 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
npm start # Production mode
```
+5. **Optional: Local Whisper from source** (only needed if you want local processing):
+ ```bash
+ npm run download:whisper-cpp
+ ```
+ This downloads the whisper.cpp binary for your current platform into `resources/bin/`.
+
### Building for Personal Use (Optional)
If you want to build a standalone app for personal use:
@@ -329,6 +335,8 @@ open-whispr/
- `npm run start` - Start production build
- `npm run setup` - First-time setup (creates .env file)
- `npm run build:renderer` - Build the React app only
+- `npm run download:whisper-cpp` - Download whisper.cpp for the current platform
+- `npm run download:whisper-cpp:all` - Download whisper.cpp for all platforms
- `npm run build` - Full build with signing (requires certificates)
- `npm run build:mac` - macOS build with signing
- `npm run build:win` - Windows build with signing
@@ -378,6 +386,8 @@ npm run build:win # Windows NSIS + Portable
npm run build:linux # AppImage + DEB
```
+Note: build/pack/dist scripts download whisper.cpp for the current platform automatically. For multi-platform packaging from one host, run `npm run download:whisper-cpp:all` first.
+
## Configuration
### Environment Variables
@@ -416,6 +426,8 @@ For local processing, OpenWhispr uses OpenAI's Whisper model via whisper.cpp - a
- macOS: `brew install whisper-cpp`
- Linux: Build from source at https://github.com/ggml-org/whisper.cpp
+**From Source**: When running locally (not a packaged build), download the binary with `npm run download:whisper-cpp` so `resources/bin/` has your platform executable.
+
**Requirements**:
- Sufficient disk space for models (75MB - 3GB depending on model)
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index 2fae01aca..b7db6ce6f 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -76,11 +76,12 @@
**Fix:**
1. The whisper.cpp binary is bundled with the app
-2. If bundled binary fails, install via package manager:
+2. If running from source, download the current-platform binary: `npm run download:whisper-cpp`
+3. If bundled binary fails, install via package manager:
- macOS: `brew install whisper-cpp`
- Linux: Build from source at https://github.com/ggml-org/whisper.cpp
-3. Clear model cache: `rm -rf ~/.cache/openwhispr/whisper-models`
-4. Try cloud transcription as fallback
+4. Clear model cache: `rm -rf ~/.cache/openwhispr/whisper-models`
+5. Try cloud transcription as fallback
### Windows-Specific Issues
diff --git a/WINDOWS_TROUBLESHOOTING.md b/WINDOWS_TROUBLESHOOTING.md
index 49eb84987..37f0e7e38 100644
--- a/WINDOWS_TROUBLESHOOTING.md
+++ b/WINDOWS_TROUBLESHOOTING.md
@@ -26,9 +26,10 @@
**Solutions:**
1. whisper.cpp is bundled with the app - try reinstalling
-2. Check antivirus isn't blocking the whisper-cpp executable
-3. Clear model cache: delete `%USERPROFILE%\.cache\openwhispr\whisper-models`
-4. Try cloud mode as fallback
+2. If running from source, run `npm run download:whisper-cpp` and confirm `resources\\bin\\whisper-cpp-win32-x64.exe` exists
+3. Check antivirus isn't blocking the whisper-cpp executable
+4. Clear model cache: delete `%USERPROFILE%\.cache\openwhispr\whisper-models`
+5. Try cloud mode as fallback
### FFmpeg Issues