Audio::Scan(3pm)

📦
version 1.13 · 7 versions
, in ubuntu stonking

💖 Audio::Scan(3pm) — or, the fast C metadata & tag reader for literally every audio format you own 💖

okay bestie, sit down, hydrate, because this one is a banger. Audio::Scan is a fast C metadata and tag reader for all common audio file formats, and it is, no cap, the moment. 🎀

✨ SYNOPSIS ✨

like, here's the vibe, in code:

use Audio::Scan;

my $data = Audio::Scan->scan('/path/to/file.mp3');

# Just file info
my $info = Audio::Scan->scan_info('/path/to/file.mp3');

# Just tags
my $tags = Audio::Scan->scan_tags('/path/to/file.mp3');

# Scan without reading (possibly large) artwork into memory.
# Instead of binary artwork data, the size of the artwork will be returned instead.
{
    local $ENV{AUDIO_SCAN_NO_ARTWORK} = 1;
    my $data = Audio::Scan->scan('/path/to/file.mp3');
}

# Scan a filehandle
open my $fh, '<', 'my.mp3';
my $data = Audio::Scan->scan_fh( mp3 => $fh );
close $fh;

# Scan and compute an audio MD5 checksum
my $data = Audio::Scan->scan( '/path/to/file.mp3', { md5_size => 100 * 1024 } );
my $md5 = $data->{info}->{audio_md5};

see that last one? md5_size => 100 * 1024 then boom, you've got $data->{info}->{audio_md5}. iconic behaviour. ✨

🌸 DESCRIPTION 🌸

Audio::Scan is a C-based scanner for audio file metadata and tag info. It currently supports:

  • MP3
  • MP4
  • Ogg Vorbis
  • FLAC
  • ASF
  • WAV
  • AIFF
  • Musepack
  • Monkey's Audio
  • WavPack

every single one of those gets its own lil section down below with the deets, so keep scrolling, bestie. 👑

🦋 METHODS 🦋

scan( $path, [ \%OPTIONS ] )

Scans $path for both metadata and tag information. Which kind of scan actually happens is decided by the file's extension, which is a choice, but a valid one. Supported extensions, in full, no skips:

MP3:  mp3, mp2
MP4:  mp4, m4a, m4b, m4p, m4v, m4r, k3g, skm, 3gp, 3g2, mov
AAC (ADTS): aac
Ogg:  ogg, oga
FLAC: flc, flac, fla
ASF:  wma, wmv, asf
Musepack:  mpc, mpp, mp+
Monkey's Audio:  ape, apl
WAV: wav
AIFF: aiff, aif
WavPack: wv

This method returns a hashref containing two other hashrefs: info and tags. And the contents of those two hashes? babe, they vary depending on file format. All the details are below. 🫶

You can also hand it an optional hashref with these values:

  • md5_size => $audio_bytes_to_checksum — an MD5 gets computed over the first N audio bytes. Any tags in the file are automatically skipped, so this is a genuinely useful way of figuring out whether a file's audio content is the same even if the tags got changed around. The hex MD5 value comes back in the $info->{audio_md5} key. Heads up though: this option will reduce performance, so pick a size small enough that it works for you — you should probably avoid using more than 64K, for example.
For FLAC files that already contain an MD5 checksum, that value will be used instead of calculating a new one. no extra work, we love an efficient queen. 💅
  • md5_offset => $offset — start computing the audio_md5 value from $offset. If you don't specify it, $offset defaults to a point in the middle of the file.

scan_info( $path, [ \%OPTIONS ] )

If you only need the file metadata and don't care about tags at all, this is your girl. ✨

scan_tags( $path, [ \%OPTIONS ] )

The opposite vibe: only the tags, and you don't care about the metadata.

scan_fh( $type => $fh, [ \%OPTIONS ] )

Scans a filehandle. $type is what kind of file you're scanning it as, like "mp3" or "ogg". Also: FLAC does not support reading from a filehandle, so don't try it, it's giving nothing. 🙈

