/ 
Music-Tag-0.28
River stage two • 10 direct dependents • 11 total dependents
/ Music::Tag

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, ealleniii _at_ cpan _dot_ org

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. 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 by a plugin).

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.

autoplugin

Option is a hash reference. Reference maps file extensions to plugins. Default is:

{   mp3	  => "MP3",
    m4a   => "M4A",
    m4p   => "M4A",
    mp4   => "M4A",
    m4b   => "M4A",
    '3gp' => "M4A",
    ogg   => "ogg",
    flac  => "flac"   }
optionfile

Array reference of files to load options from.

ANSIColor

Set to true to enable color status messages.

LevenshteinXS

Set to true to use Text::LevenshteinXS to allow approximate matching with Amazon and MusicBrainz Plugins.

Levenshtein

Same as LevenshteinXS, but with Text::Levenshtein.

TimeLocal

Attempt to use Time::Local to support unix release date tags.

Unaccent

Set to true to allow accent-neutral matching with Text::Unaccent.

Inflect

When true, uses Linque::EN::Inflect to perform approximate matches. Default false. Will reset to false if module is missing.

Stem

When true, uses Linqua::Stem to perform approximate matches. Default false. Will reset to false if module is missing.

TimeLocal

When true, uses Time::Local to perform date calculations. Defaults true. Will reset to false if module is missing.

LoadOptions()

Load options stated in optionfile from file. Default locations are /etc/musictag.conf and ~/.musictag.conf. Can be called as class method or object method.

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 or frozen.

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.

data()

Returns a reference to the hash which stores all data about a track and optionally sets it. This is useful if you want to freeze and recreate a track, or use a shared data object in a threaded environment.

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.

sha1()

Returns a sha1 digest of the first 16K of the music file.

datamethods()

Returns an array reference of all data methods supported. Optionally takes a method which is added. Data methods should be all lower case and not conflict with existing methods. Datamethod additions are global, and not tied to an object. Array reference should be considered read only.

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.

album

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.

albumartist_sortname

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

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.

booklet

URL to a digital booklet. Usually in PDF format. iTunes passes these out sometimes, or you could scan a booklet and use this to store value. URL is assumed to be realtive to file location.

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.

A copyright message can be placed here.

disc

In a multi-volume set, the disc number.

disctitle

In a multi-volume set, the title of a disc.

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.

filedir

The path that music file is located in.

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.

mip_puid

The MusicIP puid 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.
   "filename"      => A filename for the picture.  Data overrides "_Data" and will
                      be returned as _Data if queried.  Filename is calculated as relative
                      to the path of the music file as stated in "filename" or root if no
                      filename for music file available.
}

Note hashref MAY be generated each call. Do not modify and assume tag will be modified!

picture_filename

Returns filename used for picture data. If no filename returns 0. If no picture returns undef.

picture_exists

Returns true if tag has picture data (or filename), false if not. Convenience method to prevant reading the file. Will return false of filename listed for picture does not exist.

rating

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

recorddate

The date track was recorded (not release date). See notes in releasedate for format.

recordepoch

The recorddate in seconds since epoch. See notes in releaseepoch for format.

recordtime

The time and date track was recoded. See notes in releasetime for format.

releasedate

The release date in the form YYYY-MM-DD. The day or month values may be left off. Please keep this in mind if you are parsing this data.

Because of bugs in my own code, I have added 2 sanity checks. Will not set the time and return undef if either of the following are true:

1) Time is set as 0000-00-00

2) Time is set as 1900-00-00

All times should be GMT.

releaseepoch

The release date of an album in terms "unix time", or seconds since the SYSTEM epoch (usually Midnight, January 1, 1970 GMT). This can be negative or > 32 bits, so please use caution before assuming this value is a valid unix date. Using this requires the Time::Local module, so install it if you have not. Returns undef if Time::Local is not installed. This value will update releasedate and vice versa. Since this accurate to the second and releasedate only to the day, setting releasedate will always set this to 12:00 PM GMT the same day. Returns undef if Time::Local is not installed.

releasetime

Like releasedate, but adds the time. Format should be YYYY-MM-DD HH::MM::SS. Like releasedate, all entries are year are optional.

All times should be GMT.

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).

url

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. Does not set releasedate.

Non Standard Data Access Methods

These methods are not currently used by any standard plugin. They may be used in the future, or by other plugins (such as a SQL plugin). Included here to standardize expanstion methods.

albumid, artistid, songid

These three values can be used by a database plugin. I recommend using the same value as mb_albumid, mb_artistid, and mb_trackid by default when possible.

ipod, ipod_dbid, ipod_location, ipod_trackid

Values for an iPod plugin. (This does not exists yet. It may someday. Ok it does. I may PUBLISH it someday.).

pregap, postgap, gaplessdata, samplecount

Used to store gapless data in.

user

Used for user data.

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. Several plugins do not support all tags. Has not been tested in a threaded environment.

SEE ALSO INCLUDED

Music::Tag::Amazon, Music::Tag::File, Music::Tag::FLAC, Music::Tag::Lyrics, Music::Tag::M4A, Music::Tag::MP3, Music::Tag::MusicBrainz, Music::Tag::OGG, Music::Tag::Option

SEE ALSO

Term::ANSIColor, Text::LevenshteinXS, Text::Unaccent, Lingua::EN::Inflect, Lingua::Stem

AUTHOR

Edward Allen III <ealleniii _at_ cpan _dot_ org>

COPYRIGHT

Copyright (c) 2007,2008 Edward Allen III. Some rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License, distributed with Perl.