Decoder(3pm)

💖 Decoder(3pm) — the vibe-coded tour 💖

okay bestie, so this is a Perl man page — a page from the User Contributed Perl Documentation for the module Ogg::Vorbis::Decoder. Yes it's a 3pm page, yes it's for the perl peeps, and yes we're about to make it make sense. 🎀

---

✨ NAME ✨

Ogg::Vorbis::Decoder — an object-oriented Ogg Vorbis decoder. literally that's the whole job description and she does it.

---

✨ SYNOPSIS ✨

here's the moment. three ways in, pick ur fighter:

use Ogg::Vorbis::Decoder;
my $decoder = Ogg::Vorbis::Decoder->open("song.ogg");
my $buffer;
while ((my $len = $decoder->read($buffer) > 0) {
  # do something with the PCM stream
}

OR (same energy, different entry point):

open OGG, "song.ogg" or die $!;
my $decoder = Ogg::Vorbis::Decoder->open(\*OGG);

OR (for the fancy handle girls):

# can also be IO::Socket or any other IO::Handle subclass.
my $fh = IO::Handle->new("song.ogg");
my $decoder = Ogg::Vorbis::Decoder->open($fh);

💅 bestie this code is shown verbatim, so copy it exactly, quirks and all. we do not edit the synopsis. periodt.

---

✨ DESCRIPTION ✨

okay so what does this module actually do? it hands you Decoder objects for Ogg Vorbis files. from the stream you can:

• read data in PCM format
• seek by raw bytes
• seek by pcm samples
• seek by time
• and gather decoding-specific info that Ogg::Vorbis::Header does not give you

and then, the disclaimer, no cap: right now there is no support for the callback mechanism provided by the Vorbisfile API. it might show up in future releases though. we're manifesting 🦋

---

🎀 CONSTRUCTOR 🎀

open ($filename)

opens an Ogg Vorbis file for decoding 🎧. it either opens a handle to the file or uses an existing handle you already have, and then it initializes all of the internal vorbis decoding structures for you. queen behavior.

⚠️ heads up bestie: the object will maintain open file descriptors until the object is collected by the garbage handler. keep that in mind, she holds on.

returns undef on failure. 💀

---

🌸 INSTANCE METHODS 🌸

read ($buffer, [$size, $word, $signed])

reads PCM data from the Vorbis stream into $buffer. returns the number of bytes read, 0 when it reaches the end of the stream, or a value less than 0 on error. (so: positive = good, 0 = done, negative = we have a problem 😭)

the optional parameters include (with corresponding default values):

• size = 4096
• word = 2
• signed = 1

consult the Vorbisfile API (http://www.xiph.org/ogg/vorbis/doc/vorbisfile/reference.html) for an explanation of the various values. iykyk 📚

sysread ($buffer, [$size, $word, $signed])

an alias for read. same girl, different name. 🫶

raw_seek ($pos)

seeks through the compressed bitstream to the offset specified by $pos in raw bytes. returns 0 on success. ✅

pcm_seek ($pos, [$page])

seeks through the bitstream to the offset specified by $pos in pcm samples. the optional $page parameter is a boolean flag that, if set to true, will cause the method to seek to the closest full page preceding the specified location. returns 0 on success. ✅

time_seek ($pos, [$page])

seeks through the bitstream to the offset specified by $pos in seconds. the optional $page parameter is a boolean flag that, if set to true, will cause the method to seek to the closest full page preceding the specified location. returns 0 on success. ✅ (yes, same deal as pcm_seek, just in seconds bestie, no need to squint)

current_bitstream ()

returns the current logical bitstream of the decoder. this matches the bitstream parameter that's optionally passed to read. useful for saving a bitstream to jump to later, or to pass to the various information methods. very main character of it ngl 👑

bitrate ([$stream])

returns the average bitrate for the specified logical bitstream. if $stream is left out or set to -1, the average bitrate for the entire stream will be reported. 📊

bitrate_instant ()

returns the most recent bitrate read from the file. returns 0 if no read has been performed, or if the bitrate has not changed. (so 0 here doesn't always mean "zero bitrate", ok? don't @ me) 🍓

streams ()

returns the number of logical bitstreams in the file. 🔢

seekable ()

returns a non-zero value if the file is seekable, 0 if not. vibe check on the file, essentially. 🌈

serialnumber ([$stream])

returns the serial number of the specified logical bitstream — or, if $stream is left out or set to -1, that of the current bitstream. 🔖

raw_total ([$stream])

returns the total number of bytes in the physical bitstream or in the specified logical bitstream. 📏

pcm_total ([$stream])

returns the total number of pcm samples in the physical bitstream or in the specified logical bitstream. 📏

time_total ([$stream])

returns the total number of seconds in the physical bitstream or in the specified logical bitstream. ⏱️

raw_tell ()

returns the current offset in bytes. 📍

pcm_tell ()

returns the current offset in pcm samples. 📍

time_tell ()

returns the current offset in seconds. 📍

---

🧚 REQUIRES 🧚

the prerequisites. u gotta have these, no skipping:

• libogg
• libvorbis
• libogg-dev
• libvorbis-dev

---

👑 CURRENT AUTHOR 👑

• Dan Sully <daniel@cpan.org>

---

💜 AUTHOR EMERITUS 💜

• Dan Pemstein <dan@lcws.org>

---

⭐ COPYRIGHT ⭐

• Copyright (c) 2004-2010, Dan Sully. All Rights Reserved.
• Copyright (c) 2003, Dan Pemstein. All Rights Reserved.

this program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

a copy of this license is included with this module (LICENSE.GPL). 📜

---

🦋 SEE ALSO 🦋

• Ogg::Vorbis::Header

---

and that's the page, bestie, literally all of it 💖 this was perl v5.42.3 from 2026-08-19, so big up the perl maintainers and the module docs squad — go forth and decode some Ogg Vorbis, ur doing amazing, slay 🌸✨🎀