​
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
SileroVADAnalyzerBase Frame Types