Skip to content
shuv1337Public

About

Real-time push-to-talk speech-to-text for Hyprland/Wayland — streaming ASR overlay with pluggable backends (NeMo, Sherpa ONNX, Moonshine), TTS playback, and instant transcription typed into any window

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Repository files navigation

ShuVoice

ShuVoice logo

Push-to-talk speech-to-text for Hyprland/Wayland.
Hold a key, speak, release, and ShuVoice types the result into the focused window.

CI AUR License: MIT

ShuVoice splash overlay on Hyprland

What it is

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.

Features

  • 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).

Quick Start

# 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.

First Run

shuvoice wizard

Setup wizard welcome

The wizard walks through:

  1. Welcome and environment checks
  2. ASR backend selection
  3. Sherpa profile and device choice when applicable
  4. Push-to-talk key and final text injection mode
  5. TTS provider, voice, speed, and provider settings
  6. 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×.

ASR backend selection

Keybind selection

Usage

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_clipboard

Recommended 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 0

start 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.

Configuration

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 | lowercase

Native 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.

Waybar

Waybar tooltip

shuvoice-waybar emits JSON for a Waybar custom/shuvoice module. See Waybar Integration.

Troubleshooting

shuvoice preflight
systemctl --user status shuvoice.service
journalctl --user -u shuvoice.service -n 80 --no-pager

Covers feature-off exit 78, layer-shell, audio devices, control socket, worker discovery, and Sherpa CUDA fail-closed behavior: Troubleshooting.

Development

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-cli

Optional model workers (stdlib only for protocol tests):

cd workers
python -m unittest discover -s tests -v

See CONTRIBUTING.md and AGENTS.md. Architecture ADRs live under docs/adr/; rewrite map in docs/architecture/RUST_REWRITE.md.

Project Links

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

License

ShuVoice is released under the MIT License.

About

Real-time push-to-talk speech-to-text for Hyprland/Wayland — streaming ASR overlay with pluggable backends (NeMo, Sherpa ONNX, Moonshine), TTS playback, and instant transcription typed into any window

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages