Environment:Openai Openai python Voice Helpers

Knowledge Sources	openai-python
Domains	Infrastructure, Audio
Last Updated	2026-02-15 10:00 GMT

Overview

Optional audio I/O environment providing `sounddevice` and `numpy` for local audio playback and microphone recording with the OpenAI audio APIs.

Description

This environment extends the base Python 3.9+ environment with local audio device support. It provides the `LocalAudioPlayer` and `Microphone` helper classes that enable direct audio playback from TTS responses and microphone recording for speech input. These are convenience utilities; the core audio API endpoints (speech, transcriptions, translations) work without this environment by operating on file bytes directly.

Usage

Use this environment when you need local audio playback from TTS responses or microphone input for real-time voice applications. It is required by the Local_Audio_Player implementation and any code that uses the `openai.helpers.LocalAudioPlayer` or `openai.helpers.Microphone` classes.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Audio device access required
Python	>= 3.9	Same as base SDK
Hardware	Audio output device	Speakers or headphones for playback
Hardware	Audio input device	Microphone for recording (optional, only for `Microphone` class)

Dependencies

System Packages

• `portaudio` — Required by `sounddevice` on some systems (e.g., `apt install portaudio19-dev` on Debian/Ubuntu, `brew install portaudio` on macOS)

Python Packages

• `sounddevice` >= 0.5.1 — Audio device I/O
• `numpy` >= 2.0.2 — Audio array handling
• All base SDK dependencies (see Environment:Openai_Openai_python_Python_3_9_Plus)

Credentials

Same as base SDK:

• `OPENAI_API_KEY`: Required. OpenAI API key.

Quick Install

# Install SDK with voice helper support
pip install openai[voice_helpers]

# On Debian/Ubuntu, you may also need:
sudo apt install portaudio19-dev

Code Evidence

Numpy lazy proxy from `_extras/numpy_proxy.py:16-24`:

class NumpyProxy(LazyProxy[Any]):
    @override
    def __load__(self) -> Any:
        try:
            import numpy
        except ImportError as err:
            raise MissingDependencyError(NUMPY_INSTRUCTIONS) from err
        return numpy

Sounddevice lazy proxy from `_extras/sounddevice_proxy.py:16-24`:

class SounddeviceProxy(LazyProxy[Any]):
    @override
    def __load__(self) -> Any:
        try:
            import sounddevice
        except ImportError as err:
            raise MissingDependencyError(SOUNDDEVICE_INSTRUCTIONS) from err
        return sounddevice

Error message template from `_extras/_common.py:3-12`:

INSTRUCTIONS = """
OpenAI error:
    missing `{library}`
This feature requires additional dependencies:
    $ pip install openai[{extra}]
"""

Optional dependency declaration from `pyproject.toml:52`:

voice_helpers = ["sounddevice>=0.5.1", "numpy>=2.0.2"]

Common Errors

Error Message	Cause	Solution
`MissingDependencyError: missing sounddevice`	`sounddevice` not installed	`pip install openai[voice_helpers]`
`MissingDependencyError: missing numpy`	`numpy` not installed	`pip install openai[voice_helpers]`
`PortAudio library not found`	System audio library missing	Install PortAudio: `apt install portaudio19-dev` (Linux) or `brew install portaudio` (macOS)

Compatibility Notes

• Audio sample rate: The SDK uses 24kHz (24000 Hz) as the default sample rate for audio playback and recording.
• Linux: May require `portaudio19-dev` system package for `sounddevice` to build.
• macOS: May require `portaudio` via Homebrew.
• Windows: `sounddevice` typically works without additional system packages.
• Headless servers: Audio device access will fail on servers without sound hardware. Use file-based audio APIs instead.

Related Pages

• Implementation:Openai_Openai_python_Local_Audio_Player