Voxtype

https://voxtype.io/docs
Admin
Voxtype is a Linux voice typing application that enables hands-free text input through speech...
Tokens:156,136
Snippets:1,454
Trust Score:4.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Initial setup commands

Source: https://voxtype.io/docs/USER_MANUAL

Initial setup commands: verify input group membership, run the setup wizard to download the default Whisper model (base.en) and create the configuration file, then start the daemon.

```bash
# 1. Ensure you're in the input group
groups | grep input

# 2. Run the setup wizard
voxtype setup --download

# 3. Start voxtype
voxtype
```

--------------------------------

### voxtype setup dms with install, uninstall, and qml options

Source: https://voxtype.io/docs/USER_MANUAL

Install a status widget for DankMaterialShell (KDE Plasma alternative shell). Options: --install, --uninstall, --qml.

```bash
voxtype setup dms              # Show setup instructions
voxtype setup dms --install    # Install the QML widget plugin
voxtype setup dms --uninstall  # Remove the widget
voxtype setup dms --qml        # Output raw QML content
```

--------------------------------

### Verify voxtype setup

Source: https://voxtype.io/docs/TROUBLESHOOTING

Run 'voxtype setup' to show which output tools are installed and available.

```bash
voxtype setup
```

--------------------------------

### Example session output

Source: https://voxtype.io/docs/USER_MANUAL

Example session output showing the daemon starting with the default model, hotkey, and output mode, and the ready message.

```bash
$ voxtype
[INFO] Voxtype v0.1.0 starting...
[INFO] Using model: base.en
[INFO] Hotkey: SCROLLLOCK
[INFO] Output mode: type (fallback: clipboard)
[INFO] Ready! Hold SCROLLLOCK to record.
```

--------------------------------

### Setup for GNOME, KDE, and Other Desktops

Source: https://voxtype.io/docs

Commands to add the user to the input group, download the whisper model, install the systemd service, and check status. Uses kernel-level hotkey detection.

```bash
# Add user to input group (required for hotkey detection)
sudo usermod -aG input $USER
# Log out and back in for group change to take effect

# Download whisper model and configure
voxtype setup --download

# Install as systemd service (starts on login)
voxtype setup systemd

# Check status
systemctl --user status voxtype
```

--------------------------------

### Install Quickshell QML tree

Source: https://voxtype.io/docs/CONFIGURATION

Copies QML files to the user data directory, symlinks the audio bridge to PATH, and prints compositor binding examples. Pass --skip-bridge if the bridge is already on PATH.

```bash
voxtype setup quickshell
```

--------------------------------

### voxtype setup quickshell with target, source, force, bindings, and bridge options

Source: https://voxtype.io/docs/USER_MANUAL

Install the Quickshell QML tree so voxtype-osd-quickshell can find it. Options: --target, --source, --force, --print-bindings, --bridge, --bridge-target, --skip-bridge. Refuses writing outside $HOME unless --force is passed.

```bash
voxtype setup quickshell                       # Install QML + symlink the bridge
voxtype setup quickshell --target DIR          # Install QML to a custom location
voxtype setup quickshell --source DIR          # Override the source tree (default: auto-detect)
voxtype setup quickshell --force               # Overwrite an existing install
voxtype setup quickshell --print-bindings      # Print the bindings only, do not copy
voxtype setup quickshell --bridge PATH         # Override the audio-bridge source binary
voxtype setup quickshell --bridge-target PATH  # Override the audio-bridge symlink location
voxtype setup quickshell --skip-bridge         # Skip the audio-bridge symlink entirely
```

--------------------------------

### Example configuration with profiles

Source: https://voxtype.io/docs/CONFIGURATION

Full example showing default post-processing and profiles for Slack, code, and notes.

```toml
# Default post-processing
[output.post_process]
command = "ollama run llama3.2:1b 'Clean up:'"
timeout_ms = 30000

# Profile: casual chat
[profiles.slack]
post_process_command = "ollama run llama3.2:1b 'Rewrite casually for Slack:'"

# Profile: code comments, output to clipboard
[profiles.code]
post_process_command = "ollama run llama3.2:1b 'Format as code comment:'"
output_mode = "clipboard"

# Profile: meeting notes with longer timeout
[profiles.notes]
post_process_command = "ollama run llama3.2:1b 'Convert to bullet points:'"
post_process_timeout_ms = 60000
```

--------------------------------

### Install ydotool on Ubuntu/Debian and start daemon

Source: https://voxtype.io/docs/TROUBLESHOOTING

Install ydotool, which works on X11 but requires a running daemon. For Ubuntu/Debian, install via apt and enable the daemon with systemctl.

```bash
# Ubuntu/Debian:
sudo apt install ydotool

# Start the daemon (see "ydotool daemon not running" section for Fedora)
systemctl --user enable --now ydotool
```

--------------------------------

### Configuration Example

Source: https://voxtype.io/docs/USER_MANUAL

Example configuration snippet showing commented-out settings for threads and on-demand loading.

```toml
# threads = 4
# on_demand_loading = false
```

--------------------------------

### Multi-Model Setup Download Commands

Source: https://voxtype.io/docs/CONFIGURATION

Commands to download the required models for the multi-model setup.

```bash
voxtype setup --download --model base.en
voxtype setup --download --model large-v3-turbo
voxtype setup --download --model medium.en
```

--------------------------------

### Driver order examples for X11, ydotool-only, and Wayland

Source: https://voxtype.io/docs/USER_MANUAL

Shows three alternative driver_order configurations: X11-only with xclip, forcing ydotool with no fallback, and a GNOME/KDE Wayland setup preferring eitype. When driver_order is set, fallback_to_clipboard is ignored.

