# Audio Support
{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}
## Audio Support Module Overview
This module provides utilities for opening microphone or file-based audio streams and for generating audio frames. The module provides context managers and generators that simplify audio capture and processing workflows.
Key Features
* **Audio Stream Management**: Open and manage audio streams from microphones and files
* **Buffer Generation**: Generate audio frames with configurable buffer sizes
* **Overlapping Buffers**: Support for overlapping audio buffers
* **Format Support**: Handle WAV files and microphone input
* **Stream Control**: Non-blocking and blocking stream operations
* **Error Handling**: Robust error handling for stream operations
Typical Usage
1. Call `open_audio_stream()` to create an audio stream
2. Iterate over `audio_source()` or `audio_overlapped_source()` to process frames
3. Use non-blocking mode for real-time processing
4. Handle stream errors and cleanup
Integration Notes
* Works with PyAudio for microphone input
* Supports WAV file format
* Handles both local and remote audio sources
* Provides consistent interface across platforms
Key Functions
* `open_audio_stream()`: Context manager for microphone or WAV files
* `audio_source()`: Generator yielding audio buffers
* `audio_overlapped_source()`: Generator yielding overlapping buffers
Configuration Options
* Sampling rate
* Buffer size
* Source selection
* Blocking mode
## Functions
#### open\_audio\_stream(sampling\_rate\_hz, ...)
`open_audio_stream(sampling_rate_hz, buffer_size, audio_source=None)`
Open an audio stream.
This context manager opens a microphone or WAV file as an audio stream and automatically closes it when the context exits.
Parameters:
| Name | Type | Description | Default |
| ------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `sampling_rate_hz` | `int` | Desired sample rate in hertz. | *required* |
| `buffer_size` | `int` | Buffer size in frames. | *required* |
| `audio_source` | `Union[int, str, None]` | Source identifier. Use an integer for a microphone index, a string for a WAV file path or URL, or `None` to use the default source. | `None` |
Yields:
| Type | Description |
| ----- | ------------------------------------------------------------- |
| `Any` | Stream-like object with get() method returning audio buffers. |
Raises:
| Type | Description |
| ----------- | ----------------------------------------------------------------------- |
| `Exception` | If the audio stream cannot be opened or the WAV file format is invalid. |
#### audio\_source(stream, ...)
`audio_source(stream, check_abort, non_blocking=False)`
Yield audio frames from a stream.
Parameters:
| Name | Type | Description | Default |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------ | ---------- |
| `stream` | `Any` | Audio stream object returned by `open_audio_stream()`. | *required* |
| `check_abort` | `Callable[[], bool]` | Callback that returns `True` to stop iteration. | *required* |
| `non_blocking` | `bool` | If `True` and no frame is available, `None` is yielded instead of blocking. Defaults to `False`. | `False` |
Yields:
| Type | Description |
| ------------------- | -------------------------------------------------------------------------------------- |
| `Optional[ndarray]` | Waveform of int16 samples or None when no data is available and non\_blocking is True. |
#### audio\_overlapped\_source(stream, ...)
`audio_overlapped_source(stream, check_abort, non_blocking=False)`
Generate audio frames with 50% overlap.
The function reads blocks from `stream` and yields frames that overlap by half of their length. Overlapping frames produce smoother results for audio analysis.
Parameters:
| Name | Type | Description | Default |
| -------------- | -------------------- | ------------------------------------------------------------------------------------------------ | ---------- |
| `stream` | `Any` | Audio stream object returned by `open_audio_stream()`. | *required* |
| `check_abort` | `Callable[[], bool]` | Callback that returns `True` to stop iteration. | *required* |
| `non_blocking` | `bool` | If `True` and no frame is available, `None` is yielded instead of blocking. Defaults to `False`. | `False` |
Yields:
| Type | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `Optional[ndarray]` | Waveform of int16 samples with 50% overlap, or None when no data is available and non\_blocking is True. |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.degirum.com/degirum-tools/support/audio_support.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.