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
const { execFileSync } = require("child_process");
const debugLogger = require("./debugLogger");
const GnomeGlobalShortcutsPortal = require("./gnomeGlobalShortcutsPortal");
const DBUS_SERVICE_NAME = "com.openwhispr.App";
const DBUS_OBJECT_PATH = "/com/openwhispr/App";
const DBUS_INTERFACE = "com.openwhispr.App";
// Per-slot gsettings paths and display names
const SLOT_CONFIG = {
dictation: {
path: "/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr/",
name: "OpenWhispr Toggle",
},
meeting: {
path: "/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr-meeting/",
name: "OpenWhispr Meeting",
},
voiceAgent: {
path: "/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr-voice-agent/",
name: "OpenWhispr Voice Assistant",
},
translation: {
path: "/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr-translation/",
name: "OpenWhispr Translation",
},
};
const KEYBINDING_SCHEMA = "org.gnome.settings-daemon.plugins.media-keys.custom-keybinding";
const PORTAL_MODIFIER_NAMES = new Set([
"commandorcontrol",
"control",
"ctrl",
"alt",
"shift",
"super",
"meta",
]);
// Valid pattern for GNOME shortcut format using X11 keysym names (case-sensitive).
// Modifiers are case-insensitive (GTK normalizes them), keysyms are exact.
const VALID_SHORTCUT_PATTERN =
/^(<(Control|Alt|Shift|Super)>)*(F([1-9]|1[0-9]|2[0-4])|comma|period|slash|plus|minus|equal|semicolon|apostrophe|backslash|bracketleft|bracketright|asciitilde|exclam|at|numbersign|dollar|percent|asciicircum|ampersand|asterisk|parenleft|parenright|underscore|braceleft|braceright|bar|colon|quotedbl|less|greater|question|[a-z0-9]|space|Escape|Tab|BackSpace|grave|Pause|Scroll_Lock|Insert|Delete|Home|End|Page_Up|Page_Down|Up|Down|Left|Right|Return|Print)$/;
// Map Electron key names (lowercased) to X11 keysym names (case-sensitive).
// Source: X11/keysymdef.h, lookup via XStringToKeysym(3).
const ELECTRON_TO_GNOME_KEY_MAP = {
space: "space",
tab: "Tab",
escape: "Escape",
backspace: "BackSpace",
delete: "Delete",
return: "Return",
enter: "Return",
home: "Home",
end: "End",
insert: "Insert",
pause: "Pause",
print: "Print",
printscreen: "Print",
pageup: "Page_Up",
pagedown: "Page_Down",
scrolllock: "Scroll_Lock",
arrowup: "Up",
arrowdown: "Down",
arrowleft: "Left",
arrowright: "Right",
up: "Up",
down: "Down",
left: "Left",
right: "Right",
// Punctuation must be X11 keysyms; a literal "," fails VALID_SHORTCUT_PATTERN.
",": "comma",
".": "period",
"/": "slash",
"-": "minus",
"=": "equal",
";": "semicolon",
"'": "apostrophe",
"[": "bracketleft",
"]": "bracketright",
"\\": "backslash",
plus: "plus",
"+": "plus",
};
// HotkeyInput stores physical US-QWERTY keys, so Shift must be folded into
// the keysym GNOME matches rather than retained as a separate modifier.
const SHIFTED_PUNCTUATION_TO_GNOME_KEY_MAP = {
"`": "asciitilde",
1: "exclam",
2: "at",
3: "numbersign",
4: "dollar",
5: "percent",
6: "asciicircum",
7: "ampersand",
8: "asterisk",
9: "parenleft",
0: "parenright",
"-": "underscore",
"=": "plus",
"[": "braceleft",
"]": "braceright",
"\\": "bar",
";": "colon",
"'": "quotedbl",
",": "less",
".": "greater",
"/": "question",
};
// F13-F24 at the end of a GNOME accelerator ("<Control>F16") or a portal trigger ("CTRL+F16").
const EXTENDED_FUNCTION_KEY = /(?<=^|[>+])F(1[3-9]|2[0-4])$/;
const KEYMAP_QUERY_TIMEOUT_MS = 3000;
// The keysym the active keymap gives an xkb key name ("FK16"), null when the key has none,
// or undefined when the keymap can't be read. xkbcomp ships with XWayland (x11-xkb-utils).
function readKeymapKeysym(keyName) {
const display = process.env.DISPLAY;
if (!display) return undefined;
let keymap;
try {
keymap = execFileSync("xkbcomp", ["-xkb", display, "-"], {
encoding: "utf-8",
stdio: "pipe",
timeout: KEYMAP_QUERY_TIMEOUT_MS,
});
} catch (err) {
debugLogger.log("[GnomeShortcut] Could not read the keymap with xkbcomp:", err.message);
return undefined;
}
if (!keymap.includes("xkb_symbols")) return undefined;
// "key <FK16> { [ XF86Launch7 ] };" or "symbols[Group1]= [ XF86TouchpadOff, ... ]" inside a
// multi-line entry, never another field's list such as actions[Group1]; a key with no
// keysym has no entry at all.
const entry = new RegExp(
`key <${keyName}>\\s*\\{(?:[^}]*?symbols\\[[^\\]]*\\]\\s*=)?\\s*\\[\\s*([^\\s,\\]]+)`
).exec(keymap);
return entry && entry[1] !== "NoSymbol" ? entry[1] : null;
}
// For comparison: <Primary> and <Ctrl> mean <Control>, modifier order and case don't matter.
function normalizeAccelerator(accelerator) {
const mods = [];
const key = accelerator.replace(/<(\w+)>/gi, (_, mod) => {
const name = mod.toLowerCase();
mods.push(name === "primary" || name === "ctrl" ? "control" : name);
return "";
});
mods.sort();
return mods.map((m) => `<${m}>`).join("") + key.toLowerCase();
}
let dbus = null;
function getDBus() {
if (dbus) return dbus;
try {
dbus = require("@homebridge/dbus-native");
return dbus;
} catch (err) {
debugLogger.log("[GnomeShortcut] Failed to load dbus-native:", err.message);
return null;
}
}
function getSlotConfig(slotName) {
const config = SLOT_CONFIG[slotName];
if (!config) {
throw new Error(`[GnomeShortcut] Unknown slot: "${slotName}"`);
}
return config;
}
class GnomeShortcutManager {
constructor() {
this.bus = null;
this.dictationCallback = null;
this.meetingCallback = null;
this.voiceAgentCallback = null;
this.translationCallback = null;
this.globalShortcutsPortal = new GnomeGlobalShortcutsPortal();
// Track which slots have been registered in gsettings
this.registeredSlots = new Set();
// Set by HotkeyManager to debug-log each press: (slotName, action).
this.onHotkeyEvent = null;
}
static isGnome() {
const desktop = process.env.XDG_CURRENT_DESKTOP || "";
return (
desktop.toLowerCase().includes("gnome") ||
desktop.toLowerCase().includes("ubuntu") ||
desktop.toLowerCase().includes("unity")
);
}
static isWayland() {
return process.env.XDG_SESSION_TYPE === "wayland";
}
setMeetingCallback(callback) {
this.meetingCallback = callback;
debugLogger.log("[GnomeShortcut] Meeting callback registered");
}
setVoiceAgentCallback(callback) {
this.voiceAgentCallback = callback;
debugLogger.log("[GnomeShortcut] Voice agent callback registered");
}
setTranslationCallback(callback) {
this.translationCallback = callback;
debugLogger.log("[GnomeShortcut] Translation callback registered");
}
// Older builds persisted a gsettings keybinding for the removed chat-agent
// slot; its dbus-send command targets a method this app no longer exports,
// so the entry errors silently forever and squats its key. Prune it once.
removeRetiredAgentKeybinding() {
const retiredPath =
"/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr-agent/";
try {
const existing = this.getExistingKeybindings();
if (!existing.includes(retiredPath)) return;
const remaining = existing.filter((p) => p !== retiredPath);
const bindingsStr = remaining.length ? "['" + remaining.join("', '") + "']" : "[]";
execFileSync(
"gsettings",
["set", "org.gnome.settings-daemon.plugins.media-keys", "custom-keybindings", bindingsStr],
{ stdio: "pipe" }
);
execFileSync("gsettings", ["reset-recursively", `${KEYBINDING_SCHEMA}:${retiredPath}`], {
stdio: "pipe",
});
debugLogger.log("[GnomeShortcut] Removed retired chat-agent keybinding");
} catch (err) {
debugLogger.log(
"[GnomeShortcut] Failed to remove retired chat-agent keybinding:",
err.message
);
}
}
async initDBusService(dictationCallback) {
this.dictationCallback = dictationCallback;
const dbusModule = getDBus();
if (!dbusModule) {
return false;
}
try {
this.bus = dbusModule.sessionBus();
// Without a listener, async socket errors (e.g. a stale
// DBUS_SESSION_BUS_ADDRESS) crash the process as an unhandled
// "error" event — sessionBus() returns before connecting.
this.bus.connection.on("error", (err) => {
debugLogger.log("[GnomeShortcut] D-Bus connection error:", err.message);
});
this.bus.requestName(DBUS_SERVICE_NAME, 0);
this.bus.exportInterface(
{
Toggle: () => {
this.onHotkeyEvent?.("dictation", "press");
if (this.dictationCallback) {
this.dictationCallback();
}
},
ToggleMeeting: () => {
this.onHotkeyEvent?.("meeting", "press");
if (this.meetingCallback) {
this.meetingCallback();
}
},
ToggleVoiceAgent: () => {
this.onHotkeyEvent?.("voiceAgent", "press");
if (this.voiceAgentCallback) {
this.voiceAgentCallback();
}
},
ToggleTranslation: () => {
this.onHotkeyEvent?.("translation", "press");
if (this.translationCallback) {
this.translationCallback();
}
},
},
DBUS_OBJECT_PATH,
{
name: DBUS_INTERFACE,
methods: {
Toggle: ["", ""],
ToggleMeeting: ["", ""],
ToggleVoiceAgent: ["", ""],
ToggleTranslation: ["", ""],
},
}
);
debugLogger.log("[GnomeShortcut] D-Bus service initialized successfully");
this.removeRetiredAgentKeybinding();
return true;
} catch (err) {
debugLogger.log("[GnomeShortcut] Failed to initialize D-Bus service:", err.message);
if (this.bus) {
this.bus.connection.end();
this.bus = null;
}
return false;
}
}
async initGlobalShortcutsPortal() {
return this.globalShortcutsPortal.init();
}
supportsPushToTalk() {
return this.globalShortcutsPortal.isAvailable();
}
async registerPushToTalk(hotkey, callback) {
const preferredTrigger = GnomeShortcutManager.convertToPortalFormat(hotkey);
if (!preferredTrigger) return false;
const tapShortcut = GnomeShortcutManager.convertToGnomeFormat(hotkey);
const resolved = this.resolveFunctionKey(tapShortcut);
const { keysym, reason } = resolved;
if (reason) {
debugLogger.log(
`[GnomeShortcut] GNOME can't grab "${tapShortcut}" for Hold with this keymap: ${reason}`
);
return reason;
}
await this.unregisterKeybinding("dictation");
const registered = await this.globalShortcutsPortal.registerKeybinding(
keysym ? preferredTrigger.replace(EXTENDED_FUNCTION_KEY, keysym) : preferredTrigger,
(hotkeyArg, phase) => {
this.onHotkeyEvent?.("dictation", phase);
return callback(hotkeyArg, phase);
}
);
if (!registered) {
await this.registerKeybinding(tapShortcut, "dictation", resolved);
}
return registered;
}
async unregisterPushToTalk() {
await this.globalShortcutsPortal.unregisterKeybinding();
}
static isValidShortcut(shortcut) {
if (!shortcut || typeof shortcut !== "string") {
return false;
}
return VALID_SHORTCUT_PATTERN.test(shortcut);
}
// resolved: resolveFunctionKey(shortcut) when the caller already has it.
async registerKeybinding(shortcut = "<Alt>r", slotName = "dictation", resolved) {
if (!GnomeShortcutManager.isGnome()) {
debugLogger.log("[GnomeShortcut] Not running on GNOME, skipping registration");
return false;
}
if (!GnomeShortcutManager.isValidShortcut(shortcut)) {
debugLogger.log(
`[GnomeShortcut] Invalid shortcut format: "${shortcut}" for slot "${slotName}"`
);
return false;
}
const { keysym, reason } = resolved ?? this.resolveFunctionKey(shortcut);
if (reason) {
debugLogger.log(
`[GnomeShortcut] GNOME can't grab "${shortcut}" for slot "${slotName}" with this keymap: ${reason}`
);
return reason;
}
const binding = keysym ? shortcut.replace(EXTENDED_FUNCTION_KEY, keysym) : shortcut;
const { path: keybindingPath, name: keybindingName } = getSlotConfig(slotName);
const SLOT_DBUS_METHOD = {
dictation: "Toggle",
meeting: "ToggleMeeting",
voiceAgent: "ToggleVoiceAgent",
translation: "ToggleTranslation",
};
const dbusMethod = SLOT_DBUS_METHOD[slotName] || "Toggle";
const command = `dbus-send --session --type=method_call --dest=${DBUS_SERVICE_NAME} ${DBUS_OBJECT_PATH} ${DBUS_INTERFACE}.${dbusMethod}`;
try {
const existing = this.getExistingKeybindings();
const alreadyRegistered = existing.includes(keybindingPath);
// Check if another custom shortcut already uses this binding
debugLogger.log("[GnomeShortcut] Checking for conflicts", {
shortcut: binding,
existingPaths: existing,
ownPath: keybindingPath,
});
const conflict = this.findConflictingBinding(binding, existing, keybindingPath);
if (conflict) {
debugLogger.log(
`[GnomeShortcut] Shortcut conflict — "${binding}" already used by "${conflict}"`,
{
slot: slotName,
conflictPath: conflict,
}
);
return false;
}
execFileSync(
"gsettings",
["set", `${KEYBINDING_SCHEMA}:${keybindingPath}`, "name", keybindingName],
{ stdio: "pipe" }
);
execFileSync(
"gsettings",
["set", `${KEYBINDING_SCHEMA}:${keybindingPath}`, "binding", binding],
{ stdio: "pipe" }
);
execFileSync(
"gsettings",
["set", `${KEYBINDING_SCHEMA}:${keybindingPath}`, "command", command],
{ stdio: "pipe" }
);
if (!alreadyRegistered) {
const newBindings = [...existing, keybindingPath];
const bindingsStr = "['" + newBindings.join("', '") + "']";
execFileSync(
"gsettings",
[
"set",
"org.gnome.settings-daemon.plugins.media-keys",
"custom-keybindings",
bindingsStr,
],
{ stdio: "pipe" }
);
}
this.registeredSlots.add(slotName);
debugLogger.log(
`[GnomeShortcut] Keybinding "${binding}" registered for slot "${slotName}" successfully`
);
return true;
} catch (err) {
debugLogger.log(
`[GnomeShortcut] Failed to register keybinding for slot "${slotName}":`,
err.message
);
return false;
}
}
async unregisterKeybinding(slotName = "dictation") {
const { path: keybindingPath } = getSlotConfig(slotName);
try {
const existing = this.getExistingKeybindings();
const filtered = existing.filter((p) => p !== keybindingPath);
if (filtered.length === 0) {
execFileSync(
"gsettings",
["set", "org.gnome.settings-daemon.plugins.media-keys", "custom-keybindings", "[]"],
{ stdio: "pipe" }
);
} else {
const bindingsStr = "['" + filtered.join("', '") + "']";
execFileSync(
"gsettings",
[
"set",
"org.gnome.settings-daemon.plugins.media-keys",
"custom-keybindings",
bindingsStr,
],
{ stdio: "pipe" }
);
}
execFileSync("gsettings", ["reset", `${KEYBINDING_SCHEMA}:${keybindingPath}`, "name"], {
stdio: "pipe",
});
execFileSync("gsettings", ["reset", `${KEYBINDING_SCHEMA}:${keybindingPath}`, "binding"], {
stdio: "pipe",
});
execFileSync("gsettings", ["reset", `${KEYBINDING_SCHEMA}:${keybindingPath}`, "command"], {
stdio: "pipe",
});
this.registeredSlots.delete(slotName);
debugLogger.log(
`[GnomeShortcut] Keybinding unregistered for slot "${slotName}" successfully`
);
return true;
} catch (err) {
debugLogger.log(
`[GnomeShortcut] Failed to unregister keybinding for slot "${slotName}":`,
err.message
);
return false;
}
}
// Stock xkeyboard-config gives the F13-F24 keys XF86 keysyms (F16 sends XF86Launch7) and
// no F13-F24 keysym at all, and GNOME can only grab a keysym the keymap carries. Returns
// the keysym to bind instead, the reason GNOME can't grab the key, or {} to keep it.
resolveFunctionKey(accelerator) {
const match = EXTENDED_FUNCTION_KEY.exec(accelerator);
if (!match) return {};
const keysym = readKeymapKeysym(`FK${match[1]}`);
if (keysym === undefined || keysym === match[0]) return {};
if (keysym === null) return { reason: "keysym_missing" };
if (this.isMediaKeyBinding(accelerator.replace(EXTENDED_FUNCTION_KEY, keysym))) {
return { reason: "keysym_reserved" };
}
return { keysym };
}
// gsd-media-keys already grabs the hardware keys GNOME handles itself (XF86Tools opens
// Settings, XF86AudioMicMute mutes the mic), so a custom shortcut on one never fires.
isMediaKeyBinding(accelerator) {
let settings;
try {
settings = execFileSync(
"gsettings",
["list-recursively", "org.gnome.settings-daemon.plugins.media-keys"],
{ encoding: "utf-8" }
);
} catch (err) {
debugLogger.log("[GnomeShortcut] Failed to read GNOME media key bindings:", err.message);
return false;
}
const target = normalizeAccelerator(accelerator);
return [...settings.matchAll(/'([^']*)'/g)].some(
([, binding]) => normalizeAccelerator(binding) === target
);
}
findConflictingBinding(shortcut, existingPaths, ownPath) {
const normalizedShortcut = normalizeAccelerator(shortcut);
for (const path of existingPaths) {
if (path === ownPath) continue;
try {
const binding = execFileSync(
"gsettings",
["get", `${KEYBINDING_SCHEMA}:${path}`, "binding"],
{ encoding: "utf-8" }
)
.trim()
.replace(/^'|'$/g, "");
if (normalizeAccelerator(binding) === normalizedShortcut) return path;
} catch {}
}
return null;
}
getExistingKeybindings() {
try {
const output = execFileSync(
"gsettings",
["get", "org.gnome.settings-daemon.plugins.media-keys", "custom-keybindings"],
{ encoding: "utf-8" }
);
const match = output.match(/\[([^\]]*)\]/);
if (!match) return [];
const content = match[1];
if (!content.trim()) return [];
return content
.split(",")
.map((s) => s.trim().replace(/'/g, ""))
.filter(Boolean);
} catch (err) {
debugLogger.log("[GnomeShortcut] Failed to read existing keybindings:", err.message);
return [];
}
}
static convertToGnomeFormat(hotkey) {
if (!hotkey || typeof hotkey !== "string") {
return "";
}
const parts = hotkey
.split("+")
.map((p) => p.trim())
.filter(Boolean);
if (parts.length === 0) {
return "";
}
const key = parts.pop();
const keyLower = key.toLowerCase();
const shiftedPunctuationKey = parts.some((mod) => mod.toLowerCase() === "shift")
? SHIFTED_PUNCTUATION_TO_GNOME_KEY_MAP[keyLower]
: undefined;
const modifiers = parts
.map((mod) => {
const m = mod.toLowerCase();
if (m === "commandorcontrol" || m === "control" || m === "ctrl") return "<Control>";
if (m === "alt") return "<Alt>";
if (m === "shift" && shiftedPunctuationKey) return "";
if (m === "shift") return "<Shift>";
if (m === "super" || m === "meta") return "<Super>";
return "";
})
.filter(Boolean)
.join("");
let gnomeKey;
if (shiftedPunctuationKey) {
gnomeKey = shiftedPunctuationKey;
} else if (key === "`" || keyLower === "backquote") {
gnomeKey = "grave";
} else if (key === " ") {
gnomeKey = "space";
} else if (ELECTRON_TO_GNOME_KEY_MAP[keyLower]) {
gnomeKey = ELECTRON_TO_GNOME_KEY_MAP[keyLower];
} else if (/^F\d+$/i.test(key)) {
gnomeKey = key.toUpperCase();
} else {
gnomeKey = keyLower;
}
return modifiers + gnomeKey;
}
static convertToPortalFormat(hotkey) {
if (!hotkey || typeof hotkey !== "string") return "";
const parts = hotkey
.split("+")
.map((part) => part.trim())
.filter(Boolean);
// The side is stripped because a lone "RightControl" is modifier-only too, and
// the portal cannot bind a trigger that has no base key.
if (
parts.length === 0 ||
parts.every((part) => PORTAL_MODIFIER_NAMES.has(part.toLowerCase().replace(/^right/, "")))
) {
return "";
}
const key = parts.pop();
const keyLower = key.toLowerCase();
const modifiers = parts
.map((modifier) => {
const name = modifier.toLowerCase();
if (name === "commandorcontrol" || name === "control" || name === "ctrl") return "CTRL";
if (name === "alt") return "ALT";
if (name === "shift") return "SHIFT";
if (name === "super" || name === "meta") return "LOGO";
return "";
})
.filter(Boolean);
let portalKey;
if (key === "`" || keyLower === "backquote") {
portalKey = "grave";
} else if (key === " ") {
portalKey = "space";
} else if (ELECTRON_TO_GNOME_KEY_MAP[keyLower]) {
portalKey = ELECTRON_TO_GNOME_KEY_MAP[keyLower];
} else if (/^F\d+$/i.test(key)) {
portalKey = key.toUpperCase();
} else {
portalKey = keyLower;
}
return [...modifiers, portalKey].join("+");
}
async close() {
await this.globalShortcutsPortal.close();
if (this.bus) {
this.bus.connection.end();
this.bus = null;
}
}
}
module.exports = GnomeShortcutManager;