NAME

MP3::Tag - Module for reading tags of MP3 audio files

SYNOPSIS

use MP3::Tag;

$mp3 = MP3::Tag->new($filename);

# get some information about the file in the easiest way
($title, $track, $artist, $album, $comment, $year, $genre) = $mp3->autoinfo();
$comment = $mp3->comment();

# or have a closer look on the tags

# scan file for existing tags
$mp3->get_tags;

if (exists $mp3->{ID3v1}) {
    # read some information from the tag
    $id3v1 = $mp3->{ID3v1};  # $id3v1 is only a shortcut for $mp3->{ID3v1}
    print $id3v1->title;
    
    # change the tag contents
    $id3v1->all("Song","Artist","Album",2001,"Comment",10,"Top 40");
    $id3v1->write_tag;
}

if (exists $mp3->{ID3v2}) {
    # read some information from the tag
    ($name, $info) = $mp3->{ID3v2}->get_frame("TIT2");
    # delete the tag completely from the file
    $mp3->{ID3v2}->remove_tag;
} else {
    # create a new tag
    $mp3->new_tag("ID3v2");
    $mp3->{ID3v2}->add_frame("TALB", "Album title");
    $mp3->{ID3v2}->write_tag;
}

$mp3->close();

AUTHORS

Thomas Geffert, thg@users.sourceforge.net Ilya Zakharevich, ilyaz@cpan.org

DESCRIPTION

Tag is a wrapper module to read different tags of mp3 files. It provides an easy way to access the functions of seperate modules which do the handling of reading/writing the tags itself.

At the moment MP3::Tag::ID3v1 and MP3::Tag::ID3v2 are supported for read and write; MP3::Tag::Inf, MP3::Tag::CDDB_File, MP3::Tag::File, MP3::Tag::LastResort are supported for read access (the information obtained by parsing CDDB files, .inf file and the filename).

new()

$mp3 = MP3::Tag->new($filename);

Creates a mp3-object, which can be used to retrieve/set different tags.

get_tags()

[old name: getTags() . The old name is still available, but its use is not advised]

@tags = $mp3->get_tags;

Checks which tags can be found in the mp3-object. It returns a list @tags which contains strings identifying the found tags, like "ID3v1", "ID3v2", "Inf", or "CDDB_File" (the last but one if the .inf information file with the same basename as MP3 file is found).

Each found tag can then be accessed with $mp3->{tagname} , where tagname is a string returned by get_tags ;

Use the information found in MP3::Tag::ID3v1, MP3::Tag::ID3v2 and MP3::Tag::Inf, MP3::Tag::CDDB_File to see what you can do with the tags.

new_tag()

[old name: newTag() . The old name is still available, but its use is not advised]

$tag = $mp3->new_tag($tagname);

Creates a new tag of the given type $tagname. You can access it then with $mp3->{$tagname}. At the moment ID3v1 and ID3v2 are supported as tagname.

Returns an tag-object: $mp3->{$tagname}.

close()

$mp3->close;

You can use close() to explicitly close a file. Normally this is done automatically by the module, so that you do not need to do this.

genres()

$allgenres = $mp3->genres;
$genreName = $mp3->genres($genreID);
$genreID   = $mp3->genres($genreName);

Returns a list of all genres (reference to an array), or the according name or id to a given id or name.

This function is only a shortcut to MP3::Tag::ID3v1->genres.

This can be also called as MP3::Tag->genres;

autoinfo()

($title, $track, $artist, $album, $comment, $year, $genre) = $mp3->autoinfo();
$info_hashref = $mp3->autoinfo();

autoinfo() returns information about the title, track number, artist, album name, the file comment, the year and genre. It can get this information from an ID3v1-tag, an ID3v2-tag, from CDDB file, from .inf-file, and from the filename itself.

It will as default first try to find a ID3v2-tag to get this information. If this cannot be found it tries to find a ID3v1-tag, then to read an CDDB file, an .inf-file, and if these are not present either, it will use the filename to retrieve the title, track number, artist, album name. The comment, year and genre are found differently, via the comment, year and genre methods.

You can change the order of lookup with the config() command.

