+ Older guides say to right-click the tray icon. Since v0.18.1 the tray menu is slimmer: + Start on Login lives only in Settings → General, where the settings search also finds it + as “autostart”. +
+Added in v0.18.0
++ Speech models stumble on product names, colleagues' names and + project jargon. Vocalinux gives you three tools for that: custom terms + that steer Whisper-family engines toward your vocabulary, transcript + corrections that fix known mishearings on every engine, and a script + hook that can rewrite each result before it is typed. +
++ A plain text list, one term per line, passed to the engine as + context so it is more likely to spell those words your way. +
++ Heard-as and replace-with pairs applied to every finished + transcript, whatever the engine. +
++ Any executable that reads text on stdin and writes the replacement + on stdout. +
+{step.text}
++ Because corrections come before voice commands, a correction can stop + a mishearing from triggering a destructive command. The flip side: + avoid replacements that are themselves command phrases. The command + list is on the voice commands page. +
+
+ Terms live in ~/.config/vocalinux/dictionary.txt by
+ default: UTF-8, one term per line. Blank lines and lines starting with{" "}
+ # are skipped, and duplicates are ignored regardless of
+ case. The plain line format is deliberate, so accessibility tools and
+ scripts can maintain the same file.
+
+ {`# ~/.config/vocalinux/dictionary.txt
+Supabase
+Kubernetes
+PipeWire
+Okonkwo`}
+
+ dictionary.max_words in config.json), and the combined
+ prompt stops at 2,000 characters.
+ + To try a different list without touching saved settings, start + Vocalinux with: +
++ The custom terms controls are disabled for that session. Transcript + corrections still apply. +
+
+ Corrections are stored separately in{" "}
+ ~/.config/vocalinux/custom-dictionary-corrections.json,
+ always in the config directory, whatever terms file you use. The
+ format is versioned:
+
+ {`{
+ "version": 1,
+ "corrections": [
+ { "heard": "super base", "replacement": "Supabase" },
+ { "heard": "pipe wire", "replacement": "PipeWire" }
+ ]
+}`}
+
+ heard matches case-insensitively, only as a whole word
+ or phrase.
+ replacement is inserted with exactly the spelling you
+ typed.
+
+ The path is saved as post_processing.script_path (empty
+ means off). For each completed segment, Vocalinux runs the file like
+ this:
+
| + {label} + | +{value} | +
|---|
+ The example from the Vocalinux user guide. Make it executable with{" "}
+ chmod +x before setting the path.
+
+ {`#!/bin/bash
+tr '[:lower:]' '[:upper:]'`}
+
+ + Reads everything from stdin and writes it back without adding a + newline. Any exception exits non-zero, so Vocalinux falls back to the + original text. +
+
+ {`#!/usr/bin/env python3
+import sys
+
+text = sys.stdin.read()
+sys.stdout.write(text.replace("'", "\\u2019"))`}
+
+ + Before pointing Vocalinux at a script, pipe a sample sentence into it + from a terminal and check that it prints the text back. Output is not + written to the log, but anything your script does with the text + (files, network calls) is up to the script. +
+{item.a}
++ Custom terms help most with a Whisper-family engine; the{" "} + engine comparison and{" "} + advanced settings pages cover + the rest of the tuning. Developers may also like{" "} + dictation for code. +
++ Each of these features has its own setup guide with settings, limits, and troubleshooting. +
+Added in v0.18.0
++ The Dictation Pad is a small Vocalinux window with an editable text + box. When pad capture is on, everything you dictate lands there + instead of being typed into another app. You copy the text out + yourself. Because nothing is injected into other windows, the + compositor rules that make keystroke injection fragile on Wayland + never come into play. +
++ Wayland users whose compositor blocks or garbles injected text, and + anyone who wants to read and fix a draft before it reaches the real + app. +
++ Copy All puts the whole pad on the clipboard. You can also select + part of the text and copy it like any other text box. +
++ Your shortcut, engine, transcript corrections and post-processing + script all work as before. Only the destination of the text changes. +
++ On X11, Vocalinux types into the focused window with xdotool. Wayland + deliberately stops apps from sending keystrokes to each other, so + Vocalinux has to go through IBus, the RemoteDesktop portal, ydotool or + wtype, and which of those works depends on your desktop. Most setups + are covered (see the Wayland guide), but + some compositor and app combinations still drop or mangle text. +
++ The pad is the explicit fallback for those cases. Dictation is written + straight into a Vocalinux window, so there is no injection step left + to fail. Text bound for the pad also lands there even if you switched + to another app while it was being transcribed. +
+{step.text}
++ In v0.18.4 the switch moved to Settings → Dictation, next to the Open + Dictation Pad button. On older 0.18 releases, update first; the{" "} + changelog lists what changed in each + patch. +
+| Setting | +Where | +config.json key | +What it does | +
|---|---|---|---|
| {row.label} | ++ {row.where} + | +
+ {row.key}
+ |
+ {row.note} | +
+ The switch is stored in ~/.config/vocalinux/config.json.
+ Flipping it in Settings applies to the next dictated segment without a
+ restart. The saved value looks like this:
+
+ {`{
+ "text_injection": {
+ "dictate_to_pad": true
+ }
+}`}
+
+ + The text box is editable, so you can fix a word with the keyboard + between dictations. With Voice Commands on, spoken editing commands + target the pad while capture is on: delete that removes the + last dictated segment, undo and redo step through + the pad's own history, and select all,{" "} + select line, select word, select paragraph,{" "} + cut, copy and paste work on the pad's + text. They never reach the app that happens to have focus. The full + command list is on the{" "} + voice commands page. +
++ The tray's Recent Snippets menu keeps your last dictations (10 by + default) in memory. Clicking one copies it to the clipboard, which + helps when a single segment went to the wrong place. +
+/dev/input, or you can turn
+ on External Activation (Desktop Shortcut) and bind{" "}
+ vocalinux --toggle to a desktop shortcut (toggle
+ only, no push-to-talk). See{" "}
+ global shortcuts and{" "}
+ Hyprland and sway.
+
+ {item.a}
++ Install Vocalinux, open Settings → Dictation and switch on Dictate + into Dictation Pad. If injection already works on your desktop, the{" "} + troubleshooting guide covers the + other paths. +
++ + Added in v0.17.0 +
++ Faster Whisper is an optional local speech engine in Vocalinux. It + runs Whisper models through CTranslate2 with int8 quantization on your + CPU and types what you say into the focused app. It is for people who + want Whisper models and the full language catalog on a machine without + a GPU, using a different runtime from the default whisper.cpp. +
+CPU first
++ int8 on the CPU by default. No PyTorch needed for the CPU path. +
+On-device
++ After the one-time model download, recognition runs locally. Audio + stays on your machine. +
+Pinned models
++ Models load only from checksum-verified local files, never from an + unpinned upstream revision. +
++ + faster-whisper + {" "} + is a reimplementation of OpenAI's Whisper on top of + CTranslate2, an inference engine for transformer models. It runs + converted Whisper models and supports reduced precision such as + int8, which lowers memory use on the CPU. +
+
+ Vocalinux added Faster Whisper as an optional engine in v0.17.0,
+ together with Parakeet. whisper.cpp remains the default. Vocalinux
+ stores Faster Whisper models under{" "}
+
+ ~/.local/share/vocalinux/models/
+ {" "}
+ and checks each file against a pinned checksum before loading it.
+
+ {command}
+
+ ))}
+ {step.text}
+
+ To start once with Faster Whisper from a terminal, run{" "}
+
+ vocalinux --engine faster_whisper
+
+ .
+
+ The Model size picker offers these sizes. The .en{" "}
+ variants are English only; if your language is English, Settings
+ suggests the .en variant of the recommended size. There
+ is no large-v3.en.
+
| Size | +Model IDs | +Parameters | +Description | +
|---|---|---|---|
| {row.size} | +{row.ids} | ++ {row.params} + | +{row.desc} | +
+ The suggestion never changes your model or starts a download. If + dictation feels slow, go one size down; if it makes too many mistakes + and speed is fine, go one size up. The{" "} + + Whisper model guide + {" "} + explains the size trade-offs in more depth. +
+
+ Vocalinux chooses the device and precision for you; there is no
+ compute-type setting. On the CPU it loads the model with{" "}
+ int8. If PyTorch is
+ installed and reports a CUDA GPU, it loads the model on CUDA with{" "}
+ float16 instead.
+
+ The installer's Faster Whisper option is the CPU CTranslate2 + path and does not install the CUDA toolkit. If you want GPU + dictation on AMD, Intel or NVIDIA, whisper.cpp with Vulkan is the + supported route; see{" "} + + GPU acceleration + + . +
++ Faster Whisper uses the same language catalog as the other Whisper + engines, including Auto-detect. It also supports{" "} + Follow keyboard layout, which switches the dictation + language with your active layout, and custom dictionary terms that + bias recognition toward names and jargon. See{" "} + + languages by engine + + ,{" "} + + multilingual dictation + {" "} + and{" "} + + custom dictionary + + . +
+| Install method | +Faster Whisper | +Notes | +
|---|---|---|
| {pkg.name} | ++ {pkg.included ? ( + + + Yes + + ) : ( + + + No + + )} + | +{pkg.note} | +
+ All four are local engines. Choose by hardware and by how you + installed Vocalinux. For the full table, see the{" "} + + engine comparison + {" "} + or{" "} + + Parakeet + {" "} + for the other CPU engine added in v0.17.0. +
+| Engine | +Pick it when | +
|---|---|
| + {row.engine} + | +{row.pick} | +
+ If faster-whisper fails to install or import, the installer falls
+ back to whisper.cpp. Read the installer output, then re-run it
+ with{" "}
+
+ --engine=faster_whisper
+
+ .
+
+ The .en models are English only. Pick the size
+ without .en, or set Language to Auto-detect with a
+ multilingual model.
+
+ Go one size down. On CPU-only machines, Tiny or Base is the usual + starting point. Larger sizes take longer per sentence on a CPU. +
+
+ Run{" "}
+ vocalinux --debug{" "}
+ and check{" "}
+
+ ~/.local/share/vocalinux/vocalinux.log
+
+ , then see the{" "}
+
+ troubleshooting guide
+
+ .
+
{faq.answer}
++ Install Vocalinux with the Faster Whisper engine, or keep whisper.cpp + and switch later from Settings → Speech Model. +
+
+ {children}
+
+ Flatpak remote added in v0.18.0
+
+ Vocalinux publishes a signed, self-hosted Flatpak remote called{" "}
+ vocahq on every stable release. It is{" "}
+ not on Flathub: the app comes from VocaHQ, and only
+ the GNOME runtime comes from Flathub. Install once, and{" "}
+ flatpak update picks up each new release.
+
+ Pick the Flatpak if your distribution already uses Flatpak, if you run + an immutable or non-standard layout, or if you want updates handled by + the same tool as your other desktop apps. It runs on x86_64 and + aarch64, and it ships the default whisper.cpp engine with Vulkan GPU + support. +
++ Pick the install script instead if you + want Faster Whisper, Parakeet, OpenAI Whisper or VOSK, or the local + VocaGateway launcher. Those are not in the Flatpak. +
+
+ One command. The .flatpakref adds the{" "}
+ vocahq remote and resolves the GNOME runtime (
+ org.gnome.Platform//50) through Flathub, so no
+ separate Flathub setup is needed.
+
+ If you prefer explicit remotes, add flathub, add vocahq, then
+ install com.vocalinux.Vocalinux from vocahq:
+
+ Launch Vocalinux from your app menu, or run: +
++ Pick a model in Settings → Speech Model. Since v0.18.4 Vocalinux + shows the download size and asks before downloading anything. + After that one download, the whisper.cpp engine transcribes on + your machine. Then hold Right Alt and speak. +
+
+ Every stable v* tag is imported into the remote, signed
+ with the VocaHQ GPG key and published with static deltas, so an update
+ downloads only what changed:
+
.flatpak bundle on GitHub Releases.
+ Vocalinux-<version>-x86_64.flatpak or{" "}
+ -aarch64.flatpak) do not auto-update. Switch to the
+ remote if you installed one.
+
+ After a signing-key rotation, existing installs must import the new
+ public key. Re-running remote-add does not replace it.
+ The documented fix:
+
| Feature | +In the Flatpak? | +Notes | +
|---|---|---|
| whisper.cpp engine | +Yes | +
+ Built with Vulkan; the GPU is reached through{" "}
+ --device=dri
+ |
+
| Silero neural VAD | +Yes | ++ onnxruntime bundled since v0.18.4 + | +
| Remote API engine | +Yes | ++ Audio leaves the machine for the endpoint you configure + | +
| + Faster Whisper, Parakeet, OpenAI Whisper, VOSK + | +No | ++ Use the install script or a source install + | +
| + Local VocaGateway launcher + | +No | ++ The sandbox cannot reach the host podman or docker socket + | +
+ Config and models live under{" "}
+ ~/.var/app/com.vocalinux.Vocalinux/, not{" "}
+ ~/.config/vocalinux.
+
+ The manifest asks for the microphone (--socket=pulseaudio
+ ), the GPU (--device=dri), network for model downloads,
+ the Wayland and X11 sockets, IBus and the tray watcher on D-Bus, and{" "}
+ --device=all for keyboard devices and{" "}
+ /dev/uinput. Flatpak has no narrower flag for uinput.
+
/dev/input.
+ /dev/input. If you
+ tighten permissions, grant --device=input on Flatpak
+ 1.15.6 or newer, or --device=all on older versions.
+ + To drop device access but keep the GPU for whisper.cpp: +
+
+ Text injection prefers the RemoteDesktop portal, which asks for
+ permission once and handles non-US layouts. When the portal is
+ unavailable it falls back to wl-copy plus ydotool paste,
+ then xdotool for X11 and XWayland clients. Without{" "}
+ /dev/uinput the ydotool fallback is gone, but the portal
+ and xdotool remain. On KDE Plasma Wayland, set System Settings →
+ Keyboard → Virtual Keyboard to “IBus Wayland”. On GNOME,
+ the tray icon needs the AppIndicator extension. For more, see{" "}
+ Wayland voice typing and{" "}
+ global shortcuts via D-Bus.
+
+ The uninstall.sh script is for script and source
+ installs. For the Flatpak, use Flatpak itself. Remove the app:
+
+ Add --delete-data to also remove settings and downloaded
+ models under ~/.var/app/com.vocalinux.Vocalinux/. If no
+ other app uses the remote, drop it too:
+
{faq.answer}
++ + + More fixes for hotkeys, audio and text injection are on the{" "} + troubleshooting page. To keep + the whole stack local, see the{" "} + GPU acceleration guide and{" "} + Silero VAD. + +
++ The install script covers every engine, the AUR and Nix flake fit Arch + and NixOS, and the .deb and .rpm suit Debian, Ubuntu and Fedora. +
+
+ {children}
+
+ );
+}
+
+function ConfigBlock({ label, children }: { label: string; children: string }) {
+ return (
+
+ {children}
+
+ Added in v0.18.0
++ Vocalinux can hand hotkey duty to your desktop. A running instance + answers on the session D-Bus, so a GNOME or KDE custom shortcut, a + sway or Hyprland bind, or any script can start and stop voice typing + without Vocalinux reading your keyboard. +
+
+ On Wayland the built-in listener reads{" "}
+
+ Your desktop sends the key press only. Press once to start, press + again to stop. +
++ Separate Start and Stop methods let scripts set a known state + instead of flipping it. +
+
+ These names come from
| + {row.item} + | ++ {row.value} + | +
|---|
| + Command + | ++ D-Bus method + | ++ Effect + | +
|---|---|---|
| {row.cli} | ++ {row.method} + | +{row.effect} | +
+ The
{step.text}
+
+ The same switch is stored as{" "}
+
+ The key combination is your choice; the examples use Super+Shift+D. + Only the command matters to Vocalinux. Menu names and config syntax + belong to each desktop and can differ between versions. +
+
+ In Settings → Keyboard, open the custom shortcuts list, add a
+ shortcut, enter
+ Open System Settings → Keyboard → Shortcuts → Add New → Command or
+ Script (older Plasma: System Settings → Shortcuts → Custom Shortcuts →
+ Edit → New → Global Shortcut → Command/URL) and bind your keys to{" "}
+
+ If your compositor cannot find
{faq.answer}
++ Related:{" "} + + shortcuts and voice commands + + ,{" "} + + GNOME and KDE + + ,{" "} + + Flatpak + {" "} + and{" "} + + troubleshooting + + . +
++ Install Vocalinux, turn on External Activation, and let your desktop + own the shortcut. +
+
+ {children}
+
+ );
+}
+
+function ConfigBlock({ label, children }: { label: string; children: string }) {
+ return (
+
+ {children}
+
+ Tiling compositors
++ Tiling setups are hand-built, so Vocalinux cannot assume the pieces a + full desktop provides. This guide covers which text injection backend + applies on each compositor, how to bind dictation to a key in your + config, and the fallback that works when typing into other windows + does not. +
+| + Compositor / WM + | ++ Status + | ++ Session + | ++ Notes + | +
|---|---|---|---|
| + {row.name} + | +{row.status} | ++ {row.session} + | +{row.notes} | +
+ Status comes from the project's desktop compatibility table. For + GNOME, KDE and the general Wayland picture, see{" "} + + voice dictation on Wayland + + . +
+
+ Vocalinux picks a backend automatically. On Wayland, when IBus is not
+ selected, it tries the RemoteDesktop portal first, then ydotool, then
+ wtype, and finally xdotool for XWayland windows. sway and Hyprland are
+ on its list of compositors that do not bridge IBus to native Wayland
+ apps, so IBus is skipped there unless the{" "}
+
| + Backend (config value) + | ++ Where it applies + | ++ Needs + | +
|---|---|---|
| + {row.backend} + | ++ {row.where} + | +{row.needs} | +
+ Edit
+ To try a backend for one run without saving it: +
++ When text goes in through the clipboard, Vocalinux sends Ctrl+V in + normal fields and Ctrl+Shift+V in terminal windows. Terminal detection + works on Hyprland, sway and niri. +
+{step.text}
+
+ On Wayland the built-in hotkey reads{" "}
+
+ Or keep the built-in listener and join the group, then log out and + back in: +
++ The full D-Bus interface and Flatpak command are in{" "} + + global shortcuts + + . Minimal window-manager sessions may also need their own autostart + line; see{" "} + + autostart + + . +
++ If no backend types reliably on your setup, send dictation to the + Dictation Pad instead (added in v0.18.0). It is an in-app window that + receives the text, and you copy it out by hand, so no injection path + is involved. Turn on Settings → Dictation → Dictate into Dictation + Pad, then open it with Open Dictation Pad in the same group or + Dictation Pad in the tray menu. Later releases fixed the pad ghosting + away when idle under a Wayland compositor (v0.18.1) and stopped it + travelling between workspaces with Settings (v0.18.5). Details on the{" "} + + Dictation Pad page + + . +
++ Install the Wayland tools and test them by hand, then run Vocalinux + with debug logging and check which backend it reports. The startup log + records a pin request; a live test in the target app is the real + confirmation. +
+
+ ydotool needs
+ Confirm you are in the
{faq.answer}
++ More help:{" "} + + troubleshooting + {" "} + and{" "} + + desktop reliability + + . +
++ Install Vocalinux, check that wtype or xdotool can type, and bind + dictation to a key in your compositor config. +
+-
{config.intro}
++ {config.intro} +
+ Support levels come from the project’s distribution + compatibility matrix. They describe expected compatibility, not a + list of test machines. +
+ {option.note} +
+
+ {option.command}
+
+ + Compare every package format on the + + install overview + + , or read the + + Flatpak guide + + . +
+Need help selecting an engine? Read the - - whisper.cpp vs Whisper vs VOSK comparison + + engine comparison + + . Stuck? See + + troubleshooting .
diff --git a/web/src/app/install/nixos/page.tsx b/web/src/app/install/nixos/page.tsx new file mode 100644 index 0000000..493e9cf --- /dev/null +++ b/web/src/app/install/nixos/page.tsx @@ -0,0 +1,418 @@ +import Link from "next/link"; +import { type Metadata } from "next"; +import { + AlertTriangle, + Braces, + CheckCircle2, + ChevronRight, + CircleHelp, + Settings2, + Terminal, +} from "lucide-react"; +import { SeoSubpageShell } from "@/components/seo-subpage-shell"; +import { absoluteUrl, buildPageMetadata } from "@/lib/seo"; + +const PAGE_PATH = "/install/nixos"; +const PAGE_TITLE = "Vocalinux on NixOS: Nix Flake and NixOS Module | Vocalinux"; +const PAGE_DESCRIPTION = + "Install Vocalinux on NixOS or any Nix system with the official flake: nix run, nix profile, the NixOS and Home Manager modules, Wayland groups and scope."; + +const TRY_COMMANDS = `nix run github:VocaHQ/vocalinux # try it +nix profile install github:VocaHQ/vocalinux`; + +const NIXOS_SNIPPET = `{ + inputs.vocalinux.url = "github:VocaHQ/vocalinux"; + + outputs = { nixpkgs, vocalinux, ... }: { + nixosConfigurations.host = nixpkgs.lib.nixosSystem { + modules = [ + vocalinux.nixosModules.vocalinux + { + programs.vocalinux.enable = true; + users.users.you.extraGroups = [ "input" "uinput" ]; + } + ]; + }; + }; +}`; + +const HOME_MANAGER_SNIPPET = `{ + inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + inputs.home-manager.url = "github:nix-community/home-manager"; + inputs.home-manager.inputs.nixpkgs.follows = "nixpkgs"; + inputs.vocalinux.url = "github:VocaHQ/vocalinux"; + + outputs = { nixpkgs, home-manager, vocalinux, ... }: { + homeConfigurations.you = home-manager.lib.homeManagerConfiguration { + pkgs = nixpkgs.legacyPackages.x86_64-linux; + modules = [ + vocalinux.homeManagerModules.vocalinux + { programs.vocalinux.enable = true; } + ]; + }; + }; +}`; + +const flakeOutputs = [ + { + output: "packages.
+ {children}
+
+ Added in v0.18.2
++ The Vocalinux repository is a Nix flake. It builds the app against + nixpkgs, ships a NixOS module and a Home Manager module, and wires + every text-injection and clipboard tool onto the wrapped + binary’s PATH. Use it on NixOS, or on any Linux with Nix and + flakes enabled. +
+
+ No configuration needed. nix run starts Vocalinux once;{" "}
+ nix profile install keeps it in your user profile:
+
+ On a non-NixOS host, pair nix profile install with your
+ distro’s udev rule and group membership for{" "}
+ /dev/uinput and /dev/input if you use
+ Wayland.
+
{step.text}
+
+ The documented flake, with host and you{" "}
+ replaced by your hostname and user:
+
+ hardware.uinput.enable, which the module sets, loads the
+ uinput kernel module, creates the uinput group and
+ installs the matching udev rule. ydotool and the evdev backend’s
+ keyboard clone both open /dev/uinput. Group membership
+ stays per user because input grants read access to every
+ keyboard and pointer device.
+
+ homeManagerModules.vocalinux takes the same{" "}
+ programs.vocalinux options and installs into your home
+ profile. Device permissions are a system concern, so on NixOS keep the
+ NixOS module (or the group lines) on the system side.
+
| Flake output | +Use | +
|---|---|
| {row.output} | +{row.purpose} | +
+ The vosk, whisper, parakeet and{" "}
+ faster_whisper extras are not packaged, so{" "}
+ Parakeet and{" "}
+ Faster Whisper need the install
+ script on another distro. The flake follows{" "}
+ nixos-unstable and builds for x86_64-linux and
+ aarch64-linux.
+
install.sh on NixOS. It expects a
+ conventional filesystem layout; the flake is the supported path.
+ input membership, the hotkey is
+ disabled. Bind a compositor shortcut through{" "}
+ D-Bus activation instead; it
+ toggles, it cannot push-to-talk.
+ {faq.answer}
++ Not on Nix? The install script, AUR, .deb, .rpm, AppImage and the + VocaHQ Flatpak remote cover most other systems. +
+Auto-updates
+ {children}
+
+ );
+}
+
+export default function LocalGatewayPage() {
+ const jsonLd = {
+ "@context": "https://schema.org",
+ "@graph": [
+ {
+ "@type": "TechArticle",
+ headline: PAGE_TITLE,
+ description: PAGE_DESCRIPTION,
+ dateModified: "2026-11-01",
+ author: {
+ "@type": "Person",
+ name: "Jatin K Malik",
+ url: "https://github.com/jatinkrmalik",
+ },
+ publisher: {
+ "@type": "Organization",
+ name: "Vocalinux",
+ logo: {
+ "@type": "ImageObject",
+ url: absoluteUrl("/vocalinux.png"),
+ },
+ },
+ mainEntityOfPage: absoluteUrl(PAGE_PATH),
+ },
+ {
+ "@type": "HowTo",
+ name: "Run a local VocaGateway from Vocalinux Settings",
+ step: steps.map((step, index) => ({
+ "@type": "HowToStep",
+ position: index + 1,
+ name: step.name,
+ text: step.text,
+ })),
+ },
+ {
+ "@type": "FAQPage",
+ mainEntity: faqs.map((faq) => ({
+ "@type": "Question",
+ name: faq.question,
+ acceptedAnswer: { "@type": "Answer", text: faq.answer },
+ })),
+ },
+ ],
+ };
+
+ return (
+ Added in v0.18.0 · optional
++ Vocalinux can start{" "} + + VocaGateway + + , the self-hosted speech gateway in the Voca family, as a podman or + docker container from its own Settings. It is a power-user path for + people who want one transcription service shared by the desktop and a + paired phone. +
+
+ With a local engine, audio is transcribed on this machine by Vocalinux
+ itself. In gateway mode it is sent over HTTP to the gateway, even when
+ that gateway runs on
| + Mode + | ++ Audio + | ++ Setup + | ++ Network + | +
|---|---|---|---|
| + {row.mode} + | ++ {row.audio} + | ++ {row.setup} + | +{row.network} | +
{step.text}
+| + {row.status} + | +{row.meaning} | +
|---|
+ Pairable can appear before Ready, so a phone can pair while a model is + still downloading. +
+
+ This switch publishes the gateway on{" "}
+
+ The container keeps running after you quit Vocalinux, including a + LAN-published one. Use Stop local Gateway in Settings or the tray + menu, which appears whenever Compose is running. Stopping keeps the + named data volume, so downloaded models survive. Vocalinux does not + start the gateway on login. +
++ You can also run VocaGateway on a stronger box and enter its address + in Remote Server by hand. Audio then crosses your network, so prefer a + trusted LAN, Tailscale or HTTPS. Read the{" "} + + VocaGateway documentation + + {" "} + for server-side setup. +
+{faq.answer}
++ Related:{" "} + + offline dictation + + ,{" "} + + privacy + + ,{" "} + + Flatpak limitations + {" "} + and{" "} + + GPU acceleration + {" "} + for faster on-device engines. +
++ Install Vocalinux with the default on-device engine. Add a local + VocaGateway only if you need a shared transcription service. +
+Added in v0.18.0
++ Per-language shortcuts and Follow keyboard layout arrived in v0.18.0. + If you write in more than one language, Vocalinux gives you three ways + to get the right one each time: auto-detect per utterance, a separate + shortcut per language, or following whichever keyboard layout you are + typing with. This page covers each, which engines support them, and + where they fall short. For a per-language view of engine support, see + the languages page. +
++ The engine guesses the language for each utterance. Easiest to set + up, but short clips can be guessed wrong. +
++ A dedicated key per language. Explicit and reliable, for one + dictation at a time. +
++ Switch layout to switch dictation language. Best on GNOME, where the + active layout can be read. +
++ Settings → Speech Model opens with a simple Language group. Pick your + Main language from the searchable list. Turning on Other languages + makes the engine guess the language each time; the optional Other + language picker just records which one you had in mind, because + Whisper-family engines take a single language or none. On first run, + Vocalinux seeds the language from your keyboard layout and locale + (since v0.17.0). +
+
+ Picking a language other than English switches off an English-only
+ model. From the command line, --language accepts{" "}
+ auto or any catalog code below.
+
{step.text}
++ Bindings take effect immediately. A binding can also point at + Auto-detect. If two rows use the same key, the first one wins. More on + shortcut syntax and modes is on the{" "} + shortcuts page. +
++ Expand Advanced on the Speech Model page and turn on Follow keyboard + layout. Vocalinux then re-reads the active layout at the start of + every dictation and uses the matching language. The Language picker + greys out and shows what the current layout resolves to; turning the + switch off pins that language. +
+
+ Settings writes these to ~/.config/vocalinux/config.json.
+ The value "layout" is how Follow keyboard
+ layout is stored:
+
+ {`{
+ "speech_recognition": {
+ "language": "layout"
+ },
+ "shortcuts": {
+ "language_shortcuts": [
+ { "shortcut": "ctrl+alt+d", "language": "de" },
+ { "shortcut": "f10", "language": "fr" }
+ ]
+ }
+}`}
+
+
+ On whisper.cpp, Settings → Advanced (after Unlock Advanced Settings)
+ also has Language Candidates: a comma-separated list such as{" "}
+ en,es that restricts auto-detect to those languages.
+ Leave it blank to consider all languages.
+
| Engine | +Language picker | +Follow layout | +Language shortcuts | +Notes | +
|---|---|---|---|---|
| {row.engine} | ++ {row.picker} + | ++ {row.layout} + | ++ {row.shortcuts} + | +{row.note} | +
+ VOSK lists only languages that have an official Alphacephei model, 21 + of the 33. Parakeet's v3-european model covers 25 European + languages and ignores the picker; see{" "} + Parakeet on Linux. For Whisper model + sizes, see the{" "} + Whisper model guide. The + Remote API sends your audio to the endpoint you configured; details + are on the Remote API page. +
++ 33 languages plus Auto-detect, shared by Settings, language shortcuts + and the CLI. Slovenian was added in v0.18.4. +
+| Language | +Code | +VOSK model | +
|---|---|---|
| {lang.name} | +
+ {lang.code}
+ |
+ + {lang.vosk ? ( + + + Yes + + ) : ( + "No (Whisper-family only)" + )} + | +
{item.a}
++ Install Vocalinux, keep the default whisper.cpp engine with a + multilingual model, and add a shortcut for each language you write in. + Names and jargon in any language can go in the{" "} + custom dictionary. +
+- Android beta and iOS TestFlight. On-device first, gateway - optional. + Android on Google Play and iOS TestFlight. On-device first, + gateway optional.
({ + "@type": "HowToStep", + position: index + 1, + name: step.title, + text: step.text, + })), + }, + { + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((faq) => ({ + "@type": "Question", + name: faq.question, + acceptedAnswer: { "@type": "Answer", text: faq.answer }, + })), + }, + ]; + + return ( ++ + Added in v0.17.0 +
++ Parakeet is an optional local speech engine in Vocalinux. It runs + NVIDIA's Parakeet TDT 0.6B models on your CPU through sherpa-onnx + and types what you say into the focused app, with no cloud + transcription. It suits people who dictate in English or a European + language and want a CPU engine with a short list of models to choose + from. +
+On-device
++ After the one-time model download, recognition runs locally. Audio + stays on your machine. +
++ 25 European languages +
++ The default v3-european model covers 25 European languages. + v2-english is English only. +
++ Verified downloads +
++ Models come from pinned Hugging Face revisions and are checked + against SHA-256 pins before loading. +
++ Parakeet is a family of automatic speech recognition models from + NVIDIA's NeMo toolkit. Vocalinux uses the TDT 0.6B models, + which are transducer models: they turn audio straight into text + tokens rather than generating text the way Whisper does. Vocalinux + loads int8 ONNX exports of these models with{" "} + + sherpa-onnx + + , a speech runtime that runs on an ordinary CPU. +
++ Parakeet arrived in Vocalinux v0.17.0 alongside Faster Whisper. + whisper.cpp is still the default engine; Parakeet is something you + opt into. +
+
+ {command}
+
+ ))}
+ {step.text}
+
+ To start once with Parakeet from a terminal, run{" "}
+
+ vocalinux --engine parakeet
+
+ . In{" "}
+
+ ~/.config/vocalinux/config.json
+ {" "}
+ the engine name is{" "}
+ parakeet.
+
+ The Model size picker lists three models for the Parakeet engine. + Sizes are the catalog values Vocalinux shows before a download. +
+| Model ID | +Model | +Languages | +Download | +Notes | +
|---|---|---|---|---|
| {model.id} | +{model.name} | ++ {model.languages} + | ++ {model.size} + | +{model.notes} | +
+ Orukeet v0.1.0 was added in v0.18.0. It uses the same local + sherpa-onnx recognizer and covers 25 European languages; the + recommended Parakeet model and the default whisper.cpp engine are + unchanged. Vocalinux downloads it from a pinned revision of{" "} + + oruk/orukeet on Hugging Face + + , checks every file against bundled SHA-256 pins, and checks the + publisher's release manifest against those same pins. Its CC + BY-SA 4.0 weights license and NVIDIA attribution are saved with the + model. +
++ With Parakeet, the model decides the language, not the Language + picker. Vocalinux treats the language as auto for this engine, so a + language you chose for whisper.cpp is not passed to Parakeet. Choose + v2-english if you only speak English, or v3-european (or Orukeet) + for the 25-language European set. +
++ Two related features do not apply to Parakeet:{" "} + Follow keyboard layout works with whisper.cpp, + Whisper, Faster Whisper and the Remote API only, and custom + dictionary terms bias only the Whisper-family engines. + Transcript corrections from the custom dictionary do run after + Parakeet. See{" "} + + languages by engine + + ,{" "} + + multilingual dictation + {" "} + and{" "} + + custom dictionary + + . +
+
+ Parakeet runs on the CPU. Vocalinux's Vulkan and CUDA
+ acceleration applies to whisper.cpp, so a GPU does not speed up
+ Parakeet (see{" "}
+
+ GPU acceleration
+
+ ). Plan for roughly 640 MB of disk per Parakeet model, stored under{" "}
+
+ ~/.local/share/vocalinux/models/
+
+ .
+
| Install method | +Parakeet | +Notes | +
|---|---|---|
| {pkg.name} | ++ {pkg.parakeet ? ( + + + Yes + + ) : ( + + + No + + )} + | +{pkg.note} | +
+ Both are local engines. The differences are about languages, hardware + and packaging rather than a single winner. For every engine side by + side, see the{" "} + + engine comparison + + ; for whisper.cpp sizes, see the{" "} + + Whisper model guide + + . +
+| + Topic + | +Parakeet | +whisper.cpp | +
|---|---|---|
| + {row.topic} + | ++ {row.parakeet} + | ++ {row.whisperCpp} + | +
+ Pick Parakeet if you dictate in English or a supported European + language on a CPU-only machine and installed with install.sh, from + source or from the AUR. Stay on whisper.cpp if you use a language + outside that set, want GPU acceleration, rely on custom dictionary + terms, or installed the AppImage, Flatpak, Snap, .deb or .rpm. +
+
+ Settings lists only engines whose libraries are installed.
+ Parakeet appears once sherpa-onnx can be imported. Re-run the
+ installer with{" "}
+ --engine=parakeet.
+ Installs of this engine through install.sh were broken before
+ v0.18.4, so use a current installer; on Arch, install
+ python-sherpa-onnx.
+
+ Vocalinux refuses to load Parakeet files that fail checksum + verification. In Settings → Speech Model, delete the leftover + model from Unused downloads and download it + again. +
++ The Language picker does not steer Parakeet. If you only dictate + English, switch the model to v2-english. For a language outside + the European set, use whisper.cpp. +
+
+ Run{" "}
+ vocalinux --debug{" "}
+ and check{" "}
+
+ ~/.local/share/vocalinux/vocalinux.log
+
+ , then see the{" "}
+
+ troubleshooting guide
+
+ .
+
{faq.answer}
++ Install Vocalinux with the Parakeet engine, or start with whisper.cpp + and compare. Also see{" "} + + Faster Whisper on Linux + + , the other CPU engine added in v0.17.0. +
+
+ {children}
+
+ );
+}
+
+export default function PipeWirePage() {
+ const jsonLd = {
+ "@context": "https://schema.org",
+ "@graph": [
+ {
+ "@type": "TechArticle",
+ headline: PAGE_TITLE,
+ description: PAGE_DESCRIPTION,
+ dateModified: "2026-11-01",
+ author: {
+ "@type": "Person",
+ name: "Jatin K Malik",
+ url: "https://github.com/jatinkrmalik",
+ },
+ publisher: {
+ "@type": "Organization",
+ name: "Vocalinux",
+ logo: {
+ "@type": "ImageObject",
+ url: absoluteUrl("/vocalinux.png"),
+ },
+ },
+ mainEntityOfPage: absoluteUrl(PAGE_PATH),
+ },
+ {
+ "@type": "HowTo",
+ name: "Choose an audio source for Vocalinux dictation",
+ step: steps.map((step, index) => ({
+ "@type": "HowToStep",
+ position: index + 1,
+ name: step.name,
+ text: step.text,
+ })),
+ },
+ {
+ "@type": "FAQPage",
+ mainEntity: faqs.map((faq) => ({
+ "@type": "Question",
+ name: faq.question,
+ acceptedAnswer: { "@type": "Answer", text: faq.answer },
+ })),
+ },
+ ],
+ };
+
+ return (
+ Added in v0.18.0
++ Vocalinux records from two kinds of source: microphones, opened + through PortAudio, and system-audio sources that come straight from + PipeWire. This page explains what each one is for, how to pick the + right source, and what to check when dictation hears the wrong device + or nothing at all. +
+
+ PortAudio enumerates ALSA and PulseAudio devices, not PipeWire nodes.
+ That works well for microphones, but it cannot see a sink's
+ monitor, the stream of everything playing through an output. Since
+ v0.18.0 Vocalinux asks PipeWire directly: it lists sinks with{" "}
+
| + Path + | ++ What it lists + | ++ How it records + | ++ Use it for + | +
|---|---|---|---|
| + {row.path} + | ++ {row.lists} + | ++ {row.records} + | +{row.use} | +
+ Most people dictate into a microphone and never need to change + anything. System audio is for the cases a microphone cannot cover + well, such as transcribing speech from a video or a call that plays + through your speakers or headphones. For recorded files, the{" "} + + file transcription mode + {" "} + is usually the better tool. +
+{step.text}
++ Leaves valid default and virtual inputs under the sound + server's control, so the mic you pick in desktop sound + settings is the one Vocalinux hears. +
++ A valid explicit choice always wins over System Default. Vocalinux + saves the device name and matches it again by name when indexes + shift after a replug. +
++ Records one output device's monitor. Two sinks with the same + description get the PipeWire node name added in brackets so you + can tell them apart. +
+
+ The selection lives in{" "}
+
+ Select the mic by name in Settings → Audio → Input Device rather than
+ relying on System Default. On ALSA-only setups where PortAudio
+ substitutes some other hardware for the default input, Vocalinux
+ prefers an input-capable
+ Check mute state and levels in your system sound settings, then list + capture hardware: +
+
+ A Microphone Stalled notification means the selected input stopped
+ delivering audio and Vocalinux stopped that attempt. Use Microphone
+ Test, or choose another Input Device. If a stale device index is the
+ problem, quit Vocalinux and set{" "}
+
+ Bluetooth headset microphones use a separate capture profile that is + sensitive to repeated opening. Vocalinux opens the stream once per + session and pauses briefly between failed attempts on Bluetooth + devices. If capture still fails, try a wired microphone to check + whether the Bluetooth capture path is the cause. +
+{faq.answer}
++ More fixes on the{" "} + + troubleshooting page + + . How audio is handled with local and remote engines is covered in{" "} + + offline dictation + {" "} + and{" "} + + Remote API + + . Speech detection itself is explained in{" "} + + voice activity detection + + . +
++ Install Vocalinux, choose your microphone or a system-audio source in + Settings → Audio, and run the Microphone Test before your first + dictation. +
+Added in v0.18.0
++ Vocalinux can turn a recorded meeting, interview or voice memo into a + text transcript on your own machine. It uses TinyDiarize, a + whisper.cpp model that also marks where the speaker changes, so the + transcript comes out as timestamped blocks labelled Speaker 1, Speaker + 2 and so on. Start it from the tray or from a terminal. +
++ File transcription is separate from the dictation pipeline. It never + types into other apps and does not change your dictation model. +
+
+ The model is small.en-tdrz. It is English-only, so use
+ it for English recordings.
+
+ Audio is decoded and transcribed on your computer. Nothing is sent + to a server. +
+{step.text}
++ The model download is checked against a pinned SHA-256 digest before + use, like every other Vocalinux model. The status line under the + transcript reports how many blocks were found and the highest speaker + number. +
+
+ --transcribe-file PATH transcribes one file, prints the
+ diarized transcript to standard output and exits:
+
vocalinux: could not transcribe, and the exit
+ status is 1. A file with no detectable speech prints{" "}
+ vocalinux: no speech detected.
+ | Input | +How Vocalinux reads it | +
|---|---|
| {row.input} | +{row.path} | +
+ Vocalinux does not install ffmpeg for you. Without it, only 16-bit 16 + kHz WAV files can be transcribed, and the tray picker's filter + says so. +
+
+ Each block is one speaker turn: a [HH:MM:SS] timestamp
+ for where it starts, the speaker label, then the text. Blocks are
+ separated by a blank line. The Transcript window, Copy, Save As and
+ the CLI all use the same layout. The lines below show the shape only;
+ they are not real output.
+
+ {`[00:00:00] Speaker 1:
+
+[00:00:14] Speaker 2:
+
+[00:00:31] Speaker 3: `}
+
+ + TinyDiarize is a small, English-only whisper.cpp model whose output + includes a speaker-turn marker wherever it detects a change of voice. + Vocalinux runs it in whisper.cpp's tinydiarize mode and splits + the text at each marker. Each new block gets the next number. +
++ That makes the labels positional, not identities. In a two-person + interview the transcript reads Speaker 1, Speaker 2, Speaker 3, + Speaker 4 as the two people take turns, rather than alternating + between 1 and 2. Turn boundaries are useful for reading and editing; + assigning names is up to you. +
++ More on what stays on your machine:{" "} + offline dictation and the{" "} + privacy policy. +
+{item.a}
+
+ File transcription is available from v0.18.0; check yours with{" "}
+ vocalinux --version. For live dictation model choices,
+ see the Whisper model guide;
+ to fix names the model mishears in dictation, use the{" "}
+ custom dictionary.
+