Skip to content
Docs menu

Voice in the venom CLI

Dictate into the editor with /voice or ctrl+g r, and have answers read aloud with /speak or ctrl+g k.

View .md

Dictation

ctrl+g r (or /voice) starts recording from the microphone, and the same key stops it. The text goes in at the editor's cursor and nothing is sent until you press Enter. The HUD shows ● rec 0:04, then transcribing….

Recording needs sox (rec), else ffmpeg or arecord. Transcription runs on your machine when whisper.cpp's whisper-cli is on PATH with its model (voice.model, default ~/.venom/models/ggml-base.en.bin; voice.language, default en, or auto). Without it, the clip goes to your orchestrator's POST /v1/audio/transcriptions as voice.stt_model (default venom-transcribe; the VENOM_TRANSCRIBE_MODEL environment variable wins). No other host is called.

Read-aloud

/speak turns read-aloud on or off (/speak on, /speak off, /speak stop), and so does ctrl+g k. While it is on, each final answer is spoken through your orchestrator's POST /v1/audio/speech with voice.tts_model (default venom-speak) and voice.voice (default alloy). Code blocks, links and tables are skipped. voice.read_aloud: true turns it on when a session starts.

Playback starts as the audio arrives. venom uses the first player it finds on PATH:

Player How
ffplay (ffmpeg) or mpv streamed, in voice.format (default mp3)
paplay or aplay (Linux) streamed as raw PCM at the rate the orchestrator names
afplay (macOS) played once the audio has downloaded

With none of them, /speak prints one line saying what to install (brew install ffmpeg on macOS).

Any key stops playback: start typing, press Esc, or press ctrl+g k (which then stops without turning read-aloud off). The HUD shows ♪ speaking while it plays. That status is never sent to the model.

venom doctor reports the player, the model and the URL under read-aloud. Your orchestrator needs a venom-speak route: see Voice in the harness for the keys and the API.

Local speech, no orchestrator

Two extras stay on your machine and never call an orchestrator. On macOS, /voice can transcribe with the system's on-device speech recognizer when swift is installed (it fails with a message rather than send audio to Apple). And voice.speak: true (or /voice speak on) speaks a short plain-text summary of each finished turn through say, espeak-ng, espeak or piper (set voice.speak_model to a piper .onnx voice you downloaded). Tune it with voice.speak_voice and voice.speak_max_chars (40 to 600, default 240). /voice stop, the next turn or the dictation key cuts it off. It is off by default and separate from /speak; see docs/voice.md in the repository for setup.