Implementation:Elevenlabs Elevenlabs python DefaultAudioInterface

Knowledge Sources	ElevenLabs Python ElevenLabs ConvAI Docs
Domains	Audio_Processing, Conversational_AI, Hardware_Abstraction
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for bidirectional microphone/speaker audio I/O using PyAudio provided by the elevenlabs-python SDK.

Description

The DefaultAudioInterface class implements the AudioInterface ABC using PyAudio for cross-platform audio capture and playback. It opens two PCM streams (16-bit mono, 16kHz):

Input stream: Uses PyAudio callbacks with 4000-sample (250ms) buffers to capture microphone audio
Output stream: Uses a queue-based buffer with a dedicated playback thread using 1000-sample (62.5ms) write buffers

The output queue enables non-blocking audio delivery and supports instant interruption by clearing the queue. The input stream uses PyAudio's callback mode which runs in a separate thread automatically.

Usage

Instantiate this class and pass it to the Conversation constructor. It requires the pyaudio package to be installed. For custom audio handling (e.g., virtual devices, WebRTC, file-based testing), implement the AudioInterface ABC directly instead.

Code Reference

Source Location

Repository: elevenlabs-python
File: src/elevenlabs/conversational_ai/default_audio_interface.py
Lines: L9-84

Signature

class DefaultAudioInterface(AudioInterface):
    INPUT_FRAMES_PER_BUFFER = 4000   # 250ms @ 16kHz
    OUTPUT_FRAMES_PER_BUFFER = 1000  # 62.5ms @ 16kHz

    def __init__(self):
        """Initialize PyAudio. Raises ImportError if pyaudio is not installed."""

    def start(self, input_callback: Callable[[bytes], None]):
        """Start audio capture and playback streams.

        Args:
            input_callback: Called with microphone audio bytes (PCM 16-bit mono 16kHz).
        """

    def stop(self):
        """Stop streams and release PyAudio resources."""

    def output(self, audio: bytes):
        """Queue audio for playback (non-blocking).

        Args:
            audio: PCM 16-bit mono 16kHz audio bytes.
        """

    def interrupt(self):
        """Clear the output queue to stop current playback immediately."""

Import

from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

I/O Contract

Inputs

Name	Type	Required	Description
input_callback	Callable[[bytes], None]	Yes (to start())	Callback receiving microphone audio chunks (PCM 16-bit mono 16kHz, 250ms buffers)
audio	bytes	Yes (to output())	Agent audio to play (PCM 16-bit mono 16kHz)

Outputs

Name	Type	Description
input_callback calls	bytes	Microphone audio chunks delivered via callback (4000 samples / 250ms per chunk)
Speaker output	audio playback	Agent audio played through system speakers with 62.5ms write buffers

Usage Examples

Basic Conversational AI Setup

from elevenlabs import ElevenLabs
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
from elevenlabs.conversational_ai.conversation import Conversation

client = ElevenLabs()
audio_interface = DefaultAudioInterface()

conversation = Conversation(
    client=client,
    agent_id="your-agent-id",
    requires_auth=False,
    audio_interface=audio_interface,
    callback_agent_response=lambda text: print(f"Agent: {text}"),
    callback_user_transcript=lambda text: print(f"User: {text}"),
)

conversation.start_session()
# Audio I/O is now active: microphone captured, agent audio played
conversation.wait_for_session_end()

Custom Audio Interface (Pattern)

from elevenlabs.conversational_ai.conversation import AudioInterface

class FileAudioInterface(AudioInterface):
    """Example custom implementation for testing."""

    def __init__(self, input_file: str):
        self.input_file = input_file
        self.output_chunks = []

    def start(self, input_callback):
        # Read from file instead of microphone
        with open(self.input_file, "rb") as f:
            while chunk := f.read(8000):  # 4000 samples * 2 bytes
                input_callback(chunk)

    def stop(self):
        pass

    def output(self, audio: bytes):
        self.output_chunks.append(audio)

    def interrupt(self):
        self.output_chunks.clear()

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment