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 macOS mic onboarding by detecting missing inputs and deep-linking to sound/privacy settings

Gabriel Stein7c855ef519e2
diff --git a/preload.js b/preload.js
index 485c36dde..588704ac9 100644
--- a/preload.js
+++ b/preload.js
@@ -148,6 +148,11 @@ contextBridge.exposeInMainWorld("electronAPI", {
logReasoning: (stage, details) =>
ipcRenderer.invoke("log-reasoning", stage, details),
+ // System settings helpers
+ openMicrophoneSettings: () => ipcRenderer.invoke("open-microphone-settings"),
+ openSoundInputSettings: () =>
+ ipcRenderer.invoke("open-sound-input-settings"),
+
// Remove all listeners for a channel
removeAllListeners: (channel) => {
ipcRenderer.removeAllListeners(channel);
diff --git a/src/components/OnboardingFlow.tsx b/src/components/OnboardingFlow.tsx
index 7ebaa8e2b..471182d84 100644
--- a/src/components/OnboardingFlow.tsx
+++ b/src/components/OnboardingFlow.tsx
@@ -780,6 +780,31 @@ export default function OnboardingFlow({ onComplete }: OnboardingFlowProps) {
buttonText="Grant Access"
/>
+ {!permissionsHook.micPermissionGranted && (
+ <div className="rounded-lg border border-amber-200 bg-amber-50 p-4 space-y-3">
+ <p className="text-sm text-amber-900">
+ {permissionsHook.micPermissionError ||
+ "If the prompt doesn’t appear, open Sound settings, select your microphone, then try Grant Access again."}
+ </p>
+ <div className="flex flex-wrap gap-2">
+ <Button
+ variant="outline"
+ size="sm"
+ onClick={permissionsHook.openSoundInputSettings}
+ >
+ Open Sound Input Settings
+ </Button>
+ <Button
+ variant="outline"
+ size="sm"
+ onClick={permissionsHook.openMicPrivacySettings}
+ >
+ Open Microphone Privacy
+ </Button>
+ </div>
+ </div>
+ )}
+
<PermissionCard
icon={Shield}
title="Accessibility Permission"
diff --git a/src/components/SettingsPage.tsx b/src/components/SettingsPage.tsx
index 8103ba4db..352ac2ca5 100644
--- a/src/components/SettingsPage.tsx
+++ b/src/components/SettingsPage.tsx
@@ -770,6 +770,30 @@ export default function SettingsPage({
<span className="mr-2">⚙️</span>
Fix Permission Issues
</Button>
+ {!permissionsHook.micPermissionGranted && (
+ <div className="rounded-lg border border-amber-200 bg-amber-50 p-4 space-y-3">
+ <p className="text-sm text-amber-900">
+ {permissionsHook.micPermissionError ||
+ "If macOS never shows the microphone prompt, open Sound settings, pick your microphone, then try the test again."}
+ </p>
+ <div className="flex flex-wrap gap-2">
+ <Button
+ variant="outline"
+ size="sm"
+ onClick={permissionsHook.openSoundInputSettings}
+ >
+ Open Sound Input Settings
+ </Button>
+ <Button
+ variant="outline"
+ size="sm"
+ onClick={permissionsHook.openMicPrivacySettings}
+ >
+ Open Microphone Privacy
+ </Button>
+ </div>
+ </div>
+ )}
</div>
</div>
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 3a22ea01e..7ab046255 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -1,7 +1,42 @@
const { ipcMain, app, shell, BrowserWindow } = require("electron");
+const { spawn } = require("child_process");
const AppUtils = require("../utils");
const debugLogger = require("./debugLogger");
+const runDetachedCommand = (command, args = []) => {
+ try {
+ const child = spawn(command, args, {
+ detached: true,
+ stdio: "ignore",
+ });
+ if (typeof child.unref === "function") {
+ child.unref();
+ }
+ return true;
+ } catch (error) {
+ debugLogger.error(`Failed to run ${command}`, error);
+ return false;
+ }
+};
+
+const openMacPreference = (urls = []) => {
+ for (const url of urls) {
+ if (runDetachedCommand("open", [url])) {
+ return true;
+ }
+ }
+ return runDetachedCommand("open", ["-a", "System Settings"]);
+};
+
+const openLinuxSettings = (commands = []) => {
+ for (const [command, args] of commands) {
+ if (runDetachedCommand(command, args)) {
+ return true;
+ }
+ }
+ return false;
+};
+
class IPCHandlers {
constructor(managers) {
this.environmentManager = managers.environmentManager;
@@ -132,6 +167,14 @@ class IPCHandlers {
return this.clipboardManager.writeClipboard(text);
});
+ ipcMain.handle("open-microphone-settings", async () => {
+ return this.openPlatformSettings("microphone");
+ });
+
+ ipcMain.handle("open-sound-input-settings", async () => {
+ return this.openPlatformSettings("soundInput");
+ });
+
// Whisper handlers
ipcMain.handle(
"transcribe-local-whisper",
@@ -521,6 +564,59 @@ class IPCHandlers {
});
}
+ openPlatformSettings(target) {
+ if (process.platform === "darwin") {
+ const urls =
+ target === "microphone"
+ ? [
+ "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone",
+ "x-apple.systempreferences:com.apple.preference.security",
+ ]
+ : [
+ "x-apple.systempreferences:com.apple.preference.sound?input",
+ "x-apple.systempreferences:com.apple.preference.sound",
+ ];
+ openMacPreference(urls);
+ return { success: true };
+ }
+
+ if (process.platform === "win32") {
+ const uri =
+ target === "microphone"
+ ? "ms-settings:privacy-microphone"
+ : "ms-settings:sound";
+ try {
+ shell.openExternal(uri);
+ return { success: true };
+ } catch (error) {
+ debugLogger.error("Failed to open Windows settings", error);
+ return { success: false, error: error.message };
+ }
+ }
+
+ const linuxCommands =
+ target === "microphone"
+ ? [
+ ["xdg-open", ["gnome-control-center", "privacy"]],
+ ["gnome-control-center", ["privacy"]],
+ ]
+ : [
+ ["xdg-open", ["gnome-control-center", "sound"]],
+ ["gnome-control-center", ["sound"]],
+ ];
+
+ if (openLinuxSettings(linuxCommands)) {
+ return { success: true };
+ }
+
+ const fallbackMessage =
+ target === "microphone"
+ ? "Open your system privacy settings to enable microphone access."
+ : "Open your system sound settings and select your microphone.";
+
+ return { success: false, error: fallbackMessage };
+ }
+
broadcastToWindows(channel, payload) {
const windows = BrowserWindow.getAllWindows();
windows.forEach((win) => {
diff --git a/src/hooks/usePermissions.ts b/src/hooks/usePermissions.ts
index 3a7849441..77027cb55 100644
--- a/src/hooks/usePermissions.ts
+++ b/src/hooks/usePermissions.ts
@@ -4,9 +4,12 @@ export interface UsePermissionsReturn {
// State
micPermissionGranted: boolean;
accessibilityPermissionGranted: boolean;
+ micPermissionError: string | null;
requestMicPermission: () => Promise<void>;
testAccessibilityPermission: () => Promise<void>;
+ openMicPrivacySettings: () => Promise<void>;
+ openSoundInputSettings: () => Promise<void>;
setMicPermissionGranted: (granted: boolean) => void;
setAccessibilityPermissionGranted: (granted: boolean) => void;
}
@@ -15,27 +18,128 @@ export interface UsePermissionsProps {
showAlertDialog: (dialog: { title: string; description?: string }) => void;
}
+const DEFAULT_MIC_MESSAGE =
+ "If nothing pops up, open System Settings → Sound → Input, choose your microphone, then click Grant Access again.";
+
+const stopTracks = (stream?: MediaStream) => {
+ try {
+ stream?.getTracks?.().forEach((track) => track.stop());
+ } catch (error) {
+ // ignore track cleanup errors
+ }
+};
+
+const describeMicError = (error: any): string => {
+ if (!error) {
+ return DEFAULT_MIC_MESSAGE;
+ }
+
+ const name = error?.name || "";
+ const message = (error?.message || "").toLowerCase();
+
+ if (name === "NotFoundError") {
+ return "No microphones were detected. Connect or select a microphone in System Settings → Sound → Input.";
+ }
+
+ if (name === "NotAllowedError" || name === "SecurityError") {
+ return "Permission was denied. Open System Settings → Privacy & Security → Microphone and allow OpenWhispr.";
+ }
+
+ if (name === "NotReadableError" || name === "AbortError") {
+ return "macOS could not start the selected microphone. Choose an input device in System Settings → Sound → Input, then rerun the test.";
+ }
+
+ if (message.includes("no audio input") || message.includes("not available")) {
+ return "No active audio input was found. Pick a microphone in System Settings → Sound → Input.";
+ }
+
+ return `Microphone access failed: ${error?.message || "Unknown error"}. Select a different input device and try again.`;
+};
+
export const usePermissions = (
showAlertDialog?: UsePermissionsProps["showAlertDialog"]
): UsePermissionsReturn => {
const [micPermissionGranted, setMicPermissionGranted] = useState(false);
+ const [micPermissionError, setMicPermissionError] = useState<string | null>(
+ null
+ );
const [accessibilityPermissionGranted, setAccessibilityPermissionGranted] =
useState(false);
+ const openMicPrivacySettings = useCallback(async () => {
+ try {
+ await window.electronAPI?.openMicrophoneSettings?.();
+ } catch (error) {
+ console.error("Failed to open microphone privacy settings:", error);
+ }
+ }, []);
+
+ const openSoundInputSettings = useCallback(async () => {
+ try {
+ await window.electronAPI?.openSoundInputSettings?.();
+ } catch (error) {
+ console.error("Failed to open sound input settings:", error);
+ }
+ }, []);
+
const requestMicPermission = useCallback(async () => {
+ if (
+ !navigator?.mediaDevices ||
+ typeof navigator.mediaDevices.getUserMedia !== "function"
+ ) {
+ const message =
+ "Microphone APIs are unavailable in this environment. Please restart the app.";
+ setMicPermissionError(message);
+ if (showAlertDialog) {
+ showAlertDialog({
+ title: "Microphone Unavailable",
+ description: message,
+ });
+ } else {
+ alert(message);
+ }
+ return;
+ }
+
+ setMicPermissionError(null);
+
try {
- await navigator.mediaDevices.getUserMedia({ audio: true });
+ if (typeof navigator.mediaDevices.enumerateDevices === "function") {
+ const devices = await navigator.mediaDevices.enumerateDevices();
+ const audioInputs = devices.filter(
+ (device) => device.kind === "audioinput"
+ );
+ if (audioInputs.length === 0) {
+ const message =
+ "No microphones were found. Connect or select a microphone in System Settings → Sound → Input.";
+ setMicPermissionError(message);
+ if (showAlertDialog) {
+ showAlertDialog({
+ title: "No Microphone Detected",
+ description: message,
+ });
+ } else {
+ alert(message);
+ }
+ return;
+ }
+ }
+
+ const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+ stopTracks(stream);
setMicPermissionGranted(true);
+ setMicPermissionError(null);
} catch (err) {
console.error("Microphone permission denied:", err);
+ const message = describeMicError(err);
+ setMicPermissionError(message);
if (showAlertDialog) {
showAlertDialog({
title: "Microphone Permission Required",
- description:
- "Please grant microphone permissions to use voice dictation.",
+ description: message,
});
} else {
- alert("Please grant microphone permissions to use voice dictation.");
+ alert(message);
}
}
}, [showAlertDialog]);
@@ -74,8 +178,11 @@ export const usePermissions = (
return {
micPermissionGranted,
accessibilityPermissionGranted,
+ micPermissionError,
requestMicPermission,
testAccessibilityPermission,
+ openMicPrivacySettings,
+ openSoundInputSettings,
setMicPermissionGranted,
setAccessibilityPermissionGranted,
};
diff --git a/src/types/electron.ts b/src/types/electron.ts
index 7b215bccf..3d8acc298 100644
--- a/src/types/electron.ts
+++ b/src/types/electron.ts
@@ -270,6 +270,10 @@ declare global {
// FFmpeg availability
checkFFmpegAvailability: () => Promise<boolean>;
+
+ // System settings helpers
+ openMicrophoneSettings?: () => Promise<{ success: boolean; error?: string }>;
+ openSoundInputSettings?: () => Promise<{ success: boolean; error?: string }>;
};
api?: {