NAME

Music::Tag - Module for collecting information about music files.

SYNOPSIS

use Music::Tag;

my $info = Music::Tag->new($filename);

# Read basic info

$info->get_tag();

print "Performer is ", $info->artist(); print "Album is ", $info->album(); print "Release Date is ", $info->releasedate();

# Change info

$info->artist('Throwing Muses'); $info->album('University');

# Augment info from online database!

$info->add_plugin("MusicBrainz"); $info->add_plugin("Amazon");

$info->get_tag;

print "Record Label is ", $info->label();

# Save back to file

$info->set_tag(); $info->close();

AUTHOR

Edward Allen, edwardallenthethird@hotmail.com

DESCRIPTION

The motiviation behind this was to provide a convenient method for fixing broken tags.

This module is a wrapper module, which calls various plugin modules to find information about a music file and write it back into the tag.

METHODS

new()

my $info = Music::Tag->new($filename, [ $options ], [ "PLUGIN" ] ) ;

Takes a filename, a hashref of options, and an optonal first plugin and returns a new Music::Tag object.

If no plugin is listed, then it will automatically add the appropriate file plugin based on the extension. If it can't do that, it will return undef. Please note that when a plugin is added, the plugin's get_tag method is immediatly called. If you are the kind of person who uses ID3v2 and ID3v1 tags for everything, then use "MP3" as an option here to prevent it from trying to use iTunes tags for you .m4a files.

Options are global (apply to all plugins) and default (can be overridden). Plugin specific options can be applied here, if you wish. They will be ignored by plugins that don't know what to do with them. See the POD for each plugins for more details on options a particular plugin accepts.

Current global options include:

verbose

Default is false. Setting this to true causes plugin to generate a lot of noise.

quiet

Default is false. Setting this to true causes prevents the plugin from giving status messages.

add_plugin()

my $plugin = $info->add_plugin("PLUGIN", $options)

Takes a plugin name and optional set of options and it to a the Music::Tag object. Returns reference to a new plugin object.

$options is a hashref that can be used to override the global options for a plugin.

Current plugins include MP3, OGG, FLAC, M4A, Amazon, File, and MusicBrainz. Additional plugins can be created. See <L/Plugin Syntax> for information.

First option can be an string such as "MP3" in which case Music::Tag::MP3->new($self, $options) is called,an object name such as "Music::Tag::Custom::MyPlugin" in which case Music::Tag::MP3->new($self, $options) is called. It can also be an object.

Options can also be included in the string, as in Amazon;locale=us;trust_title=1.

plugin()

my $plugin = $item->plugin("MP3")->strip_tag();

The plugin method takes a regular expression as a string value and returns the first plugin whose package name matches the regular expression. Used to access package methods directly. Please see <L/PLUGINS> section for more details on standard plugin methods.

get_tag()

$info->get_tag();

get_tag applies all active plugins to the current tag object in the order that the plugin was added. Specifically, it runs through the list of plugins and performs the get_tag() method on each.

set_tag()

$info->set_tag();

set_tag writes info back to disk for all tags, or submits info if appropriate. Specifically, it runs through the list of plugins and performs the set_tag() method on each.

strip_tag()

$info->strip_tag();

strip_tag removes info from on disc tag for all plugins. Specifically, it performs the strip_tag methd on all plugins in the order added.

close()

$info->close();

closes active filehandles on all plugins. Should be called before object destroyed.

changed()

$ischanged = $info->changed($new);

Returns true if changed. Optional value $new sets changed set to True of $new is true. A "change" is any tag additions done by MusicBrainz, Amazon, or File plugins.

options()

my $verbose = $info->options("verbose"); my $verbose = $info->options->{verbose}; $info->options("verbose", 0); $info->options->{verbose} = 0;

This method is used to access or change the options. When called with no options, returns a reference to the options hash. When called with one string option returns the value for that key. When called with one hash value, merges hash with current options. When called with 2 options, the first is a key and the second is a value and the ket gets set to the value. This method is for global options.

datamethods()

Returns a list of all data methods supported.

Data access methods

These methods are used to access the tag info. Not all methods are supported by all plugins. In fact, no single plugin supports all methods (yet). Each of these is an accessort function. If you pass it a value, it will set the variable. It always returns the value of the variable. It can return undef.

The title of the release.

album_type

The type of the release. Specifically, the MusicBrainz type (ALBUM OFFICIAL, etc.)

albumartist

The artist responsible for the album. Usually the same as the artist, and will return the value of artist if unset.

artist

The artist responsible for the track.

artist_type

The type of artist. Usually Group or Person.

asin

The Amazon ASIN number for this album.

bitrate

Enconding bitrate.

comment

A comment about the track.

compilation

True if album is Various Artist, false otherwise. Don't set to true for Best Hits.

composer

Composer of song.

copyright

A copyright message can be placed here.

disc

In a multi-volume set, the disc number.

discnum

The disc number and optionally the total number of discs, seperated by a slash. Setting it sets the disc and totaldiscs values (and vice-versa).

duration

The length of the track in milliseconds. Returns secs * 1000 if not set. Changes the value of secs when set.

encoder

The codec used to encode the song.

filename

The filename of the track.

frequency

The frequency of the recording (in Hz).

genre

The genre of the song. Various tags use this field differently, so it may be lost.

label

The label responsible for distributing the recording.

lyrics

The lyrics of the recording.

mb_albumid

The MusicBrainz database ID of the album or release object.

mb_artistid

The MusicBrainz database ID for the artist.

mb_trackid

The MusicBrainz database ID for the track.

picture

A hashref that contains the following:

{ "MIME type" => The MIME Type of the picture encoding "Picture Type" => What the picture is off. Usually set to 'Cover (front)' "Description" => A short description of the picture "_Data" => The binary data for the picture. }

The rating (value is 0 - 100) for the track.

releasedate

The release date in the form YYYY-MM-DD. Months and days can be left off.

secs

The number of seconds in the recording.

sortname

The name of the sort-name of the artist (e.g. Hersh, Kristin or Throwing Muses, The)

tempo

The tempo of the track

title

The name of the song.

totaldiscs

The total number of discs, if a multi volume set.

totaltracks

The total number of tracks on the album.

track

The track number

tracknum

The track number and optionally the total number of tracks, seperated by a slash. Setting it sets the track and totaltracks values (and vice-versa).

A url associated with the track (often the buy link for Amazon).

year

The year a track was released. Defaults to year set in releasedate if not set.

PLUGINS

All plugins should set @ISA to include Music::Tag::Generic and contain one or more of the following methods:

new()

Set in template. If you override, it should take as options a reference to a Music::Tag object and an href of options.

info()

Should return a reference to the associated Music::Tag object. If passed an object, should set the associated Music::Tag object to it.

get_tag()

Populates the data in the Music::Tag object.

set_tag()

Optional method to save info back to tag.

strip_tag

Optional method to remove a tag.

close

Optional method to close open file handles.

tagchange

Inhereted method that can be called to announce a tag change from what is read on file. Used by secondary plugins like Amazon, MusicBrainz, and File.

simplify

A usfull method for simplifying artist names and titles. Takes a string, and returns a sting with no whitespace. Also removes accents (if Text::Unaccent is available) and converts numbers like 1,2,3 as words to one, two, three. Removes a,the

status

Inhereted method to print a pretty status message.

error

Inhereted method to print an error message.

options

Returns a hashref of options (or sets options, just like Music::Tag method).

default_options

method should return default options

BUGS

No method for analysing album as a whole, only track-by-track method.

cpanm Music::Tag

perl -MCPAN -e shell
install Music::Tag