From 9292ebf714cbb17823b3dcd23e5e002a7bc04d51 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 26 Mar 2026 13:25:44 +0000 Subject: [PATCH] Restructure repo: PTT workaround is now the primary focus 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 --- CHANGELOG.md | 28 ++++++++ README.md | 200 ++++++++++++++++++++++++++++----------------------- 2 files changed, 139 insertions(+), 89 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 799adfa..4bf84de 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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/), 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 ### Added diff --git a/README.md b/README.md index a940e6d..881b1d9 100644 --- a/README.md +++ b/README.md @@ -3,111 +3,133 @@ [![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) -**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. + +
+Full installer details ```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 ``` -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 | |------|--------|---------| -| 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, picks correct package | -| 4/8 | **Paste dependencies** | xdotool (X11), wtype (Wayland), kdotool (KDE), or D-Bus (GNOME) | -| 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 and hotkey setup | -| 8/8 | **Summary** | Prints config, useful commands, and next steps | +| 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 | -## STT options - -| 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 +- **OpenWhispr** installed ([releases](https://github.com/OpenWhispr/openwhispr/releases)) - **bash 4+** -- **curl** — for downloading -- **jq** — for parsing GitHub API (script offers to install if missing) +- **Python 3** with `evdev` (installed by setup script) +- **xdotool** (installed by setup script) +- **X11** session (Wayland support may vary) -## Safe to re-run +## Known OpenWhispr Issues on Linux -The script is idempotent: -- Skips OpenWhispr install if the latest version is already present -- Never overwrites existing API keys in `~/.bashrc` -- Detects already-installed paste dependencies - -## Troubleshooting - -- [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) +| 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