root/openwhispr-easy-setup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure repo: PTT workaround is now the primary focus

Browse Source 
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
This commit is contained in:
Claude
2026-03-26 13:25:44 +00:00
parent 62b2a2277e
commit 9292ebf714
2 changed files with 139 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+28
View File
@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/), The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/). and this project adheres to [Semantic Versioning](https://semver.org/).
## [1.1.0] — 2026-03-26
### Added
- **Push-to-talk setup script** `setup-ptt.sh` — one-command PTT setup
- Interactive hotkey selection (Ctrl+Alt, Ctrl+Shift, Alt+Shift, Right Ctrl, Right Alt)
- Generates PTT Python script using `evdev` for reliable key detection
- Creates systemd user service (auto-start, restart on failure)
- Adds user to `input` group (no sudo needed for PTT)
- Checks if OpenWhispr is running, offers to launch
- Creates uninstall script
- PTT script `openwhispr-ptt.py` using `evdev` for physical key events
- Filters key repeats (evdev value=2) — no rapid-fire toggling
- Skips virtual keyboards (ydotoold)
- Clean xdotool keyup/keydown sequence for reliable Ctrl+` delivery
### Changed
- README restructured — PTT workaround is now the primary focus
- Original installer (`setup-openwhispr.sh`) moved to optional/secondary
### Fixed
- Script works when run via `bash <(curl ...)` — all reads use `/dev/tty`
- Script wrapped in `main()` to prevent line-by-line execution bug
- Binary detection searches `/opt/`, `/usr/lib/`, `dpkg -L` paths
- Replaced `YOUR_USERNAME` placeholder with `outis1one`
## [1.0.0] — 2026-03-25 ## [1.0.0] — 2026-03-25
### Added ### Added
README.md
+111 -89
View File
@@ -3,111 +3,133 @@
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![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) [![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)
**One-command installer for [OpenWhispr](https://github.com/OpenWhispr/openwhispr) on Linux** — distro detection, dependencies, API keys, first-run setup. 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 only question is whether you want AI to clean up the text after transcription.* > *Your voice stays on your machine. Always.*
## Quick install ## 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 ```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 curl -fsSL https://raw.githubusercontent.com/outis1one/openwhispr-easy-setup/main/setup-openwhispr.sh -o /tmp/setup-openwhispr.sh && bash /tmp/setup-openwhispr.sh
``` ```
Or clone and run:
```bash
git clone https://github.com/outis1one/openwhispr-easy-setup.git
cd openwhispr-easy-setup
bash setup-openwhispr.sh
```
## What it does
| Step | Action | Details | | Step | Action | Details |
|------|--------|---------| |------|--------|---------|
| 1/8 | **Intro** | Explains OpenWhispr and the privacy model | | 1/8 | Intro | Explains OpenWhispr and the privacy model |
| 2/8 | **Detect distro + arch** | Ubuntu, Debian, Mint, Fedora, openSUSE, Arch — amd64/arm64 | | 2/8 | Detect distro + arch | Ubuntu, Debian, Mint, Fedora, openSUSE, Arch — amd64/arm64 |
| 3/8 | **Install OpenWhispr** | Fetches latest release from GitHub, picks correct package | | 3/8 | Install OpenWhispr | Fetches latest release from GitHub |
| 4/8 | **Paste dependencies** | xdotool (X11), wtype (Wayland), kdotool (KDE), or D-Bus (GNOME) | | 4/8 | Paste dependencies | xdotool (X11), wtype (Wayland), kdotool (KDE) |
| 5/8 | **STT provider** | Local Whisper/Parakeet, Groq, or OpenAI Realtime | | 5/8 | STT provider | Local Whisper/Parakeet, Groq, or OpenAI Realtime |
| 6/8 | **AI cleanup** | OpenAI, Anthropic, Groq, Ollama, or skip | | 6/8 | AI cleanup | OpenAI, Anthropic, Groq, Ollama, or skip |
| 7/8 | **First launch** | Opens OpenWhispr for model download and hotkey setup | | 7/8 | First launch | Opens OpenWhispr for model download |
| 8/8 | **Summary** | Prints config, useful commands, and next steps | | 8/8 | Summary | Prints config and next steps |
## STT options </details>
| Option | Method | Streaming | Cost | Audio sent to |
|--------|--------|-----------|------|---------------|
| 1 (default) | Local Whisper/Parakeet | No | Free | Nobody, ever |
| 2 | Groq whisper-large-v3-turbo | No | $0.04/hr* | Groq servers |
| 3 | OpenAI Realtime API | Yes | $0.06/min | OpenAI servers |
\*Groq free tier: ~2,000 audio seconds/day.
## AI cleanup options
| Provider | Model | Per use | 50/day/mo | 200/day/mo |
|----------|-------|---------|-----------|------------|
| OpenAI | gpt-4o-mini-2024-07-18 | $0.000058 | $0.09 | $0.35 |
| Anthropic | claude-haiku-4-5 | $0.000450 | $0.68 | $2.70 |
| Groq | llama-3.3-70b-versatile | Free* | Free* | Free* |
| Ollama | Local (fully offline) | Free | Free | Free |
| Skip | Raw transcription only | Free | Free | Free |
\*Groq free: 1,000 req/day, 100K tokens/day.
## Privacy
| Data | Where it goes | Condition |
|------|---------------|-----------|
| **Audio** | Stays on your machine | Default (local Whisper/Parakeet) |
| **Audio** | Groq or OpenAI servers | Only if you choose cloud STT |
| **Text** | AI cleanup provider | Only if you choose AI cleanup |
| **API keys** | `~/.bashrc` on your machine | Never sent anywhere by this script |
No provider uses your data for training. Cloud data is deleted within 30 days.
## Useful commands
```bash
openwhispr # Launch the app
openwhispr --help # Show options
source ~/.bashrc # Reload API keys in current shell
```
In the app:
- **Settings → Hotkey** — change your hotkey (default: backtick `` ` ``)
- **Settings → Models** — download better speech models
- **Settings → Processing** — change STT or AI provider
## Supported distros
| Distro | Package format | Status |
|--------|---------------|--------|
| Ubuntu / Debian / Mint | `.deb` | Supported |
| Fedora | `.rpm` (dnf) | Supported |
| openSUSE | `.rpm` (zypper) | Supported |
| Arch / Manjaro / EndeavourOS | `.tar.gz` | Supported |
Architecture: `x86_64` (amd64) and `aarch64` (arm64).
## Requirements ## Requirements
- **OpenWhispr** installed ([releases](https://github.com/OpenWhispr/openwhispr/releases))
- **bash 4+** - **bash 4+**
- **curl** — for downloading - **Python 3** with `evdev` (installed by setup script)
- **jq** — for parsing GitHub API (script offers to install if missing) - **xdotool** (installed by setup script)
- **X11** session (Wayland support may vary)
## Safe to re-run ## Known OpenWhispr Issues on Linux
The script is idempotent: | Issue | Status | Workaround |
- Skips OpenWhispr install if the latest version is already present |-------|--------|------------|
- Never overwrites existing API keys in `~/.bashrc` | Hold mode doesn't persist | App bug | This PTT script |
- Detects already-installed paste dependencies | 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 |
## Troubleshooting | NVIDIA provider on non-GPU systems | Config issue | Switch to CPU Whisper in Settings → Transcription |
- [OpenWhispr Troubleshooting Guide](https://github.com/OpenWhispr/openwhispr/blob/main/TROUBLESHOOTING.md)
- [Open an issue](https://github.com/outis1one/openwhispr-easy-setup/issues/new/choose)
## License ## License