> ## 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 `zeroruntime.serve(room= zeroruntime.Room(...))`. An explicit file URL is required. An unset or empty file disables the audio.
    </Note>
  </Tab>

  <Tab title="Node JS">
    <Note>
      Pass `background_audio: true` to `zeroruntime.serve(Agent, { room: 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 as the agent enters, in the constructor. Provide a `file` to play; an unset file disables the audio.

<CodeGroup>
  ```python title="Python" 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,
          )
  ```

  ```typescript title="Node JS" Node JS theme={null}
  import { Agent } from '@zeroruntime/js-sdk';

  class VoiceAgent extends Agent {
    constructor(pipeline) {
      super({
        agent_id: 'assistant',
        instructions: 'You are a helpful assistant.',
        pipeline,
      });
    }

    // The thinking sound is set on the live session, so it is armed once the
    // agent has joined rather than in the constructor.
    async on_enter(): Promise<void> {
      await this.session!.set_thinking_audio(
        '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="Python" 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."
  ```

  ```typescript title="Node JS" Node JS theme={null}
  import { current_session, function_tool } from '@zeroruntime/js-sdk';

  const control_background_music = function_tool({
    name: 'control_background_music',
    description: "Play or stop background music. action: 'play' or 'stop'.",
    parameters: {
      action: { type: 'string', description: "Either 'play' or 'stop'." },
    },
    // Background audio is a session call, so this reads the live session rather
    // than the agent. Hold the tool on an agent field and `this` is bound for you.
    execute: async ({ action }) => {
      const session = current_session();
      if (action === 'play') {
        await session.play_background_audio(
          'https://cdn.zeroruntime.ai/zrt/bg-audio/bg-noise-1.wav',
          { volume: 0.8, looping: true, override_thinking: false },
        );
        return 'Music started.';
      }
      await session.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/zeroruntime-python-examples/blob/main/speech/background_audio.py">
        Play ambient or hold audio during a call.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Node JS">
    #### Examples

    <CardGroup cols={2}>
      <Card title="Background Audio" icon="github" href="https://github.com/ZeroRuntimeAI/zeroruntime-js-examples/blob/main/speech/background_audio.ts">
        Play ambient or hold audio during a call.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>