initial commit with brainstorming

2025-08-06 18:48:25 +02:00
commit d3fc5ee3a4
2 changed files with 132 additions and 0 deletions
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leonardo Trapani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,111 @@
+# 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.