Source code for audiomp3

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Play MP3 files.

`MP3Decoder` reads an MP3 file while it plays and hands out signed 16-bit
audio. It is an audio sample, so it plays wherever an `audiocore.WaveFile`
does. The module has CircuitPython's own `audiomp3` API, so one script runs on
both.

The decoder reads its file during playback, so keep the file open while the
sample plays.
"""

from __future__ import annotations
from types import TracebackType
from typing import BinaryIO, 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 MP3Decoder: """Decodes an MP3 file as it plays. Args: file: A path, or a file object opened for reading in binary mode. buffer: A writable buffer to use for the decoder's input and output instead of allocating one. Leave it out to let the decoder allocate its own. Raises: TypeError: ``file`` is a file opened in text mode. OSError: The file cannot be opened or read. RuntimeError: The file has no MP3 frames the decoder can read. MemoryError: The decoder's buffers do not fit. """ def __init__(self, file: str | BinaryIO, buffer: bytearray | memoryview | None = None, /) -> None: ... file: BinaryIO """The file being decoded. Assign a new file object, opened in binary mode, to play another MP3 with the same decoder.""" sample_rate: int """Frames per second, from the file. Writable, to 1 or more.""" @property def bits_per_sample(self) -> int: """Size of one sample in bits: always 16.""" @property def channel_count(self) -> int: """Number of channels: 1 or 2, from the file.""" @property def rms_level(self) -> float: """How loud the most recently decoded block was, in 16-bit sample units: the square root of the sum of its squared samples, divided by the number of samples. Louder audio reads higher; it is not a true RMS, so compare readings with each other rather than with a decibel scale.""" @property def samples_decoded(self) -> int: """How many frames have been decoded so far."""
[docs] def open(self, path: str, /) -> None: """Open an MP3 file by path and decode that instead. Args: path: The file to open. It is opened for reading in binary mode. Raises: OSError: The file cannot be opened or read. """
[docs] def deinit(self) -> None: """Release the decoder and close nothing else. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ... def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...