Ogg Vorbis: audiovorbis
audiovorbis.VorbisDecoder plays an Ogg Vorbis file the way
audiomp3.MP3Decoder plays an MP3. CircuitPython has no Vorbis module, so this
one is PyDevices’ own; it builds on MicroPython (unix, Windows, ESP32 and the
other ports audiodsp builds for), into the CPython wheel, and into
CircuitPython as a user C module.
import audiocore, audiomixer, audiovorbis
song = audiovorbis.VorbisDecoder("song.ogg") # a path, or a file opened "rb"
print(song.sample_rate, song.channel_count) # from the file
mixer.voice[0].play(song, loop=True)
What it has, and how it differs from MP3Decoder
The constructor takes a file or a path and an optional buffer, and the object
has file (settable), open(path), rms_level, samples_decoded,
sample_rate, channel_count, bits_per_sample, deinit() and with,
exactly as MP3Decoder does. It always hands out signed 16-bit samples.
Where it behaves differently, on purpose:
Mono and stereo only. A file with more channels is refused with
ValueError, because nothing downstream of an audio sample takes more than two.The buffer holds decoded audio only (Tremor reads the file itself, so there is no input buffer). Each pull hands out half of it, in whole stereo frames; a buffer whose halves are under 256 bytes isn’t used. Without one, each pull is 1024 frames.
A rewind always rewinds.
reset_buffer()goes back to the start whenever anything has played.MP3Decoderrewinds only once it has reached the end, so an MP3 played half way and played again carries on.A stream that fails mid-play ends the playback with
GET_BUFFER_ERRORrather than raising inside the pull. Opening a file still raises the stream’s own exception.Errors opening a file are
RuntimeError("Failed to parse Vorbis file: ..."), naming what was wrong: not Ogg Vorbis, damaged headers, a version it can’t read.
Like an MP3, it reads its file while it plays, so audiopump refuses it at
the door wherever it sits in a graph. Decode into a ring from the interpreter
instead.
A chained file (several Ogg streams back to back) plays through as long as every link has the first one’s rate and channel count, and ends at the first link that doesn’t.
The decoder, and decoding from C
The decoding is Xiph’s Tremor, the lowmem branch: integer-only, BSD-3-Clause, carried in third_party/tremor with a few small changes with its ORIGIN.txt. It is compiled as one translation unit, src/shared/audiodsp_vorbis.c, which:
renames every symbol Tremor defines to
audiodsp_tremor_*(audiodsp_tremor_names.h), so a firmware can link another copy of Tremor beside it;keeps Tremor’s warnings to Tremor’s code, so a port that builds with
-Werrorstill checks ours;routes Tremor’s allocations through the bound driver (below).
Any C module in the same firmware can decode through it with src/shared/audiodsp_vorbis.h: give it a read callback (and seek and tell, for a stream that can), then pull interleaved int16 frames. It never touches an interpreter, so it can run on a thread of its own; one decoder belongs to one thread at a time.
static long my_read(void *s, void *buf, size_t len); // bytes, 0 at the end, -1 on error
static const audiodsp_vorbis_io_t io = { my_read, NULL, NULL };
int err;
audiodsp_vorbis_t *v = audiodsp_vorbis_open(&io, my_stream, &err);
long n;
int16_t pcm[1024 * 2];
while ((n = audiodsp_vorbis_read(v, pcm, 1024)) > 0) { /* n frames */ }
audiodsp_vorbis_close(v);
Memory
Nothing comes from the MicroPython or CPython heap. Tremor allocates through
the bound driver’s memory hooks (mem_alloc, mem_realloc and mem_free in
audiodsp_port.h), and through the C
library’s malloc when there are none. A driver for a board with PSRAM puts
the decoder there: it is tens of kilobytes in many small blocks that no DMA
touches, and internal RAM is what Wi-Fi and DMA can’t do without. Because it
isn’t on the MicroPython heap, gc.mem_free() doesn’t see it; deinit(), or
the finaliser at a soft reset, frees it.
What a stream needs, measured on a 64-bit desktop with the decoder’s own
counter (AUDIODSP_VORBIS_HEAP_STATS); a 32-bit board needs somewhat less,
since many of the blocks are tables of pointers:
File |
Heap after opening |
Heap at most |
|---|---|---|
mono 44.1 kHz, 48 kbit/s |
24 KB |
30 KB |
stereo 48 kHz, 500 kbit/s |
83 KB |
96 KB |
On a Waveshare ESP32-P4 DEV-KIT, a 44.1 kHz stereo file at 112 kbit/s took
31 KB to open and 47 KB once playing, every byte of it in PSRAM and none in
internal RAM; five open, decode and deinit() cycles left both exactly where
they started.
Most of it is the stream’s codebooks, which a higher bitrate makes larger,
and the rest is two blocks of decode state per channel. On top of that the
binding keeps two output buffers on the interpreter’s heap: 8 KB without a
buffer.
Stack: Tremor’s call chains are about 1 KB deep on RISC-V, and a packet
puts up to about 2 KB more of scratch on the stack while it decodes; under
that sits the stream’s own read. Unpacking a stream’s codebooks used to take
scratch on the stack sized by the codebook, which on the ESP32’s 16 KB
Python stack crashed a board when an ordinary file was opened from deep in
a call chain, so that scratch comes from the heap now (and a codebook too
large to be real is refused). Tremor doesn’t check its own depth, so the
binding checks before every call into it that 6 KB are left: a program that
deep gets RuntimeError("not enough stack to open a Vorbis file here"), or
a pull that returns GET_BUFFER_ERROR, rather than a crashed board.
Flash: the decoder is about 90 KB of code and tables on an ESP32-P4
(riscv32-esp-elf-size on audiodsp_vorbis.c’s object), most of it the
MDCT and window lookup tables.
Tremor doesn’t check for a failed allocation. A board that runs out of memory while opening or decoding a file fails the way it would in any other C library that doesn’t, so leave it the room above.
Tests
tests/parity/vorbis_probe.py runs on MicroPython, CircuitPython and CPython from two small fixtures: the attributes, a rewound lap against the first, a
Mixervoice playing the file unchanged and looping it, a file cut off in its headers and in its audio, things that aren’t Vorbis,deinit()twice, and the pump’s refusal.--faultskips the rewind and must fail.tests/parity/verify_vorbis.py makes files with ffmpeg (mono and stereo, 44.1 and 48 kHz, 4 s and 3 minutes, from the lowest libvorbis quality to the highest), decodes them with ffmpeg, and compares every sample. Tremor and ffmpeg land on 16 bits differently: Tremor’s shift rounds down, ffmpeg rounds to nearest, so half the samples are one step apart (RMS 0.71); none has been more than 2 apart, and the gate is 3. Every interpreter must decode the same bytes.
--fault swap(left and right exchanged) and--fault drop(a block lost) must fail.tests/parity/vorbis_symbols_check.py compiles the decoder alone and fails on any global symbol outside
audiodsp_;--faultplants one.
Names and signatures
Generated from audiovorbis.pyi; the file reads on its own.
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.
- class audiovorbis.VorbisDecoder(file, buffer=None, /)[source]
Bases:
objectDecodes 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.
- Parameters:
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 –
fileis 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.
- file
The file being decoded. Assign a new file object, opened in binary mode, to play another with the same decoder.
- sample_rate
Frames per second, from the file. Writable, to 1 or more.
- property bits_per_sample
Size of one sample in bits: always 16.
- property channel_count
Number of channels: 1 or 2, from the file.
- property rms_level
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 samples_decoded
How many frames have been decoded so far.
- open(path, /)[source]
Open an Ogg Vorbis file by path and decode that instead.
- Parameters:
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.
- deinit()[source]
Release the decoder. Every later use raises
ValueError.