```toml
# X11-only setup (no Wayland)
driver_order = ["ydotool", "xclip"]

# Force ydotool only (no fallback)
driver_order = ["ydotool"]

# GNOME/KDE Wayland (prefer eitype, wtype doesn't work)
driver_order = ["eitype", "dotool", "clipboard"]
```

--------------------------------

### Download Moonshine models via setup tool

Source: https://voxtype.io/docs/MOONSHINE

Runs the interactive setup tool to download and configure Moonshine models. Shows a menu of available engines and models.

```bash
voxtype setup model
```

--------------------------------

### Request an available model via CLI

Source: https://voxtype.io/docs/CONFIGURATION

Use this bash command to start recording with a model from the available_models list. The model must be downloaded first using voxtype setup --download --model <name>.

```bash
voxtype record start --model medium.en
```

--------------------------------

### Standard Setup for Hyprland, Sway, and River

Source: https://voxtype.io/docs

Commands to download the whisper model, disable the built-in hotkey, enable the state file, install the systemd service, and optionally fix modifier key interference. Uses native compositor keybindings, so no input group is required.

```bash
# Download whisper model and configure
voxtype setup --download

# Disable built-in hotkey (we'll use compositor keybindings)
cat >> ~/.config/voxtype/config.toml << 'EOF'

[hotkey]
enabled = false
EOF

# Enable state file (required for toggle mode)
echo 'state_file = "auto"' >> ~/.config/voxtype/config.toml

# Install as systemd service
voxtype setup systemd

# Optional: Fix modifier key interference (if using SUPER+key combos)
voxtype setup compositor hyprland  # or: sway
```

--------------------------------

### Cohere on_demand_loading configuration example

Source: https://voxtype.io/docs/CONFIGURATION

Enables loading the model only when recording starts and unloading after transcription. Useful on laptops where 3 GB of RAM dedicated to the daemon is too costly.

```toml
[cohere]
on_demand_loading = true
```

--------------------------------

### post_output_command compositor integration example

Source: https://voxtype.io/docs/CONFIGURATION

Compositor integration example for post_output_command.

```toml
[output]

```

--------------------------------

### OpenVINO device configuration TOML example

Source: https://voxtype.io/docs/CONFIGURATION

Example configuration for OpenVINO engine with NPU device, model, and openvino_dir. Requires matching OpenVINO GenAI SDK and device packages.

```toml
engine = "openvino"

[openvino]
model = "base.en-int8"
device = "NPU"
quantized = true
language = "en"
on_demand_loading = false
openvino_dir = "/opt/intel/openvino"

```

--------------------------------

### TOML: driver_order examples

Source: https://voxtype.io/docs/CONFIGURATION

Shows multiple driver_order configurations: preferring ydotool over dotool, an X11-only setup, forcing a single driver, and a GNOME/KDE Wayland setup. When driver_order is set, fallback_to_clipboard is ignored.

```toml
[output]
mode = "type"

# Prefer ydotool over dotool, skip wtype
driver_order = ["ydotool", "dotool", "clipboard"]

# X11-only setup
driver_order = ["dotool", "ydotool", "xclip"]

# Force single driver (no fallback)
driver_order = ["ydotool"]

# GNOME/KDE Wayland (prefer eitype, wtype doesn't work)
driver_order = ["eitype", "dotool", "clipboard"]

```

--------------------------------

### Install wl-clipboard and test clipboard

Source: https://voxtype.io/docs/TROUBLESHOOTING

Commands to install wl-clipboard on various distributions and test that it works.

```bash
# Install wl-clipboard
# Arch: sudo pacman -S wl-clipboard
# Debian: sudo apt install wl-clipboard
# Fedora: sudo dnf install wl-clipboard

# Test it works
echo "test" | wl-copy
wl-paste

```

--------------------------------

### Install xclip on Ubuntu/Debian

Source: https://voxtype.io/docs/TROUBLESHOOTING

Install xclip for clipboard-only output, where you paste manually with Ctrl+V.

```bash
# Ubuntu/Debian:
sudo apt install xclip
```

--------------------------------

### Rerun setup after NPU compile warning

Source: https://voxtype.io/docs/TROUBLESHOOTING

After installing missing packages and verifying the NPU device, rerun setup to compile the model for the NPU. The compile is skipped if the cache blob already exists.

```bash
voxtype setup --download --model <model-name>
```

--------------------------------

### Download and switch models with voxtype setup model

Source: https://voxtype.io/docs/smoke_tests/model-switching

Use 'voxtype setup model' to interactively select a model to download if not present. Alternatively, specify the model directly with '--set small.en'. To test with different models, edit config.toml or use the --model flag.

```bash
voxtype setup model  # Interactive selection

# Or specify directly
voxtype setup model --set small.en

# Test with different models (edit config.toml or use --model flag)
```

--------------------------------

### Install libnotify and test notifications

Source: https://voxtype.io/docs/TROUBLESHOOTING

Install libnotify on Arch, Debian, or Fedora, then test with notify-send.

```bash
# Install libnotify
# Arch: sudo pacman -S libnotify
# Debian: sudo apt install libnotify-bin
# Fedora: sudo dnf install libnotify

# Test
notify-send "Test" "This is a test"
```

--------------------------------

### Verify Voxtype CLI with version, help, config, and status commands

Source: https://voxtype.io/docs/smoke_tests/basic-verification

Run these commands to confirm the Voxtype CLI is installed and working. The first group checks version and help for the main command and its subcommands (daemon, record, setup). The second group shows the current configuration and checks the daemon status.

