Voice in the harness
The @venom/harness/voice client (speak, listVoices, transcribe, translate), the agent's speak and transcribe tools, and venom.yaml's voice keys.
The voice client
@venom/harness/voice is a typed client for the orchestrator's audio API. It talks only to the base URL you give it.
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
Every session has two agent tools:
speakturns text (up to 4,096 characters) into an audio file and returns its path. Without apaththe file goes in the session's temp dir.transcribeturns an audio file in the workspace (mp3, m4a, wav, webm, ogg or flac, up to 25 MB) into text.translate: truegives 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
| 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.