Skip to main content

​
Command

voxtype setup [action] [flags]

​
Description

Interactive and automated setup utilities for installing Voxtype, configuring integrations, and managing models. Running voxtype setup without arguments performs a basic setup: creates directories, generates a default config file, and checks for the configured Whisper model.

​
Flags

​
--download
boolean
Download the configured model if missing (shorthand for basic setup)
​
--model
string
Specify which model to download (use with --download)Whisper models: tiny, base, small, medium, large-v3, large-v3-turbo (and .en variants)Parakeet models: parakeet-tdt-0.6b-v3, parakeet-tdt-0.6b-v3-int8
​
--quiet
boolean
Suppress all output (for scripting/automation)
​
--no-post-install
boolean
Suppress “Next steps” instructions (show progress, but no tutorial)

​
Subcommands

​
check

Run comprehensive system checks: CPU compatibility, directories, config file, input group membership, output chain status, and installed models. 
voxtype setup check
Unlike the default setup command (which is non-blocking and informational), check validates the installation and shows red X marks for failures.

​
systemd

Install Voxtype as a systemd user service. 
voxtype setup systemd
voxtype setup systemd --status
voxtype setup systemd --uninstall
​
--install
boolean
Install the systemd service (default action)
​
--uninstall
boolean
Remove the systemd service
​
--status
boolean
Show service status
Example: 
voxtype setup systemd
systemctl --user enable --now voxtype
voxtype setup systemd --status

​
waybar

Show Waybar configuration snippets for integrating Voxtype status into your bar. 
voxtype setup waybar
voxtype setup waybar --json
voxtype setup waybar --install
​
--json
boolean
Output only the JSON config (for scripting)
​
--css
boolean
Output only the CSS config (for scripting)
​
--install
boolean
Install Waybar integration (inject config and CSS into your Waybar config)
​
--uninstall
boolean
Remove Waybar integration
Example: 
voxtype setup waybar --install
pkill -SIGUSR2 waybar  # Reload Waybar

​
dms

DankMaterialShell (DMS) integration for Plasma desktop widgets. 
voxtype setup dms
voxtype setup dms --install
​
--install
boolean
Install DMS plugin (create widget directory and QML file)
​
--uninstall
boolean
Uninstall DMS plugin
​
--qml
boolean
Output only the QML content (for scripting)

​
model

Interactive model selection and download. 
voxtype setup model                    # Interactive selection
voxtype setup model --list             # List installed models
voxtype setup model --set large-v3     # Set specific model
voxtype setup model --set base --restart
​
--list
boolean
List installed models instead of interactive selection
​
--set
string
Set a specific model as default (must already be downloaded)
​
--restart
boolean
Restart the daemon after changing the model (use with --set)
Example: 
# Download and switch to large-v3-turbo, restart daemon
voxtype setup --download --model large-v3-turbo
voxtype setup model --set large-v3-turbo --restart

​
gpu

Manage GPU acceleration (Vulkan for Whisper, CUDA/ROCm for Parakeet). 
voxtype setup gpu                      # Show status
voxtype setup gpu --enable
voxtype setup gpu --disable
voxtype setup gpu --status
​
--enable
boolean
Enable GPU acceleration (auto-detects best backend: Vulkan, CUDA, or ROCm)
​
--disable
boolean
Disable GPU acceleration (switch back to CPU)
​
--status
boolean
Show current backend status (default action)
GPU acceleration requires the appropriate binary variant:
  • Vulkan: voxtype-*-vulkan (AMD/Intel GPUs)
  • CUDA: voxtype-*-onnx-cuda (NVIDIA GPUs, Parakeet/ONNX only)
  • ROCm: voxtype-*-onnx-rocm (AMD GPUs, Parakeet/ONNX only)

​
onnx