```bash
# Version and help
voxtype --version
voxtype --help
voxtype daemon --help
voxtype record --help
voxtype setup --help

# Show current config
voxtype config

# Check status
voxtype status
```

--------------------------------

### Set up ydotool with daemon for wtype fallback

Source: https://voxtype.io/docs/TROUBLESHOOTING

Alternative solution: install ydotool and ensure its daemon is running. The daemon is required for the fallback to work; simply having ydotool installed is not enough.

```bash
# 1. Install ydotool
# Arch:
sudo pacman -S ydotool
# Fedora:
sudo dnf install ydotool
# Ubuntu/Debian:
sudo apt install ydotool

# 2. Enable and start the daemon (required!)
systemctl --user enable --now ydotool

# 3. Verify it's running
systemctl --user status ydotool
```

--------------------------------

### Switch to Parakeet ONNX binary manually

Source: https://voxtype.io/docs/PARAKEET

Commands to download the Parakeet-enabled voxtype binary (e.g., AVX-512), make it executable, install it to /usr/local/bin/voxtype, restart the daemon, and verify the version. This is required until 'voxtype setup engine' is implemented.

```bash
# Download the Parakeet binary for your CPU
# Example: AVX-512 capable CPU
curl -L https://github.com/peteonrails/voxtype/releases/download/v0.6.3/voxtype-0.6.3-linux-x86_64-onnx-avx512 \
  -o /tmp/voxtype-onnx

# Make executable and install
chmod +x /tmp/voxtype-onnx
sudo mv /tmp/voxtype-onnx /usr/local/bin/voxtype

# Restart the daemon
systemctl --user restart voxtype

# Verify
voxtype --version

```

--------------------------------

### Install and configure dotool for wtype fallback

Source: https://voxtype.io/docs/TROUBLESHOOTING

Recommended solution: install dotool, add user to input group for uinput access, and optionally configure keyboard layout for non-US keyboards. Requires logging out and back in after group change.

```bash
# 1. Install dotool (check your distribution's package manager)
# Arch (AUR):
yay -S dotool
# From source: https://sr.ht/~geb/dotool/

# 2. Add user to input group (required for uinput access)
sudo usermod -aG input $USER
# Log out and back in for group change to take effect

# 3. Configure keyboard layout if needed (non-US keyboards)
# Add to config.toml:
# [output]
# dotool_xkb_layout = "de"  # German, French ("fr"), etc.
```

--------------------------------

### Meeting audio configuration example

Source: https://voxtype.io/docs/CONFIGURATION

Example TOML for [meeting.audio] showing loopback_device, echo_cancel, and vad_threshold settings. Includes a comment for quiet mic tuning.

```toml
[meeting.audio]
loopback_device = "auto"
echo_cancel = "auto"  # GTCRN enhancement + transcript dedup
vad_threshold = 0.001  # Optional: quiet mic tuning
```

--------------------------------

### terms_file example

Source: https://voxtype.io/docs/CONFIGURATION

TOML configuration showing how to set a path to a JSON file containing vocabulary boost terms.

```toml
[soniox]
terms_file = "/home/me/dotfiles/voxtype-terms.json"
```

--------------------------------

### Install dotool on Ubuntu/Debian and Arch

Source: https://voxtype.io/docs/TROUBLESHOOTING

Install dotool, which works on X11, supports keyboard layouts, and doesn't require a daemon. For Ubuntu/Debian, build from source; for Arch, use AUR. After installation, add the user to the input group and log out and back in.

```bash
# Ubuntu/Debian (from source):
sudo apt install libxkbcommon-dev
git clone https://git.sr.ht/~geb/dotool
cd dotool && ./build.sh && sudo cp dotool /usr/local/bin/

# Arch (AUR):
yay -S dotool

# Add user to input group
sudo usermod -aG input $USER
# Log out and back in
```

--------------------------------

### Switch to ONNX engine binary with voxtype setup onnx

Source: https://voxtype.io/docs/USER_MANUAL

Switch between ONNX and Whisper binary variants using the setup command. All engines except Whisper require an ONNX binary variant.

```bash
voxtype setup onnx --enable    # Switch to ONNX binary
voxtype setup onnx --disable   # Switch back to Whisper binary
voxtype setup onnx --status    # Show current backend
```

--------------------------------

### Install wl-clipboard for clipboard restoration

Source: https://voxtype.io/docs/TROUBLESHOOTING

Install wl-clipboard on Arch, Debian, or Fedora to enable clipboard restoration on Wayland.

```bash
# Arch: sudo pacman -S wl-clipboard
# Debian: sudo apt install wl-clipboard
# Fedora: sudo dnf install wl-clipboard
```

--------------------------------

### Install Cohere Model

Source: https://voxtype.io/docs/USER_MANUAL

Command to install the Cohere model, with a comment about picking the Cohere section and confirming the size warning.

```bash
voxtype setup model      # Pick the Cohere section, confirm the size warning
```

--------------------------------

### Complete Parakeet configuration example

Source: https://voxtype.io/docs/CONFIGURATION

A complete example configuration for the Parakeet engine, with on_demand_loading disabled to keep the model loaded for fast response.

```toml
engine = "parakeet"

[parakeet]
model = "parakeet-tdt-0.6b-v3"
on_demand_loading = false  # Keep model loaded for fast response
```

--------------------------------

### Re-run setup --download to test cached-file revalidation

Source: https://voxtype.io/docs/smoke_tests/v076/models-cdn-r2

Re-runs setup --download to test cached-file revalidation. Expects the command to complete quickly and indicate that files were validated rather than re-downloaded.

