NAME

Audio::TagLib - Read and write audio metadata with TagLib (ID3v2, Vorbis Comments, and more)

SYNOPSIS

use Audio::TagLib;

my $taglib = Audio::TagLib.new($path); # returns a Failure on error

# Abstract API - aliases for simple fields
say "{$taglib.title} by {$taglib.artist}";
say "$path has no album field set" unless $taglib.album.defined;

# Access to any abstract tag
.say for $taglib.get('ALBUMARTIST');

# Update a value
$taglib.set('ALBUM', 'Greatest Hits'); # multiple values supported
$taglib.set('ALBUMARTIST', 'Band 1', 'Band 2'); # multiple values supported

# Write pending changes
$taglib.save;

DESCRIPTION

Audio::TagLib provides Raku bindings to the TagLib audio metadata library, providing a fast way to read metadata from many audio file formats: mp3, m4a, ogg, flac, opus, and more. See https://taglib.org for more details.

Audio::TagLib vs Audio::Taglib::Simple

This module uses the C++ interface to TagLib rather than the C bindings. This means installation requires a C++ compiler, but provides the full API rather than the "abstract only" API.

This module does not keep a taglib object open and reads everything into memory initially, meaning there is no free method needed (unlike Simple).

Audio::Taglib::Simple has a lowercase 'l' in its name, where this module uses TagLib (as does the official website). I thought adjusting the case was a good idea at the time.

Audio::TagLib

new($path, :$load-raw-id3v2)

Loads the metadata from the given file. All metadata is read at this point.

The optional :load-raw-id3v2 flag determines whether the raw-id3v2 list is populated. This is false by default, since the abstract interface is preferred, and it's faster to not generate this mapping.

If any errors are encountered while reading the file or parsing the tags, a Failure is returned which contains an Exception explaining the error.

Basic API

TagLib provides what is known as the "basic API", which provides an easy interface to common tags. This module provides these as attributes of Audio::TagLib. The following fields are available as strings (Str):

title
artist
album
comment
genre

The following are provided as integers (Int):

year
track
length - length of the file, in seconds

These attributes will be undefined if they are not present in the file.

Abstract API

TagLib also provides a format-independent mapping of tags known as the "abstract API". This allows you to interact with almost any tag, without having to care about the exact identifier used by ID3v2 vs Vorbis comments. For example, this allows the ID3v2 tag TPE2 and the MP4 tag aART to be recognized as ALBUMARTIST.

A mapping is available in the TagLib documentation at https://taglib.org/api/p_propertymapping.html.

get(Str $key --> @values)

Returns a list of values for the provided tag. This uses the abstract tag names, identical to the propertymap list below but more efficient for getting individual tags.

set(Str $key, *@values)

Sets the value of the given tag to the provided values. This method does not update the file (or the in-memory TagLib values), it only stages the updates.

save

Writes pending tag updates to the file. Returns a Failure if an error occurs.

@.propertymap

This is a List of Pairs of all the recognized tags within the file. This is useful if you want to extract every tag in a file. If you only need a single tag, prefer the get method instead for efficiency.

ID3v2 API

This module also provides a read-only interface to ID3v2 tags. You must request ID3v2 parsing when creating the Audio::TagLib object.

Bool has-id3v2

True if the file has an ID3v2 tag. This value is defined whether or not :load-raw-id3v2 is specified.

@.raw-id3v2

Similar to propertymap, this is a list of native ID3v2 tags, by their short identifier (e.g. TPE2 instead of ALBUMARTIST). This list is empty if there are no ID3v2 Tag, and will return a Failure if the :load-raw-id3v2 flag was not provided to the constructor.

Album Art

Album art can be extracted from most types of audio files. This module provides access to the first picture data in the file. Most files only have a single picture attached, so this is usually the album art.

album-art-size - the size of the album art in bytes
album-art-mime - the mime type of the album art, such as 'image/png'

The data can be retrieved by calling one of the following methods:

get-album-art - returns the data as a Blob[uint8]
get-album-art-raw - returns the data as a CArray (call .elems to get the size)

The raw variant is much faster if you are passing the data to another function that uses a CArray. If speed is important, consider using NativeHelpers::Blob to convert the raw variant.

Note that the mime type is stored in the file, and not determined from the image, so it may be inaccurate.

AUTHOR

Adrian Kreher avuserow@gmail.com

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.