Skip to content

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

feat: add ydotool fallback on linux

Gabriel Stein349cfd8d803c
diff --git a/CLAUDE.md b/CLAUDE.md
index a18b72030..9530d0a5b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,7 +42,10 @@ OpenWhispr is an Electron-based desktop dictation application that uses whisper.
### Helper Modules (src/helpers/)
- **audioManager.js**: Handles audio device management
-- **clipboard.js**: Cross-platform clipboard operations with AppleScript fallback
+- **clipboard.js**: Cross-platform clipboard operations
+ - macOS: AppleScript-based paste with accessibility permission check
+ - Windows: PowerShell SendKeys with nircmd.exe fallback
+ - Linux: Multi-tool support (wtype, ydotool, xdotool) for X11/Wayland compatibility
- **database.js**: SQLite operations for transcription history
- **debugLogger.js**: Debug logging system with file output
- **devServerManager.js**: Vite dev server integration
@@ -300,8 +303,12 @@ Enable with `--log-level=debug` or `OPENWHISPR_LOG_LEVEL=debug` (can be set in `
- Verify FFmpeg is executable
3. **Clipboard Not Working**:
- - macOS: Check accessibility permissions
- - Use AppleScript fallback on macOS
+ - macOS: Check accessibility permissions (required for AppleScript paste)
+ - Linux X11: Install `xdotool` for paste simulation
+ - Linux Wayland: Install `wtype` or `ydotool` (requires `ydotoold` daemon)
+ - GNOME Wayland: Use `xdotool` for XWayland apps only
+ - Other Wayland compositors: `wtype` (if compositor supports virtual keyboard) or `ydotool`
+ - Windows: PowerShell SendKeys (built-in) or nircmd.exe (bundled)
4. **Build Issues**:
- Use `npm run pack` for unsigned builds (CSC_IDENTITY_AUTO_DISCOVERY=false)
@@ -337,6 +344,12 @@ Enable with `--log-level=debug` or `OPENWHISPR_LOG_LEVEL=debug` (can be set in `
- No standardized URL scheme for system settings (user must open manually)
- Privacy settings button hidden in UI (not applicable on Linux)
- Recommend `pavucontrol` for audio device management
+- **Clipboard paste tools** (at least one required for auto-paste):
+ - **X11**: `xdotool` (recommended)
+ - **Wayland** (non-GNOME): `wtype` (requires virtual keyboard protocol) or `ydotool` (requires `ydotoold` daemon)
+ - **GNOME Wayland**: `xdotool` for XWayland apps only (native Wayland apps require manual paste)
+ - Terminal detection: Auto-detects terminal emulators and uses Ctrl+Shift+V
+ - Fallback: Text copied to clipboard with manual paste instructions
## Code Style and Conventions
diff --git a/README.md b/README.md
index 343d4a955..c723c9967 100644
--- a/README.md
+++ b/README.md
@@ -178,6 +178,10 @@ sudo pacman -S xdotool
```
**Wayland (Modern Linux Desktop)**:
+
+Choose **one** of the following paste tools:
+
+**Option 1: wtype** (requires virtual keyboard protocol support)
```bash
# Debian/Ubuntu
sudo apt install wtype
@@ -187,15 +191,35 @@ sudo dnf install wtype
# Arch
sudo pacman -S wtype
+```
+
+**Option 2: ydotool** (works on more compositors, requires daemon)
+```bash
+# Debian/Ubuntu
+sudo apt install ydotool
+sudo systemctl enable --now ydotoold
-# Alternative: ydotool (requires uinput permissions)
-sudo apt install ydotool # or equivalent for your distro
+# Fedora/RHEL
+sudo dnf install ydotool
+sudo systemctl enable --now ydotoold
+
+# Arch
+sudo pacman -S ydotool
+sudo systemctl enable --now ydotoold
+```
-# On KDE Wayland you will additionally need `kdotool` to detect if a terminal is focused for automatically pasting with Ctrl+Shift+V instead of Ctrl+V. Automatic terminal detection on non-KDE Wayland is not yet supported.
-sudo apt install kdotool # or equivalent for your distro
+**Terminal Detection** (Optional - for KDE Wayland users):
+```bash
+# On KDE Wayland, kdotool enables automatic terminal detection
+# to paste with Ctrl+Shift+V instead of Ctrl+V
+sudo apt install kdotool # Debian/Ubuntu
+sudo dnf install kdotool # Fedora/RHEL
+sudo pacman -S kdotool # Arch
```
-> ℹ️ **Note**: OpenWhispr automatically detects your display server (X11 vs Wayland) and uses the appropriate paste tool. If no paste tool is installed, text will still be copied to the clipboard - you'll just need to paste manually with Ctrl+V.
+> ℹ️ **Note**: OpenWhispr automatically tries paste tools in this order: `wtype` → `ydotool` → `xdotool` (for XWayland apps). If no paste tool is installed, text will still be copied to the clipboard - you'll just need to paste manually with Ctrl+V.
+
+> ⚠️ **ydotool Requirements**: The `ydotoold` daemon must be running for ydotool to work. Start it manually with `sudo ydotoold &` or enable the systemd service as shown above.
> 🔒 **Flatpak Security**: The Flatpak package includes sandboxing with explicit permissions for microphone, clipboard, and file access. See [electron-builder.json](electron-builder.json) for the complete permission list.
@@ -490,7 +514,11 @@ OpenWhispr is designed with privacy and security in mind:
- If bundled binary fails, install via `brew install whisper-cpp` (macOS)
- Check available disk space for models
5. **Global hotkey conflicts**: Change the hotkey in the Control Panel - any key can be used
-6. **Text not pasting**: Check accessibility permissions and try manual paste with Cmd+V
+6. **Text not pasting**:
+ - macOS: Check accessibility permissions (System Settings → Privacy & Security → Accessibility)
+ - Linux X11: Install `xdotool`
+ - Linux Wayland: Install `wtype` or `ydotool` (ensure `ydotoold` daemon is running)
+ - All platforms: Text is always copied to clipboard - use Ctrl+V (Cmd+V on macOS) to paste manually
7. **Panel position**: If the panel appears off-screen, restart the app to reset position
### Getting Help
diff --git a/src/helpers/clipboard.js b/src/helpers/clipboard.js
index 886ac6980..e053aa812 100644
--- a/src/helpers/clipboard.js
+++ b/src/helpers/clipboard.js
@@ -435,6 +435,7 @@ class ClipboardManager {
const { isWayland, xwaylandAvailable, isGnome } = getLinuxSessionInfo();
const xdotoolExists = this.commandExists("xdotool");
const wtypeExists = this.commandExists("wtype");
+ const ydotoolExists = this.commandExists("ydotool");
debugLogger.debug(
"Linux paste environment",
@@ -444,6 +445,7 @@ class ClipboardManager {
isGnome,
xdotoolExists,
wtypeExists,
+ ydotoolExists,
display: process.env.DISPLAY,
waylandDisplay: process.env.WAYLAND_DISPLAY,
xdgSessionType: process.env.XDG_SESSION_TYPE,
@@ -551,6 +553,7 @@ class ClipboardManager {
const pasteKeys = inTerminal ? "ctrl+shift+v" : "ctrl+v";
const canUseWtype = isWayland && !isGnome;
+ const canUseYdotool = isWayland;
const canUseXdotool = isWayland ? !!xdotoolWindowClass : xdotoolExists;
// Define paste tools in preference order based on display server
@@ -566,6 +569,12 @@ class ClipboardManager {
);
}
+ // ydotool uses key codes: 29=LeftCtrl, 42=LeftShift, 47=V
+ // Format: keycode:1 (press), keycode:0 (release)
+ const ydotoolArgs = inTerminal
+ ? ["key", "29:1", "42:1", "47:1", "47:0", "42:0", "29:0"] // Ctrl+Shift+V
+ : ["key", "29:1", "47:1", "47:0", "29:0"]; // Ctrl+V
+
const candidates = [
...(canUseWtype
? [
@@ -577,6 +586,7 @@ class ClipboardManager {
: { cmd: "wtype", args: ["-M", "ctrl", "-k", "v", "-m", "ctrl"] },
]
: []),
+ ...(canUseYdotool ? [{ cmd: "ydotool", args: ydotoolArgs }] : []),
...(canUseXdotool ? [{ cmd: "xdotool", args: xdotoolArgs }] : []),
];
@@ -767,16 +777,16 @@ class ClipboardManager {
errorMsg =
"Clipboard copied, but paste simulation failed via XWayland. Please paste manually with Ctrl+V.";
}
- } else if (!wtypeExists) {
+ } else if (!wtypeExists && !ydotoolExists) {
if (!xwaylandAvailable) {
errorMsg =
- "Clipboard copied, but automatic pasting on Wayland requires wtype. Please install wtype or paste manually with Ctrl+V.";
+ "Clipboard copied, but automatic pasting on Wayland requires wtype or ydotool. Please install one or paste manually with Ctrl+V.";
} else if (!xdotoolExists) {
errorMsg =
- "Clipboard copied, but automatic pasting on Wayland requires wtype (Wayland apps) or xdotool (XWayland apps). Please install one or paste manually with Ctrl+V.";
+ "Clipboard copied, but automatic pasting on Wayland requires wtype/ydotool (Wayland apps) or xdotool (XWayland apps). Please install one or paste manually with Ctrl+V.";
} else if (!xdotoolWindowClass) {
errorMsg =
- "Clipboard copied, but the active app isn't running under XWayland. Please install wtype for Wayland apps or paste manually with Ctrl+V.";
+ "Clipboard copied, but the active app isn't running under XWayland. Please install wtype or ydotool for Wayland apps or paste manually with Ctrl+V.";
} else {
errorMsg =
"Clipboard copied, but paste simulation failed via XWayland. Please paste manually with Ctrl+V.";
@@ -786,9 +796,15 @@ class ClipboardManager {
xwaylandAvailable && xdotoolExists
? " If this is an XWayland app, xdotool can also be used."
: "";
+ const installNote =
+ !ydotoolExists
+ ? " Consider installing ydotool as an alternative (requires ydotoold daemon)."
+ : " If using ydotool, ensure the ydotoold daemon is running.";
errorMsg =
- "Clipboard copied, but paste simulation failed on Wayland. Ensure your compositor supports the virtual keyboard protocol or paste manually with Ctrl+V." +
- xwaylandNote;
+ "Clipboard copied, but paste simulation failed on Wayland. Your compositor may not support the virtual keyboard protocol." +
+ installNote +
+ xwaylandNote +
+ " Alternatively, paste manually with Ctrl+V.";
}
} else {
errorMsg =
@@ -1010,11 +1026,15 @@ Would you like to open System Settings now?`;
// Check which tools are available
const tools = [];
const canUseWtype = isWayland && !isGnome;
+ const canUseYdotool = isWayland;
const canUseXdotool = !isWayland || xwaylandAvailable;
if (canUseWtype && this.commandExists("wtype")) {
tools.push("wtype");
}
+ if (canUseYdotool && this.commandExists("ydotool")) {
+ tools.push("ydotool");
+ }
if (canUseXdotool && this.commandExists("xdotool")) {
tools.push("xdotool");
}
@@ -1027,7 +1047,7 @@ Would you like to open System Settings now?`;
} else if (isGnome) {
recommendedInstall = xwaylandAvailable ? "xdotool" : undefined;
} else {
- recommendedInstall = "wtype";
+ recommendedInstall = "wtype or ydotool";
}
}