autoinfo() returns an array with the information or a hashref. The hash has four keys 'title', 'track', 'artist' and 'album' where the information is stored. If comment, year or genre are found, the hash will have keys 'comment' and/or 'year' and/or 'genre' too.

If an optional argument 'from' is given, the returned values (title, track number, artist, album name, the file comment, the year and genre) are array references with the first element being the value, the second the tag (ID3v2 or ID3v1 or Inf or CDDB_File or filename) from which it is taken.

(Deprecated name 'song' can be used instead of 'title' as well.)

comment()

$comment = $mp3->comment();		# empty string unless found

comment() returns comment information. It can get this information from an ID3v1-tag, or an ID3v2-tag (from COMM frame with empty <short> field), CDDB file (from EXTD or EXTT fields), or .inf-file (from Trackcomment field).

It will as default first try to find a ID3v2-tag to get this information. If no comment is found there, it tries to find it in a ID3v1-tag, if none present, will try CDDB file, then .inf-file. It returns an empty string if no comment is found.

You can change the order of this with the config() command.

If an optional argument 'from' is given, returns an array reference with the first element being the value, the second the tag (ID3v2 or ID3v1) from which the value is taken.

year()

$year = $mp3->year();		# empty string unless found

year() returns the year information. It can get this information from an ID3v2-tag, or ID3v1-tag, or .inf-file, or filename.

It will as default first try to find a ID3v2-tag to get this information. If no year is found there, it tries to find it in a ID3v1-tag, if none present, will try CDDB file, then .inf-file, then by parsing the file name. It returns an empty string if no year is found.

You can change the order of this with the config() command.

If an optional argument 'from' is given, returns an array reference with the first element being the value, the second the tag (ID3v2 or ID3v1 or filename) from which the value is taken.

comment_collection(), comment_track(), title_track(). author_collection()

access the corresponding fields returned by parse() method of CDDB_File.

genre()

$genre = $mp3->genre();		# empty string unless found

genre() returns the genre string. It can get this information from an ID3v2-tag or ID3v1-tag.

It will as default first try to find a ID3v2-tag to get this information. If no genre is found there, it tries to find it in a ID3v1-tag, if none present, will try .inf-file, It returns an empty string if no genre is found.

You can change the order of this with the config() command.

If an optional argument 'from' is given, returns an array reference with the first element being the value, the second the tag (ID3v2 or ID3v1 or filename) from which the value is taken.

config

MP3::Tag->config(item => value1, value2...);	# Set options globally
$mp3->config(item => value1, value2...);	# Set object options

When object options are first time set or get, the global options are propagated into object options. (So if global options are changed later, these changes are not inherited.)

Possible items are:

autoinfo

Configure the order in which ID3v1-, ID3v2-tag and filename are used by autoinfo. Options can be "ID3v1", "ID3v2", "CDDB_File", "Inf", "filename". The order in which they are given to config also sets the order how they are used by autoinfo. If an option is not present, it will not be used by autoinfo (and other auto-methods if the specific overriding config command were not issued).

$mp3->config("autoinfo","ID3v1","ID3v2","filename");

sets the order to check first ID3v1, then ID3v2 and at last the Filename

$mp3->config("autoinfo","ID3v1","filename","ID3v2");

sets the order to check first ID3v1, then the Filename and last ID3v2. As the filename will be always present ID3v2 will here never be checked.

$mp3->config("autoinfo","ID3v1","ID3v2");

sets the order to check first ID3v1, then ID3v2. The filename will never be used.

title artist album year comment track genre

Configure the order in which ID3v1- and ID3v2-tag are used by the corresponding methods (e.g., comment()). Options can be "ID3v1", "ID3v2", "Inf", "CDDB_File", "filename". The order in which they are given to config also sets the order how they are used by comment(). If an option is not present, then autoinfo option will be used instead.

extension

regular expression to match the file extension (including the dot). The default is to match 1..4 letter extensions which are not numbers.

parse_data

the data used by MP3::Tag::ParseData handler; each option is an array reference of the form [$flag, $string, $pattern1, ...]. All the options are processed in the following way: patterns are matched against $string until one of them succeeds; the information obtained from later options takes precedence over the information obtained from earlier ones.

parse_split