```bash
XDG_DATA_HOME=/tmp/voxtype-r2-test voxtype setup --download --model parakeet-unified-en-0.6b
# Expected: completes fast; output indicates files were validated rather than re-fetched
```

--------------------------------

### Post-processing command examples

Source: https://voxtype.io/docs/CONFIGURATION

Provides multiple post_process.command examples: using Ollama for cleanup, sed for filler word removal, a custom Python script, and an LM Studio API script.

```toml
# Use Ollama with a small model for quick cleanup
[output.post_process]
command = "ollama run llama3.2:1b 'Clean up this transcription. Fix grammar and remove filler words. Output only the cleaned text:'"

# Simple filler word removal with sed
[output.post_process]
command = "sed 's/\bum\b//g; s/\buh\b//g; s/\blike\b//g'"

# Custom Python script
[output.post_process]
command = "python3 ~/.config/voxtype/cleanup.py"

# LM Studio API (OpenAI-compatible)
[output.post_process]
command = "~/.config/voxtype/lm-studio-cleanup.sh"
```

--------------------------------

### Install wtype for Wayland type mode

Source: https://voxtype.io/docs/USER_MANUAL

Install wtype for Wayland type mode. Recommended for best CJK/Unicode support.

```bash
# Install wtype
# Fedora: sudo dnf install wtype
# Arch: sudo pacman -S wtype
# Ubuntu: sudo apt install wtype
```

--------------------------------

### Multi-Model Setup Configuration

Source: https://voxtype.io/docs/CONFIGURATION

Uses a fast model for everyday dictation and a more accurate model on-demand via hotkey modifier.

```toml
[hotkey]
key = "SCROLLLOCK"
model_modifier = "LEFTSHIFT"  # Hold Shift + hotkey for secondary model

[whisper]
model = "base.en"                    # Fast model, always ready
secondary_model = "large-v3-turbo"   # Accurate model on-demand
available_models = ["medium.en"]     # Additional models for CLI
max_loaded_models = 2                # Keep 2 models in memory
cold_model_timeout_secs = 300        # Evict unused models after 5 min

[audio.feedback]
enabled = true  # Helpful when switching models
```

--------------------------------

### Check Output Chain Availability

Source: https://voxtype.io/docs/smoke_tests/output-chain-verification

Run this command to verify the installation status of each output method in the fallback chain. The expected output shows whether each method is installed and if the daemon is running.

```bash
# Check which output methods are available:
voxtype config | grep -A10 "Output Chain"

# Expected output shows installed status for each method:
#   wtype:    installed
#   dotool:   installed (if available)
#   ydotool:  installed, daemon running
#   wl-copy:  installed
```

--------------------------------

### Verification output

Source: https://voxtype.io/docs/CI-SETUP

Example output from the build script verifying binaries are clean of AVX-512/GFNI instructions.

```text
=== Verifying Binaries ===
✓ voxtype-0.4.1-linux-x86_64-avx2: Clean (no AVX-512/GFNI)
✓ voxtype-0.4.1-linux-x86_64-vulkan: Clean (no AVX-512/GFNI)
```

--------------------------------

### Enable and start ydotool daemon

Source: https://voxtype.io/docs/USER_MANUAL

Enables and starts the ydotool daemon as a systemd user service. Required before using ydotool commands.

```bash
systemctl --user enable --now ydotool
```

--------------------------------

### audio.device example

Source: https://voxtype.io/docs/CONFIGURATION

Sets the audio input device to an ALSA device name. PulseAudio and PipeWire source names will not match.

```toml
[audio]
device = "sysdefault:CARD=Yeti"

```

--------------------------------

### Manage Voxtype DankMaterialShell widget

Source: https://voxtype.io/docs/USER_MANUAL

Other DankMaterialShell setup commands: show instructions, uninstall the widget, or output raw QML for scripting.

```bash
voxtype setup dms              # Show setup instructions
voxtype setup dms --uninstall  # Remove the widget
voxtype setup dms --qml        # Output raw QML (for scripting)
```

--------------------------------

### terms example

Source: https://voxtype.io/docs/CONFIGURATION

TOML configuration showing how to set inline vocabulary boost terms.

```toml
[soniox]
terms = ["Voxtype", "Hyprland", "tokio-tungstenite"]
```

--------------------------------

### Manual test: start dotoold with XKB layout

Source: https://voxtype.io/docs/CONFIGURATION

Starts the dotoold daemon with the Hungarian layout (hu) and verifies the FIFO pipe exists. Replace 'hu' with your XKB layout (e.g., de, fr, us).

```bash
DOTOOL_XKB_LAYOUT=hu dotoold &
ls -la /tmp/dotool-pipe   # confirm FIFO exists
```

--------------------------------

### Download Voxtype model via setup or curl

Source: https://voxtype.io/docs/TROUBLESHOOTING

Use 'voxtype setup --download' to download the default model, or manually download the ggml-base.en.bin model from Hugging Face using curl. The manual method requires creating the model directory first.

```bash
voxtype setup --download
```

```bash
mkdir -p ~/.local/share/voxtype/models
curl -L -o ~/.local/share/voxtype/models/ggml-base.en.bin \
    https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin
```

--------------------------------

### Complete Cohere configuration example

Source: https://voxtype.io/docs/CONFIGURATION

A full TOML configuration for the Cohere engine, including model, language, and on_demand_loading settings.

```toml
engine = "cohere"

[cohere]
model = "cohere-transcribe-q4f16"
language = "en"
on_demand_loading = false
```

--------------------------------

### Build and install whisper-cli from whisper.cpp

