# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Audio sample sources: raw PCM in memory, WAV files, and the calls that read
a source's buffers directly.
`RawSample` plays a buffer you already hold and `WaveFile` streams a `.wav`
file. Both are audio samples, the objects every other audiodsp module reads
from __future__ import annotations
from and writes to: each has `sample_rate`, `bits_per_sample` and
`channel_count`, and hands its audio to whatever plays it. The module has
CircuitPython's own `audiocore` API, so one script runs on both.
`get_buffer`, `reset_buffer` and `get_structure` pull audio out of any audio
sample by hand, with no output device, which is how a test reads what a chain
of nodes produces.
"""
from types import TracebackType
from typing import Self
__version__: str
"""The audiodsp release this module came from."""
__revision__: str
"""Which source this build was made from, from `git describe`: a release tag,
or the nearest one and the commit. "unknown" when the build had no git."""
[docs]
class RawSample:
"""Plays a buffer of raw PCM samples that you provide.
The buffer is read in place and never copied, so keep it unchanged while
the sample plays. Samples are 8 or 16 bits, signed or unsigned, taken
from the buffer's type.
Args:
buffer: A `bytearray` or an `array.array` of type ``'b'``, ``'B'``,
``'h'`` or ``'H'``. A ``'b'`` or ``'h'`` array holds signed
samples; the others hold unsigned samples.
channel_count: 1 for mono, 2 for interleaved stereo.
sample_rate: Frames per second.
single_buffer: True to play the buffer once through as one block.
False splits it into two halves handed out alternately, so the
buffer's length must be a multiple of twice the size of one frame.
Raises:
ValueError: The buffer is not one of the types above, or
``single_buffer`` is False and its length is not a multiple of
``channel_count`` times the sample size times two.
"""
def __init__(
self,
buffer: bytes | bytearray | memoryview,
*,
channel_count: int = 1,
sample_rate: int = 8000,
single_buffer: bool = True,
) -> None: ...
sample_rate: int
"""Frames per second. You can change it while the sample plays, to 1 or
more, to play it faster or slower."""
@property
def bits_per_sample(self) -> int:
"""Size of one sample in bits: 8 or 16."""
@property
def channel_count(self) -> int:
"""Number of channels: 1 or 2."""
[docs]
def deinit(self) -> None:
"""Release the sample. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ...
def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs]
class WaveFile:
"""Streams audio from a ``.wav`` file.
The file stays open and is read a block at a time while the sample
plays. Uncompressed PCM of 16 bits or fewer, mono or stereo, is
supported: 8-bit samples are unsigned and 16-bit samples are signed.
Args:
file: A path, or a binary file object opened for reading.
buffer: A writable buffer, 8 to 1024 bytes and a multiple of 8, to
read blocks into. Leave it out to let the sample allocate its
own.
Raises:
ValueError: The file is not a supported WAV file, or the buffer is
the wrong size.
OSError: The file cannot be opened or read.
"""
def __init__(self, file: str | object, buffer: bytearray | memoryview | None = None, /) -> None: ...
sample_rate: int
"""Frames per second. You can change it while the sample plays, to 1 or
more, to play it faster or slower."""
@property
def bits_per_sample(self) -> int:
"""Size of one sample in bits: 8 or 16."""
@property
def channel_count(self) -> int:
"""Number of channels: 1 or 2."""
[docs]
def deinit(self) -> None:
"""Release the sample and close its file. Every later use raises
`ValueError`."""
def __enter__(self) -> Self: ...
def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...
[docs]
def get_buffer(sample: RawSample | WaveFile | object, /) -> tuple[int, memoryview | None]:
"""Read the next block of audio from a sample.
Args:
sample: Any audio sample: a `RawSample`, a `WaveFile`, or a node from
another audiodsp module.
Returns:
``(status, block)``. ``status`` is 0 when this was the last block, 1
when more follow and 2 on an error; ``block`` is a copy of the audio
as a byte `memoryview`, and None when the status is 2. Its length is
in bytes, whatever the sample width.
Raises:
TypeError: ``sample`` is not an audio sample.
ValueError: The sample was deinitialised.
"""
[docs]
def reset_buffer(sample: RawSample | WaveFile | object, /) -> None:
"""Rewind a sample so the next `get_buffer` starts from its beginning.
Raises:
TypeError: ``sample`` is not an audio sample.
ValueError: The sample was deinitialised.
"""
[docs]
def get_structure(sample: RawSample | WaveFile | object, /) -> tuple[int, int, int, int]:
"""Describe how a sample hands out its audio.
Returns:
``(single_buffer, samples_signed, max_buffer_length, spacing)``:
whether one block holds the whole sample, whether samples are signed,
the most bytes one block can hold, and the bytes between one
channel's samples.
Raises:
TypeError: ``sample`` is not an audio sample.
ValueError: The sample was deinitialised.
"""