The regular expression to split the data when parsing with n or l flags.

parse_filename_ignore_case

If true (default), calling parse() and parse_rex() with match-filename escapes (such as %=D) matches case-insensitively.

parse_filename_merge_dots

If true (default), calling parse() and parse_rex() with match-filename escapes (such as %=D) does not distinguish a dot and many consequent dots.

parse_join

string to put between multiple occurences of a tag in a parse pattern; defaults to '; '. E.g., parsing '1988-1992, Homer (LP)' with pattern '%c, %a (%c)' results in comment set to '1988-1992; LP' with the default value of parse_join.

v2title

Configure the elements of ID3v2-tag which are used by ID3v2::title(). Options can be "TIT1", "TIT2", "TIT3"; the present values are combined. If an option is not present, it will not be used by ID3v2::title().

cddb_files

List of files to look for in the directory of MP3 file to get CDDB info.

year_is_timestamp

If TRUE (default) parse() will match complicated timestamps against %y; for example, 2001-10-23--30,2002-02-28 is a range from 23rd to 30th of October 2001, and 28th of February of 2002. According to ISO, -- can be replaced by / as well. For convenience, the leading 0 can be omited from the fields which ISO requires to be 2-digit.

comment_remove_date

When extracting the date from comment fields, remove the recognized portion even if it is human readable (e.g., Recorded on 2014-3-23) if TRUE. Current default: FALSE.

id3v2_frame_empty_ok

When setting the individual id3v2 frames via ParseData, do not remove the frames set to an empty string. Default 0 (empty means 'remove').

id3v2_minpadding

Minimal padding to reserve after ID3v2 tag when writing (default 128),

id3v2_sizemult

Additionally to id3v2_minpadding, insert padding to make file size multiple of this when writing ID3v2 tag (default 512), Should be power of 2.

id3v2_shrink

If TRUE, when writing ID3v2 tag, shrink the file if needed (default FALSE).

id3v2_mergepadding

If TRUE, when writing ID3v2 tag, consider the 0-bytes following the ID3v2 header as writable space for the tag (default FALSE).

update_length

If TRUE, when writing ID3v2 tag, create a TLEN tag if the duration is known (as it is after calling methods like total_secs, or interpolation the duration value). If this field is 2 or more, force creation of ID3v2 tag by update_tags if the duration is known.

translate_*

A subroutine used to munch a field * (out of title track artist album comment year genre) Takes two arguments: the MP3::Tag object, and the current value of the field.

The second argument may also have the form [value, handler], where handler is the string indentifying the handler which returned the value.

id3v2_missing_fatal

If TRUE, interpolating ID3v2 frames (e.g., by %{TCOM}) when the ID3v2 tags is missing is a fatal error. If false (default), in such cases interpolation results in an empty string.

parse_minmatch

may be 0, 1, or a list of %-escapes (matching any string) which should matched non-greedily by parse() and friends. E.g., parsing 'Adagio - Andante - Piano Sonata' via '%t - %l' gives different results for the settings 0 and 1; note that greediness of %l does not matter, thus the value of 1 is equivalent for the value of t for this particular pattern.

id3v23_unsync_size_w

Version 2.3 if the standard is not clear about frame size field, whether it is the size of the frame after unsyncronization, or not. Old versions were assuming that this size is one before unsyncronization (as in v2.2). Setting these values will assume another interpretation (as in v2.4) for write; experimental - to test why ITunes refuse to handle unsyncronized tags.

*

Later there will be probably more things to configure.

get_config

$opt = $mp3->get_config("item");

When object options are first time set or get, the global options are propagated into object options. (So if global options are changed later, these changes are not inherited.)

pure_filetags

$data = $mp3->pure_filetags()->autoinfo;

Configures $mp3 to not read anything except the pure ID3v2 or ID3v1 tags, and do not postprocess them. Returns the object reference itself to simplify chaining of method calls.

get_user

$data = $mp3->get_user($n);	# n-th piece of user scratch space

Queries an entry in a scratch array ($n=3 corresponds to %{U3}).

set_user

$mp3->set_user($n, $data);	# n-th piece of user scratch space

Sets an entry in a scratch array ($n=3 corresponds to %{U3}).

