Push-to-talk speech-to-text for Hyprland/Wayland.
Hold a key, speak, release, and ShuVoice types the result into the focused window.
ShuVoice is a Rust desktop application: shell, runtime, GTK overlays, control
socket, setup/wizard, and packaging entrypoints are all native. The default
Cargo feature set is desktop (audio + native Sherpa/OpenAI ASR + GTK UI + TTS,
including MeloTTS over the worker protocol).
Optional heavy model stacks — NeMo ASR, Moonshine ASR, and MeloTTS —
run as isolated, versioned Python workers under workers/. They speak a
framed worker protocol (shuvoice-worker-proto) over stdio. The app never
imports Python ML code into its process.
- Push-to-talk dictation for Wayland desktops, optimized for Hyprland.
- Native ASR: static Sherpa-ONNX (CPU) and OpenAI Realtime Whisper.
- Optional worker ASR: NeMo and Moonshine (isolated Python processes).
- TTS: ElevenLabs, OpenAI, local Piper, Kokoro (HTTP), and MeloTTS (worker-proto only).
- Native GTK4 layer-shell overlays with live status and transcription feedback.
- Waybar helper (
shuvoice-waybar) with recording, service, setup, and TTS actions. - Native settings window with search, vocabulary/corrections, model downloads, shortcut previews, diagnostics, and guided setup.
Open ShuVoice from the desktop launcher or run shuvoice settings.
shuvoice wizard opens setup; shuvoice-settings --onboarding selects guided
setup directly. Apply & Restart validates the draft, waits until speech is
idle, reserves the service, then saves and restarts. Shortcut changes apply
immediately after preview and confirmation. Source-build instructions:
apps/settings/README.md.
- User systemd service with dependency failures exiting 78 (no restart storms).
# 1. Install from AUR on Arch Linux
yay -S shuvoice-git
# 2. Run the setup wizard
shuvoice wizard
# 3. Enable and start the background service
systemctl --user enable --now shuvoice.service
# 4. Hold your push-to-talk key, speak, and release.The wizard handles backend selection, model downloads, Hyprland keybinds, final text injection mode, and optional TTS setup. For source installs, dependency details, and service overrides, see Installation.
shuvoice wizardThe wizard walks through:
- Welcome and environment checks
- ASR backend selection
- Sherpa profile and device choice when applicable
- Push-to-talk key and final text injection mode
- TTS provider, voice, speed, and provider settings
- Model download and Hyprland keybind setup
Wizard defaults (stable instant profile): Sherpa Parakeet int8 on CPU,
instant_mode = true, sherpa_decode_mode = "offline_instant", typing
final_only / auto injection, Kokoro TTS at 1.25×.
Hold your configured push-to-talk key, speak, and release. ShuVoice transcribes the audio and injects final text into the focused app.
shuvoice --help
shuvoice wizard
shuvoice preflight
shuvoice audio list-devices
shuvoice config effective
shuvoice control start
shuvoice control stop
shuvoice control status
shuvoice control tts_speak
shuvoice control tts_speak_clipboardRecommended Hyprland binds:
bind = , Control_R, exec, shuvoice control start --control-wait-sec 0
bindr = , Control_R, exec, shuvoice control stop --control-wait-sec 0
bindr = CTRL, Control_R, exec, shuvoice control stop --control-wait-sec 0
bind = SHIFT, Control_R, exec, shuvoice control start_alt --control-wait-sec 0
bindr = SHIFT, Control_R, exec, shuvoice control stop --control-wait-sec 0
bindr = CTRL SHIFT, Control_R, exec, shuvoice control stop --control-wait-sec 0
bind = SUPER CTRL, S, exec, shuvoice control tts_speak --control-wait-sec 0
bind = SUPER CTRL SHIFT, S, exec, shuvoice control tts_speak_clipboard --control-wait-sec 0start dictates in your configured typing_text_case; start_alt (Shift +
the same key) dictates in the other mode — lowercase when you normally type
as-transcribed, as-transcribed when you normally type lowercase. Both share
stop. toggle_alt is the matching toggle for click-style bindings.
tts_speak reads the primary selection first, then falls back to the clipboard.
tts_speak_clipboard reads only the system clipboard — useful in Zellij and
other terminals where you copy text explicitly before triggering TTS.
Primary config: ~/.config/shuvoice/config.toml (wizard-written). Local API keys
belong in ~/.config/shuvoice/local.dev. Manual examples live under examples/.
[asr]
asr_backend = "sherpa" # sherpa | nemo | moonshine | openai_realtime
[typing]
typing_final_injection_mode = "auto" # auto | clipboard | direct
typing_text_case = "default" # default | lowercaseNative Sherpa is static CPU. sherpa_provider = "cuda" fails closed at
setup/preflight/load — there is no Python wheel install or RUNPATH repair path.
See Configuration for full keys, profiles, and TTS.
shuvoice-waybar emits JSON for a Waybar custom/shuvoice module. See
Waybar Integration.
shuvoice preflight
systemctl --user status shuvoice.service
journalctl --user -u shuvoice.service -n 80 --no-pagerCovers feature-off exit 78, layer-shell, audio devices, control socket, worker discovery, and Sherpa CUDA fail-closed behavior: Troubleshooting.
Rust workspace (application):
git clone https://github.com/shuv1337/shuvoice.git
cd shuvoice
cargo fmt
cargo check -p shuvoice-cli # default features = desktop
cargo clippy -p shuvoice-cli -- -D warnings
cargo test -p shuvoice-cliOptional model workers (stdlib only for protocol tests):
cd workers
python -m unittest discover -s tests -vSee CONTRIBUTING.md and AGENTS.md. Architecture
ADRs live under docs/adr/; rewrite map in docs/architecture/RUST_REWRITE.md.
| Repository | github.com/shuv1337/shuvoice |
| AUR Package | shuvoice-git |
| Installation | docs/INSTALLATION.md |
| Configuration | docs/CONFIGURATION.md |
| Waybar | docs/WAYBAR.md |
| Troubleshooting | docs/TROUBLESHOOTING.md |
| Brand Assets | docs/BRANDING.md |
| Security | SECURITY.md |
ShuVoice is released under the MIT License.




