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

Merge pull request #5 from outis1one/claude/create-bash-installer-GSmST
ShellCheck / ShellCheck (push) Canceled after 0s
Details

Browse Source 
Restructure repo: PTT workaround is now the primary focus
This commit is contained in:
Outis
2026-03-26 09:50:46 -04:00
committed by GitHub
parent 6d21f18a20 9292ebf714
commit df058569c4
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/),
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
README.md
+111 -89
View File
@@ -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.
<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
```
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).
</details>
## 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