Source: https://voxtype.io/docs/TROUBLESHOOTING

Clone whisper.cpp, build with CMake, and copy the whisper-cli binary to /usr/local/bin. Required for the CLI backend.

```bash
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp
cmake -B build
cmake --build build --config Release
sudo cp build/bin/whisper-cli /usr/local/bin/
```

--------------------------------

### voxtype setup gpu with enable and disable options

Source: https://voxtype.io/docs/USER_MANUAL

Manage GPU acceleration backends. --enable and --disable require sudo.

```bash
voxtype setup gpu            # Show current backend status
voxtype setup gpu --enable   # Switch to Vulkan GPU backend (requires sudo)
voxtype setup gpu --disable  # Switch back to CPU backend (requires sudo)
```

--------------------------------

### List styles and set OSD config from CLI

Source: https://voxtype.io/docs/CONFIGURATION

Shows how to list installed styles, set the style, layout, and frame border, and list every settable key via the command line.

```bash
voxtype info styles            # lists installed styles with their source paths
voxtype config set osd.style aegis-hud
voxtype config set osd.layout orb
voxtype config set osd.frame.border accent
voxtype config schema          # lists every settable key
```

--------------------------------

### CLI Model Selection

Source: https://voxtype.io/docs/USER_MANUAL

CLI commands to start recording with different models: primary, secondary, and any available model.

```bash
# Use primary model
voxtype record start

# Use secondary model
voxtype record start --model large-v3-turbo

# Use any available model
voxtype record start --model medium.en
```

--------------------------------

### Hotkey mode toggle example

Source: https://voxtype.io/docs/CONFIGURATION

Sets the hotkey to toggle mode: press once to start recording, press again to stop. Default mode is push_to_talk.

```toml
[hotkey]
key = "SCROLLLOCK"
mode = "toggle"  # Press to start, press again to stop
```

--------------------------------

### Install dotool and add user to input group

Source: https://voxtype.io/docs/TROUBLESHOOTING

Commands to install dotool on Arch (AUR) and add the user to the input group for uinput access. Log out and back in after the group change.

```bash
# 1. Install dotool
# Arch (AUR):
yay -S dotool
# Ubuntu/Debian (from source):
# See https://sr.ht/~geb/dotool/ for instructions
# Fedora (from source):
# See https://sr.ht/~geb/dotool/ for instructions

# 2. Add user to input group (required for uinput access)
sudo usermod -aG input $USER
# Log out and back in for group change to take effect
```

--------------------------------

### Install Voxtype via AppImage

Source: https://voxtype.io/docs

Self-contained binary for distros that don't have a packaged voxtype. Three variants: CPU, Vulkan GPU, and ONNX engines. Run directly or move to ~/.local/bin/ for permanent install.

```bash
# Download a variant from the latest release
wget https://github.com/peteonrails/voxtype/releases/download/v0.7.5/voxtype-0.7.5-x86_64.AppImage
chmod +x voxtype-0.7.5-x86_64.AppImage

# Run directly, or move to ~/.local/bin/ for permanent install
./voxtype-0.7.5-x86_64.AppImage --help
mv voxtype-0.7.5-x86_64.AppImage ~/.local/bin/voxtype
```

--------------------------------

### Automatic compositor setup for modifier blocking

Source: https://voxtype.io/docs/USER_MANUAL

Automatically install a modifier-blocking workaround for Hyprland, Sway, or River. This command does NOT set up keybindings for voxtype; it only installs a workaround that blocks modifier keys during text output. It writes a submap/mode config to ~/.config/hypr/conf.d/voxtype-submap.conf (or sway/conf.d/voxtype-mode.conf, or river/conf.d/voxtype-mode.sh), adds pre/post output hooks, and checks that your compositor sources the conf.d directory. If voxtype crashes while typing, press F12 to escape the submap. Use --status to check installation status, --uninstall to remove, or --show to view the configuration without installing.

```bash
# For Hyprland
voxtype setup compositor hyprland
hyprctl reload
systemctl --user restart voxtype

# For Sway
voxtype setup compositor sway
swaymsg reload
systemctl --user restart voxtype

# For River
voxtype setup compositor river
# Restart River or source the new config
systemctl --user restart voxtype
```

--------------------------------

### Basic record start/stop, toggle, and cancel commands

Source: https://voxtype.io/docs/smoke_tests/recording-cycle

Demonstrates the core recording commands: start, stop, toggle, and cancel. The toggle command starts or stops recording depending on the current state. The cancel command should not transcribe, and the script includes a journalctl command to verify no transcription appears in the logs.

```bash
# Basic record start/stop
voxtype record start
sleep 3
voxtype record stop

# Toggle mode
voxtype record toggle  # starts recording
sleep 3
voxtype record toggle  # stops and transcribes

# Cancel recording (should not transcribe)
voxtype record start
sleep 2
voxtype record cancel
# Verify no transcription in logs:
journalctl --user -u voxtype --since "30 seconds ago" | grep -i transcri
```

--------------------------------

### pre_output_command example

Source: https://voxtype.io/docs/CONFIGURATION

Shell command executed immediately before typing output, used for compositor integration to block modifier keys during typing.

```toml
[output]
pre_output_command = "hyprctl dispatch submap voxtype_suppress"

```

--------------------------------

### Enable GPU acceleration: sudo voxtype setup gpu --enable

Source: https://voxtype.io/docs/FAQ

Sets up GPU acceleration for Voxtype. On Arch Linux, install the vulkan-icd-loader package; on Debian, use libvulkan1; on Fedora, use vulkan-loader.

```bash
sudo voxtype setup gpu --enable
```

