xhisper /ˈzɪspər/

Dictation at cursor for Linux.

Installation

Dependencies

Arch Linux / Manjaro

sudo pacman -S pipewire jq curl ffmpeg gcc

Debian / Ubuntu / Linux Mint

sudo apt update
sudo apt install pipewire jq curl ffmpeg gcc

Fedora / RHEL / AlmaLinux / Rocky

sudo dnf install -y pipewire pipewire-utils jq curl ffmpeg gcc

OpenSUSE (Leap / Tumbleweed)

sudo zypper refresh
sudo zypper install pipewire jq curl ffmpeg gcc

Void Linux

sudo xbps-install -S
sudo xbps-install pipewire jq curl ffmpeg gcc

Note: wl-clipboard (Wayland) or xclip (X11) required for non-ASCII but usually pre-installed.

Setup

Add user to input group to access /dev/uinput:

sudo usermod -aG input $USER

Then log out and log back in (restart is safer) for the group change to take effect.

Check by running:

groups

You should see input in the output.

Get a Groq API key from console.groq.com (free tier available) and add to ~/.env:

GROQ_API_KEY=<your_API_key>

Clone the repository and install:

git clone --depth 1 https://github.com/imaginalnika/xhisper.git
cd xhisper && make
sudo make install

Bind xhisper binary to your favorite key:

keyd

[main]
capslock = layer(dictate)

[dictate:C]
d = macro(xhisper)

sxhkd

super + d
    xhisper

i3 / sway

bindsym $mod+d exec xhisper

Hyprland

bind = $mainMod, D, exec, xhisper

Gnome

# In your terminal:

name="xhisper"
binding="<CTRL><SHIFT>X"
action="/usr/local/bin/xhisper"

media_keys=org.gnome.settings-daemon.plugins.media-keys
custom_kbd=org.gnome.settings-daemon.plugins.media-keys.custom-keybinding
kbd_path=/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/$name/
new_bindings=`gsettings get $media_keys custom-keybindings | sed -e"s>'\]>','$kbd_path']>"| sed -e"s>@as \[\]>['$kbd_path']>"`
gsettings set $media_keys custom-keybindings "$new_bindings"
gsettings set $custom_kbd:$kbd_path name "$name"
gsettings set $custom_kbd:$kbd_path binding "$binding"
gsettings set $custom_kbd:$kbd_path command "$action"

Usage

Simply run xhisper twice (via your favorite keybinding):

First run: Starts recording
Second run: Stops and transcribes

The transcription will be typed at your cursor position.

View logs:

xhisper --log

Non-QWERTY layouts:

For non-QWERTY layouts (e.g. Dvorak, International), set up an input switch key to QWERTY (e.g. rightalt). Then instead of binding to xhisper, bind to:

xhisper --<your-input-switch-key>

Available input switch keys: --leftalt, --rightalt, --leftctrl, --rightctrl, --leftshift, --rightshift, --super

Key chords (like ctrl-space) not available yet.

Configuration

Configuration is read from ~/.config/xhisper/xhisperrc:

mkdir -p ~/.config/xhisper
cp default_xhisperrc ~/.config/xhisper/xhisperrc

Troubleshooting

Terminal Applications: Clipboard paste uses Ctrl+V, which doesn't work in terminal emulators (they require Ctrl+Shift+V). Temporary workaround is to remap Ctrl+V to paste in your terminal emulator's settings. Note that this limitation only affects international/Unicode characters. ASCII characters (a-z, A-Z, 0-9, punctuation) are typed directly and doesn't care whether terminal or not.

Non-ASCII Transcription: Increase non-ascii-*-delay to give the transcription longer timing buffer.

Low complexity dictation for Linux

NunoSempere/xhisper