> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Background Audio

> Play thinking sounds while the agent generates and ambient music or hold audio during a call.

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.

<Tabs>
  <Tab title="Python">
    <Note>
      Pass `background_audio=True` to `zrt.serve(...)` or `zrt.Room(...)`. An explicit file URL is required. An unset or empty file disables the audio.
    </Note>
  </Tab>
</Tabs>

## 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.

<CodeGroup>
  ```python title="main.py" Python theme={null}
  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,
          )
  ```
</CodeGroup>

## Ambient / background music

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

<CodeGroup>
  ```python title="main.py" Python theme={null}
  @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."
  ```
</CodeGroup>

## 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

<CardGroup cols={2}>
  <Card title="Audio Customization" icon="sliders" href="/build/modalities/speech-and-audio/audio-customization">
    Tune the agent's voice.
  </Card>

  <Card title="Modalities Overview" icon="shapes" href="/build/modalities/overview">
    Browse vision, text, and avatar modalities.
  </Card>
</CardGroup>

## References

<Tabs>
  <Tab title="Python">
    #### Examples

    <CardGroup cols={2}>
      <Card title="Background Audio" icon="github" href="https://github.com/ZeroRuntimeAI/zrt-python-sdk-examples/blob/main/features/background_audio.py">
        Play ambient or hold audio during a call.
      </Card>
    </CardGroup>

    #### SDK Reference

    <CardGroup cols={2}>
      <Card title="Background Audio" icon="book" href="/api-reference/python/core/recording-and-audio">
        `Background Audio` in the Python API reference.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>