strands.experimental.bidi.io

Send and receive audio data from devices.

Reads user audio from input device and sends agent audio to output device using PyAudio. If a user interrupts the agent, the output buffer is cleared to stop playback.

Audio configuration is provided by models that implement AudioCapable.

Optional microphone audio processing (acoustic echo cancellation, noise suppression, and automatic gain control) is enabled by passing audio_processor=True or an AudioProcessorConfig to AudioIO. It requires pywebrtc-audio (pip install strands-agents[bidi-aec]).

AudioIO

class AudioIO()

Defined in: src/strands/experimental/bidi/io/audio.py:304

Send and receive audio data from devices using PyAudio.

Reads microphone audio via input(), plays agent audio via output(), and displays user and assistant transcripts. Interruptions clear the playback buffer to stop the agent mid-response.

When audio_processor=True or an AudioProcessorConfig is passed, the microphone signal gets audio processing and, when echo cancellation is enabled, the agent’s speaker output is used as a reference to cancel echo from the mic input. A shared processor coordinates the input and output channels, so echo cancellation only works when both come from the same AudioIO instance.

Audio processing requires pywebrtc-audio (pip install strands-agents[bidi-aec]) and a microphone sample rate of 16000, 32000, or 48000 Hz (set via the model’s audio config).

Device audio requires PyAudio. Install the PortAudio system library, then install strands-agents[bidi-pyaudio].

Example:

from strands.experimental.bidi.io import AudioIO, AudioProcessorConfig

# Plain mic/speaker, no processing (a headset is recommended to avoid echo):
audio_io = AudioIO()
await agent.run(inputs=[audio_io.input()], outputs=[audio_io.output()])

# Full processing with defaults: echo cancellation, noise suppression, and auto gain control:
audio_io = AudioIO(audio_processor=True)
await agent.run(inputs=[audio_io.input()], outputs=[audio_io.output()])

# Noise suppression and auto gain control without echo cancellation (e.g. headset users):
audio_io = AudioIO(audio_processor=AudioProcessorConfig(echo_cancellation=False))
await agent.run(inputs=[audio_io.input()], outputs=[audio_io.output()])

# Processing on a specific input device:
audio_io = AudioIO(audio_processor=AudioProcessorConfig(), input_device_index=1)
await agent.run(inputs=[audio_io.input()], outputs=[audio_io.output()])

init

def __init__(**config: Unpack[AudioIOConfig]) -> None

Defined in: src/strands/experimental/bidi/io/audio.py:346

Initialize audio devices.

Arguments:

**config - Optional configuration:
- audio_processor (bool | AudioProcessorConfig): Set to True to enable microphone audio processing with defaults, or supply a configuration for custom options. False and None disable processing.
- input_buffer_size (int): Maximum input buffer size (default: None). Must be between 1 and 100 when echo cancellation is on; defaults to 100 so the mic and reference buffers remain aligned.
- input_device_index (int): Specific input device (default: None = system default)
- input_frames_per_buffer (int): Input buffer size (default: 512). Must not be provided when echo cancellation is on because it is calculated from the model’s input rate.
- output_buffer_size (int): Maximum output buffer size (default: None)
- output_device_index (int): Specific output device (default: None = system default)
- output_frames_per_buffer (int): Output buffer size (default: 512). Must not be provided when echo cancellation is on because it is calculated from the model’s output rate.

Raises: