Add detailed comments to scripts and comprehensive README
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
28allday
parent
6ef6c141ab
commit
dc69aeb311
1 changed files with 141 additions and 0 deletions
141
README.md
Normal file
141
README.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
# Voxtype Keybind - Omarchy
|
||||
|
||||
Customise how [Voxtype](https://omarchy.com) dictation works in [Omarchy](https://omarchy.com). Switch between push-to-talk (hold to dictate) and toggle mode (press to start/stop), or bind dictation to any key on your keyboard.
|
||||
|
||||
## Scripts
|
||||
|
||||
| Script | Purpose |
|
||||
|--------|---------|
|
||||
| `switch-voxtype-to-ptt.sh` | Set up push-to-talk with any key you choose |
|
||||
| `switch-voxtype-to-toggle.sh` | Switch to toggle mode (press once to start, again to stop) |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
git clone https://github.com/28allday/Voxtype-Keybind-Omarchy.git
|
||||
cd Voxtype-Keybind-Omarchy
|
||||
|
||||
# Option 1: Push-to-talk with a custom key
|
||||
chmod +x switch-voxtype-to-ptt.sh
|
||||
./switch-voxtype-to-ptt.sh
|
||||
|
||||
# Option 2: Toggle mode (Super+Ctrl+X on/off)
|
||||
chmod +x switch-voxtype-to-toggle.sh
|
||||
./switch-voxtype-to-toggle.sh
|
||||
```
|
||||
|
||||
## Push-to-Talk Mode
|
||||
|
||||
**Hold a key to dictate, release to stop** — like a walkie-talkie.
|
||||
|
||||
When you run `switch-voxtype-to-ptt.sh`, you get three options:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| **1** | Bind any regular key (F13, Scroll Lock, macro keys, etc.) |
|
||||
| **2** | Bind a modifier key (Ctrl, Alt, Shift, Caps Lock) |
|
||||
| **3** | Restore the default (Super+Ctrl+X hold-to-talk) |
|
||||
|
||||
### How Key Detection Works
|
||||
|
||||
The script uses **wev** (Wayland Event Viewer) to detect which key you press:
|
||||
|
||||
1. A small window opens for 5 seconds
|
||||
2. Press the key you want to use for push-to-talk
|
||||
3. The window closes and shows the detected key
|
||||
4. Confirm to apply the binding
|
||||
|
||||
The keybind uses the raw **keycode** (not the key name) for reliability across keyboard layouts, and the **'i' flag** to ignore other modifiers — so push-to-talk works regardless of what other keys you're holding.
|
||||
|
||||
### Recommended Keys for Push-to-Talk
|
||||
|
||||
| Key | Why |
|
||||
|-----|-----|
|
||||
| **F13-F24** | Unused by most apps, won't conflict with anything |
|
||||
| **Scroll Lock** | Rarely used, easy to reach |
|
||||
| **Caps Lock** | Convenient, but disables caps lock functionality |
|
||||
| **Mouse side button** | If your mouse supports it via input-remapper |
|
||||
| **Macro keys** | If your keyboard has dedicated macro keys |
|
||||
|
||||
## Toggle Mode
|
||||
|
||||
**Press once to start dictating, press again to stop.**
|
||||
|
||||
Run `switch-voxtype-to-toggle.sh` to change from the default hold-to-talk to toggle mode using Super+Ctrl+X.
|
||||
|
||||
Better for longer dictation sessions where holding a key would be uncomfortable.
|
||||
|
||||
## How It Works
|
||||
|
||||
Both scripts modify Hyprland's keybinding config at:
|
||||
```
|
||||
~/.local/share/omarchy/default/hypr/bindings/utilities.conf
|
||||
```
|
||||
|
||||
They look for the `# Dictation` section and replace the voxtype bindings.
|
||||
|
||||
### Push-to-Talk Binding Format
|
||||
|
||||
```
|
||||
bindid = , code:201, Start dictation, exec, voxtype record start
|
||||
bindidr = , code:201, Stop dictation, exec, voxtype record stop
|
||||
```
|
||||
|
||||
- `bindid` — triggers on key **press** (i=ignore modifiers, d=has description)
|
||||
- `bindidr` — triggers on key **release** (r=release)
|
||||
|
||||
### Toggle Binding Format
|
||||
|
||||
```
|
||||
bindd = SUPER CTRL, X, Toggle dictation, exec, voxtype record toggle
|
||||
```
|
||||
|
||||
- `bindd` — standard keybind with description
|
||||
|
||||
## Backups
|
||||
|
||||
Both scripts create a timestamped backup before making changes:
|
||||
```
|
||||
utilities.conf.backup.20260328_143000
|
||||
```
|
||||
|
||||
To restore a backup:
|
||||
```bash
|
||||
cp ~/.local/share/omarchy/default/hypr/bindings/utilities.conf.backup.TIMESTAMP \
|
||||
~/.local/share/omarchy/default/hypr/bindings/utilities.conf
|
||||
hyprctl reload
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Dependency | Purpose | Auto-installed? |
|
||||
|-----------|---------|----------------|
|
||||
| `wev` | Detects key presses (push-to-talk script only) | Yes |
|
||||
| `hyprctl` | Reloads Hyprland config after changes | Comes with Hyprland |
|
||||
| `voxtype` | Omarchy's voice dictation tool | Comes with Omarchy |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Key detection doesn't work
|
||||
|
||||
- Make sure to press the key **inside the wev window**, not the terminal
|
||||
- Try running `wev` manually to check it works: `wev`
|
||||
|
||||
### Binding doesn't work after configuration
|
||||
|
||||
- Check the config was updated: `grep voxtype ~/.local/share/omarchy/default/hypr/bindings/utilities.conf`
|
||||
- Force reload: `hyprctl reload`
|
||||
|
||||
### Want to go back to default
|
||||
|
||||
Run the push-to-talk script and choose **option 3** (Restore default).
|
||||
|
||||
## Credits
|
||||
|
||||
- [Omarchy](https://omarchy.com) - The Arch Linux distribution
|
||||
- [Voxtype](https://omarchy.com) - Voice dictation for Omarchy
|
||||
- [wev](https://git.sr.ht/~sircmpwn/wev) - Wayland event viewer
|
||||
|
||||
## License
|
||||
|
||||
This project is provided as-is for the Omarchy community.
|
||||
Loading…
Add table
Reference in a new issue