Voxtray

Voxtray is a real-time transcription utility (CLI + system tray) with interchangeable local and cloud providers.

It is designed for daily Ubuntu/WSL2 usage with quick toggle activation, automatic clipboard copy, and recent-history tracking. You can run it fully locally with Voxtral/vLLM, or switch to cloud transcription profiles for Mistral Realtime or OpenAI Realtime when you prefer managed models.

Spanish documentation: LEEME.md.

Features

• start/stop/toggle recording from terminal.
• Global GNOME shortcut (Super+F9 by default).
• Automatic copy of final transcript to clipboard.
• Persistent history (last 5 transcripts by default).
• Tray mode (tray) with quick actions and engine status.
• Audio file transcription (transcribe-file).
• Provider profiles for local Voxtral/vLLM or cloud models through Mistral Realtime and OpenAI Realtime.
• Windows + WSL2 distribution flow (included scripts).

Requirements

Ubuntu 24.04 / WSL2

sudo apt-get update
sudo apt-get install -y ffmpeg xclip libportaudio2 libxcb-cursor0

Python

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e '.[dev]'

If you want Qt tray mode:

pip install -e '.[ui]'

Install vLLM (NVIDIA GPU):

pip install -U vllm --extra-index-url https://download.pytorch.org/whl/cu129

Hugging Face access (optional):

• For public models, a token is usually not required.
• You only need a token if the model is gated/restricted or private.

export HF_TOKEN=...

Cloud providers do not need vLLM. Install the optional Mistral SDK only if you use the Mistral Realtime profile:

pip install -e '.[cloud]'
export MISTRAL_API_KEY=...
export OPENAI_API_KEY=...

Quick Start

Initialize config:

voxtray init

Check status and logs:

voxtray status
voxtray logs --target all --lines 200

Record from terminal:

voxtray record --start
voxtray record --stop
# recommended for global shortcut usage
voxtray record --toggle

Engine/model controls:

voxtray warm on
voxtray warm off
voxtray warm status
voxtray model load
voxtray model unload
voxtray model status

For cloud profiles, warm and model commands return an explicit no-op message because no local engine is used.

History:

voxtray history list
voxtray history copy 1

Transcribe audio file:

voxtray transcribe-file /path/audio.m4a --copy

Audit saved recording quality:

voxtray recordings audit --limit 200
# CI/local gate when you expect a clean corpus
voxtray recordings audit --limit 200 --fail-on-issues

Configuration and Profiles

Main file:

• ~/.config/voxtray/config.toml

Included memory profiles:

• profiles/voxtray-balanced.toml
• profiles/voxtray-vram-saver.toml
• profiles/voxtray-latency.toml
• profiles/voxtray-online-mistral.toml
• profiles/voxtray-online-openai.toml

Apply profile:

scripts/apply_profile.sh local-balanced

Available values:

• local-balanced (balanced legacy alias)
• local-vram-saver (vram-saver legacy alias)
• local-latency (latency legacy alias)
• online-mistral
• online-openai

Provider config is stored without secrets:

[transcription]
provider = "openai_realtime"

[openai_realtime]
api_key_env = "OPENAI_API_KEY"
model = "gpt-realtime-whisper"
fallback_model = "whisper-1"
sample_rate = 24000
turn_detection = "manual"
delay = "high"
language = "es"
prompt = "Transcribe literally Spanish voice commands. Preserve project names mentioned by the speaker."

The CLI/tray resolves the configured variable from the process environment, and also from the repo-local .env file when present. This keeps GNOME autostart working without storing the actual API key in config.toml.

The OpenAI profile uses gpt-realtime-whisper for native streaming transcription with delay = "high" for better accuracy, and whisper-1 for the batch fallback so recovery stays in the Whisper model family instead of jumping to a GPT-4o transcription model. You can still set openai_realtime.model and fallback_model to another supported transcription model without storing any key in the config file. For recordings where Realtime returns empty or clearly truncated text, Voxtray automatically retries the captured WAV with fallback_model before saving history or copying to the clipboard.

voxtray status reports provider, provider_ready, local_engine_ready, model_id, warm_supported, and api_key_env_present.

GNOME Integration

Install desktop entry + autostart + default shortcut (Super+F9):

scripts/install_ubuntu_integration.sh

Install only shortcut:

voxtray install-shortcut --binding '<Super>F9'

Windows + WSL2

Build bundle to share:

scripts/build_wsl2_bundle.sh

Initial install on Windows (PowerShell), inside the extracted folder:

powershell -ExecutionPolicy Bypass -File .\scripts\install_windows_shortcuts.ps1 -Distro Ubuntu

What this installer does:

• Installs dependencies inside WSL2 (Ubuntu).
• Creates the Python environment and Voxtray in ~/.voxtray.
• Generates Windows shortcuts to run Voxtray without opening a Linux terminal.

Daily activation and usage on Windows:

1. Use Voxtray Toggle shortcut (desktop or start menu) to start/stop recording.
2. Use Voxtray Warm On/Off to keep or release the engine in memory.
3. Use Voxtray Status for quick status checks.
4. Use Voxtray Logs for diagnostics.

Global shortcut on Windows (optional):

1. Right-click Voxtray Toggle and open Properties.
2. In the Shortcut tab, focus Shortcut key.
3. Press your desired key combination (recommended: Ctrl + Alt + F9).
4. Click Apply and OK.

Notes:

• The shortcut also exists in %APPDATA%\Microsoft\Windows\Start Menu\Programs\Voxtray WSL.
• If you choose a simple key, Windows typically converts it to Ctrl + Alt + <key>.
• Avoid combinations already used by other apps or the OS.

Quick check from PowerShell:

wsl -d Ubuntu -- bash -lc "~/.voxtray/.venv/bin/voxtray status"
wsl -d Ubuntu -- bash -lc "~/.voxtray/.venv/bin/voxtray warm on"

Development

Run tests:

pytest

Project structure:

• src/voxtray/: main implementation (CLI, controller, realtime, tray).
• tests/: unit tests.
• scripts/: Ubuntu/WSL2 integration and packaging utilities.
• profiles/: performance/memory configuration templates.

License

Apache-2.0. See LICENSE.