Claude
9292ebf714
README rewritten to lead with the push-to-talk setup script as the main feature, with the full OpenWhispr installer demoted to an optional collapsed section. Documents known Linux bugs in OpenWhispr (Hold mode, Ctrl+Super, settings persistence). CHANGELOG updated with v1.1.0 entry. https://claude.ai/code/session_01XKYC1basxdwtHy71tky7xm
137 lines
4.7 KiB
Markdown
137 lines
4.7 KiB
Markdown
# OpenWhispr Easy Setup
|
|
|
|
[](LICENSE)
|
|
[](https://github.com/outis1one/openwhispr-easy-setup/actions/workflows/lint.yml)
|
|
|
|
Setup scripts for [OpenWhispr](https://github.com/OpenWhispr/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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
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](https://github.com/OpenWhispr/openwhispr/releases) and skip this.
|
|
|
|
<details>
|
|
<summary>Full installer details</summary>
|
|
|
|
```bash
|
|
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 |
|
|
|
|
</details>
|
|
|
|
## Requirements
|
|
|
|
- **OpenWhispr** installed ([releases](https://github.com/OpenWhispr/openwhispr/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](LICENSE)
|