From 6a64ba700fad9401db4f84fb976f65d9007eb45f Mon Sep 17 00:00:00 2001 From: leonardotrapani Date: Sat, 14 Mar 2026 15:23:35 +0100 Subject: [PATCH 1/4] document push-to-talk and keybinding patterns in readme and config docs --- README.md | 36 +++++++++++++++++++++++++++++++++++- docs/config.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9812b33..9d88f42 100644 --- a/README.md +++ b/README.md @@ -80,9 +80,11 @@ systemctl --user enable --now hyprvoice.service 3. Add a keybinding (Hyprland example): ```bash -bind = SUPER, R, exec, hyprvoice toggle +bindr = SUPER, R, exec, hyprvoice toggle ``` +See [Hyprland Keybindings](#hyprland-keybindings) for push-to-talk and other patterns. + 4. Test voice input: ```bash @@ -91,6 +93,38 @@ hyprvoice toggle Run `hyprvoice configure` anytime for advanced settings. +## Hyprland Keybindings + +Hyprland has two bind types that matter for voice input: + +- **`bind`** — fires when the key is **pressed down** +- **`bindr`** — fires when the key is **released** + +### Simple toggle (recommended default) + +```bash +# ~/.config/hypr/hyprland.conf +bindr = SUPER, R, exec, hyprvoice toggle +``` + +Using `bindr` (release) is important: modifiers like SUPER are fully released before `hyprvoice toggle` runs, so they don't interfere with text injection. With `bind`, the modifier may still be held when text is typed, causing stuck keys or wrong characters. + +### Push-to-talk (hold-to-record) + +Combine both bind types to get hold-to-record behavior — press to start, release to stop: + +```bash +# ~/.config/hypr/hyprland.conf +bind = SUPER, R, exec, hyprvoice toggle # key down → start recording +bindr = SUPER, R, exec, hyprvoice toggle # key up → stop and transcribe +``` + +This gives a walkie-talkie feel: hold the key while speaking, release when done. The daemon receives two `toggle` commands — the first starts recording, the second stops it and triggers transcription. + +### Why `bindr` matters + +When you press SUPER+R with a regular `bind`, the SUPER modifier is still physically held when the command fires. If hyprvoice tries to inject text while SUPER is down, the compositor interprets the injected keystrokes as SUPER+key combos — leading to stuck modifiers, missed characters, or unexpected window management actions. `bindr` waits until you lift the key, ensuring a clean keyboard state for injection. + ## Commands ### Core CLI diff --git a/docs/config.md b/docs/config.md index 8d6998d..a0dd292 100644 --- a/docs/config.md +++ b/docs/config.md @@ -21,6 +21,7 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app ## Table of Contents +- [Hyprland Keybinding Patterns](#hyprland-keybinding-patterns) - [Unified Provider System](#unified-provider-system) - [Transcription Providers](#transcription-providers) - [Cloud Providers](#cloud-providers) @@ -36,6 +37,48 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app - [Example Configurations](#example-configurations) - [Legacy Configs](#legacy-configs) +## Hyprland Keybinding Patterns + +Hyprvoice is triggered via Hyprland keybindings. The bind type you choose affects reliability and workflow. + +### `bind` vs `bindr` + +| Keyword | Fires on | Use for | +|---------|----------|---------| +| `bind` | Key **press** (down) | Starting recording | +| `bindr` | Key **release** (up) | Stopping recording / injecting text | + +The critical difference: with `bindr`, modifier keys (SUPER, CTRL, etc.) are fully released before the command executes. This prevents modifiers from interfering with text injection — avoiding stuck keys, wrong characters, or accidental compositor actions. + +### Simple toggle (recommended) + +A single `bindr` binding toggles recording on and off: + +```bash +# ~/.config/hypr/hyprland.conf +bindr = SUPER, R, exec, hyprvoice toggle +``` + +First release starts recording, second release stops and transcribes. This is the safest default because the keyboard is always in a clean state when text is injected. + +### Push-to-talk (hold-to-record) + +Pair `bind` (press) with `bindr` (release) on the same key for hold-to-record: + +```bash +# ~/.config/hypr/hyprland.conf +bind = SUPER, R, exec, hyprvoice toggle # key down → start recording +bindr = SUPER, R, exec, hyprvoice toggle # key up → stop and transcribe +``` + +Hold the key while speaking, release when done. Both lines send `toggle` to the daemon — the first starts the pipeline, the second stops it. Because the stop fires on release, modifiers are clean for injection. + +### Why modifier release matters + +When SUPER+R is pressed with a regular `bind`, the SUPER key is still physically held when `hyprvoice toggle` fires. If hyprvoice then injects text (via wtype or ydotool), the compositor sees SUPER+ for every keystroke — triggering window management shortcuts instead of typing. Using `bindr` for the stop/inject side ensures modifiers are released first. + +This is especially relevant if you use the `wtype` or `ydotool` injection backends. The `clipboard` backend is less affected since it uses paste rather than simulated keystrokes, but `bindr` is still recommended for consistency. + ## Unified Provider System Hyprvoice uses a unified provider system where API keys are configured once and shared between transcription and LLM features: From 3db74580d8f41cb26ed5f7e966dfb40c956f4292 Mon Sep 17 00:00:00 2001 From: leonardotrapani Date: Sun, 15 Mar 2026 15:43:14 +0100 Subject: [PATCH 2/4] keep bind as default, document bindr as alternative --- README.md | 8 ++++---- docs/config.md | 12 +++++------- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 9d88f42..88c886b 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ systemctl --user enable --now hyprvoice.service 3. Add a keybinding (Hyprland example): ```bash -bindr = SUPER, R, exec, hyprvoice toggle +bind = SUPER, R, exec, hyprvoice toggle ``` See [Hyprland Keybindings](#hyprland-keybindings) for push-to-talk and other patterns. @@ -100,14 +100,14 @@ Hyprland has two bind types that matter for voice input: - **`bind`** — fires when the key is **pressed down** - **`bindr`** — fires when the key is **released** -### Simple toggle (recommended default) +### Simple toggle ```bash # ~/.config/hypr/hyprland.conf -bindr = SUPER, R, exec, hyprvoice toggle +bind = SUPER, R, exec, hyprvoice toggle ``` -Using `bindr` (release) is important: modifiers like SUPER are fully released before `hyprvoice toggle` runs, so they don't interfere with text injection. With `bind`, the modifier may still be held when text is typed, causing stuck keys or wrong characters. +Each press toggles between recording and idle. If you experience issues with text injection (stuck keys, wrong characters), try `bindr` instead — it fires on key release, so modifiers like SUPER are fully released before the command runs. ### Push-to-talk (hold-to-record) diff --git a/docs/config.md b/docs/config.md index a0dd292..309fcef 100644 --- a/docs/config.md +++ b/docs/config.md @@ -45,21 +45,19 @@ Hyprvoice is triggered via Hyprland keybindings. The bind type you choose affect | Keyword | Fires on | Use for | |---------|----------|---------| -| `bind` | Key **press** (down) | Starting recording | +| `bind` | Key **press** (down) | Simple toggle, starting recording | | `bindr` | Key **release** (up) | Stopping recording / injecting text | -The critical difference: with `bindr`, modifier keys (SUPER, CTRL, etc.) are fully released before the command executes. This prevents modifiers from interfering with text injection — avoiding stuck keys, wrong characters, or accidental compositor actions. +With `bindr`, modifier keys (SUPER, CTRL, etc.) are fully released before the command executes. This can prevent modifiers from interfering with text injection. -### Simple toggle (recommended) - -A single `bindr` binding toggles recording on and off: +### Simple toggle ```bash # ~/.config/hypr/hyprland.conf -bindr = SUPER, R, exec, hyprvoice toggle +bind = SUPER, R, exec, hyprvoice toggle ``` -First release starts recording, second release stops and transcribes. This is the safest default because the keyboard is always in a clean state when text is injected. +Each press toggles between recording and idle. If you run into issues with text injection (stuck keys, wrong characters), try `bindr` instead — it fires on key release so modifiers are guaranteed released before the command runs. ### Push-to-talk (hold-to-record) From c755c6efea5b5eb1085a927b788fa83a86a4f516 Mon Sep 17 00:00:00 2001 From: leonardotrapani Date: Sun, 15 Mar 2026 15:55:23 +0100 Subject: [PATCH 3/4] move bind vs bindr after push-to-talk, remove verbose explanation --- README.md | 14 +++++++------- docs/config.md | 18 ++++++------------ 2 files changed, 13 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 88c886b..1251039 100644 --- a/README.md +++ b/README.md @@ -95,11 +95,6 @@ Run `hyprvoice configure` anytime for advanced settings. ## Hyprland Keybindings -Hyprland has two bind types that matter for voice input: - -- **`bind`** — fires when the key is **pressed down** -- **`bindr`** — fires when the key is **released** - ### Simple toggle ```bash @@ -121,9 +116,14 @@ bindr = SUPER, R, exec, hyprvoice toggle # key up → stop and transcribe This gives a walkie-talkie feel: hold the key while speaking, release when done. The daemon receives two `toggle` commands — the first starts recording, the second stops it and triggers transcription. -### Why `bindr` matters +### `bind` vs `bindr` -When you press SUPER+R with a regular `bind`, the SUPER modifier is still physically held when the command fires. If hyprvoice tries to inject text while SUPER is down, the compositor interprets the injected keystrokes as SUPER+key combos — leading to stuck modifiers, missed characters, or unexpected window management actions. `bindr` waits until you lift the key, ensuring a clean keyboard state for injection. +| Keyword | Fires on | +|---------|----------| +| `bind` | Key **press** (down) | +| `bindr` | Key **release** (up) | + +With `bindr`, modifier keys (SUPER, CTRL, etc.) are fully released before the command executes. This can prevent modifiers from interfering with text injection. ## Commands diff --git a/docs/config.md b/docs/config.md index 309fcef..0f119c4 100644 --- a/docs/config.md +++ b/docs/config.md @@ -41,15 +41,6 @@ Configuration is stored in `~/.config/hyprvoice/config.toml` and changes are app Hyprvoice is triggered via Hyprland keybindings. The bind type you choose affects reliability and workflow. -### `bind` vs `bindr` - -| Keyword | Fires on | Use for | -|---------|----------|---------| -| `bind` | Key **press** (down) | Simple toggle, starting recording | -| `bindr` | Key **release** (up) | Stopping recording / injecting text | - -With `bindr`, modifier keys (SUPER, CTRL, etc.) are fully released before the command executes. This can prevent modifiers from interfering with text injection. - ### Simple toggle ```bash @@ -71,11 +62,14 @@ bindr = SUPER, R, exec, hyprvoice toggle # key up → stop and transcribe Hold the key while speaking, release when done. Both lines send `toggle` to the daemon — the first starts the pipeline, the second stops it. Because the stop fires on release, modifiers are clean for injection. -### Why modifier release matters +### `bind` vs `bindr` -When SUPER+R is pressed with a regular `bind`, the SUPER key is still physically held when `hyprvoice toggle` fires. If hyprvoice then injects text (via wtype or ydotool), the compositor sees SUPER+ for every keystroke — triggering window management shortcuts instead of typing. Using `bindr` for the stop/inject side ensures modifiers are released first. +| Keyword | Fires on | +|---------|----------| +| `bind` | Key **press** (down) | +| `bindr` | Key **release** (up) | -This is especially relevant if you use the `wtype` or `ydotool` injection backends. The `clipboard` backend is less affected since it uses paste rather than simulated keystrokes, but `bindr` is still recommended for consistency. +With `bindr`, modifier keys (SUPER, CTRL, etc.) are fully released before the command executes. This can prevent modifiers from interfering with text injection. ## Unified Provider System From 36b252b30bfdd4a2cac5d1204460afc314df246f Mon Sep 17 00:00:00 2001 From: leonardotrapani Date: Sun, 15 Mar 2026 16:06:16 +0100 Subject: [PATCH 4/4] remove bindr troubleshooting hint from simple toggle --- README.md | 2 +- docs/config.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1251039..17056ce 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ Run `hyprvoice configure` anytime for advanced settings. bind = SUPER, R, exec, hyprvoice toggle ``` -Each press toggles between recording and idle. If you experience issues with text injection (stuck keys, wrong characters), try `bindr` instead — it fires on key release, so modifiers like SUPER are fully released before the command runs. +Each press toggles between recording and idle. ### Push-to-talk (hold-to-record) diff --git a/docs/config.md b/docs/config.md index 0f119c4..1a848e3 100644 --- a/docs/config.md +++ b/docs/config.md @@ -48,7 +48,7 @@ Hyprvoice is triggered via Hyprland keybindings. The bind type you choose affect bind = SUPER, R, exec, hyprvoice toggle ``` -Each press toggles between recording and idle. If you run into issues with text injection (stuck keys, wrong characters), try `bindr` instead — it fires on key release so modifiers are guaranteed released before the command runs. +Each press toggles between recording and idle. ### Push-to-talk (hold-to-record)