> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/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.

## Installation

The soundfile mixer requires additional dependencies:

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

## Constructor Parameters

<ParamField path="sound_files" type="Mapping[str, str]" required>
  Dictionary mapping sound names to file paths. Files must be mono (single channel).
</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 task.queue_frame(MixerUpdateSettingsFrame({"volume": 0.5}))
await task.queue_frame(MixerEnableFrame(False))  # Disable mixing
await task.queue_frame(MixerEnableFrame(True))   # Enable mixing
```

## Notes

* Supports any audio format that soundfile can read
* Automatically resamples audio files to match output sample rate
* Files must be mono (single channel)
* 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