Skip to content

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

fix: Improve Windows Python discovery, user guidance, and docs for Local Whisper

Gabriel Stein95175a26831a
diff --git a/LOCAL_WHISPER_SETUP.md b/LOCAL_WHISPER_SETUP.md
index b5fd19e52..86eccacaa 100644
--- a/LOCAL_WHISPER_SETUP.md
+++ b/LOCAL_WHISPER_SETUP.md
@@ -159,10 +159,8 @@ If you see this status:
## 🔧 Advanced Configuration
### Custom Python Path
-If you need to use a specific Python installation:
-1. Edit `main.js`
-2. Modify the `findPythonExecutable()` function
-3. Add your Python path to the `possiblePaths` array
+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).
+The new detector also scans the Windows `py` launcher plus the usual install folders, so manual code edits are no longer required.
### Model Storage Location
Models are downloaded to `~/.cache/whisper/` by default.
@@ -195,4 +193,4 @@ The integration is complete and ready for production use. All files have been mo
- ✅ `src/App.jsx` - Enhanced with local/API switching
- ✅ `src/components/ControlPanel.tsx` - New Whisper settings UI
-Everything is ready to use! 🎉
\ No newline at end of file
+Everything is ready to use! 🎉
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index ca42d8d89..e87d818ed 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -60,4 +60,14 @@ If any of these look wrong (e.g., `x86_64` binaries on an Apple Silicon host), r
4. Delete `~/Library/Application Support/whisper` if partially downloaded models exist, then try again.
5. 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.
diff --git a/src/helpers/whisper.js b/src/helpers/whisper.js
index 5f63a75c4..818cc1766 100644
--- a/src/helpers/whisper.js
+++ b/src/helpers/whisper.js
@@ -335,6 +335,23 @@ class WhisperManager {
if (isResolved) return;
isResolved = true;
clearTimeout(timeout);
+
+ if (error.code === "ENOENT") {
+ const platformHelp =
+ process.platform === "win32"
+ ? 'Install Python 3.11+ from python.org with the "Install launcher" option, or set OPENWHISPR_PYTHON to the full path (for example C:\\\\Python312\\\\python.exe).'
+ : "Install Python 3.11+ (for example `brew install [email protected]`) or set OPENWHISPR_PYTHON to the interpreter you want OpenWhispr to use.";
+ const fallbackHelp =
+ "You can also disable Local Whisper or enable the OpenAI fallback in Settings to continue using cloud transcription.";
+ const message = [
+ "Local Whisper could not start because Python was not found on this system.",
+ platformHelp,
+ fallbackHelp,
+ ].join(" ");
+ reject(new Error(message));
+ return;
+ }
+
reject(new Error(`Whisper process error: ${error.message}`));
});
});
@@ -381,30 +398,62 @@ class WhisperManager {
}
async findPythonExecutable() {
- // Return cached result if available
if (this.pythonCmd) {
return this.pythonCmd;
}
- const possiblePaths = [
+ const candidateSet = new Set();
+ const addCandidate = (candidate) => {
+ if (!candidate || typeof candidate !== "string") {
+ return;
+ }
+ const sanitized = candidate.trim().replace(/^["']|["']$/g, "");
+ if (sanitized.length === 0) {
+ return;
+ }
+ candidateSet.add(sanitized);
+ };
+
+ if (process.env.OPENWHISPR_PYTHON) {
+ addCandidate(process.env.OPENWHISPR_PYTHON);
+ }
+
+ if (process.platform === "win32") {
+ this.getWindowsPythonCandidates().forEach(addCandidate);
+ }
+
+ const commonCandidates = [
+ "python3.12",
"python3.11",
+ "python3.10",
"python3",
"python",
+ "/usr/bin/python3.12",
"/usr/bin/python3.11",
+ "/usr/bin/python3.10",
"/usr/bin/python3",
+ "/usr/local/bin/python3.12",
"/usr/local/bin/python3.11",
+ "/usr/local/bin/python3.10",
"/usr/local/bin/python3",
+ "/opt/homebrew/bin/python3.12",
"/opt/homebrew/bin/python3.11",
+ "/opt/homebrew/bin/python3.10",
"/opt/homebrew/bin/python3",
"/usr/bin/python",
"/usr/local/bin/python",
];
+ commonCandidates.forEach(addCandidate);
+
+ for (const pythonPath of candidateSet) {
+ if (path.isAbsolute(pythonPath) && !fs.existsSync(pythonPath)) {
+ continue;
+ }
- for (const pythonPath of possiblePaths) {
try {
const version = await this.getPythonVersion(pythonPath);
if (this.isPythonVersionSupported(version)) {
- this.pythonCmd = pythonPath; // Cache the result
+ this.pythonCmd = pythonPath;
return pythonPath;
}
} catch (error) {
@@ -413,10 +462,59 @@ class WhisperManager {
}
throw new Error(
- "Python 3.x not found. Use installPython() to install it automatically."
+ 'Python 3.x not found. Click "Install Python" in Settings or set OPENWHISPR_PYTHON to a valid interpreter path.'
);
}
+ getWindowsPythonCandidates() {
+ const candidates = [];
+ const versionSuffixes = ["313", "312", "311", "310", "39", "38"];
+
+ const systemDrive = process.env.SystemDrive || "C:";
+ const windowsDir =
+ process.env.WINDIR || path.join(systemDrive, "Windows");
+
+ candidates.push("py");
+ candidates.push("py.exe");
+ candidates.push("python3");
+ candidates.push("python3.exe");
+ candidates.push("python");
+ candidates.push("python.exe");
+ candidates.push(path.join(windowsDir, "py.exe"));
+
+ const baseDirs = [];
+ if (process.env.LOCALAPPDATA) {
+ baseDirs.push(path.join(process.env.LOCALAPPDATA, "Programs", "Python"));
+ const windowsApps = path.join(
+ process.env.LOCALAPPDATA,
+ "Microsoft",
+ "WindowsApps"
+ );
+ candidates.push(path.join(windowsApps, "python.exe"));
+ candidates.push(path.join(windowsApps, "python3.exe"));
+ }
+ if (process.env.ProgramFiles) {
+ baseDirs.push(process.env.ProgramFiles);
+ }
+ if (process.env["ProgramFiles(x86)"]) {
+ baseDirs.push(process.env["ProgramFiles(x86)"]);
+ }
+ baseDirs.push(systemDrive);
+
+ for (const baseDir of baseDirs) {
+ if (!baseDir) {
+ continue;
+ }
+
+ for (const suffix of versionSuffixes) {
+ const folderName = `Python${suffix}`;
+ candidates.push(path.join(baseDir, folderName, "python.exe"));
+ }
+ }
+
+ return candidates;
+ }
+
async installPython(progressCallback = null) {
try {
// Clear cached Python command since we're installing new one