set_id3v2_frame

$mp3->set_id3v2_frame($name, @values);

When called with only $name as the argument, removes the specified frame (if it existed). Otherwise sets the frame passing the specified @values to the add_frame() function of MP3::Tag::ID3v2.

get_id3v2_frames

($descr, @frames) = $mp3->get_id3v2_frames($fname);

Returns the specified frame(s); has the same API as MP3::Tag::ID3v2::get_frames, but also returns undef if no ID3v2 tag is present.

is_id3v2_modified

$frame = $mp3->is_id3v2_modified();

Returns TRUE if ID3v2 tag exists and was modified after creation.

select_id3v2_frame

$frame = $mp3->select_id3v2_frame($fname, $descrs, $langs [, $VALUE]);

Returns the specified frame(s); has the same API as MP3::Tag::ID3v2::frame_select (args are frame name, list of wanted Descriptors, list of wanted Languages, and possibly the new contents - with undef meaning deletion). For read-only access it returns undef if no ID3v2 tag is present.

have_id3v2_frame

$have_it = $mp3->have_id3v2_frame($fname, $descrs, $langs);

Returns TRUE the specified frame(s) exist; has the same API as MP3::Tag::ID3v2::frame_have (args are frame name, list of wanted Descriptors, list of wanted Languages).

get_id3v2_frame_ids

$h = $mp3->get_id3v2_frame_ids();
print "  $_ => $h{$_}" for keys %$h;

Returns a hash reference with the short names of ID3v2 frames present in the tag as keys (and long description of the meaning as values), or FALSE if no ID3v2 tag is present. See MP3::Tags::ID3v2::get_frame_ids for details.

interpolate

$string = $mp3->interpolate($pattern)

interpolates %-escapes in $pattern using the information from $mp3 tags. The syntax of escapes is similar to this of sprintf():

% [ [FLAGS] MINWIDTH] [.MAXWIDTH] ESCAPE

The only recognized FLAGS are - (to denote left-alignment inside MINWIDTH- wide field), ' ' (SPACE), and 0 (denoting the fill character to use), as well as an arbitrary character in parentheses (which becomes the fill character). MINWIDTH and MAXWIDTH should be numbers.

The one-letter ESCAPEs are replaced by

% => literal '%'
t => title
a => artist
l => album
y => year
g => genre
c => comment
n => track
f => filename without the directory path
F => filename with the directory path
D => the directory path of the filename
E => file extension
e => file extension without the leading dot
A => absolute filename without extension
B => filename without the directory part and extension
N => filename as originally given without extension

v	mpeg_version
L	mpeg_layer_roman
r	bitrate_kbps
q	frequency_kHz
Q	frequency_Hz
S	total_secs_int
M	total_millisecs_int
m	total_mins
s	leftover_secs
C	is_copyrighted_YN
p	frames_padded_YN
o	channel_mode
u	frames

Additionally, ESCAPE can be a string (with all backslashes and curlies escaped) enclosed in curly braces {}. The interpretation is the following:

