NAME

Music::Tag - Interface 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 an 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();

DESCRIPTION

Extendable module for working with Music Tags. Music::Tag Is powered by various plugins that collect data about a song based on whatever information has already been discovered.

The motivation behind this was to provide a convenient method for fixing broken tags in music files. This developed into a universal interface to various music file tagging schemes and a convenient way to augment this from online databases.

Several plugin modules to find information about a music file and write it back into the tag are available. These modules will use available information (REQUIRED DATA VALUES and USED DATA VALUES) and set various data values back to the tag.

EXECUTABLE SCRIPT

An executable script, musictag is allows quick tagging of MP3 files. To learn more, use:

musictag --help 
musictag --longhelp

METHODS

new()

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

my $info = Music::Tag->new($filename, { quiet => 1 }, "MP3" ) ;

If no plugin is listed, then it will automatically add the appropriate file plugin based on the extension. It does this by using the Music::Tag::Auto plugin. If no plugin is appropriate, it will return.

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 of the 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 prevents the plugin from giving status messages.

autoplugin

Option is a hash reference mapping file extensions to plugins. Technically, this option is for the Music::Tag::Auto plugin. 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. Default is:

[   "/etc/musictag.conf",   
    $ENV{HOME} . "/.musictag.conf"  ]

Note that this is only used if the "load_options" method is called.

Option file is a pure perl config file using Config::Options.

ANSIColor

Default false. Set to true to enable color status messages.

LevenshteinXS

Default true. Set to true to use Text::LevenshteinXS to allow approximate matching with Amazon and MusicBrainz Plugins. Will reset to false if module is missing.

Levenshtein

Default true. Same as LevenshteinXS, but with Text::Levenshtein. Will not use if Text::Levenshtein can be loaded. Will reset to false if module is missing.

Unaccent

Default true. When true, allows accent-neutral matching with Text::Unaccent::PurePerl. Will reset to false if module is missing.

Inflect

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

available_plugins()

Class method. Returns list of available plugins. For example:

foreach (Music::Tag->available_plugins) {
    if ($_ eq "Amazon") {
        print "Amazon is available!\n";
        $info->add_plugin("Amazon", { locale => "uk" });
    }
}

default_options()

Class method. Returns default options as a Config::Options method.

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. If called as a class method the default values for all future Music::Tag objects are changed.

add_plugin()

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

    my $plugin = $info->add_plugin("MusicBrainz", 
								   { preferred_country => "UK" });

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

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 or an object, which is added to the list.

Current plugins include MP3, OGG, FLAC, M4A, Amazon, File, MusicBrainz, Lyrics and l<LyricsFetcher|Music::Tag::LyricsFetcher>,

Additional plugins can be created and may be available on CPAN. See <L:Plugin Syntax> for information.

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

get_tag applies all active plugins to the current Music::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. For example:

$info->get_tag();

set_tag()

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

$info->set_tag();

strip_tag()

strip_tag removes info from on disc tag for all plugins. Specifically, it performs the strip_tag method on all plugins in the order added. For example:

$info->strip_tag();

close()

closes active filehandles on all plugins. Should be called before object destroyed or frozen. For example:

$info->close();

changed()

Returns true if changed. Optional value $new sets changed set to True of $new is true. A "change" is any data-value additions or changes done by MusicBrainz, Amazon, File, or Lyrics plugins. For example:

# Check if there is a change:
$ischanged = $info->changed();

# Force there to be a change
$info->changed(1);

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. For example;

use Data::Dumper;
my $bighash = $info->data();
print Dumper($bighash);

options()

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 key gets set to the value. This method is for global options. For example:

# Get value for "verbose" option
my $verbose = $info->options("verbose");

# or...
my $verbose = $info->options->{verbose};

# Set value for "verbose" option
$info->options("verbose", 0);

# or...
$info->options->{verbose} = 0;

setfileinfo

Sets the mtime and bytes attributes for you from filename.

sha1()

Returns a sha1 digest of the filesize in little endian then the first 16K of the music file. Should be fairly unique.

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. Data method additions are global, and not tied to an object. Array reference should be considered read only. For example:

# Print supported data methods:
my $all_methods = Music::Tag->datamethods();
foreach (@{$all_methods}) {
    print '$info->'. $_ . " is supported\n";
}

# Add is_hairband data method:
Music::Tag->datamethods("is_hairband");

used_datamethods()

Returns an array reference of all data methods that will not return. For example:

my $info = Music::Tag->new($filename);
$info->get_tag();
foreach (@{$info->used_datamethods}) {
    print $_ , ": ", $info->$_, "\n";
}

wav_out($fh)

Pipes audio data as a wav file to filehandled $fh. Returns true on success, false on failure, undefined if no plugin supports this.

Data Access Methods

These methods are used to access the Music::Tag data values. Not all methods are supported by all plugins. In fact, no single plugin supports all methods (yet). Each of these is an accessor function. If you pass it a value, it will set the variable. It always returns the value of the variable.

