Setup Guide for Ubuntu 24.04 LTS

[JosefJezek]

OpenWhispr on Ubuntu 24.04 (GNOME Wayland) — Setup Guide

Problem

OpenWhispr's auto-paste doesn't work out of the box on Ubuntu 24.04 due to two issues:

1. ydotoold (the daemon for ydotool) is not running and has no systemd service in the Ubuntu package
2. ydotool 0.1.8 (shipped with Ubuntu 24.04) doesn't understand the raw keycode format (29:1 47:1 47:0 29:0) that OpenWhispr sends — it expects key names (ctrl+v). This causes garbage characters like 2442 to be typed instead of pasting.

Setup

1. Install OpenWhispr

# Download and install the latest .deb
gh release download v1.4.11 --repo OpenWhispr/openwhispr --pattern "*linux-amd64.deb" --dir /tmp
sudo apt install -y /tmp/OpenWhispr-*-linux-amd64.deb

2. Install dependencies

sudo apt install -y ydotool ydotoold wl-clipboard

3. Fix /dev/uinput permissions

ydotool needs write access to /dev/uinput. By default only root can access it.

# Create udev rule
echo 'KERNEL=="uinput", GROUP="input", MODE="0660", TAG+="uaccess"' | sudo tee /etc/udev/rules.d/80-uinput.rules

# Add your user to the input group
sudo usermod -aG input $USER

# Apply immediately (persists after reboot via udev rule + group membership)
sudo udevadm control --reload-rules
sudo udevadm trigger /dev/uinput

4. Create ydotoold systemd user service

Ubuntu 24.04's ydotoold package doesn't include a systemd service file.

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/ydotoold.service << 'EOF'
[Unit]
Description=ydotoold - ydotool daemon
Documentation=man:ydotoold(8)

[Service]
ExecStart=/usr/bin/ydotoold
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable ydotoold
systemctl --user start ydotoold

If it fails with a socket error, kill any stale root-owned instances first:

sudo pkill ydotoold
sudo rm -f /tmp/.ydotool_socket
systemctl --user start ydotoold

5. Create ydotool wrapper (critical fix)

OpenWhispr sends raw Linux keycodes in ydotool 1.0.x format (29:1 47:1 47:0 29:0), but Ubuntu 24.04 ships ydotool 0.1.8 which expects key names (ctrl+v). Without this wrapper, you get garbage characters instead of paste.

# Rename original binary
sudo mv /usr/bin/ydotool /usr/bin/ydotool.real

# Create wrapper script
sudo tee /usr/bin/ydotool > /dev/null << 'WRAPPER'
#!/bin/bash
# Wrapper: translates ydotool 1.0.x raw keycode syntax to 0.1.8 key name syntax
# 29:1 47:1 47:0 29:0 (Ctrl+V) → ctrl+v
# 29:1 42:1 47:1 47:0 42:0 29:0 (Ctrl+Shift+V) → ctrl+shift+v

if [ "$1" = "key" ]; then
    shift
    flags=()
    codes=()
    while [ $# -gt 0 ]; do
        case "$1" in
            --*) flags+=("$1" "$2"); shift 2 ;;
            *) codes+=("$1"); shift ;;
        esac
    done

    if [[ "${codes[0]}" =~ ^[0-9]+:[01]$ ]]; then
        pressed=()
        for c in "${codes[@]}"; do
            code="${c%%:*}"
            state="${c##*:}"
            [ "$state" = "1" ] && pressed+=("$code")
        done

        declare -A KEYMAP=(
            [29]="ctrl" [97]="ctrl" [42]="shift" [54]="shift"
            [56]="alt" [100]="alt" [125]="super" [126]="super"
            [16]="q" [17]="w" [18]="e" [19]="r" [20]="t"
            [21]="y" [22]="u" [23]="i" [24]="o" [25]="p"
            [30]="a" [31]="s" [32]="d" [33]="f" [34]="g"
            [35]="h" [36]="j" [37]="k" [38]="l" [44]="z"
            [45]="x" [46]="c" [47]="v" [48]="b" [49]="n" [50]="m"
            [2]="1" [3]="2" [4]="3" [5]="4" [6]="5"
            [7]="6" [8]="7" [9]="8" [10]="9" [11]="0"
        )

        seen=()
        combo=""
        for code in "${pressed[@]}"; do
            name="${KEYMAP[$code]:-$code}"
            dup=0
            for s in "${seen[@]}"; do [ "$s" = "$name" ] && dup=1 && break; done
            [ "$dup" = "1" ] && continue
            seen+=("$name")
            [ -n "$combo" ] && combo="${combo}+"
            combo="${combo}${name}"
        done

        exec /usr/bin/ydotool.real key "${flags[@]}" "$combo"
    else
        exec /usr/bin/ydotool.real key "${flags[@]}" "${codes[@]}"
    fi
