OpenWhispr Easy Setup

Setup scripts for OpenWhispr on Linux — push-to-talk workaround, dependency setup, and systemd autostart.

Your voice stays on your machine. Always.

The Problem

OpenWhispr v1.6.6 on Linux has bugs where:

• Hold-to-talk ("Hold" mode) doesn't persist — always reverts to Tap/toggle
• Ctrl+Super hotkey fails to register on most desktop environments
• Settings changes in the UI don't save to config correctly

The Solution: Push-to-Talk Wrapper

setup-ptt.sh installs a lightweight Python script that provides real hold-to-talk on top of OpenWhispr's toggle mode. Hold your chosen keys to start dictation, release to stop.

Quick install

curl -fsSL https://raw.githubusercontent.com/outis1one/openwhispr-easy-setup/main/setup-ptt.sh -o /tmp/setup-ptt.sh && bash /tmp/setup-ptt.sh

What it does

Step	Action
1/6	Intro
2/6	Install dependencies (xdotool, evdev), add user to input group
3/6	Choose PTT hotkey (Ctrl+Alt, Ctrl+Shift, Alt+Shift, Right Ctrl, Right Alt)
4/6	Generate PTT Python script with your chosen hotkey
5/6	Create systemd user service (auto-start on login, restart on failure)
6/6	Check OpenWhispr is running, create uninstall script, print summary

How it works

The PTT script uses evdev to read physical key events directly (no key-repeat issues), then sends xdotool commands to toggle OpenWhispr's Ctrl+` hotkey:

1. Hold your PTT keys → script sends Ctrl+` to start recording
2. Release → script sends Ctrl+` again to stop recording
3. OpenWhispr transcribes and pastes the text

Hotkey options

Option	Keys	Notes
1 (default)	Ctrl + Alt	Works on all desktops
2	Ctrl + Shift
3	Alt + Shift
4	Right Ctrl alone	Easy one-hand use
5	Right Alt alone	Easy one-hand use

Avoid Super/Windows key — most desktops intercept it.

Useful commands

# Check PTT status
systemctl --user status openwhispr-ptt

# View live logs
journalctl --user -u openwhispr-ptt -f

# Restart PTT
systemctl --user restart openwhispr-ptt

# Stop PTT
systemctl --user stop openwhispr-ptt

# Disable auto-start
systemctl --user disable openwhispr-ptt

# Re-enable auto-start
systemctl --user enable openwhispr-ptt

# Run manually (for debugging)
python3 ~/.local/share/openwhispr-ptt/openwhispr-ptt.py

Uninstall PTT

bash ~/.local/share/openwhispr-ptt/uninstall-ptt.sh

This removes only the PTT wrapper, not OpenWhispr itself.

---

Optional: Full Installer

setup-openwhispr.sh is a separate script that installs OpenWhispr itself from GitHub releases with distro detection, paste dependencies, and API key setup. Most users can just install OpenWhispr directly from their releases page and skip this.

Full installer details

curl -fsSL https://raw.githubusercontent.com/outis1one/openwhispr-easy-setup/main/setup-openwhispr.sh -o /tmp/setup-openwhispr.sh && bash /tmp/setup-openwhispr.sh

Step	Action	Details
1/8	Intro	Explains OpenWhispr and the privacy model
2/8	Detect distro + arch	Ubuntu, Debian, Mint, Fedora, openSUSE, Arch — amd64/arm64
3/8	Install OpenWhispr	Fetches latest release from GitHub
4/8	Paste dependencies	xdotool (X11), wtype (Wayland), kdotool (KDE)
5/8	STT provider	Local Whisper/Parakeet, Groq, or OpenAI Realtime
6/8	AI cleanup	OpenAI, Anthropic, Groq, Ollama, or skip
7/8	First launch	Opens OpenWhispr for model download
8/8	Summary	Prints config and next steps

Requirements

• OpenWhispr installed (releases)
• bash 4+
• Python 3 with evdev (installed by setup script)
• xdotool (installed by setup script)
• X11 session (Wayland support may vary)

Known OpenWhispr Issues on Linux

Issue	Status	Workaround
Hold mode doesn't persist	App bug	This PTT script
Ctrl+Super hotkey fails	App bug	Use Ctrl+` for OW, PTT script for hold
Settings don't save	App bug	Edit .env or LevelDB directly
NVIDIA provider on non-GPU systems	Config issue	Switch to CPU Whisper in Settings → Transcription

License

MIT