---
title: Voice in the venom CLI
description: Dictate into the editor with /voice or ctrl+g r, and have answers read aloud with /speak or ctrl+g k.
section: voice
order: 10
audience: [user]
sources: [cli/src/voice.ts, cli/src/speak.ts, cli/src/voice-speech.ts, docs/configuration.md]
features: [voice.voice-input, voice.read-aloud, voice.voice]
---

## Dictation {#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 {#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](/docs/voice/harness-voice.md) for the keys and the API.

## Local speech, no orchestrator {#local-speech}

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.
