Clip playback for voice agents
September 7, 2026 · release
@voicethere/agent
Voice agents can play sound effects, hold music, and notification clips without synthesizing speech. Clips mix with live microphones and TTS and route to selected listeners.
API
play({ url, sessionIds?, volume?, bytes? }) returns { ok, playId?, reason, requestId }. Omit sessionIds for all voice clients.
getPlay(playId) returns { ok, playId, status?, reason, requestId } with status: buffering | playing | stopped | ended | error.
stopPlay(playId) ends a clip early.
Encodings: WAV PCM, MP3, OGG Vorbis, OGG/Opus, FLAC, AAC-LC files. HTTPS-only URLs with download cache. Optional base64 bytes for clips under 64 KiB.
Clips are not TTS. They do not emit agent_speaking_* events.
Try it
- Docs: Clip playback (includes play to all listeners and placement / pose on
play()) - Mixing context: Positional mix & orbiting TTS
import { play, getPlay } from "@voicethere/agent";
const result = await play({
url: "https://cdn.example.com/sfx/chime.mp3",
sessionIds: [sessionId],
});
if (result.ok && result.playId) {
const status = await getPlay(result.playId);
}