# OpenWhispr Easy Setup

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![ShellCheck](https://github.com/outis1one/openwhispr-easy-setup/actions/workflows/lint.yml/badge.svg)](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)