else
    exec /usr/bin/ydotool.real "$@"
fi
WRAPPER

sudo chmod 755 /usr/bin/ydotool

6. Log out and back in

Required for the input group membership to take effect. After re-login, ydotoold will start automatically.

7. Set a global hotkey (e.g. Alt+X)

On GNOME Wayland, Electron can't register global shortcuts directly. OpenWhispr uses GNOME custom shortcuts via gsettings + D-Bus. You can set this up before launching the app:

# Replace <Alt>x with your preferred combo (e.g. <Alt>r, <Super>d, <Control><Alt>space)
HOTKEY="<Alt>x"

gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr/ name "OpenWhispr Toggle"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr/ binding "$HOTKEY"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr/ command "dbus-send --session --type=method_call --dest=com.openwhispr.App /com/openwhispr/App com.openwhispr.App.Toggle"

# Register the shortcut path (preserves existing custom shortcuts)
EXISTING=$(gsettings get org.gnome.settings-daemon.plugins.media-keys custom-keybindings)
PATH_ENTRY="/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr/"
if [[ "$EXISTING" != *"$PATH_ENTRY"* ]]; then
    if [ "$EXISTING" = "@as []" ]; then
        gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings "['$PATH_ENTRY']"
    else
        NEW=$(echo "$EXISTING" | sed "s/]$/, '$PATH_ENTRY']/")
        gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings "$NEW"
    fi
fi

You can verify the shortcut is registered in Settings → Keyboard → Keyboard Shortcuts → Custom Shortcuts.

Also set the hotkey in the OpenWhispr .env so the app knows about it:

# Set the matching hotkey in OpenWhispr config
sed -i 's/^DICTATION_KEY=.*/DICTATION_KEY=Alt+X/' ~/.config/open-whispr/.env

8. Launch OpenWhispr and configure

open-whispr

• Configure a speech-to-text engine (OpenWhispr Cloud, OpenAI API key, or local Whisper model)
• The global hotkey is already set — press it anywhere to start/stop dictation

Verification

# ydotoold is running
systemctl --user status ydotoold

# uinput is accessible
test -w /dev/uinput && echo "OK" || echo "FAIL: log out and back in"

# Paste simulation works (switch to a text editor within 3 seconds)
echo "paste test" | wl-copy && sleep 3 && ydotool key ctrl+v

Notes

• The global hotkey on GNOME Wayland is registered as a GNOME custom shortcut (visible in Settings → Keyboard → Shortcuts → Custom Shortcuts)
• Push-to-talk is not available on GNOME Wayland (only tap-to-talk)
• The ydotool wrapper is needed until Ubuntu ships ydotool 1.0.x+ or OpenWhispr adds 0.1.x compatibility
• If apt upgrade replaces /usr/bin/ydotool, re-run step 5

[gabrielste1n]

@JosefJezek thank you for this - what version of OpenWhispr are you on?

[christian-taillon]

Linking related threads so we can track Linux auto-paste behavior in one place:

• Original ydotool discussion/workaround: Linux GNOME Wayland paste reliability improvements #292
• Similar report/approach: Setup Guide for Ubuntu 24.04 LTS #310
• Current implementation attempt (PR): fix: restore paste reliability on GNOME Wayland (terminals + GUI) #293

Context: PR #293 currently relies on ydotool as an external dependency. That works as a workaround, but maintainers (and I agree) would prefer to keep this self-contained via linux-fast-paste instead of requiring extra system setup.

For clarity: I'm not suggesting this should be merged as-is for maintainers. I'm applying the PR #293 patch locally on top of the latest maintainer release so I can use ydotool as a temporary workaround in my own setup.

My current theory is this is largely Wayland security related: on Wayland, apps can't globally inject keyboard input the way X11 tools can, so approaches like xdotool often fail for native Wayland windows. linux-fast-paste may hit the same compositor/input-permission boundaries depending on session/compositor setup, while ydotool works in some cases because it injects via kernel/uinput (with additional system requirements).

Goal is still to get linux-fast-paste working reliably across Linux/Wayland setups so ydotool can remain optional (or unnecessary).

If anyone has findings on why linux-fast-paste fails in their environment (compositor/session/tooling), please share details here so we can converge on a native fix.