Switch between Whisper and ONNX transcription engines (Parakeet, Moonshine, SenseVoice, etc.). 
voxtype setup onnx                     # Show status
voxtype setup onnx --enable
voxtype setup onnx --disable
​
--enable
boolean
Enable ONNX engine (switch to ONNX binary)
​
--disable
boolean
Disable ONNX engine (switch back to Whisper binary)
​
--status
boolean
Show current ONNX backend status (default action)
ONNX backends support multiple engines via the --engine flag or config engine field:
  • parakeet - NVIDIA Parakeet-TDT (punctuation, streaming)
  • moonshine - UsefulSensors Moonshine (fast, multilingual)
  • sensevoice - Alibaba SenseVoice (emotion detection, event tagging)
  • paraformer - Alibaba Paraformer (timestamp prediction)
  • dolphin - SYSTRAN Faster-Whisper equivalent
  • omnilingual - Multilingual optimized model

​
compositor

Compositor integration (fixes modifier key interference for Hyprland/Sway/River). 
voxtype setup compositor hyprland
voxtype setup compositor sway --show
voxtype setup compositor river --uninstall
​
hyprland
subcommand
Hyprland compositor configuration
​
sway
subcommand
Sway compositor configuration
​
river
subcommand
River compositor configuration
Each compositor subcommand supports:
​
--uninstall
boolean
Uninstall the compositor integration
​
--status
boolean
Show installation status
​
--show
boolean
Show config without installing (print to stdout)
Example (Hyprland): 
voxtype setup compositor hyprland --show   # Preview config
voxtype setup compositor hyprland          # Install
This creates ~/.config/hypr/voxtype.conf with keybinding pass-through rules that prevent modifier keys (like Shift) from interfering with Voxtype recording.

​
vad

Download the Silero VAD model for Voice Activity Detection. 
voxtype setup vad
voxtype setup vad --status
​
--status
boolean
Show VAD model status (default: download)
VAD filters silence before transcription, reducing latency and hallucinations. After downloading, enable in config: 
[vad]
enabled = true
backend = "whisper"  # Or "energy" (no model needed)

​
Examples

​
Basic Setup

# First-time setup (creates directories, config, checks for model)
voxtype setup

# Download the default model (base)
voxtype setup --download

# Download a specific model
voxtype setup --download --model large-v3-turbo

# Silent setup for scripts
voxtype setup --download --model base --quiet

​
Model Management

# Interactive model selection (shows menu)
voxtype setup model

# List what's installed
voxtype setup model --list

# Switch to a different model (must be downloaded first)
voxtype setup model --set medium.en --restart

# Download Parakeet model
voxtype setup --download --model parakeet-tdt-0.6b-v3

​
Integration Setup

# Install as systemd service
voxtype setup systemd
systemctl --user enable --now voxtype

# Add Waybar status widget
voxtype setup waybar --install

# Fix Hyprland modifier keys
voxtype setup compositor hyprland

​
GPU Acceleration

# Check current backend
voxtype setup gpu --status

# Enable GPU (auto-detects Vulkan/CUDA/ROCm)
voxtype setup gpu --enable

# Requires appropriate binary:
# - voxtype-*-vulkan (Whisper + Vulkan)
# - voxtype-*-onnx-cuda (ONNX + CUDA)
# - voxtype-*-onnx-rocm (ONNX + ROCm)

​
System Verification

# Run all checks (shows failures in red)
voxtype setup check

# Check output chain (wtype, ydotool, clipboard)
voxtype config  # Includes output chain status

​
Notes

  • Root warning: Setup commands detect if run as root and warn that models will download to /root/.local/share/voxtype/ instead of your user directory.
  • Model paths: Models are stored in ~/.local/share/voxtype/models/ by default.
  • Config location: ~/.config/voxtype/config.toml
  • Backend switching: When using packaged installations (/usr/bin/voxtype symlink), switching GPU backends only requires a service restart, not reinstalling the service.

Build docs developers (and LLMs) love

Get started for freeTalk to us