--------------------------------

### post_output_command example

Source: https://voxtype.io/docs/CONFIGURATION

Shell command executed immediately after typing output completes, used to restore normal modifier behavior.

```toml
[output]
post_output_command = "hyprctl dispatch submap reset"

```

--------------------------------

### Enable ONNX binary with sudo voxtype setup onnx --enable

Source: https://voxtype.io/docs/MODEL_SELECTION_GUIDE

Use this command to switch to the ONNX binary, which includes Whisper plus all ONNX-based engines. Requires sudo privileges.

```bash
sudo voxtype setup onnx --enable
```

--------------------------------

### language_hints examples

Source: https://voxtype.io/docs/CONFIGURATION

Shows three ways to set language_hints: a single language, a list of languages, or an empty list for auto-detection.

```python
language_hints = ["hu"]
```

```python
language_hints = ["hu", "en", "de"] # Hungarian, English, German
```

```python
language_hints = []                 # auto-detect everything
```

--------------------------------

### Moonshine complete configuration example

Source: https://voxtype.io/docs/CONFIGURATION

Complete Moonshine configuration with model, quantized, and on_demand_loading options. The comment notes keeping the model loaded for fast response.

```toml
engine = "moonshine"

[moonshine]
model = "base"
quantized = true
on_demand_loading = false  # Keep model loaded for fast response
```

--------------------------------

### audio.duck_media example

Source: https://voxtype.io/docs/CONFIGURATION

When true, lowers active media stream volume when recording starts and restores the original volume as soon as recording stops. Use as an alternative to pause_media to keep music or video playing quietly during push-to-talk.

```toml
[audio]
duck_media = true
duck_media_volume_percent = 34

```

--------------------------------

### List, preview, and apply OSD recipes

Source: https://voxtype.io/docs/CONFIGURATION

Commands to list installed recipes, preview a recipe with --dry-run, apply a recipe by name, or apply a recipe from a file. Recipe keys replace matching config keys, and the result is validated before writing.

```bash
voxtype setup osd --list                                # installed recipes
voxtype setup osd --recipe showcase-bars --dry-run      # preview
voxtype setup osd --recipe showcase-bars                # apply
voxtype setup osd --recipe ./my-recipe.toml             # apply a file
```

--------------------------------

### audio.pause_media example

Source: https://voxtype.io/docs/CONFIGURATION

When true, pauses currently playing MPRIS media players before microphone capture starts and resumes only those players as soon as capture stops. Transcription and text output continue without keeping playback paused.

```toml
[audio]
pause_media = true

```

--------------------------------

### Check dependencies and download models with voxtype setup

Source: https://voxtype.io/docs/USER_MANUAL

Check dependencies and optionally download models. Use --download to fetch the default model (base.en), model for interactive selection, vad for the Silero VAD model, or onnx to switch between Whisper and ONNX engines.

```bash
voxtype setup              # Check dependencies only
voxtype setup --download   # Download default model (base.en)
voxtype setup model        # Interactive model selection
voxtype setup vad          # Download the Silero VAD model
voxtype setup onnx         # Switch between Whisper and ONNX engines
```

--------------------------------

### Reject invalid model names in record start

Source: https://voxtype.io/docs/smoke_tests/invalid-model-rejection

Smoke test verifying that invalid model names are rejected before any recording starts. The `record start` command must fail with exit 1 and the error "Unknown model 'nonexistent'. Run `voxtype info models` to list available models." without falling back to the default model, leaving status "idle". Other commands like `config` still fall back to the default model with a warning, and `setup model --set` rejects invalid models.

```bash
voxtype --model nonexistent record start; echo "exit=$?"
voxtype status

# Expected behavior:
# 1. Only this error, exit 1: "Unknown model 'nonexistent'. Run `voxtype info models` to list available models."
#    (no "using default model" warning: that fallback applies to other commands, not record)
# 2. No recording starts: status stays "idle"

# Other commands still fall back to the default model and say so:
voxtype --model nonexistent config 2>&1 | grep -i "unknown model"
# Expected: WARN "Unknown model 'nonexistent', using default model '...'"

# The setup --set command should still reject invalid models:
voxtype setup model --set nonexistent
# Expected: error about model not installed
```

--------------------------------

### Install Voxtype on NixOS via flake

Source: https://voxtype.io/docs

NixOS users get a flake with packages for every binary variant. Pulls prebuilt ONNX Runtime; CPU-only variant builds entirely from source. Available outputs: default, vulkan, cuda, rocm, osdGtk4, osdNative.

```nix
# Imperative install
nix profile install github:peteonrails/voxtype/v1.1.1#vulkan

# Available outputs: default, vulkan, cuda, rocm, osdGtk4, osdNative
nix build github:peteonrails/voxtype/v1.1.1#osdGtk4

# Or pin in your flake inputs
inputs.voxtype.url = "github:peteonrails/voxtype/v1.1.1";
```

--------------------------------

### Complete Example — Realtime (with live partials)

Source: https://voxtype.io/docs/CONFIGURATION

TOML configuration for Soniox realtime streaming with live partials. Requires hotkey mode 'toggle' when streaming is true. API key is set via SONIOX_API_KEY environment variable.

```toml
engine = "soniox"

[hotkey]
mode = "toggle"   # Required when [soniox] streaming = true

[soniox]
language_hints = ["hu", "en"]
streaming = true
type_partials = true
# api_key set via SONIOX_API_KEY env var
```

--------------------------------

### Install Voxtype on Fedora via RPM package

Source: https://voxtype.io/docs

Requires Fedora 40+ (glibc 2.39). Downloads and installs the RPM package, then installs recommended optional dependencies.

