> For the complete documentation index, see [llms.txt](https://docs.degirum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.degirum.com/degirum-tools/support/audio_support.md).

# Audio Support

DeGirum Tools API Reference Guide. Open microphone or file-based audio streams.

{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}

## Audio Support Module Overview <a href="#audio-support-module-overview" id="audio-support-module-overview"></a>

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 <a href="#functions" id="functions"></a>

#### open\_audio\_stream(sampling\_rate\_hz, ...) <a href="#open_audio_stream" id="open_audio_stream"></a>

`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, ...) <a href="#audio_source" id="audio_source"></a>

`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, ...) <a href="#audio_overlapped_source" id="audio_overlapped_source"></a>

`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. |