Audio Support

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

This API Reference is based on DeGirum Tools version 0.18.0.

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.