Decoder(3pm)

💖 Decoder(3pm) — Audio::FLAC::Decoder, bestie edition 🎀

okay so you found the Decoder(3pm) page in the User Contributed Perl Documentation section and you're like "what is this" — and honestly? it's giving object-oriented FLAC decoder and it's iconic. sit down, hydrate, let's go 🦋

---

🌸 NAME 🌸

Audio::FLAC::Decoder — an object-oriented FLAC decoder. periodt. that's the whole name. no cap, that's literally it 💅

---

✨ SYNOPSIS ✨

okay so here's how you actually use this thing, three ways, pick your fighter 🫶

use Audio::FLAC::Decoder;
my $decoder = Audio::FLAC::Decoder->open("song.flac");
my $buffer;
while ((my $len = $decoder->sysread($buffer) > 0) {
  # do something with the PCM stream
}

OR

open FLAC, "song.flac" or die $!;
my $decoder = Audio::FLAC::Decoder->open(\*FLAC);

OR

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

see? it's flexible like that 💁‍♀️

---

🦋 DESCRIPTION 🦋

so this module hands you Decoder objects for FLAC files. that's the whole vibe. once you have one you can:

• read data in PCM format from the stream
• seek by pcm samples
• or seek by time

three whole personality traits. main character energy fr fr 👑

---

🎀 CONSTRUCTOR 🎀

open ($filename)

opens an FLAC file for decoding. it either opens a handle to the file itself, or it uses an existing handle you already have lying around, and then it initializes all of the internal FLAC decoding structures. the whole setup. the whole little machine. ⚙️✨

⚠️ heads up bestie: the object maintains open file descriptors until the object gets collected by the garbage handler. so don't just leave these floating around like old iced coffee cups. it's giving leaky 💀

returns undef on failure. no drama, just undef.

---

💅 INSTANCE METHODS 💅

sysread ($buffer, [$size])

reads PCM data from the FLAC stream into $buffer. so basically it fills your buffer and tells you how it went. the return values are:

• the number of bytes read — slay, data incoming
• 0 when it reaches the end of the stream — it's over, wrap it up
• a value less than 0 on error — 😭

the optional $size can specify how many bytes to read. perfect for when you're picky (as you should be).

raw_seek ($pos)

seeks through the compressed bitstream to the offset specified by $pos, measured in raw bytes. returns 0 on success. lowkey the most chaotic seek because you're diving into compressed data but go off 🏊‍♀️

sample_seek ($pos)

seeks through the bitstream to the offset specified by $pos in pcm samples. returns 0 on success. much more reasonable of it honestly.

time_seek ($pos, [$page])

seeks through the bitstream to the offset specified by $pos in seconds. returns 0 on success. takes an optional $page too. time travel but make it FLAC ⏰🌈

bitrate ([$stream])

returns the average bitrate for the specified logical bitstream. and if you leave $stream out, or set it to -1, you get the average bitrate for the entire stream. so you can be specific or you can be everything, your call 💖

time_total ([$stream])

returns the total number of seconds in the bitstream. the whole duration. the full timeline. the runtime of the movie 🎬

raw_tell ()

returns the current offset in bytes. where are we? here. we're here. 📍

time_tell ()

returns the current offset in seconds. but — and I cannot stress this enough — NOT YET IMPLEMENTED. it's giving "coming soon" energy. don't build your whole app on this one bestie, fr fr 🙈

---

🧚 REQUIRES 🧚

libFLAC

that's it. that's the whole list. no cap.

---

👑 COPYRIGHT 👑

Copyright (c) 2004-2008, Dan Sully. 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. so like, version 2 or later, your choice, we support you either way 🫶

---

🌈 SEE ALSO 🌈

• Audio::FLAC::Header

go read that one too, it's the sibling, the duo, the dynamic pair ⭐

---

and that's the tea 🍓 this page was served to you by perl v5.42.3, dated 2026-08-19, straight from the Decoder(3pm) manpage. go decode something beautiful, bestie 💜✨🎀