SoundfileMixer

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.

SoundfileMixer does not resample sound files. Each file must already match the output transport’s sample rate.

Installation

The soundfile mixer requires additional dependencies:

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

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.

str

required

Name of the default sound to play (must be a key in sound_files).

float

default:"0.4"

Initial volume for the mixed sound. Values typically range from 0.0 to 1.0, but can go higher.

bool

default:"true"

Whether to loop the sound file when it reaches the end.

Control Frames

Frame

Updates mixer settings at runtime

Show properties

str

Changes the current playing sound (must be a key in sound_files)

float

Updates the mixing volume

bool

Updates whether the sound should loop

Frame

Enables or disables the mixer

Show properties

bool

Whether mixing should be enabled

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 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)
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

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Overview

Installation

Sample Rate Requirements

Constructor Parameters

Control Frames

Usage Example

Notes

​Overview

​Installation

​Sample Rate Requirements

​Constructor Parameters

​Control Frames

​Usage Example

​Notes

Overview

Installation

Sample Rate Requirements

Constructor Parameters

Control Frames

Usage Example

Notes