# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Play Ogg Vorbis files.
`VorbisDecoder` plays an Ogg Vorbis file the way `audiomp3.MP3Decoder` plays an
MP3, with the same properties and methods. It is an audio sample, so it plays
wherever an `audiocore.WaveFile` does. CircuitPython has no Vorbis module; this
one is audiodsp's own.
The decoder reads its file during playback, so keep the file open while the
sample plays. Decoding is integer-only, using Xiph's Tremor.
"""
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 VorbisDecoder:
"""Decodes an Ogg Vorbis file as it plays.
It hands out signed 16-bit audio, mono or stereo. A chained file plays
through as long as every link has the first one's rate and channel count,
and ends at the first link that does not.
Args:
file: A path, or a file object opened for reading in binary mode.
buffer: A writable buffer for decoded audio, in place of the
decoder's own. Each block handed out is half of it, in whole
stereo frames; a buffer whose halves are under 256 bytes is not
used. Without one, each block is 1024 frames.
Raises:
TypeError: ``file`` is a file opened in text mode.
OSError: The file cannot be opened or read.
RuntimeError: The file is not Ogg Vorbis, its headers are damaged or
it is a version the decoder cannot read.
ValueError: The file has more than two channels.
"""
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 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 Ogg Vorbis 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.
RuntimeError: The file is not a Vorbis file the decoder can read.
"""
[docs]
def deinit(self) -> None:
"""Release the decoder. Every later use raises `ValueError`."""
def __enter__(self) -> Self: ...
def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None, /) -> None: ...