dNUMBER is replaced by NUMBER-th component of the directory name (with 0 corresponding to the last component).
UNUMBER is replaced by NUMBER-th component of the user scratch array.
DNUMBER is replaced by the directory name with NUMBER components stripped.
Names of ID3v2 frames are replaced by their text values (empty for missing frames).
If string starts with FNAME:: if frame FNAME does not exists, the escape is ignored; otherwise the rest of the string is reinterpreted (after stripping backslashes from backslashes and curlies).
String starting with !FNAME: are treated similarly with inverted test.
If string starts with FNAME||: if frame FNAME exists, the part after || is ignored; otherwise the part before || is ignored, and the rest is reinterpreted (after stripping backslashes from backslashes and curlies).
If string starts with FNAME|: if frame FNAME exists, the part after | is ignored; otherwise the part before | is ignored, and the rest is reinterpreted as if it started with %{.
String starting with LETTER: or !LETTER: are treated similarly to ID3v2 conditionals, but the condition is that the corresponding escape expands to non-empty string.
Likewise for string starting with LETTER| or LETTER||.
Strings aC, tT, cC, cT are replaced by the collection artist, track title, collection comment, and track comment as obtained from CDDB_File.
Strings ID3v1 and ID3v2 are replaced by the whole ID3v1/2 tag.
Strings of the form FRAM(list,of,languages)[description]' are replaced by the first FRAM frame with the descriptor "description" in the specified comma-separated list of languages. Instead of a language (ID3v2 uses lowercase 3-char ISO-639-2 language notations) one can use a string of the form #Number; e.g., #4 means 4th FRAM frame, or FRAM04. Empty string for the language means any language.) Works as a condition for conditional interpolation too.

Any one of the list of languages and the disription can be omitted; this means that either the frame FRAM has no language or descriptor associated, or no restriction should be applied.

Unknown language should be denoted as XXX (in uppercase!). The language match is case-insensitive.

EXAMPLE SCRIPTS

Some example scripts come with this module:

mp3info2: perform command line manipulation of audio tags (and more!);
audio_rename: rename audio files according to associated tags (and more!);
type_mp3_dir: write LaTeX files suitable for CD covers and normal-size sheet descriptions of hierarchy of audio files;
mp3_total_time: Calculate total duration of audio files;
eat_wav_mp3_header: remove WAV headers from MP3 files in WAV containers.

(Last two do not use these modules!)

Some more examples:

  # Convert from one (non-standard-conforming!) encoding to another
  perl -MMP3::Tag -MEncode -wle '
    my @fields = qw(artist album title comment);
    for my $f (@ARGV) {
      print $f;
      my $t = MP3::Tag->new($f) or die;
      $t->update_tags(
	{ map { $_ => encode "cp1251", decode "koi8-r", $t->$_() }, @fields }
      );
    }' list_of_audio_files

Problems with ID3 format

The largest problem with ID3 format is that the first versions of these format were absolutely broken (underspecified). It looks like the newer versions of this format resolved most of these problems; however, in reality they did not (due to unspecified backward compatibility, and grandfathering considerations).

What are the problems with ID3v1? First, one of the fields was artist, which does not make any sense. In particular, different people/publishers would put there performer(s), composer, author of text/lyrics, or a combination of these. The second problem is that the only allowed encoding was iso-8859-1; since most of languages of the world can't be expressed in this encoding, this restriction was completely ignored, thus the encoding is essentially "unknown".

Newer versions of ID3 allow specification of encodings; however, since there is no way to specify that the encoding is "unknown", when a tag is automatically upgraded from ID3v1, it is most probably assumed to be in the "standard" iso-8859-1 encoding. Thus impossibility to distinguish "unknown, assumed iso-8859-1" from "known to be iso-8859-1" in ID3v2, essentially, makes any encoding specified in the tag "unknown" (or, at least, "untrusted").

This is why this module provides what some may consider only lukewarm support for encoding field in ID3v2 tags: if done fully automatic, it can allow instant propagation of wrong information; and propagation in a form which is very hard to undo.

Likewise, the same happens with the artist field in ID3v1. Since there is no way to specify just "artist, type unknown" in ID3v2 tags, when ID3v1 tag is automatically upgraded to ID3v2, the content would most probably be put in the "main performer", TPE1, tag. As a result, the content of TPE1 tag is also "untrusted" - it may contain, e.g., composer.

In my opinion, a different field should be used for "known to be principal performer"; for example, the script mp3info2 shipped with this module uses %{TXXX[TPE1]} in preference to %{TPE1}.

For example, interpolate %{TXXX[TPE1]|TPE1} or %{TXXX[TPE1]|a} - this will use the frame TXXX with identifier TPE1 if present, if not, it will use the frame TPE1 (the first example), or will try to get artist by other means (including TPE1 frame) (the second example).

COPYRIGHT

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

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 634:

Expected text after =item, not a bullet

Around line 977:

You can't have =items (as at line 1180) unless the first thing after the =over is an =item

Around line 1685:

You forgot a '=back' before '=head1'

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

cpanm

cpanm MP3::Tag

CPAN shell

perl -MCPAN -e shell
install MP3::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

AUTHORS

DESCRIPTION

EXAMPLE SCRIPTS

Problems with ID3 format

SEE ALSO

COPYRIGHT

Module Install Instructions