find_frame( $path, $timestamp_in_ms )

Returns the byte offset to the first audio frame starting from the given timestamp, in milliseconds. ⏱️

  • MP3, Ogg, FLAC, ASF, MP4 — you get the byte offset to the data packet containing that timestamp. For file formats that don't provide timestamp info, like MP3, you get the best estimate for where that timestamp lives. It'll be more accurate if the file has a Xing header or is CBR, for example.
  • WAV, AIFF, Musepack, Monkey's Audio, WavPack — Not yet supported by find_frame. 💀

find_frame_return_info( $path, $timestamp_in_ms )

So the header of an MP4/OggFlac file contains a bunch of metadata that refers to the structure of the audio data, which makes seeking harder to pull off. This method returns the usual $info hash but with 2 additional keys:

seek_offset - The seek offset in bytes
seek_header - A rewritten MP4/OggFlac header that can be prepended to the audio data
              found at seek_offset to construct a valid bitstream. Specifically, for MP4
              the following boxes are rewritten: stts, stsc, stsz, stco. For FLAC, the
              number of samples and md5 in STREAMINFO are zero'd

and here's the whole serve, like, to seek 30 seconds into a file and write out a new MP4 file seeked to that point:

my $info = Audio::Scan->find_frame_return_info( $file, 30000 );

open my $f, '<', $file;
sysseek $f, $info->{seek_offset}, 1;

open my $fh, '>', 'seeked.m4a';
print $fh $info->{seek_header};

while ( sysread( $f, my $buf, 65536 ) ) {
    print $fh $buf;
}

close $f;
close $fh;

periodt. 💅

find_frame_fh( $type => $fh, $offset )

Same as find_frame, but with a filehandle.

find_frame_fh_return_info( $type => $fh, $offset )

Same as find_frame_return_info, but with a filehandle.

has_flac()

Deprecated. It always returns 1 now, because FLAC is always enabled. that's it, that's the whole method. 🫠

is_supported( $path )

Returns 1 if the given path can be scanned by Audio::Scan, or 0 if it can't. vibe check, basically. ✅

get_types()

Returns an array of strings of the file types supported by Audio::Scan.

extensions_for( $type )

Returns an array of strings of the file extensions that are considered to be the file type $type.

type_for( $extension )

