Skip to content

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

fix(linux): improve KDE hotkey reliability and fix GNOME Wayland shortcuts

Haz522bf4f16c1d
diff --git a/src/components/OnboardingFlow.tsx b/src/components/OnboardingFlow.tsx
index 9d8586902..7d7f107d8 100644
--- a/src/components/OnboardingFlow.tsx
+++ b/src/components/OnboardingFlow.tsx
@@ -155,6 +155,17 @@ export default function OnboardingFlow({ onComplete }: OnboardingFlowProps) {
checkHotkeyMode();
}, [setActivationMode]);
+ // Update wizard state when backend falls back to a different hotkey
+ useEffect(() => {
+ const unsubscribe = window.electronAPI?.onHotkeyFallbackUsed?.((data: { fallback: string }) => {
+ if (data?.fallback) {
+ setHotkey(data.fallback);
+ setDictationKey(data.fallback);
+ }
+ });
+ return () => unsubscribe?.();
+ }, [setDictationKey]);
+
useEffect(() => {
const modelToCheck = localTranscriptionProvider === "nvidia" ? parakeetModel : whisperModel;
if (!useLocalWhisper || !modelToCheck) {
@@ -199,6 +210,14 @@ export default function OnboardingFlow({ onComplete }: OnboardingFlowProps) {
hotkeyStepInitializedRef.current = true;
try {
+ // Check if backend already registered a hotkey (e.g., KDE D-Bus fallback)
+ const backendKey = localStorage.getItem("dictationKey");
+ if (backendKey && backendKey.trim() !== "") {
+ setHotkey(backendKey);
+ setDictationKey(backendKey);
+ return;
+ }
+
// Get platform-appropriate default hotkey
const defaultHotkey = getDefaultHotkey();
const platform = window.electronAPI?.getPlatform?.() ?? "darwin";
diff --git a/src/helpers/hotkeyManager.js b/src/helpers/hotkeyManager.js
index a2a8119ef..4722af5a0 100644
--- a/src/helpers/hotkeyManager.js
+++ b/src/helpers/hotkeyManager.js
@@ -1,4 +1,4 @@
-const { globalShortcut } = require("electron");
+const { globalShortcut, dialog } = require("electron");
const debugLogger = require("./debugLogger");
const GnomeShortcutManager = require("./gnomeShortcut");
const HyprlandShortcutManager = require("./hyprlandShortcut");
@@ -8,6 +8,12 @@ const { i18nMain } = require("./i18nMain");
// Delay to ensure localStorage is accessible after window load
const HOTKEY_REGISTRATION_DELAY_MS = 1000;
+// KDE registration failure reasons for user-facing messages
+const KDE_FAILURE_REASONS = {
+ "conflict": (hotkey) => `Hotkey "${hotkey}" is already used by another application.`,
+ "modifier-only": (hotkey) => `Hotkey "${hotkey}" contains only modifier keys and cannot be used on X11. Add a regular key (e.g. Control+Super+Space).`,
+};
+
// Right-side single modifiers are handled by native listeners, not globalShortcut
const RIGHT_SIDE_MODIFIER_PATTERN =
/^Right(Control|Ctrl|Alt|Option|Shift|Command|Cmd|Super|Meta|Win)$/i;
@@ -188,21 +194,20 @@ class HotkeyManager {
return { success: true, hotkey };
}
- // On KDE Wayland, route all slots through KGlobalAccel D-Bus
+ // On KDE (X11 or Wayland), route all slots through KGlobalAccel D-Bus
if (this.useKDE && this.kdeManager) {
if (slotName === "agent") {
this.kdeManager.setAgentCallback(callback);
}
- const success = await this.kdeManager.registerKeybinding(hotkey, slotName, callback);
- if (!success) {
+ const result = await this.kdeManager.registerKeybinding(hotkey, slotName, callback);
+ if (result !== true) {
+ const reason = KDE_FAILURE_REASONS[result]?.(hotkey) || `Failed to register KDE hotkey "${hotkey}" for ${slotName}`;
debugLogger.log(
- `[HotkeyManager] KDE keybinding registration failed for slot "${slotName}" ("${hotkey}")`
+ `[HotkeyManager] KDE keybinding registration failed for slot "${slotName}" ("${hotkey}")`,
+ { reason: result }
);
- return {
- success: false,
- error: `Failed to register KDE hotkey "${hotkey}" for ${slotName}`,
- };
+ return { success: false, error: reason };
}
const slot = this.slots.get(slotName) || { hotkey: null, callback: null, accelerator: null };
@@ -483,7 +488,6 @@ class HotkeyManager {
async initializeKDEShortcuts(callback) {
if (
process.platform !== "linux" ||
- !KDEShortcutManager.isWayland() ||
!KDEShortcutManager.isKDE()
) {
return false;
@@ -495,7 +499,7 @@ class HotkeyManager {
if (ok) {
this.useKDE = true;
this.hotkeyCallback = callback;
- debugLogger.log("[HotkeyManager] KDE Wayland shortcuts initialized via KGlobalAccel D-Bus");
+ debugLogger.log("[HotkeyManager] KDE shortcuts initialized via KGlobalAccel D-Bus");
return true;
}
} catch (err) {
@@ -559,9 +563,11 @@ class HotkeyManager {
this.mainWindow = mainWindow;
this.hotkeyCallback = callback;
- // On XWayland, skip D-Bus shortcut managers — globalShortcut works via X11.
- const isXWayland = process.argv.includes("--ozone-platform=x11");
- if (process.platform === "linux" && GnomeShortcutManager.isWayland() && !isXWayland) {
+ // On Wayland, use native D-Bus shortcut managers (GNOME gsettings, Hyprland hyprctl).
+ // These work regardless of XWayland mode because they use session D-Bus, not X11 grabs.
+ // globalShortcut (XGrabKey) does NOT work globally on GNOME Wayland even under XWayland
+ // (Mutter doesn't forward X11 grabs to XWayland), so native managers are required.
+ if (process.platform === "linux" && GnomeShortcutManager.isWayland()) {
const gnomeOk = await this.initializeGnomeShortcuts(callback);
if (gnomeOk) {
@@ -597,81 +603,111 @@ class HotkeyManager {
return;
}
- // Try KDE native shortcuts via KGlobalAccel
- const kdeOk = await this.initializeKDEShortcuts(callback);
+ // Try Hyprland native shortcuts if GNOME path was not applicable
+ const hyprlandOk = await this.initializeHyprlandShortcuts(callback);
- if (kdeOk) {
- const registerKDEHotkey = async () => {
+ if (hyprlandOk) {
+ const registerHyprlandHotkey = async () => {
try {
const savedHotkey = await mainWindow.webContents.executeJavaScript(`
localStorage.getItem("dictationKey") || ""
`);
const hotkey = savedHotkey && savedHotkey.trim() !== "" ? savedHotkey : "Control+Super";
- const success = await this.kdeManager.registerKeybinding(hotkey, "dictation", callback);
+
+ const success = await this.hyprlandManager.registerKeybinding(hotkey);
if (success) {
this.currentHotkey = hotkey;
- debugLogger.log(`[HotkeyManager] KDE hotkey "${hotkey}" registered successfully`);
+ debugLogger.log(
+ `[HotkeyManager] Hyprland hotkey "${hotkey}" registered successfully`
+ );
} else {
debugLogger.log(
- "[HotkeyManager] KDE keybinding failed, falling back to globalShortcut"
+ "[HotkeyManager] Hyprland keybinding failed, falling back to globalShortcut"
);
- this.kdeManager.close();
- this.kdeManager = null;
- this.useKDE = false;
+ this.useHyprland = false;
this.loadSavedHotkeyOrDefault(mainWindow, callback);
}
} catch (err) {
debugLogger.log(
- "[HotkeyManager] KDE keybinding failed, falling back to globalShortcut:",
+ "[HotkeyManager] Hyprland keybinding failed, falling back to globalShortcut:",
err.message
);
- this.kdeManager?.close();
- this.kdeManager = null;
- this.useKDE = false;
+ this.useHyprland = false;
this.loadSavedHotkeyOrDefault(mainWindow, callback);
}
};
- setTimeout(registerKDEHotkey, HOTKEY_REGISTRATION_DELAY_MS);
+ setTimeout(registerHyprlandHotkey, HOTKEY_REGISTRATION_DELAY_MS);
this.isInitialized = true;
return;
}
+ }
+ // Falls through to KDE or globalShortcut below when GNOME/Hyprland are not applicable
- // Try Hyprland native shortcuts if GNOME/KDE paths were not applicable
- const hyprlandOk = await this.initializeHyprlandShortcuts(callback);
+ // Try KDE native shortcuts on any KDE session (X11 or Wayland)
+ if (process.platform === "linux" && KDEShortcutManager.isKDE()) {
+ const kdeOk = await this.initializeKDEShortcuts(callback);
- if (hyprlandOk) {
- const registerHyprlandHotkey = async () => {
+ if (kdeOk) {
+ const registerKDEHotkey = async () => {
try {
const savedHotkey = await mainWindow.webContents.executeJavaScript(`
localStorage.getItem("dictationKey") || ""
`);
const hotkey = savedHotkey && savedHotkey.trim() !== "" ? savedHotkey : "Control+Super";
-
- const success = await this.hyprlandManager.registerKeybinding(hotkey);
- if (success) {
+ const result = await this.kdeManager.registerKeybinding(hotkey, "dictation", callback);
+ if (result === true) {
this.currentHotkey = hotkey;
+ debugLogger.log(`[HotkeyManager] KDE hotkey "${hotkey}" registered successfully`);
+ } else if (result === "conflict" || result === "modifier-only") {
debugLogger.log(
- `[HotkeyManager] Hyprland hotkey "${hotkey}" registered successfully`
+ `[HotkeyManager] KDE keybinding ${result} for "${hotkey}", trying fallbacks via KDE D-Bus...`
);
+ const fallbacks = ["F8", "F9", "Control+Shift+Space"];
+ let fallbackRegistered = false;
+ for (const fallback of fallbacks) {
+ const fbResult = await this.kdeManager.registerKeybinding(fallback, "dictation", callback);
+ if (fbResult === true) {
+ this.currentHotkey = fallback;
+ debugLogger.log(`[HotkeyManager] KDE fallback hotkey "${fallback}" registered successfully`);
+ await this.saveHotkeyToRenderer(fallback);
+ this.notifyHotkeyFallback(hotkey, fallback);
+ fallbackRegistered = true;
+ break;
+ }
+ }
+ if (!fallbackRegistered) {
+ debugLogger.log("[HotkeyManager] All KDE fallback hotkeys failed");
+ this.currentHotkey = hotkey;
+ dialog.showMessageBox({
+ type: "warning",
+ title: "Hotkey Unavailable",
+ message: `Could not register any hotkey via KDE shortcuts.`,
+ detail: "Open OpenWhispr Settings → Hotkeys to choose a different shortcut.",
+ });
+ }
} else {
debugLogger.log(
- "[HotkeyManager] Hyprland keybinding failed, falling back to globalShortcut"
+ "[HotkeyManager] KDE keybinding failed, falling back to globalShortcut"
);
- this.useHyprland = false;
+ this.kdeManager.close();
+ this.kdeManager = null;
+ this.useKDE = false;
this.loadSavedHotkeyOrDefault(mainWindow, callback);
}
} catch (err) {
debugLogger.log(
- "[HotkeyManager] Hyprland keybinding failed, falling back to globalShortcut:",
+ "[HotkeyManager] KDE keybinding failed, falling back to globalShortcut:",
err.message
);
- this.useHyprland = false;
+ this.kdeManager?.close();
+ this.kdeManager = null;
+ this.useKDE = false;
this.loadSavedHotkeyOrDefault(mainWindow, callback);
}
};
- setTimeout(registerHyprlandHotkey, HOTKEY_REGISTRATION_DELAY_MS);
+ setTimeout(registerKDEHotkey, HOTKEY_REGISTRATION_DELAY_MS);
this.isInitialized = true;
return;
}
@@ -885,12 +921,11 @@ class HotkeyManager {
if (this.useKDE && this.kdeManager) {
debugLogger.log(`[HotkeyManager] Updating KDE hotkey to "${hotkey}"`);
- const success = await this.kdeManager.registerKeybinding(hotkey, "dictation", callback);
- if (!success) {
- return {
- success: false,
- message: `Failed to update KDE hotkey to "${hotkey}". Check the format is valid.`,
- };
+ await this.kdeManager.unregisterKeybinding("dictation");
+ const result = await this.kdeManager.registerKeybinding(hotkey, "dictation", callback);
+ if (result !== true) {
+ const reason = KDE_FAILURE_REASONS[result]?.(hotkey) || `Failed to update KDE hotkey to "${hotkey}". Check the format is valid.`;
+ return { success: false, message: reason };
}
this.currentHotkey = hotkey;
const saved = await this.saveHotkeyToRenderer(hotkey);
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index de595f725..d83c3de92 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -1623,9 +1623,19 @@ class IPCHandlers {
debugLogger.warn("[IPC] Failed to unregister Hyprland keybinding:", err.message);
});
}
+
+ // On KDE (X11 or Wayland), unregister the keybinding during capture
+ if (hotkeyManager.isUsingKDE() && hotkeyManager.kdeManager) {
+ debugLogger.log("[IPC] Unregistering KDE keybinding for hotkey capture mode");
+ await hotkeyManager.kdeManager.unregisterKeybinding().catch((err) => {
+ debugLogger.warn("[IPC] Failed to unregister KDE keybinding:", err.message);
+ });
+ }
} else {
// Exiting capture mode - re-register globalShortcut if not already registered
- if (effectiveHotkey && !usesNativeListener(effectiveHotkey)) {
+ // Skip for KDE/GNOME/Hyprland — updateHotkey handles re-registration via native path
+ const usesNativePath = hotkeyManager.isUsingKDE() || hotkeyManager.isUsingGnome() || hotkeyManager.isUsingHyprland();
+ if (effectiveHotkey && !usesNativeListener(effectiveHotkey) && !usesNativePath) {
const { globalShortcut } = require("electron");
const accelerator = effectiveHotkey.startsWith("Fn+")
? effectiveHotkey.slice(3)
@@ -1685,6 +1695,18 @@ class IPCHandlers {
hotkeyManager.currentHotkey = effectiveHotkey;
}
}
+
+ // On KDE (X11 or Wayland), re-register the keybinding with the effective hotkey
+ if (hotkeyManager.isUsingKDE() && hotkeyManager.kdeManager && effectiveHotkey) {
+ debugLogger.log(
+ `[IPC] Re-registering KDE keybinding "${effectiveHotkey}" after capture mode`
+ );
+ const callback = this.windowManager.createHotkeyCallback();
+ const result = await hotkeyManager.kdeManager.registerKeybinding(effectiveHotkey, "dictation", callback);
+ if (result === true) {
+ hotkeyManager.currentHotkey = effectiveHotkey;
+ }
+ }
}
return { success: true };
diff --git a/src/helpers/kdeShortcut.js b/src/helpers/kdeShortcut.js
index 7c53e4c5d..9538d8056 100644
--- a/src/helpers/kdeShortcut.js
+++ b/src/helpers/kdeShortcut.js
@@ -216,14 +216,77 @@ class KDEShortcutManager {
return false;
}
+ // Modifier-only shortcuts (e.g. Control+Super) don't work on X11 —
+ // XGrabKey requires an actual key code, not just modifiers.
+ // On Wayland, KWin handles modifier-only natively, so allow them.
+ const QT_MODIFIER_MASK = 0xFE000000;
+ if (!KDEShortcutManager.isWayland() && (qtKey & ~QT_MODIFIER_MASK) === 0) {
+ debugLogger.log("[KDEShortcut] Modifier-only shortcut not supported on X11", {
+ slot: slotName,
+ hotkey: electronHotkey,
+ qtKey: `0x${qtKey.toString(16)}`,
+ });
+ return "modifier-only";
+ }
+
// actionId: [componentUnique, actionUnique, componentFriendly, actionFriendly]
const actionId = [COMPONENT_NAME, slotName, "OpenWhispr", `OpenWhispr ${slotName}`];
try {
- // Flag 0: always overwrite. 0x02 keeps stale saved values that
- // silently prevent the hotkey from firing on startup.
+ // Pre-registration conflict check: query if another component already owns this key.
+ // We use a low-level D-Bus call because dbus-next proxy can't marshal the 'ai'
+ // signature correctly (it receives a number instead of an array).
+ try {
+ const dbusModule = getDBus();
+ const msg = new dbusModule.Message({
+ destination: "org.kde.kglobalaccel",
+ path: "/kglobalaccel",
+ interface: "org.kde.KGlobalAccel",
+ member: "globalShortcutsByKey",
+ signature: "aii",
+ body: [[qtKey], 0],
+ });
+ const reply = await this.bus.call(msg);
+ const owners = reply.body?.[0];
+ if (Array.isArray(owners) && owners.length > 0) {
+ const otherOwners = owners.filter(
+ (aid) => Array.isArray(aid) && aid[0] !== COMPONENT_NAME
+ );
+ if (otherOwners.length > 0) {
+ debugLogger.log("[KDEShortcut] Shortcut conflict — key owned by another component", {
+ slot: slotName,
+ hotkey: electronHotkey,
+ owners: otherOwners.map((a) => a[0]),
+ });
+ return "conflict";
+ }
+ }
+ } catch (checkErr) {
+ // globalShortcutsByKey may not exist on older KDE — proceed without check
+ debugLogger.log("[KDEShortcut] Could not check for conflicts, proceeding:", checkErr.message);
+ }
+
+ // Clear any stale registration first, then register with flag 0x02.
+ // Flag 0x02 (SetPresent) is required for globalShortcutPressed signal delivery.
+ // Flag 0 breaks signal delivery (shortcut registers but never fires).
+ // Stale values are handled by the explicit unRegister before doRegister.
+ try { await this.kglobalaccel.unRegister(actionId); } catch {}
await this.kglobalaccel.doRegister(actionId);
- const result = await this.kglobalaccel.setShortcut(actionId, [qtKey], 0);
+ const result = await this.kglobalaccel.setShortcut(actionId, [qtKey], 0x02);
+
+ // Post-registration conflict check: setShortcut returns the actual key
+ // sequence assigned. If it differs from what we requested (e.g. returns [0]
+ // or empty), the key is owned by another component.
+ const assignedKey = Array.isArray(result) && result.length > 0 ? result[0] : null;
+ if (assignedKey !== null && assignedKey !== qtKey) {
+ debugLogger.log("[KDEShortcut] Shortcut conflict — setShortcut assigned different key", {
+ slot: slotName,
+ requested: `0x${qtKey.toString(16)}`,
+ assigned: `0x${assignedKey.toString(16)}`,
+ });
+ try { await this.kglobalaccel.unRegister(actionId); } catch {}
+ return "conflict";
+ }
if (callback) this.callbacks.set(slotName, callback);
this.registeredSlots.add(slotName);
@@ -241,7 +304,6 @@ class KDEShortcutManager {
slot: slotName,
hotkey: electronHotkey,
qtKey: `0x${qtKey.toString(16)}`,
- result,
});
return true;
} catch (err) {