Please note that an undefined function will return undef. This means that in list context, it will be true even when empty. This behavior may change, however, so don't rely on it.

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)

albumtags

A array reference or comma seperated list of tags in plain text for the album.

albumrating

The rating (value is 0 - 100) for the album (not supported by any plugins yet).

artist

The artist responsible for the track.

artist_start

The date the artist was born or a group was founded. Sets artist_start_time and artist_start_epoch.

artist_start_time

The time the artist was born or a group was founded. Sets artist_start and artist_start_epoch

artist_start_epoch

The number of seconds since the epoch when artist was born or a group was founded. Sets artist_start and artist_start_time

See release_epoch.

artist_end

The date the artist died or a group was disbanded. Sets artist_end_time and artist_end_epoch.

artist_end_time

The time the artist died or a group was disbanded. Sets artist_end and artist_end_epoch

artist_end_epoch

The number of seconds since the epoch when artist died or a group was disbanded. Sets artist_end and artist_end_time

See release_epoch.

artisttags

A array reference or comma seperated list of tags in plain text for the artist.

artist_type

The type of artist. Usually Group or Person.

asin

The Amazon ASIN number for this album.

bitrate

Bitrate of file (average).

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

copyright

A copyright message can be placed here.

country

Return the country that the track was released in.

countrycode

The two digit country code. Sets country (and is set by country)

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.

duration

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

ean

The European Article Number on the package of product. Must be the EAN-13 (13 digits 0-9).

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 music tagging schemes use this field differently. It should be text and not a code. As a result, some plugins may be more restrictive in what can be written to disk,

jan

Same as ean.

label

The label responsible for distributing the recording.

lastplayeddate

The date the song was last played.

lastplayedtime

The time the song was last played.

lastplayedepoch

The number of seconds since the epoch the time the song was last played.

See release_epoch.

lyrics

The lyrics of the recording.

mdate

The date the file was last modified.

mtime

The time the file was last modified.

mepoch

The number of seconds since the epoch the time the file was last modified.

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.

mip_fingerprint

The Music Magic fingerprint

performer

The performer. This is an alias for artist.

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 data-value in object will be modified! Passing a value will modify the data-value as expected. In other words:

# This works:
$info->picture( { filename => "cover.jpg" } ) ;

# This may not:
my $pic = $info->picture;
$pic->{filename} = "back_cover.jpg";

picture_filename

Returns filename used for picture data. If no filename returns 0. If no picture returns undef. If a value is passed, sets the filename. filename is path relative to the music file.

picture_exists

Returns true if Music::Tag object 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 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. 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.

Please note that this has some limitations. In 32bit Linux, the only supported dates are Dec 1901 to Jan 2038. In windows, dates before 1970 will not work. Refer to the docs for Time::Local for more details.

releasetime

Like releasedate, but adds the time. Format should be YYYY-MM-DD HH::MM::SS. Like releasedate, all entries but 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

tracktags

A array reference or comma seperated list of tags in plain text for the track.

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

upc

The Universal Product Code on the package of a product. Returns same value as ean without initial 0 if ean has an initial 0. If set and ean is not set, sets ean and adds initial 0. It is possible for ean and upc to be different if ean does not have an initial 0.

url

A url associated with the track (often a link to the details page on 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 expansion methods.

albumid, artistid, songid: These three values can be used by a database plugin. They should be GUIDs like the MusicBrainz IDs. 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: Suggested values for an iPod plugin.
pregap, postgap, gaplessdata, samplecount, appleid: Used to store gapless data. Some of this is supported by Music::Tag::MP3 as an optional value requiring a patched MP3::Info.
user: Used for user data. Reserved. Please do not use this in any Music::Tag plugin published on CPAN.
bytes, codec, encoded_by, filetype, frames, framesize, mtime, originalartist, path, playcount, stereo, vbr: TODO: These need to be documented
status: Semi-internal method for printing status.
error: Semi-internal method for printing errors.

PLUGINS

See Music::Tag::Generic for base class for plugins.

BUGS

No method for evaluating an album as a whole, only track-by-track method. Several plugins do not support all data values. Has not been tested in a threaded environment.

SOURCE

Source is available at github: http://github.com/riemann42/Music-Tag.

BUG TRACKING

Please use github for bug tracking: http://github.com/riemann42/Music-Tag/issues.

AUTHOR

Edward Allen III <ealleniii _at_ cpan _dot_ org>

COPYRIGHT

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with Perl.

To install Music::Tag, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Music::Tag

CPAN shell

perl -MCPAN -e shell
install Music::Tag

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

EXECUTABLE SCRIPT

METHODS

Data Access Methods

Non Standard Data Access Methods

PLUGINS

BUGS

SEE ALSO

SOURCE

BUG TRACKING

AUTHOR

COPYRIGHT

LICENSE

Module Install Instructions