Returns the file type for a given extension. Returns undef for unsupported extensions. (so check your undef, bestie, it's not gonna warn you.) 😭

🎀 SKIPPING ARTWORK 🎀

To save memory while reading tags, you can opt to skip the potentially large embedded artwork. To do this, just set the environment variable AUDIO_SCAN_NO_ARTWORK:

local $ENV{AUDIO_SCAN_NO_ARTWORK} = 1;
my $tags = Audio::Scan->scan_tags($file);

Doing that gives you the length of the embedded artwork instead of the actual image data. In some cases it'll also give you a byte offset to the image data, which you can use to extract the image through more efficient means. But — and this is the important bit — the offset is not always returned, so if you want to use this data, make sure to check for offset. If offset isn't present, the only way to get the image data is to do a normal tag scan without the environment variable set. no shortcuts, sorry babe. 🙈

One limitation that currently exists: memory for embedded images is still allocated for ASF and Ogg Vorbis files. we're aware, it's giving character development.

This info comes back in different ways depending on the format:

  • ID3 (MP3, AAC, WAV, AIFF):
$tags->{APIC}->[3]: image length
$tags->{APIC}->[4]: image offset (unless APIC would need unsynchronization)
  • MP4:
$tags->{COVR}: image length
$tags->{COVR_offset}: image offset (always available)
  • Ogg Vorbis:
$tags->{ALLPICTURES}->[0]->{image_data}: image length
Image offset is not supported with Vorbis because the data is always base64-encoded.
  • FLAC:
$tags->{ALLPICTURES}->[0]->{image_data}: image length
$tags->{ALLPICTURES}->[0]->{offset}: image offset (always available)
  • ASF:
$tags->{'WM/Picture'}->{image}: image length
$tags->{'WM/Picture'}->{offset}: image offset (always available)
  • APE, Musepack, WavPack, MP3 with APEv2:
$tags->{'COVER ART (FRONT)'}: image length
$tags->{'COVER ART (FRONT)_offset'}: image offset (always available)

🎵 MP3 🎵

INFO

The following metadata about a file may be returned:

id3_version (i.e. "ID3v2.4.0")
id3_was_unsynced (if a v2.2/v2.3 file needed whole-tag unsynchronization)
song_length_ms (duration in milliseconds)
layer (i.e. 3)
stereo
samples_per_frame
padding
audio_size (size of all audio frames)
audio_offset (byte offset to first audio frame)
bitrate (in bps, determined using Xing/LAME/VBRI if possible, or average in the worst case)
samplerate (in kHz)
vbr (1 if file is VBR)
dlna_profile (if file is compliant)

If a Xing header is found:

xing_frames
xing_bytes
xing_quality

If a VBRI header is found:

vbri_delay
vbri_frames
vbri_bytes
vbri_quality

If a LAME header is found:

lame_encoder_version
lame_tag_revision
lame_vbr_method
lame_lowpass
lame_replay_gain_radio
lame_replay_gain_audiophile
lame_encoder_delay
lame_encoder_padding
lame_noise_shaping
lame_stereo_mode
lame_unwise_settings
lame_source_freq
lame_surround
lame_preset

TAGS

Raw tags come back as found. Which means older tags like ID3v1 and ID3v2.2/v2.3 get converted to ID3v2.4 tag names. Multiple instances of a tag in a file come back as arrays. Complex tags like APIC and COMM come back as arrays. All tag fields get converted to upper-case. All text gets converted to UTF-8. the glow-up is real. ✨

Sample tag data:

tags => {
      ALBUMARTISTSORT => "Solar Fields",
      APIC => [ "image/jpeg", 3, "", <binary data snipped> ],
      CATALOGNUMBER => "INRE 017",
      COMM => ["eng", "", "Amazon.com Song ID: 202981429"],
      "MUSICBRAINZ ALBUM ARTIST ID" => "a2af1f31-c9eb-4fff-990c-c4f547a11b75",
      "MUSICBRAINZ ALBUM ID" => "282143c9-6191-474d-a31a-1117b8c88cc0",
      "MUSICBRAINZ ALBUM RELEASE COUNTRY" => "FR",
      "MUSICBRAINZ ALBUM STATUS" => "official",
      "MUSICBRAINZ ALBUM TYPE" => "album",
      "MUSICBRAINZ ARTIST ID" => "a2af1f31-c9eb-4fff-990c-c4f547a11b75",
      "REPLAYGAIN_ALBUM_GAIN" => "-2.96 dB",
      "REPLAYGAIN_ALBUM_PEAK" => "1.045736",
      "REPLAYGAIN_TRACK_GAIN" => "+3.60 dB",
      "REPLAYGAIN_TRACK_PEAK" => "0.892606",
      TALB => "Leaving Home",
      TCOM => "Magnus Birgersson",
      TCON => "Ambient",
      TCOP => "2005 ULTIMAE RECORDS",
      TDRC => "2004-10",
      TIT2 => "Home",
      TPE1 => "Solar Fields",
      TPE2 => "Solar Fields",
      TPOS => "1/1",
      TPUB => "Ultimae Records",
      TRCK => "1/11",
      TSOP => "Solar Fields",
      UFID => [
            "http://musicbrainz.org",
            "1084278a-2254-4613-a03c-9fed7a8937ca",
      ],
},

MP4

INFO

okay bestie, MP4 is out here being the whole ecosystem 💅 and the metadata it hands back can include literally all of this:

audio_offset (byte offset to start of mdat)
audio_size
compatible_brands
file_size
leading_mdat (if file has mdat before moov)
major_brand
minor_version
song_length_ms
timescale
dlna_profile (if file is compliant)
tracks (array of tracks in the file)

and inside each one of those tracks? it's giving its own little world 💖 each track may contain:

audio_type
avg_bitrate
bits_per_sample
channels
duration
encoding
handler_name
handler_type
id
max_bitrate
samplerate

TAGS

the tags come back as a hash, and every single key gets converted to UPPER-CASE, no exceptions 🫶 oh and also — keys that start with 0xA9 (that's the copyright symbol, iykyk) get that character stripped right out. iconic behavior honestly.

here's what sample tag data is serving:

tags => {
   AART              => "Album Artist",
   ALB               => "Album",
   ART               => "Artist",
   CMT               => "Comments",
   COVR              => <binary data snipped>,
   CPIL              => 1,
   DAY               => 2009,
   DESC              => "Video Description",
   DISK              => "1/2",
   "ENCODING PARAMS" => "vers\0\0\0\1acbf\0\0\0\2brat\0\1w\0cdcv\0\1\6\5",
   GNRE              => "Jazz",
   GRP               => "Grouping",
   ITUNNORM          => " 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000",
   ITUNSMPB          => " 00000000 00000840 000001E4 00000000000001DC 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000",
   LYR               => "Lyrics",
   NAM               => "Name",
   PGAP              => 1,
   SOAA              => "Sort Album Artist",
   SOAL              => "Sort Album",
   SOAR              => "Sort Artist",
   SOCO              => "Sort Composer",
   SONM              => "Sort Name",
   SOSN              => "Sort Show",
   TMPO              => 120,
   TOO               => "iTunes 8.1.1, QuickTime 7.6",
   TRKN              => "1/10",
   TVEN              => "Episode ID",
   TVES              => 12,
   TVSH              => "Show",
   TVSN              => 12,
   WRT               => "Composer",
},

like. look at ITUNNORM and ITUNSMPB just sitting there with their wall of zeros 😭 that's not a vibe, that's a war crime of a string, but we report it faithfully anyway 💀

AAC (ADTS)

INFO

for AAC, the metadata that comes back is this lil set here 🌸

audio_offset
audio_size
bitrate (in bps)
channels
file_size
profile (Main, LC, or SSR)
samplerate (in kHz)
song_length_ms (duration in milliseconds)
dlna_profile (if file is compliant)

note the units bestie: bitrate is in bps, but samplerate is in kHz, and song_length_ms is in milliseconds ⭐ don't mix them up, that's how you end up with a 44100 kHz audio file and a very confused playlist 🙈

OGG VORBIS

INFO

here's what Ogg Vorbis reports back 👑

version
channels
stereo
samplerate (in kHz)
bitrate_average (in bps)
bitrate_upper
bitrate_nominal
bitrate_lower
blocksize_0
blocksize_1
audio_offset (byte offset to audio)
audio_size
song_length_ms (duration in milliseconds)

TAGS

raw Vorbis comments come straight through, no filter, no edit — and all the comment keys get capitalized 💅

FLAC

INFO

FLAC said "lossless and thorough" and honestly? it ate 🔥

channels
samplerate (in kHz)
bitrate (in bps)
file_size
audio_offset (byte offset to first audio frame)
audio_size
song_length_ms (duration in milliseconds)
bits_per_sample
frames
minimum_blocksize
maximum_blocksize
minimum_framesize
maximum_framesize
audio_md5
total_samples

TAGS

raw FLAC comments, keys all capitalized, same deal as Vorbis 🎀 but some of the data is ✨special✨ and gets its own treatment:

APPLICATION

each application block comes back inside the APPLICATION tag, keyed by application ID 🦋

CUESHEET_BLOCK

the CUESHEET_BLOCK tag is an array holding every line of the cue sheet, one per element 📋

ALLPICTURES

embedded pictures live in an ALLPICTURES array, and every single picture carries this metadata:

mime_type
description
width
height
depth
color_index
image_data
picture_type
ngl, image_data can be a LOT of bytes. it's the actual picture, bestie, not a thumbnail. handle with care 🫶

ASF (Windows Media Audio/Video)

INFO

okay so ASF can return a pile of metadata. the manpage lowkey recommends you go read the ASF spec if you want the deep lore on any of these values 📚 anyway here's the full list, no skips:

audio_offset (byte offset to first data packet)
audio_size
broadcast (boolean, whether the file is a live broadcast or not)
codec_list (array of information about codecs used in the file)
creation_date (UNIX timestamp when file was created)
data_packets
drm_key
drm_license_url
drm_protection_type
drm_data
file_id (unique file ID)
file_size
index_blocks
index_entry_interval (in milliseconds)
index_offsets (byte offsets for each second of audio, per stream. Useful for seeking)
index_specifiers (indicates which stream a given index_offset points to)
language_list (array of languages referenced by the file's metadata)
lossless (boolean)
max_bitrate
max_packet_size
min_packet_size
mutex_list (mutually exclusive stream information)
play_duration_ms
preroll
script_commands
script_types
seekable (boolean, whether the file is seekable or not)
send_duration_ms
song_length_ms (the actual length of the audio, in milliseconds)
dlna_profile (if file is compliant)

STREAMS

the streams array is where per-stream metadata lives — one entry per individual stream inside the file 🌈 here's everything that may show up in there:

DeviceConformanceTemplate
IsVBR
alt_bitrate
alt_buffer_fullness
alt_buffer_size
avg_bitrate (most accurate bitrate for this stream)
avg_bytes_per_sec (audio only)
bitrate
bits_per_sample (audio only)
block_alignment (audio only)
bpp (video only)
buffer_fullness
buffer_size
channels (audio only)
codec_id (audio only)
compression_id (video only)
encode_options
encrypted (boolean)
error_correction_type
flag_seekable (boolean)
height (video only)
index_type
language_index (offset into language_list array)
max_object_size
samplerate (in kHz) (audio only)
samples_per_block
stream_number
stream_type
super_block_align
time_offset
width (video only)

see those (audio only) and (video only) notes? those are doing so much work, don't ignore them 💀

TAGS

raw tags come back raw, periodt. and here's the twist — if a tag shows up more than once, you get an array. also, unlike basically every other format on this page, ASF tag keys are NOT capitalized. no cap. it's just built different 😤

there's one special key though, and it's the one you actually care about:

WM/Picture

pictures come back as a hash with these keys:

image_type (numeric type, same as ID3v2 APIC)
mime_type
description
image

WAV

INFO

WAV might return any of these:

audio_offset
audio_size
bitrate (in bps)
bits_per_sample
block_align
channels
dlna_profile (if file is compliant)
file_size
format (WAV format code, 1 == PCM)
id3_version (if an ID3v2 tag is found)
samplerate (in kHz)
song_length_ms

quick note: format is the WAV format code, and 1 means PCM, bestie — remember that one, it's the most common answer by far 🎀

TAGS

WAV files can be carrying several different kinds of tags at once, which is chaotic of them honestly 🙈 the "native" WAV tags live in a LIST block and may include these (and others):

  • IARL — Archival Location
  • IART — Artist
  • ICMS — Commissioned
  • ICMT — Comment
  • ICOP — Copyright
  • ICRD — Creation Date
  • ICRP — Cropped
  • IENG — Engineer
  • IGNR — Genre
  • IKEY — Keywords
  • IMED — Medium
  • INAM — Name (Title)
  • IPRD — Product (Album)
  • ISBJ — Subject
  • ISFT — Software
  • ISRC — Source
  • ISRF — Source Form
  • TORG — Label
  • LOCA — Location
  • TVER — Version
  • TURL — URL
  • TLEN — Length
  • ITCH — Technician
  • TRCK — Track
  • ITRK — Track

and ID3v2 tags can also be embedded inside WAV files too — those come back exactly the same way they do for MP3 files 🫶

AIFF

INFO

AIFF may return:

audio_offset
audio_size
bitrate (in bps)
bits_per_sample
block_align
channels
compression_name (if AIFC)
compression_type (if AIFC)
dlna_profile (if file is compliant)
file_size
id3_version (if an ID3v2 tag is found)
samplerate (in kHz)
song_length_ms

see compression_name and compression_type? those only show up if it's AIFC 💅 regular AIFF has no compression to gossip about.

TAGS

ID3v2 tags can be embedded within AIFF files, and they come back exactly as for MP3 files ⭐ same deal, same vibe.

MONKEY'S AUDIO (APE)

INFO

APE may return:

audio_offset
audio_size
bitrate (in bps)
channels
compression
file_size
samplerate (in kHz)
song_length_ms
version

TAGS

APEv2 tags come back as a hash of key/value pairs, simple as that 🌸

MUSEPACK

INFO

Musepack may return:

audio_offset
audio_size
bitrate (in bps)
channels
encoder
file_size
profile
samplerate (in kHz)
song_length_ms

TAGS

Musepack uses APEv2 tags — returned as a hash of key/value pairs, same as APE 🦋

WAVPACK

INFO

WavPack may return:

audio_offset
audio_size
bitrate (in bps)
bits_per_sample
channels
encoder_version
file_size
hybrid (1 if file is lossy) (v4 only)
lossless (1 if file is lossless) (v4 only)
samplerate
song_length_ms
total_samples

heads up bestie: hybrid means 1 if the file is lossy, lossless means 1 if the file is lossless — and both of those are v4 only 👑 also note samplerate here has no kHz note on it like the others do, that's just how the page lists it, we're reporting it faithfully 🙈

TAGS

WavPack uses APEv2 tags too — returned as a hash of key/value pairs 💜

DSF

INFO

DSF may return:

audio_offset
audio_size
bits_per_sample
channels
song_length_ms
samplerate
block_size_per_channel

TAGS

ID3v2 tags can be embedded within DSF files, and they come back exactly as for MP3 files 🎀

DSDIFF (DFF)

INFO

DSDIFF — also known as DFF — may return:

audio_offset
audio_size
bits_per_sample
channels
song_length_ms
samplerate
tag_diti_title
tag_diar_artist

TAGS

and the tags situation here? there isn't one 💀 the DSDIFF format supports no separate tags. the title and artist you see above are it, that's the whole story.

💖 THANKS 💖

Bestie, this whole thing literally would not exist without the people below, so let's give them their flowers 🌷

  • Logitech & Slim Devices — for letting us release SO much of our code out into the world. No gatekeeping here. Long live Squeezebox! 👑
  • Kimmo Taskinen, Adrian Smith, Clive Messer, and Jurgen Kramer — for DSF/DSDIFF support plus various other fixes. Absolute legends, fr fr 🫶
  • Some code from the Rockbox project was very helpful in implementing ASF and MP4 seeking. Shoutout 🎀
  • Some of the file format parsing code was derived from the mt-daapd project, and adapted by Netgear. It has been heavily rewritten to fix bugs and add more features. Glow-up of the century ✨
  • The source to the original Netgear C scanner for SqueezeCenter lives at http://svn.slimdevices.com/repos/slim/7.3/trunk/platforms/readynas/contrib/scanner — go peek if you're nosy (affectionate) 💅
  • The audio MD5 feature uses an MD5 implementation by L. Peter Deutsch, ghost@aladdin.com. Iconic work, honestly 🌈

🌟 SEE ALSO 🌟

Go read the source material, bestie, it's giving scholarly:

👑 AUTHORS 👑

These are the main characters of this story, ok:

  • Andy Grundman, andy@hybridized.org
  • Dan Sully, daniel@cpan.org

Copyright (C) 2010-2011 Logitech, Inc.

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. Periodt 💅

And that's the whole page, bestie!! 🎀 This lil' rendition is from perl v5.42.3, dated 2026-08-19, and yeah it's Audio::Scan(3pm) — go read your files like the icon you are 💖 🦋 ⭐

📦 where this page comes from