112 lines
4.4 KiB
Markdown
112 lines
4.4 KiB
Markdown
# Hyprvoice
|
||
|
||
> **Voice‑powered typing for Wayland/Hyprland desktops** — press a global shortcut, speak, and watch words appear in whatever window you’re focused on.
|
||
|
||
---
|
||
|
||
## Why does this hyprvoice exist?
|
||
|
||
Typing is slow, repetitive strain injuries are real, and proprietary speech‑to‑text solutions leak your data. This project aims to give Wayland users a fast, privacy‑respecting alternative that works entirely on their own hardware _or_ any cloud ASR they trust.
|
||
|
||
---
|
||
|
||
## Key Features
|
||
|
||
| Category | Highlights |
|
||
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||
| **Hot‑key daemon** | Background service triggered by a global shortcut (via `hyprctl dispatch exec …` or other compositor hooks). |
|
||
| **Live audio capture** | Low‑latency PipeWire input with optional VAD/noise gate. |
|
||
| **Pluggable ASR** | 🔌 Local Whisper (via `whisper.cpp`) or cloud APIs (OpenAI, Deepgram, AssemblyAI). Select at runtime. |
|
||
| **Optional LLM polish** | Feed raw transcript into a local Ollama model or GPT‑4o to add punctuation, change tone, etc. |
|
||
| **Text injection** | `wtype`/`ydotool` sends keystrokes to the focused surface; clipboard fallback for stubborn clients. |
|
||
| **Zero‑friction config** | Single `~/.config/hyprvoice/config.toml` with sensible defaults and live reload on SIGHUP. |
|
||
| **Cross‑platform binary** | Static Go build; no Python environment required. |
|
||
|
||
---
|
||
|
||
## Quick Start (Arch / Hyprland)
|
||
|
||
```bash
|
||
# 1. Install from AUR (source build)
|
||
yay -S hyprvoice
|
||
# or pre‑built binary
|
||
yay -S hyprvoice-bin
|
||
|
||
# 2. Run the interactive setup helper
|
||
hyprvoice-install run --backend whispercpp
|
||
|
||
# 3. Enable the user service
|
||
systemctl --user enable --now hyprvoice.service
|
||
|
||
# 4. Add a key binding in Hyprland conf
|
||
bind = $mod, R, exec, hyprvoice toggle
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration file (`~/.config/hyprvoice/config.toml`)
|
||
|
||
```toml
|
||
[asr]
|
||
backend = "whispercpp" # whispercpp | openai
|
||
model = "medium.en.bin" # used if backend = whispercpp
|
||
api_key = "" # used if backend = openai
|
||
|
||
[vad]
|
||
threshold = -45 # dBFS
|
||
hang_ms = 300
|
||
|
||
[inject]
|
||
method = "wtype" # wtype | ydotool | clipboard
|
||
|
||
[keybind]
|
||
# If you don't use Hyprland, set an XDG desktop accelerator here
|
||
shortcut = "CTRL+ALT+SPACE"
|
||
```
|
||
|
||
All options are documented in the sample config generated by `--init`.
|
||
|
||
---
|
||
|
||
## Architecture Overview
|
||
|
||
```
|
||
┌──────────┐ PCM ┌──────────┐ chunks ┌──────────┐ text ┌──────────┐
|
||
│ Hot‑key │────────▶│ Audio │────────▶│ ASR │──────▶│ Inject │
|
||
│ Listener │ │ Capture │ │ Adapter │ │ (wtype) │
|
||
└──────────┘ └──────────┘ └──────────┘ └──────────┘
|
||
▲ │ │
|
||
│ stats / errors │ ▼
|
||
└──────────────┬────────┘ ┌──────────┐
|
||
│ │ Desktop │
|
||
└──────────────────▶ UI │
|
||
└──────────┘
|
||
```
|
||
|
||
Each box is a Go package inside `internal/` so you can swap implementations without touching public APIs.
|
||
|
||
---
|
||
|
||
## Building from Source
|
||
|
||
```bash
|
||
git clone https://github.com/leonardotrapani/hyprvoice.git
|
||
cd hyprvoice
|
||
# Compile
|
||
CGO_ENABLED=1 go build -o hyprvoice ./cmd/hyprvoice
|
||
# Run tests
|
||
go test ./...
|
||
```
|
||
|
||
**Requires** Go 1.22+, a C compiler, and `pkg-config` with PipeWire headers.
|
||
|
||
---
|
||
|
||
Contributions welcome! Check the [issues](https://github.com/leonardotrapani/hyprvoice/issues) for good first tasks.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.
|