​
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: 
pip install "pipecat-ai[soundfile]"

​
Constructor Parameters

​
sound_files
Mapping[str, str]
required
Dictionary mapping sound names to file paths. Files must be mono (single channel).
​
default_sound
str
required
Name of the default sound to play (must be a key in sound_files).
​
volume
float
default:"0.4"
Initial volume for the mixed sound. Values typically range from 0.0 to 1.0, but can go higher.
​
loop
bool
default:"true"
Whether to loop the sound file when it reaches the end.

​
Control Frames

​
MixerUpdateSettingsFrame
Frame
Updates mixer settings at runtime
​
MixerEnableFrame
Frame
Enables or disables the mixer

​
Usage Example

# 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