Environment:Elevenlabs Elevenlabs python PyAudio
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Audio_IO |
| Last Updated | 2026-02-15 12:00 GMT |
Overview
Python environment with PyAudio for real-time microphone input and speaker output in conversational AI sessions.
Description
This environment provides the audio I/O layer for the ElevenLabs Conversational AI feature. PyAudio is an optional dependency that wraps PortAudio to provide cross-platform microphone capture and speaker output. The `DefaultAudioInterface` and `AsyncDefaultAudioInterface` classes use PyAudio to open 16-bit PCM mono streams at 16kHz for both input and output, enabling real-time two-way voice conversations with ElevenLabs agents.
Usage
Use this environment when running the Conversational AI feature with the built-in `DefaultAudioInterface`. It is required for real-time microphone input and audio playback during `Conversation` and `AsyncConversation` sessions. If you implement a custom `AudioInterface`, PyAudio is not needed.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Any (Windows, macOS, Linux) | PortAudio system library required on Linux |
| Python | >= 3.8 | Required by elevenlabs SDK |
| Hardware | Audio input device (microphone) | Required for voice input capture |
| Hardware | Audio output device (speakers/headphones) | Required for agent voice playback |
| System Library | PortAudio | Linux: `apt install portaudio19-dev`; macOS: `brew install portaudio` |
Dependencies
System Packages
- `portaudio19-dev` (Linux/Debian) or `portaudio` (macOS/Homebrew)
Python Packages
- `pyaudio` >= 0.2.14
Credentials
No additional credentials required beyond the base ElevenLabs API key.
Quick Install
# Install with PyAudio extra
pip install elevenlabs[pyaudio]
# Or install PyAudio separately
pip install pyaudio>=0.2.14
# On Linux, you may need the PortAudio system library first:
# sudo apt-get install portaudio19-dev
# On macOS:
# brew install portaudio
Code Evidence
Optional dependency declaration in `pyproject.toml:41`:
pyaudio = { version = ">=0.2.14", optional = true}
Extras definition in `pyproject.toml:93-94`:
[tool.poetry.extras]
pyaudio=["pyaudio"]
Lazy import with error message in `default_audio_interface.py:14-17`:
try:
import pyaudio
except ImportError:
raise ImportError("To use DefaultAudioInterface you must install pyaudio.")
Audio stream configuration in `default_audio_interface.py:31-46`:
self.in_stream = self.p.open(
format=self.pyaudio.paInt16,
channels=1,
rate=16000,
input=True,
stream_callback=self._in_callback,
frames_per_buffer=self.INPUT_FRAMES_PER_BUFFER,
start=True,
)
self.out_stream = self.p.open(
format=self.pyaudio.paInt16,
channels=1,
rate=16000,
output=True,
frames_per_buffer=self.OUTPUT_FRAMES_PER_BUFFER,
start=True,
)
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ImportError: To use DefaultAudioInterface you must install pyaudio.` | PyAudio not installed | `pip install elevenlabs[pyaudio]` or `pip install pyaudio` |
| `Could not find PyAudio; No such file or directory: 'portaudio.h'` | PortAudio system library missing | Install PortAudio: `apt install portaudio19-dev` (Linux) or `brew install portaudio` (macOS) |
| `IOError: [Errno -9996] Invalid input device` | No microphone detected | Connect a microphone or configure the default audio input device in OS settings |
| `IOError: [Errno -9997] Invalid sample rate` | Audio device doesn't support 16kHz | Use a different audio device or implement a custom AudioInterface with resampling |
Compatibility Notes
- Optional dependency: PyAudio is declared as optional in pyproject.toml. Install via `pip install elevenlabs[pyaudio]`.
- Custom AudioInterface: If PyAudio is not available or not suitable, users can implement the `AudioInterface` or `AsyncAudioInterface` ABC with any audio library.
- Audio format: Fixed at 16-bit PCM mono, 16kHz sample rate. This is a server-side requirement for the ConvAI WebSocket protocol.
- Linux: Requires `portaudio19-dev` system package before pip install.
- macOS: Requires `portaudio` via Homebrew before pip install.
- Windows: PyAudio wheels typically include PortAudio; no system package needed.