Audio Effects

This recipe shows how to inject background noise, codec degradation, and other audio impairments into a voice scenario. Effects are applied to the user simulator's audio after TTS synthesis — they are never baked into the TTS cache.

Pattern

Pass a list of effect functions to UserSimulatorAgent(audio_effects=[...]). Effects compose left-to-right: the output of each effect is the input to the next.

scenario.UserSimulatorAgent(
    voice="openai/nova",
    audio_effects=[
        scenario.effects.background_noise("cafe", volume=0.4),
        scenario.effects.phone_quality(),
    ],
)

Available effects

Effect	Description
`background_noise(preset_or_path, volume)`	Overlay ambient noise. Built-in presets: `"cafe"`, `"street"`, `"office"`, `"airport"`. Pass a `.wav` path for custom noise.
`static(intensity)`	White-noise static at the given fraction of full scale.
`multiple_voices()`	Mix with a babble sample to simulate background conversation.
`phone_quality()`	Bandpass 300Hz–3.4kHz + mild compression, mimicking a phone line.
`low_quality(bitrate)`	Downsample to `bitrate` Hz and back — aliasing and quantisation artefacts.
`packet_loss(probability, chunk_ms)`	Zero out random windows at the given probability.
`echo(delay_ms, decay)`	Overlay a delayed, attenuated copy of the signal.
`robotic()`	Ring-modulate the signal with a 100Hz carrier for a robotic timbre.
`breaking_up()`	Frequent 100ms dropouts simulating a losing-signal scenario.
`custom(fn)`	Bring your own `Callable[[bytes], bytes]` operating on PCM16 @ 24kHz mono.

Per-step overrides

The audio_effects list on UserSimulatorAgent applies to every user turn in the scenario.

Worked example

angry_customer.py — applies background_noise("cafe", 0.4) and phone_quality() to simulate an angry caller from a noisy cafe on a poor phone connection. JudgeAgent verifies the agent handles the emotional tone and noise robustly.

background_handoff.py — uses background_noise("cafe", 0.5) to simulate overheard conversation during a handoff; verifies the agent does not respond to the background audio as user speech.