Header(3pm)

📦
version 2.4 · 6 versions
, in ubuntu stonking

💖 Header(3pm) — Audio::FLAC::Header 💖

User Contributed Perl Documentation · a whole manual page · she's giving FLAC metadata realness

okay bestie, sit down, grab a strawberry 🍓, because we're about to read the most iconic little Perl module manual you've ever seen. this is Header(3pm) from the User Contributed Perl Documentation section and it's literally about reading FLAC file metadata and it ATE. no cap.

✨ NAME ✨

Audio::FLAC::Header — the interface to FLAC header metadata. that's it, that's the whole vibe. 🎀

🦋 SYNOPSIS 🦋

here's the little opening number, and you KNOW we keep it exact:

use Audio::FLAC::Header;
my $flac = Audio::FLAC::Header->new("song.flac");

my $info = $flac->info();

foreach (keys %$info) {
        print "$_: $info->{$_}\n";
}

my $tags = $flac->tags();

foreach (keys %$tags) {
        print "$_: $tags->{$_}\n";
}

look at her go. make the object, pull the info, pull the tags, print them. main character energy fr fr. 👑

🌸 DESCRIPTION 🌸

so what does this module actually DO, you ask? it hands you back a hash stuffed with the basic tea about a FLAC file, a representation of the embedded cue sheet if one exists, AND all the tag info chilling inside the FLAC file's Vorbis tags. that's three (3) whole things. obsessed. 💜

now here's the thing — there is no complete list of tag keys for Vorbis tags, because they can be defined by the user. the user! the people! the girlies! so the keys are whatever they wanna be. but the basic set of tags used for FLAC files includes these lil guys:

ALBUM
ARTIST
TITLE
DATE
GENRE
TRACKNUMBER
COMMENT

the info that Audio::FLAC::info gives you back is keyed by:

MINIMUMBLOCKSIZE
MAXIMUMBLOCKSIZE
MINIMUMFRAMESIZE
MAXIMUMFRAMESIZE
TOTALSAMPLES
SAMPLERATE
NUMCHANNELS
BITSPERSAMPLE
MD5CHECKSUM

and the info stored in the main hash that relates to the file itself or is calculated from some of those information fields is keyed by:

trackLengthMinutes      : minutes field of track length
trackLengthSeconds      : seconds field of track length
trackLengthFrames       : frames field of track length (base 75)
trackTotalLengthSeconds : total length of track in fractional seconds
bitRate                 : average bits per second of file
fileSize                : file size, in bytes

not her casually doing math with base 75 frames and fractional seconds. a genius honestly. 🧚

💅 CONSTRUCTORS 💅

new ($filename)

opens a FLAC file, makes sure it actually exists and is actually an FLAC stream (she does NOT get catfished), then loads the information and comment fields. so thorough. so iconic. 🫶

🔥 INSTANCE METHODS 🔥

  • info( [$key] ) — returns a hashref containing information about the FLAC file from the file's information header.

the optional parameter, key, lets you grab a single value from the info hash. returns undef if the key isn't found — so like, don't be shocked when it ghosts you on a bad key. undef is the ghosting. 💀

  • tags( [$key] ) — returns a hashref containing tag keys and values of the FLAC file from the file's Vorbis Comment header.

again, the optional parameter, key, lets you pull out a single value from the tag hash. returns undef if the key is not found. same rules, same strongest soldier.

  • cuesheet( ) — returns an arrayref containing a textual representation of the cuesheet metadata block. each element in the array corresponds to one line in a .cue file. if there's no cuesheet block in this FLAC file, the array will be empty. and the resulting cuesheet should match the output of metaflac's --export-cuesheet-to option, with ONE exception: the FILE line includes the actual file name instead of "dummy.wav". yes, "dummy.wav". she said no to the dummy wav. 💅
  • seektable( ) — returns the seektable. currently disabled for performance. 😭 she's on a break bestie, do not disturb her.
  • application( $appId ) — returns the application block for the passed id.
  • picture( [$type ] ) — returns a hash containing data from a PICTURE block if found.

defaults to type 3 — "Front Cover".

when the passed variable is 'all', an array of hashes containing picture data from all PICTURE blocks is returned. this allows for multiple instances of the same picture type, because sometimes you have three front covers and you simply need all of them. collection behavior. 🌈

  • set_separator( ) — for multi-value ID3 tags, set the separator string. defaults to '/'.
  • vendor_string( ) — returns the vendor string.
  • set_vendor_string( $string ) — set the vendor string. will be written on write().
  • write( ) — writes the current contents of the tag hash to the FLAC file, given there's enough space in the header to do so. if there's insufficient space available (using pre-existing padding), the file will remain unchanged, and the function will return a zero value. no partial writes, no chaos, just a zero and a dream. ⭐
ngl the write() one is the realest one here — it either writes or it doesn't, and it TELLS you which one happened. respect.

🎀 SEE ALSO 🎀

(the lore. the source material. go read it if you want the deep cuts. iykyk.)

👑 AUTHORS 👑

Dan Sully, <daniel@cpan.org>

pure perl code Copyright (c) 2003-2004, Erik Reckase.

pure perl code Copyright (c) 2003-2007, Dan Sully & Slim Devices. pure perl code Copyright (c) 2008-2009, Dan Sully.

XS code Copyright (c) 2004-2007, Dan Sully & Slim Devices. XS code Copyright (c) 2008-2009, Dan Sully.

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.

and that's a wrap, bestie! 🦋 this page came to you from perl v5.42.3, dated 2026-08-19 — so go forth, read your FLAC headers, and stay slaying. periodt. ✨💜

📦 where this page comes from