Getting started
Install Voisu, add your Deepgram and Groq API keys, and make your first Recording. It takes a few minutes on either platform.
Before you start
- A supported system. Windows 10 or 11 (x64), or Linux: Fedora, Arch, or Debian/Ubuntu. Fedora KDE Plasma on Wayland is the primary Linux target; GNOME, Hyprland and X11 desktops work with the differences noted below.
- Two API keys. Create one at Groq and one at Deepgram. Providers & API keys explains what each one does. You pay the providers directly; Voisu adds no charge.
Using Claude Code, Codex or another terminal agent? Install with an agent gives you a prompt to paste. The agent runs the steps below, and you type your keys into Voisu yourself.
Install
Pick your system. Each tab ends with Voisu running and your keys saved.
Windows
-
Download the installer.
Run it. The installer isn't code-signed yet, so SmartScreen may warn on first run: choose More info → Run anyway. Voisu installs for your user account only.
Add your keys. Voisu opens its setup screen on first launch. Choose Get a free API key on each card, paste your Groq and Deepgram keys, and choose Save and start. Voisu checks each key with its provider before saving it. Both keys are required. The step-by-step Windows guide walks through it with screenshots.
Voisu now lives in the tray and turns on Start at login after your first successful setup. You can close the settings window; it reopens from the tray's Settings… item.
macOS
-
Download the disk image, open it and drag Voisu onto Applications.
Let macOS open it. Voisu isn't notarized yet, so the first open is blocked. Choose Done (not Move to Trash), then System Settings → Privacy & Security → Open Anyway.
Allow the permissions: Microphone, Accessibility (so Voisu can paste) and Input Monitoring (for the Trigger Key). Quit and reopen Voisu once after granting them.
Add your keys. Paste your Groq and Deepgram keys into the setup window and choose Save and start. They're stored in the macOS Keychain.
Then hold Control Option, speak and let go. The step-by-step Mac guide covers each screen.
Fedora
-
Install the package. The overlay is the optional on-screen capsule.
$ sudo dnf copr enable anuraj-dev/voisu $ sudo dnf install voisu # optional on-screen overlay: $ sudo dnf install voisu-overlay
-
Start the daemon for your user. Voisu runs as a systemd user service, so nothing needs root from here on.
$ systemctl --user daemon-reload $ systemctl --user enable --now voisu.service
If you installed the overlay, turn it on too:
$ systemctl --user enable --now voisu-overlay.service Choose your Trigger Key. On KDE Plasma and GNOME, your desktop shows a dialog the first time the daemon starts. Pick the key there; the choice persists.
-
Add your keys. Setup asks for both and checks them with each provider. Afterwards, run
voisuany time to see whether Voisu is ready and to change settings.$ voisu setup
Arch
-
Install the package.
$ yay -S voisu-binTo build from source instead, install
voisu. The two packages conflict, so pick one. -
Run setup. It asks for your API keys and checks them with each provider. Afterwards, run
voisuany time to see whether Voisu is ready and to change settings.$ voisu setupOn Hyprland there is no shortcut dialog, so setup binds the Trigger Key for you: Caps Lock if you accept the default, or Right Alt if you decline or Caps Lock is already bound. It also starts Voisu's services. Using Caps Lock as the Trigger Key stops it toggling caps on that key.
Debian / Ubuntu
-
Add the repository and install.
# Add Voisu's signing key. $ sudo install -d -m 0755 /etc/apt/keyrings $ curl -fsSL https://anuraj-dev.github.io/voisu/voisu-archive-keyring.asc \ | sudo tee /etc/apt/keyrings/voisu-archive-keyring.asc >/dev/null # Add the repository. $ echo 'deb [signed-by=/etc/apt/keyrings/voisu-archive-keyring.asc arch=amd64] https://anuraj-dev.github.io/voisu stable main' \ | sudo tee /etc/apt/sources.list.d/voisu.list # Install. $ sudo apt-get update && sudo apt-get install -y voisu
Signing key fingerprint
4149 EE38 68B3 6B60 0759 2966 D08B CFDC 3412 5B28Verify the key first
# Fetch the key to a temp file and check its fingerprint before trusting it. $ EXPECT=4149EE3868B36B6007592966D08BCFDC34125B28 $ curl -fsSL https://anuraj-dev.github.io/voisu/voisu-archive-keyring.asc -o /tmp/voisu.asc $ gpg --show-keys --with-colons /tmp/voisu.asc \ | awk -F: '$1=="fpr"{print $10; exit}' # The printed fingerprint must equal $EXPECT before you add the key above.
-
Run setup.
$ voisu setupSetup asks for your API keys, enables the daemon and the native GNOME capsule, and uses Ctrl Space as the Trigger Key by default. If it asks, log out and back in, or reboot.
Other desktops (X11, Cinnamon)
Install with your distribution's tab, then bind the Trigger Key yourself. In System Settings → Keyboard → Shortcuts → Custom Shortcuts, add a shortcut that runs:
$ voisu toggleOn X11 Voisu uses xclip for the clipboard, and its feedback arrives as desktop notifications instead of the capsule.
Your first Recording
Click into a text field: an editor, a chat box, a browser address bar.
Windows: hold Ctrl Win and speak. Mac: hold Control Option and speak. Linux: press your Trigger Key once and speak. The capsule appears and shows your voice.
Windows and Mac: release the keys. Linux: press the Trigger Key again.
The capsule switches to Processing, then the Transcript lands at your cursor.
Nothing happened? On Linux, run voisu doctor. It checks the daemon, the shortcut portal, Delivery and your keys, and voisu doctor --verbose explains each result. On Windows, try Test paste (in 3 s) from the tray. Troubleshooting covers the common cases.
Next steps
- Dictating: hands-free, cancelling, what the capsule is telling you, and getting a Transcript back.
- Settings & commands: every setting on Windows and every
voisucommand on Linux. - Privacy: what leaves your computer and what stays on it.