voicr

Press a key. Speak. Release. Your words appear wherever your cursor is.
No GUI. Runs entirely on your machine — or via Groq, OpenAI, Sarvam, or a custom cloud endpoint for faster cold-start.

Why voicr?

Most voice-to-text tools on the market are either a polished but closed, cloud-only, subscription product (Wispr Flow), or an open, hybrid local/cloud tool wrapped in a full Electron desktop app (OpenWhispr). voicr takes a different shape entirely: no GUI app at all. It's a single static binary that runs as a background daemon — no Electron, no menu bar icon, no window to manage.

It's built by a developer, for developers who want a tool that gets out of the way. Set it up once — pick a local model or a cloud provider (Groq, OpenAI, Sarvam, or your own OpenAI-compatible endpoint) — and forget it exists. From then on it's just a hotkey: hold it, talk, release, and the words land wherever your cursor already is — terminal, editor, browser, anywhere.

The optional configuration UI is a tiny page served directly by the daemon itself (http://127.0.0.1:7898) — open it in any browser only when you need to change a setting; it adds no runtime overhead when you don't.

It runs as a background daemon you control with a hotkey or a Unix socket. Hold Ctrl+Space, speak, release — the transcription is pasted directly into whatever window is focused. No switching apps. No clicking. Just talk.

Hold Ctrl+Space → speak → release → text appears in your editor / terminal / browser

Run fully offline with a local model, or add --cloud to route transcription through Groq, OpenAI, Sarvam, or a custom endpoint for near-instant results without downloading any model.

Features

Hold-to-talk hotkey — configurable combo (Ctrl+Space by default), pastes into the active window automatically
Daemon mode — persistent background process, scriptable over a Unix socket with newline-delimited JSON
Local Web UI — built-in web configuration dashboard (http://127.0.0.1:7898) to switch models, tune settings, and pick audio devices
Multiple engines — Parakeet, Moonshine (streaming), SenseVoice, GigaAM, Whisper (including custom .bin auto-discovery)
Multi-provider Cloud mode — route transcription through Groq, OpenAI, Sarvam AI, or any custom OpenAI-compatible endpoint with dynamic model fetching
Auto-start on login — single-command or one-click toggle to automatically start voicr when logging into your desktop
Multilingual paste — auto-detects Unicode text and uses clipboard + Ctrl+V; ASCII text uses zero-latency keystroke typing
Voice Activity Detection — silence filtering for --auto-stop transcription mode
Transcription history — SQLite-backed log with search, export, and retention policies
Fully offline option — local inference, no API keys, no telemetry
Single binary — one file, no runtime dependencies, works on Linux / macOS / Windows

Installation

Download a pre-built binary

Go to the latest release and grab the binary for your platform.

Linux (x86_64)

curl -L https://github.com/habitual69/voicr/releases/latest/download/voicr-linux-x86_64 -o voicr
chmod +x voicr
sudo mv voicr /usr/local/bin/

macOS (Apple Silicon)

curl -L https://github.com/habitual69/voicr/releases/latest/download/voicr-macos-arm64 -o voicr
chmod +x voicr
sudo mv voicr /usr/local/bin/

macOS (Intel)

curl -L https://github.com/habitual69/voicr/releases/latest/download/voicr-macos-x86_64 -o voicr
chmod +x voicr
sudo mv voicr /usr/local/bin/

Windows (x86_64)

Download voicr-windows-x86_64.exe, rename it to voicr.exe, and move it to a folder in your %PATH% (e.g. C:\Windows\System32\).

Note: Daemon mode requires Linux or macOS (Unix socket).

Build from source

Requires Rust stable.

# Linux: install ALSA headers first
sudo apt-get install libasound2-dev pkg-config

git clone https://github.com/habitual69/voicr
cd voicr
cargo build --release
# binary at: target/release/voicr

Enable Whisper support (requires Vulkan SDK: libvulkan-dev glslang-tools):

cargo build --release --features whisper

Quick Start

# 1. Download a model
voicr model download parakeet-tdt-0.6b-v3

# 2. Run — hold Ctrl+Space, speak, release
voicr

# 3. Or run as a daemon and control it from anywhere
voicr daemon &
voicr send toggle        # start recording
voicr send toggle        # stop and transcribe

Cloud Mode (Groq, OpenAI, Sarvam AI, Custom)

Skip local model downloads and route transcription through cloud APIs for near-instant latency and high accuracy:

⚡ Groq: Ultra-fast inference with whisper-large-v3-turbo or whisper-large-v3.
🟩 OpenAI: Standard cloud transcription with whisper-1.
🇮🇳 Sarvam AI: Optimized transcription for Indian languages and English using saaras:v3.
⚙️ Custom: Any OpenAI-compatible /audio/transcriptions endpoint (e.g. self-hosted vLLM or LocalAI).

Setup via Web UI

Open the Web UI (http://127.0.0.1:7898) while the daemon is running, head to the Cloud tab, select your provider, enter your API key, and click "Fetch Models" to automatically load available models.

Setup via CLI

# Choose provider: groq, openai, sarvam, or custom
voicr config set cloud.provider groq
voicr config set cloud.groq_api_key YOUR_GROQ_KEY
voicr config set cloud.model whisper-large-v3-turbo

# For OpenAI:
voicr config set cloud.provider openai
voicr config set cloud.openai_api_key YOUR_OPENAI_KEY
voicr config set cloud.model whisper-1

# For Sarvam AI:
voicr config set cloud.provider sarvam
voicr config set cloud.sarvam_api_key YOUR_SARVAM_KEY
voicr config set cloud.model saaras:v3

# Enable cloud mode permanently
voicr config set cloud.enabled true

Use:

voicr --cloud                          # hold-to-talk, cloud transcription
voicr --cloud hotkey                   # hotkey mode via cloud
voicr --cloud daemon                   # daemon mode via cloud
voicr --cloud transcribe               # one-shot via cloud

Commands

Default mode

voicr          # hold-to-talk with auto-paste (Ctrl+Space)

On first run, voicr downloads the recommended model automatically. After that, just hold the hotkey and speak.

`voicr daemon`

Starts a background daemon that listens on a Unix socket for commands.

voicr daemon                          # uses /tmp/voicr.sock
voicr daemon --socket /run/voicr.sock # custom socket path

The daemon loads the configured model at startup, then waits for commands. Transcription results are broadcast to all connected clients and also printed to stdout (useful for piping).

`voicr send <command>`

Sends a command to a running daemon.

voicr send start           # start recording
voicr send stop            # stop recording and transcribe
voicr send toggle          # start if idle, stop if recording
voicr send cancel          # cancel recording without transcribing
voicr send status          # query current state
voicr send shutdown        # shut the daemon down

# wait for and print the result
voicr send toggle --wait

`voicr transcribe`

One-shot: record from microphone, transcribe, print result.

voicr transcribe                      # record until Ctrl+C
voicr transcribe --duration 10        # stop after 10 seconds
voicr transcribe --auto-stop          # stop on silence
voicr transcribe --no-vad             # disable silence filtering
voicr transcribe --file audio.wav     # transcribe a WAV file
voicr transcribe --output result.txt  # save to file instead of stdout

`voicr hotkey`

Push-to-talk mode with a custom hotkey combo.

voicr hotkey                          # uses configured combo
voicr hotkey --combo "alt+shift+r"    # override combo
voicr hotkey --no-paste               # print to stdout instead of pasting

`voicr model`

voicr model list                      # list all models with status
voicr model download <id>             # download a model
voicr model set <id>                  # set as active model
voicr model delete <id>               # delete a downloaded model
voicr model info <id>                 # show model details

`voicr config`

voicr config show                     # print current config
voicr config set <key> <value>        # update a setting
voicr config path                     # print config file location

`voicr history`

voicr history list                    # list recent transcriptions
voicr history list --limit 50         # show more entries
voicr history get <id>                # show full text of an entry
voicr history save <id>               # toggle saved/starred status
voicr history delete <id>             # delete an entry
voicr history export                  # export all history as JSON
voicr history export --output out.json

`voicr devices`

voicr devices                         # list audio input/output devices

`voicr autostart`

Manage automatic startup on system login:

voicr autostart enable                # enable launch on system login
voicr autostart disable               # disable launch on system login
voicr autostart status                # print current autostart status

Web Configuration UI

When the daemon is running, voicr serves a clean, lightweight web configuration dashboard locally at:

http://127.0.0.1:7898

From the UI, you can:

View the active transcription mode (Local model vs Cloud provider)
Select your audio input device with system default detection
Switch and download local models with real-time download progress
Configure and test Cloud providers (Groq, OpenAI, Sarvam AI, Custom) and fetch their STT models
Tune VAD sensitivity, hotkey combos, language detection, and output targets
Toggle system login autostart with a single click
Save settings and restart the background daemon smoothly

Models

ID	Name	Size	Languages	Notes
`moonshine-tiny-streaming-en`	Moonshine V2 Tiny	31 MB	English	Ultra-fast, lowest latency
`moonshine-base`	Moonshine Base	58 MB	English	Fast, handles accents well
`moonshine-small-streaming-en`	Moonshine V2 Small	100 MB	English	Great speed/accuracy balance
`sense-voice-int8`	SenseVoice	160 MB	EN / ZH / JA	CJK + English specialist
`moonshine-medium-streaming-en`	Moonshine V2 Medium	192 MB	English	Near-Parakeet accuracy
`gigaam-v3-e2e-ctc`	GigaAM v3	225 MB	Multilingual	Strong on Russian
`parakeet-tdt-0.6b-v2`	Parakeet V2	473 MB	English	Best English accuracy
`parakeet-tdt-0.6b-v3` ⭐	Parakeet V3	478 MB	25 European	Best overall — recommended
`small`	Whisper Small	487 MB	100+	Multilingual, translation
`medium`	Whisper Medium	492 MB	100+	Higher accuracy, slower
`large`	Whisper Large	1100 MB	100+	Max accuracy, slow
`turbo`	Whisper Turbo	1600 MB	100+	Balanced large variant
`breeze-asr`	Breeze ASR	1080 MB	ZH-TW / EN	Taiwanese Mandarin specialist

⭐ Recommended starting point. Whisper models require --features whisper at build time.

Models are stored in ~/.local/share/voicr/models/ (Linux/macOS) or %APPDATA%\voicr\models\ (Windows).

Configuration

Config file location:

voicr config path
# ~/.config/voicr/config.toml  (Linux)
# ~/Library/Application Support/voicr/config.toml  (macOS)
# %APPDATA%\voicr\config.toml  (Windows)

Full config with defaults:

[audio]
vad_enabled = true              # silence filtering for --auto-stop transcription
vad_threshold = 0.3             # VAD sensitivity (0.0–1.0, lower = more sensitive)
vad_hangover_frames = 8         # silence frames before stopping (1 frame = 30ms)
vad_prefill_frames = 5          # lead-in frames captured before speech onset
max_duration_secs = 0           # max recording length in seconds (0 = unlimited)
device = ""                     # audio device name (empty = system default)

[model]
selected = ""                   # active model ID
unload_timeout = "never"        # when to unload model from memory after use
                                # values: never | immediately | 2min | 5min | 10min | 15min | 1h

[transcription]
language = "auto"               # language code or "auto" for detection
translate_to_english = false    # translate to English (Whisper only)
custom_words = []               # words to boost recognition for (e.g. ["Alice", "Bob"])
filter_filler_words = true      # remove um/uh/etc from output
word_correction_threshold = 0.3

[history]
enabled = true                  # save transcriptions to local SQLite database
limit = 100                     # max entries to keep
retention = "months3"           # how long to keep entries
                                # values: never | preserve_limit | 3days | 2weeks | 3months

[output]
method = "stdout"               # where to send results: stdout | clipboard | file
file_path = ""                  # path when method = "file"
append_newline = true
append_trailing_space = false

[hotkey]
combo = "ctrl+space"            # global hotkey combo

[cloud]
enabled = false                 # use cloud transcription instead of a local model
provider = "groq"               # groq | openai | sarvam | custom
model = "whisper-large-v3-turbo"
groq_api_key = ""               # console.groq.com
openai_api_key = ""             # platform.openai.com
sarvam_api_key = ""             # dashboard.sarvam.ai
custom_api_key = ""             # for a custom OpenAI-compatible endpoint

Common config examples

# Set active model
voicr config set model.selected parakeet-tdt-0.6b-v3

# Use a specific microphone
voicr devices                               # find device name
voicr config set audio.device "HyperX SoloCast"

# Unload model 5 minutes after last use (saves RAM)
voicr config set model.unload_timeout 5min

# Transcribe in Spanish
voicr config set transcription.language es

# Tune silence detection for --auto-stop
voicr config set audio.vad_hangover_frames 8    # 240ms (default, snappy)
voicr config set audio.vad_hangover_frames 15   # 450ms (more forgiving pauses)

# Keep recordings for 2 weeks only
voicr config set history.retention 2weeks

# Enable cloud mode permanently
voicr config set cloud.groq_api_key YOUR_KEY
voicr config set cloud.enabled true

Daemon protocol

The daemon speaks newline-delimited JSON over a Unix socket. Any number of clients can connect simultaneously — events are broadcast to all.

Commands (client → daemon)

{"cmd":"start"}
{"cmd":"stop"}
{"cmd":"toggle"}
{"cmd":"cancel"}
{"cmd":"status"}
{"cmd":"models"}
{"cmd":"set","key":"model.selected","value":"parakeet-tdt-0.6b-v3"}
{"cmd":"shutdown"}

Events (daemon → clients)

{"type":"recording","state":"started"}
{"type":"recording","state":"stopped"}
{"type":"recording","state":"cancelled"}
{"type":"transcribing"}
{"type":"transcription","text":"Hello, world."}
{"type":"model_status","status":"loading","model_id":"parakeet-tdt-0.6b-v3"}
{"type":"model_status","status":"loaded","model_id":"parakeet-tdt-0.6b-v3","model_name":"Parakeet V3"}
{"type":"model_status","status":"unloaded"}
{"type":"models","models":[{"id":"parakeet-tdt-0.6b-v3","name":"Parakeet V3","is_downloaded":true,...}]}
{"type":"ok","message":"Set model.selected = parakeet-tdt-0.6b-v3"}
{"type":"status","state":"idle","model":"parakeet-tdt-0.6b-v3"}
{"type":"error","message":"..."}
{"type":"shutdown"}

Integrations

Auto-type transcriptions (X11)

voicr daemon &
nc -U /tmp/voicr.sock | while IFS= read -r line; do
  text=$(echo "$line" | jq -r 'select(.type=="transcription") | .text')
  [ -n "$text" ] && xdotool type --clearmodifiers "$text"
done

Hotkey daemon (sxhkd)

# ~/.config/sxhkd/sxhkdrc
super + space
    echo '{"cmd":"toggle"}' | nc -U /tmp/voicr.sock

Pipe to an LLM

voicr transcribe | llm "answer concisely:"

Autostart (systemd)

# ~/.config/systemd/user/voicr.service
[Unit]
Description=voicr speech-to-text daemon
After=sound.target

[Service]
ExecStart=/usr/local/bin/voicr daemon
# For cloud mode: ExecStart=/usr/local/bin/voicr --cloud daemon
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

systemctl --user enable --now voicr
systemctl --user status voicr

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
icons		icons
src		src
video		video
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md
build.rs		build.rs

Navigation Menu

Repository files navigation

voicr

Why voicr?

Features

Installation

Download a pre-built binary

Build from source

Quick Start

Cloud Mode (Groq, OpenAI, Sarvam AI, Custom)

Setup via Web UI

Setup via CLI

Commands

Default mode

`voicr daemon`

`voicr send <command>`

`voicr transcribe`

`voicr hotkey`

`voicr model`

`voicr config`

`voicr history`

`voicr devices`

`voicr autostart`

Web Configuration UI

Models

Configuration

Common config examples

Daemon protocol

Commands (client → daemon)

Events (daemon → clients)

Integrations

Autostart (systemd)

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

voicr

Why voicr?

Features

Installation

Download a pre-built binary

Build from source

Quick Start

Cloud Mode (Groq, OpenAI, Sarvam AI, Custom)

Setup via Web UI

Setup via CLI

Commands

Default mode

voicr daemon

voicr send <command>

voicr transcribe

voicr hotkey

voicr model

voicr config

voicr history

voicr devices

voicr autostart

Web Configuration UI

Models

Configuration

Common config examples

Daemon protocol

Commands (client → daemon)

Events (daemon → clients)

Integrations

Autostart (systemd)

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`voicr daemon`

`voicr send <command>`

`voicr transcribe`

`voicr hotkey`

`voicr model`

`voicr config`

`voicr history`

`voicr devices`

`voicr autostart`