```bash
# Download and install
wget https://github.com/peteonrails/voxtype/releases/download/v1.1.1/voxtype-1.1.1-1.x86_64.rpm
sudo dnf install ./voxtype-1.1.1-1.x86_64.rpm

# Recommended optional dependencies
sudo dnf install wtype wl-clipboard libnotify pipewire-alsa playerctl
```

--------------------------------

### Install Voxtype on Debian/Ubuntu via .deb package

Source: https://voxtype.io/docs

Requires Ubuntu 24.04+ or Debian Trixie+ (glibc 2.39). Downloads and installs the .deb package, then installs recommended optional dependencies.

```bash
# Download and install
wget https://github.com/peteonrails/voxtype/releases/download/v1.1.1/voxtype_1.1.1-1_amd64.deb
sudo apt install ./voxtype_1.1.1-1_amd64.deb

# Recommended optional dependencies
sudo apt install wtype wl-clipboard libnotify-bin pipewire-alsa playerctl
```

--------------------------------

### Configure profiles.code and profiles.notes in config file

Source: https://voxtype.io/docs/USER_MANUAL

Configuration file example showing two profiles: 'code' for formatting as code comments and 'notes' for converting to bullet points. Each profile sets a post_process_command using ollama and an output_mode.

```toml
[profiles.code]
post_process_command = "ollama run llama3.2:1b 'Format as a code comment in the style of the surrounding code:'"
output_mode = "clipboard"

# Meeting notes: bullet points
[profiles.notes]
post_process_command = "ollama run llama3.2:1b 'Convert to bullet points. Be concise:'"
```

--------------------------------

### Set up self-hosted whisper.cpp server

Source: https://voxtype.io/docs/USER_MANUAL

Commands to set up a self-hosted whisper.cpp server that implements the OpenAI Whisper API. Clone the repository, build the server, download a model, and run it on port 8080. Adjust the model and GPU settings as needed.

```bash
# Clone whisper.cpp
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp

# Build the server
make server

# Download a model
./models/download-ggml-model.sh large-v3-turbo

# Run the server (adjust for your GPU)
./server -m models/ggml-large-v3-turbo.bin --host 0.0.0.0 --port 8080
```

--------------------------------

### Configure streaming engine with [streaming] section

Source: https://voxtype.io/docs/CONFIGURATION

TOML example showing the [streaming] section with optional tuning fields. Requires [hotkey] mode = "toggle" and [whisper] streaming = true. The [streaming] section overrides old per-engine streaming_* fields.

```toml
[hotkey]
mode = "toggle"   # Required for streaming — see [whisper] streaming above

[whisper]
streaming = true

[streaming]
interval_secs = 0.5        # More responsive, more CPU/NPU load
max_buffer_secs = 20.0
partial_min_words = 2
```

--------------------------------

### Minimal Configuration

Source: https://voxtype.io/docs/CONFIGURATION

Basic configuration with the 'base.en' model.

```toml
[whisper]
model = "base.en"
```

--------------------------------

### XDG_CONFIG_HOME environment variable example

Source: https://voxtype.io/docs/CONFIGURATION

Overrides the config directory location. The default is `~/.config`; this example looks for `/custom/config/voxtype/config.toml`.

```bash
XDG_CONFIG_HOME=/custom/config voxtype
# Looks for: /custom/config/voxtype/config.toml
```

--------------------------------

### Extended status JSON output example

Source: https://voxtype.io/docs/WAYBAR

Example JSON output from voxtype status with --extended flag.

```json
{
  "text": "🎙️",
  "class": "idle",
  "tooltip": "Voxtype ready\nModel: base.en\nDevice: default\nBackend: CPU (AVX-512)",
  "model": "base.en",
  "device": "default",
  "backend": "CPU (AVX-512)"
}

```

--------------------------------

### Install Voxtype widget for DankMaterialShell

Source: https://voxtype.io/docs/USER_MANUAL

Automatically installs the VoxtypeWidget plugin for DankMaterialShell (KDE Plasma). Creates the plugin in ~/.config/DankMaterialShell/plugins/.

```bash
voxtype setup dms --install
```

--------------------------------

### Run Voxtype Waybar Setup Command

Source: https://voxtype.io/docs/WAYBAR

Run this command to generate ready-to-use Waybar module JSON and CSS styling snippets.

```bash
voxtype setup waybar
```

--------------------------------

### Start a new meeting

Source: https://voxtype.io/docs/USER_MANUAL

Starts a new meeting. The optional --title flag sets a custom title for the meeting.

```bash
voxtype meeting start
voxtype meeting start --title "Weekly standup"
```

--------------------------------

### Status icon override example

Source: https://voxtype.io/docs/CONFIGURATION

Example TOML showing how to override the recording icon using [status.icons] while keeping the emoji theme.

```toml
[status]
icon_theme = "emoji"

[status.icons]
recording = "🔴"  # Override just the recording icon
```

--------------------------------

### CLI override examples

Source: https://voxtype.io/docs/CONFIGURATION

Shows how to override configuration options via command line flags, such as `--hotkey`, `--model`, `--clipboard`, and `--icon-theme`.

```bash
voxtype --hotkey PAUSE --model small.en --clipboard
voxtype status --format json --icon-theme nerd-font
```

--------------------------------

### Filler word filtering example

Source: https://voxtype.io/docs/USER_MANUAL

Example showing how filler word filtering cleans up punctuation and removes disfluencies like 'um'.

```text
# You say:    "Well, um, I think we should ship it"
# Voxtype types: "Well, I think we should ship it"
```

