Implementation:Openai Openai python Microphone Helper
| Knowledge Sources | |
|---|---|
| Domains | Audio, Helpers |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Concrete tool for microphone audio recording provided by the openai-python SDK.
Description
The microphone module provides the Microphone class, a generic helper for recording audio from the system microphone. It is parameterized by a NumPy dtype (defaulting to np.int16) and uses the sounddevice library to capture audio at a fixed SAMPLE_RATE of 24000 Hz. The async record() method opens an sd.InputStream with a callback that accumulates audio chunks into buffer_chunks. Recording stops when either the optional should_record callable returns False or the optional timeout (in seconds) is reached, signaled via an asyncio.Event. The method can return either raw npt.NDArray[DType] data (when return_ndarray=True) or a FileTypes tuple of ("audio.wav", BytesIO, "audio/wav") produced by the internal _ndarray_to_wav() method, which writes a proper WAV header via Python's wave module.
Usage
Use this class when building real-time audio applications that need to capture microphone input for the OpenAI Realtime API, audio transcription, or speech-to-text workflows.
Code Reference
Source Location
- Repository: openai-python
- File: src/openai/helpers/microphone.py
- Lines: 1-100
Signature
SAMPLE_RATE = 24000
class Microphone(Generic[DType]):
def __init__(
self,
channels: int = 1,
dtype: Type[DType] = np.int16,
should_record: Union[Callable[[], bool], None] = None,
timeout: Union[float, None] = None,
): ...
async def record(
self, return_ndarray: Union[bool, None] = False
) -> Union[npt.NDArray[DType], FileTypes]: ...
Import
from openai.helpers.microphone import Microphone
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| channels | int | No | Number of audio channels (default: 1 for mono) |
| dtype | Type[DType] | No | NumPy dtype for audio samples (default: np.int16) |
| should_record | Callable[[], bool] or None | No | Callback that returns False to stop recording |
| timeout | float or None | No | Maximum recording duration in seconds |
| return_ndarray | bool or None | No | If True, return raw NumPy array; otherwise return WAV FileTypes tuple |
Outputs
| Name | Type | Description |
|---|---|---|
| record() result (ndarray) | npt.NDArray[DType] | Raw audio samples as a NumPy array |
| record() result (file) | FileTypes | Tuple of ("audio.wav", BytesIO with WAV data, "audio/wav") |
Usage Examples
Basic Usage
import asyncio
from openai.helpers.microphone import Microphone
async def main():
# Record for 5 seconds, return as WAV file
mic = Microphone(timeout=5.0)
audio_file = await mic.record()
# audio_file is ("audio.wav", <BytesIO>, "audio/wav")
# Record until callback says stop, return as ndarray
import time
start = time.time()
mic = Microphone(
should_record=lambda: time.time() - start < 3.0,
)
audio_array = await mic.record(return_ndarray=True)
asyncio.run(main())