---
title: Voice in the harness
description: The @venom/harness/voice client (speak, listVoices, transcribe, translate), the agent's speak and transcribe tools, and venom.yaml's voice keys.
section: voice
order: 20
audience: [builder, user, agent]
sources: [packages/harness/src/voice/index.ts, packages/harness/src/extensions/voice-tools.ts, packages/harness/src/config/schema.ts]
features: [harness.voice, cli.tool-speak, cli.tool-transcribe, voice.speech]
---

## The voice client {#client}

`@venom/harness/voice` is a typed client for the orchestrator's audio API. It talks only to the base URL you give it.

```ts
import { createWriteStream } from "node:fs";
import { Writable } from "node:stream";
import { VoiceClient } from "@venom/harness/voice";

const voice = new VoiceClient({ baseUrl: "http://127.0.0.1:8787/v1", apiKey: process.env.VENOM_API_KEY });

const audio = await voice.speak({ input: "Build passed.", voice: "alloy", format: "mp3" });
await audio.body.pipeTo(Writable.toWeb(createWriteStream("done.mp3")));

const voices = await voice.listVoices("venom-speak");
const { text } = await voice.transcribe({ file: await audio.bytes(), filename: "clip.mp3" });
```

| Method | Endpoint | Returns |
|---|---|---|
| `speak({ input, model?, voice?, format?, speed?, instructions?, stream?, language?, sampleRate?, provider? })` | `POST /v1/audio/speech` | `{ format, contentType, sampleRate?, model, voice, body, bytes() }`: read the audio as a stream (`body`) or all at once (`bytes()`) |
| `listVoices(model?)` | `GET /v1/audio/voices?model=` | `[{ id, name?, languages?, gender?, preview_url?, provider, model }]` |
| `transcribe({ file, filename?, model?, language?, prompt?, temperature? })` | `POST /v1/audio/transcriptions` | `{ text, language?, duration?, model, raw }` |
| `translate({ file, filename?, model?, prompt? })` | `POST /v1/audio/translations` | the same, in English |

Defaults: model `venom-speak` for speech and `venom-transcribe` for transcription, voice `alloy`, format `mp3`. `stream: true` asks the orchestrator to use the provider's streaming endpoint where there is one; the audio is a stream either way. For `pcm` (signed 16-bit mono) and `wav`, `sampleRate` comes from the `x-venom-sample-rate` header, or 24000 Hz for `pcm`. `language`, `sampleRate` and `provider` go in `venom_options`. A failure throws `VoiceError` with the HTTP `status` and OpenAI's error `code`, such as `model_not_tts`.

## The speak and transcribe tools {#tools}

Every session has two agent tools:

- `speak` turns text (up to 4,096 characters) into an audio file and returns its path. Without a `path` the file goes in the session's temp dir.
- `transcribe` turns an audio file in the workspace (mp3, m4a, wav, webm, ogg or flac, up to 25 MB) into text. `translate: true` gives English.

Neither is in the tool list or system prompt at the start of a session, so they cost nothing per request. `tool_search` loads them in sessions where it is on, and an app can name them in the session's tools. The permission gate asks before either runs, as it does for any tool it has no category for: plan mode denies them and yolo allows them. `transcribe` only reads a file that `read` may read, and `speak` only writes where `write` isn't denied. An app sets their models with `HarnessOptions.voice` (`{ ttsModel, voice, sttModel, format }`) and removes them with `voice: false`.

## venom.yaml {#config}

| Key | Default | What |
|---|---|---|
| `voice.tts_model` | `venom-speak` | the model or alias that speaks |
| `voice.voice` | `alloy` | the voice id; `GET /v1/audio/voices?model=` lists a model's voices |
| `voice.format` | `mp3` | `mp3`, `opus`, `aac`, `flac`, `wav` or `pcm` |
| `voice.stt_model` | `venom-transcribe` | the model or alias that transcribes when whisper.cpp isn't installed, and the `transcribe` tool's; `VENOM_TRANSCRIBE_MODEL` wins |
| `voice.read_aloud` | `false` | speak the assistant's final answers from the start of a terminal session |

`voiceConfig(cfg)` reads these keys with their defaults.
