Background Audio

Background audio fills the silences. The agent can play a subtle thinking sound while the LLM is generating, and ambient audio (hold music, office noise) on demand, so the call never feels dead. Any libav-decodable file works: WAV, MP3, Ogg/Vorbis, Ogg/Opus, FLAC, M4A/AAC.

Python

Pass background_audio=True to zrt.serve(...) or zrt.Room(...). An explicit file URL is required. An unset or empty file disables the audio.

Thinking audio

set_thinking_audio() plays a short sound while the agent is thinking (LLM generation). Call it in the agent’s constructor. Provide a file to play; an unset file disables the audio.

class VoiceAgent(Agent):
    def __init__(self, pipeline):
        super().__init__(
            agent_id="assistant",
            instructions="You are a helpful assistant.",
            pipeline=pipeline,
        )
        self.set_thinking_audio(
            file="https://cdn.zeroruntime.ai/zrt/bg-audio/bg-noise-1.wav",
            volume=0.3,
        )

Ambient / background music

Start and stop ambient audio on demand, for example, from a function tool the LLM can call:

@function_tool
async def control_background_music(self, action: str):
    """Play or stop background music. action: 'play' or 'stop'."""
    if action == "play":
        await self.play_background_audio(
            file="https://cdn.zeroruntime.ai/zrt/bg-audio/bg-noise-1.wav",
            volume=0.8,
            looping=True,
            override_thinking=False,
        )
        return "Music started."
    await self.stop_background_audio()
    return "Music stopped."

Parameters

set_thinking_audio(file=None, volume=0.3)

Parameter	Type	Default	Description
`file`	`str`	`None`	Audio file to play while the agent generates a reply. Required. An unset file disables it.
`volume`	`float`	`0.3`	Playback volume.

play_background_audio(file=None, volume=1.0, looping=False, override_thinking=True)

Parameter	Type	Default	Description
`file`	`str`	`None`	Audio file to play in the background. Required. An unset file disables it.
`volume`	`float`	`1.0`	Playback volume.
`looping`	`bool`	`False`	Loop the file until stopped.
`override_thinking`	`bool`	`True`	`True`: thinking audio layers over the music. `False`: music is exclusive and suppresses thinking audio while it plays.

Call stop_background_audio() to stop ambient playback.

What’s Next

Audio Customization

Tune the agent’s voice.

Modalities Overview

Browse vision, text, and avatar modalities.

References

Python

Examples

Play ambient or hold audio during a call.

SDK Reference