> ## Documentation Index
> Fetch the complete documentation index at: https://daily-main.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SoundfileMixer

> Audio mixer for combining real-time audio with sound files

## Overview

`SoundfileMixer` is an audio mixer that combines incoming audio with audio from files. It supports multiple audio file formats through the soundfile library and can handle runtime volume adjustments and sound switching.

<Warning>
  `SoundfileMixer` does not resample sound files. Each file must already match
  the output transport's sample rate.
</Warning>

## Installation

The soundfile mixer requires additional dependencies:

```bash theme={null}
uv add "pipecat-ai[soundfile]"
```

## Sample Rate Requirements

Sound files must match the output transport's sample rate and be mono (single channel). If a file's sample rate doesn't match, the mixer skips it at load time and logs a warning:

```
Sound file office_ambience.wav has incorrect sample rate 44100 (should be 24000)
```

The bot otherwise runs normally, so the only symptom is that background audio never plays. If that happens, check your logs for `has incorrect sample rate` and convert the file to the transport's sample rate.

## Constructor Parameters

<ParamField path="sound_files" type="Mapping[str, str]" required>
  Dictionary mapping sound names to file paths. Files must be mono (single channel), and each file's sample rate must match the output transport's sample rate.
</ParamField>

<ParamField path="default_sound" type="str" required>
  Name of the default sound to play (must be a key in sound\_files).
</ParamField>

<ParamField path="volume" type="float" default="0.4">
  Initial volume for the mixed sound. Values typically range from 0.0 to 1.0, but can go higher.
</ParamField>

<ParamField path="loop" type="bool" default="true">
  Whether to loop the sound file when it reaches the end.
</ParamField>

## Control Frames

<ParamField path="MixerUpdateSettingsFrame" type="Frame">
  Updates mixer settings at runtime

  <Expandable title="properties">
    <ParamField path="sound" type="str">
      Changes the current playing sound (must be a key in sound\_files)
    </ParamField>

    <ParamField path="volume" type="float">
      Updates the mixing volume
    </ParamField>

    <ParamField path="loop" type="bool">
      Updates whether the sound should loop
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="MixerEnableFrame" type="Frame">
  Enables or disables the mixer

  <Expandable title="properties">
    <ParamField path="enable" type="bool">
      Whether mixing should be enabled
    </ParamField>
  </Expandable>
</ParamField>

## Usage Example

```python theme={null}
# Initialize mixer with sound files
mixer = SoundfileMixer(
    sound_files={"office": "office_ambience.wav"},
    default_sound="office",
    volume=2.0,
)

# Add to transport
transport = DailyTransport(
    room_url,
    token,
    "Audio Bot",
    DailyParams(
        audio_out_enabled=True,
        audio_out_mixer=mixer,
    ),
)

# Control mixer at runtime
await worker.queue_frame(MixerUpdateSettingsFrame({"volume": 0.5}))
await worker.queue_frame(MixerEnableFrame(False))  # Disable mixing
await worker.queue_frame(MixerEnableFrame(True))   # Enable mixing
```

## Notes

* Supports any audio format that soundfile can read
* Sound files must be mono and match the output transport's sample rate — they are not resampled (see [Sample Rate Requirements](#sample-rate-requirements))
* Thread-safe for pipeline processing
* Can dynamically switch between multiple sound files
* Volume can be adjusted in real-time
* Mixing can be enabled/disabled on demand