--------------------------------

### Complete Example — Async (PTT-compatible, batch-only)

Source: https://voxtype.io/docs/CONFIGURATION

TOML configuration for Soniox async API with push-to-talk hotkey. Model defaults to stt-async-v4 when async_api is true. API key is set via SONIOX_API_KEY environment variable.

```toml
engine = "soniox"

[hotkey]
mode = "push_to_talk"   # Works with async_api; no toggle promotion

[soniox]
async_api = true
language_hints = ["hu", "en"]
# model defaults to stt-async-v4 when async_api = true
# api_key set via SONIOX_API_KEY env var
```

--------------------------------

### Check installed voxtype binary variant

Source: https://voxtype.io/docs/smoke_tests/v076/engine-binary-mismatch-detection

Confirms the installed wrapper is the CPU variant (not ONNX) before testing the mismatch banner. Expects voxtype-avx2 or voxtype-avx512.

```bash
readlink -f /usr/bin/voxtype
# Expected: voxtype-avx2 or voxtype-avx512 (NOT voxtype-onnx-*)
```

--------------------------------

### Start meeting without title

Source: https://voxtype.io/docs/smoke_tests/meeting-mode

Starts a meeting without a title, expecting the system to auto-generate one from the date. Records for 5 seconds then stops.

```bash
voxtype meeting start
sleep 5
voxtype meeting stop
```

--------------------------------

### River Keybindings for Push-to-Talk

Source: https://voxtype.io/docs

Add these keybindings to ~/.config/river/init. Hold Super+V to record, release to transcribe.

```conf
# Push-to-talk: hold Super+V to record, release to transcribe
riverctl map normal Super V spawn 'voxtype record start'
riverctl map -release normal Super V spawn 'voxtype record stop'
```

--------------------------------

### Send notification on typing start

Source: https://voxtype.io/docs/USER_MANUAL

Sends a desktop notification when typing starts. Output hooks are generic shell commands, so this works with any compositor or custom workflow.

```toml
pre_output_command = "notify-send 'Typing...'"
```

--------------------------------

### Install eitype with cargo

Source: https://voxtype.io/docs/USER_MANUAL

Installs eitype via Cargo. Recommended for KDE Plasma and GNOME Wayland users because eitype uses the libei/EI protocol supported by these compositors.

```bash
cargo install eitype
```

--------------------------------

### Test hotkey manually: voxtype record start and stop

Source: https://voxtype.io/docs/FAQ

Manually tests the hotkey by starting and stopping recording. These commands are part of the compositor keybinding troubleshooting steps.

```bash
voxtype record start
```

```bash
voxtype record stop
```

--------------------------------

### Configure file output mode with file_path (TOML)

Source: https://voxtype.io/docs/CONFIGURATION

Example for [output] with mode = "file" and file_path. Transcriptions are written to the file. Parent directories are created automatically. If the file can't be written, fallback to clipboard occurs when fallback_to_clipboard is true.

```toml
[output]
mode = "file"
file_path = "~/transcriptions/output.txt"
```

--------------------------------

### Soniox language_hints configuration example

Source: https://voxtype.io/docs/CONFIGURATION

Sets language hints for the Soniox engine. Use an empty array for full auto-detect across all 60+ supported languages.

```toml
[soniox]
language_hints = ["en"]            # English only
```

--------------------------------

### Run meeting with loopback and verify speaker attribution

Source: https://voxtype.io/docs/smoke_tests/meeting-mode

Start a meeting while in a video call, wait for remote participants to speak, then stop and check speaker attribution and export with speaker labels.

```bash
voxtype meeting start --title "Video Call Test"
```

```bash
sleep 30
voxtype meeting stop
```

```bash
voxtype meeting show latest
```

```bash
voxtype meeting export latest --format text --speakers
```

--------------------------------

### Select OSD frontend in TOML config

Source: https://voxtype.io/docs/CONFIGURATION

Sets the OSD frontend to gtk4 (default), native, or quickshell. Uncomment the desired line to switch.

```toml
[osd]
frontend = "gtk4"           # Default. Uses voxtype-osd-gtk4.
# frontend = "native"       # wgpu/egui-based (voxtype-osd-native).
# frontend = "quickshell"   # QML/Quickshell launcher (voxtype-osd-quickshell).
```

--------------------------------

### Moonshine configuration example

Source: https://voxtype.io/docs/MODEL_SELECTION_GUIDE

Configures the Moonshine engine with the 'base' model for English (237 MB). The quantized option is commented out (default true) and CPU threads for ONNX Runtime are also commented out.

```toml
engine = "moonshine"

[moonshine]
model = "base"         # English, 237 MB
# quantized = true     # Use quantized variant if available (default: true)
# threads = 4          # CPU threads for ONNX Runtime
```

--------------------------------

### Build Soniox from source

Source: https://voxtype.io/docs/CONFIGURATION

Build the project in release mode. Soniox is built unconditionally; no Cargo feature flag is required.

```bash
cargo build --release
```

--------------------------------

### Set delay before typing starts

Source: https://voxtype.io/docs/CONFIGURATION

Adds a 100ms delay before typing starts to allow the virtual keyboard to initialize and prevent the first character from being dropped on some compositors. Try 100-200ms if you experience issues.

```toml
[output]
pre_type_delay_ms = 100  # 100ms delay before typing starts
```

--------------------------------

### XDG_DATA_HOME environment variable example

Source: https://voxtype.io/docs/CONFIGURATION

Overrides the data directory location. The default is `~/.local/share`.

```bash
XDG_DATA_HOME=/custom/data voxtype
```
Tokens:
Raw