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_fake

$obj = MP3::Tag->new_fake();

This method produces a "fake" MP3::Tag object which behaves as an MP3 file without tags. Give a TRUE optional argument if you want to set some properties of this object.

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

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

cddb_id(), cdindex_id()

access the corresponding methods of ID3v2, Inf or 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.

composer()

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

composer() returns the composer. By default, it gets from ID3v2 tag, otherwise returns artist.

You can change the inspected fields with the config() command. Subject to normalization via translate_composer or translate_person configuration variables.

performer()

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

performer() returns the main performer. By default, it gets from ID3v2 tag TXXX[TPE1], otherwise from ID3v2 tag TPE1, otherwise returns artist.

You can change the inspected fields with the config() command. Subject to normalization via translate_performer or translate_person configuration variables.

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.

composer

string to put into %{} to interpolate to get the composer. Default is 'TCOM|a'.

performer

string to put into %{} to interpolate to get the main performer. Default is 'TXXX[TPE1]|TPE1|a'.

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.

default_language

The language to use to select ID3v2 frames, and to choose COMM ID3v2 frame accessed in comment() method (default is 'XXX'; if not XXX, this should be lowercase 3-letter abbreviation according to ISO-639-2).

default_descr_c

The description field used to choose the COMM ID3v2 frame accessed in comment() method. Defaults to ''.

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_*

FALSE, or a subroutine used to munch a field * (out of title track artist album comment year genre comment_collection comment_track title_track artist_collection person) to some "normalized" form. 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.

short_person

Similar to translate_person, but the intent is for this subroutine to translate a personal name field to a shortest "normalized" form.

person_frames

list of ID3v2 frames subject to normalization via translate_person handler; current default is TEXT TCOM TXXX[TPE1] TPE1 TPE3 TOPE TOLY TMCL TIPL TENC TXXX[person-file-by]. Used by select_id3v2_frame_by_descr(), frame_translate(), frames_translate().

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.

id3v2_recalculate

If TRUE, interpolating the whole ID3v2 tag (by %{ID3v2}) will recalculate the tag even if its contents is not modified.

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.

id3v23_unsync

Some broken MP3 players (e.g., ITunes, at least up to v6) refuse to handle unsyncronized (e.g., written as the standard requires it) tags; they may need this to be set to FALSE. Default: TRUE.

encoded_v1_fits

If TRUE, data is considered to fit ID3v1 tag even if encode_encoding_v1 is set (so the resulting tag is not standard-complying, thus ambiguous), or is not set, but decode_encoding_v1 is set (thus read+write operation is not idempotent), and the tag data contains "high bit characters". Default FALSE (so that ID3v2 tag will forced to written if encode_encoding_v1 is set).

decode_encoding_v1

encode_encoding_v1

decode_encoding_v2

decode_encoding_filename

decode_encoding_inf

decode_encoding_cddb_file

decode_encoding_files

encode_encoding_files

Encodings of ID3v1, non-Unicode frames of ID3v2, filenames, external files, .inf files and CDDB files correspondingly. The value of 0 means "latin1".

The default values for decode_encoding_* are set from the corresponding MP3TAG_DECODE_*_DEFAULT environment variable (here * stands for the uppercased last component of the name); if this variable is not set, from MP3TAG_DECODE_DEFAULT. Likewise, the default value for encode_encoding_v1 is set from MP3TAG_ENCODE_V1_DEFAULT or MP3TAG_ENCODE_DEFAULT; if not present, from the value for decode_encoding_v1; similarly for encode_encoding_files.

Note that decode_encoding_v2 has no "encode" pair; it may also be disabled per tag via effects of ignore_trusted_encoding0_v2 and the corresponding frame TXXX[trusted_encoding0_v2] in the tag.

ignore_trusted_encoding0_v2

If FALSE (default), and the frame TXXX[trusted_encoding0_v2] is set to TRUE, the setting of decode_encoding_v2 is ignored.

id3v2_set_trusted_encoding0

If TRUE (default), and frames are converted from the given decode_encoding_v2 to a standard-conforming encoding, a frame TXXX[trusted_encoding0_v2] with a TRUE value is added.

[The purpose is to make multi-step update in presence of decode_encoding_v2 possible; with id3v2_set_trusted_encoding0 TRUE, and ignore_trusted_encoding0_v2 FALSE (both are default values), editing of tags can be idempotent.]

id3v2_fix_encoding_on_write

If TRUE and decode_encoding_v2 is defined, the ID3v2 frames are converted to standard-conforming encodings on write. The default is FALSE.

id3v2_fix_encoding_on_edit

If TRUE (default) and decode_encoding_v2 is defined (and not disabled via a frame TXXX[trusted_encoding0_v2] and the setting ignore_trusted_encoding0_v2), a CYA action is performed when an edit may result in a confusion. More precise, adding an ID3v2 frame which is essentially affected by decode_encoding_v2 would convert other frames to a standard-conforming encoding (and would set TXXX[trusted_encoding0_v2] if required by id3v2_set_trusted_encoding0).

Recall that the added frames are always encoded in standard-conformant way; the action above avoids mixing non-standard-conformant frames with standard-conformant frames. Such a mix could not be cleared up by setting decode_encoding_v2! One should also keep in mind that this does not affect frames which contain characters above 0x255; such frames are always written in Unicode, thus are not affected by decode_encoding_v2.

id3v2_frames_autofill

Hash of suggested ID3v2 frames to autogenerate basing on extra information available; keys are frame descriptors (such as TXXX[cddb_id]), values indicate whether ID3v2 tag should be created if it was not present.

This variable is inspected by the method id3v2_frames_autofill, which is not called automatically when the tag is accessed, but may be called by scripts using the module.

The default is to force creation of tag for TXXX[MCDI-fulltoc] frame, and do not force creation for TXXX[cddb_id] and TXXX[cdindex_id].

local_cfg_file

Name of configuration file read at startup by the method parse_cfg(); is ~-substituted; defaults to ~/.mp3tagprc.

prohibit_v24

If FALSE (default), reading of ID3v2.4 is allowed (it is not fully supported, but most things work acceptably).

write_v24

If FALSE (default), writing of ID3v2.4 is prohibited (it is not fully supported; allow on your own risk).

*

Later there will be probably more things to configure.

get_config

$opt_array = $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.)

get_config1

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

Similar to get_config(), but returns UNDEF if no config array is present, or the first entry of array otherwise.

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. (The old value is removed.)

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.

delete_tag

$deleted = $mp3->delete_tag($tag);

$tag should be either ID3v1 or ID3v2. Deletes the tag if it is present. Returns FALSE if the tag is not 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.

If new context is specified, all the existing frames matching the specification are deleted.

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.

id3v2_frame_descriptors

Returns the list of human-readable "long names" of frames (such as COMM(eng)[lyricist birthdate]), appropriate for interpolation, or for select_id3v2_frame_by_descr().

select_id3v2_frame_by_descr

have_id3v2_frame_by_descr

Similar to select_id3v2_frame(), have_id3v2_frame(), but instead of arguments $fname, $descrs, $langs take one string of the form

NAME(langs)[descr]

Both (langs) and [descr] parts may be omitted; langs should contain comma-separated list of needed languages.

It is allowed to have NAME of the form FRAMnn; nn-th frame with name FRAM is chosen.

$frame = $mp3->select_id3v2_frame_by_descr($descr [, $VALUE]);
$have_it = $mp3->have_id3v2_frame_by_descr($descr);

select_id3v2_frame_by_descr() will also apply the normalizer in config setting translate_person if the frame name matches one of the elements of the configuration setting person_frames.

frame_translate

$mp3->frame_translate('TCOM'); # Normalize TCOM ID3v2 frame

assuming that the frame value denotes a person, normalizes the value using personal name normalization logic (via translate_person configuration value). Frame is updated, but the tag is not written back. The frame must be in the list of personal names frames (person_frames configuration value).

frames_translate

Similar to frame_translate(), but updates all the frames in person_frames configuration value.

shorten_person

$string = $mp3->shorten_person($person_name);

shorten $person_name as a personal name (according to short_person configuration setting).

normalize_person

$string = $mp3->normalize_person($person_name);

normalize $person_name as a personal name (according to translate_person configuration setting).

id3v2_frames_autofill

$mp3->id3v2_frames_autofill($force);

Generates missing tags from the list specified in id3v2_frames_autofill configuration variable. The tags should be from a short list this method knows how to deal with:

  TXXX[MCDI-fulltoc]:	filled from file audio_cd.toc in directory of the
			audio file.  [Create this file with
			  readcd -fulltoc dev=0,1,0 -f=audio_cd >& nul
			 modifying the dev (and redirection per your shell). ]
  TXXX[cddb_id]
  TXXX[cdindex_id]:	filled from the result of the corresponding method
				(which may extract from .inf or cddb files).

Existing frames are not modified unless $force option is specified; when $force is true, ID3v2 tag will be created even if it was not present.

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
mL	leftover_mins
H	total_hours
s	leftover_secs
SL	leftover_secs_trunc
ML	leftover_msec
SML	leftover_secs_float
C	is_copyrighted_YN
p	frames_padded_YN
o	channel_mode
u	frames

Additionally, ESCAPE can be a string enclosed in curly braces {}. The interpretation is the following:

Names of ID3v2 frames are replaced by their text values (empty for missing frames).
Strings aC, tT, cC, cT are replaced by the collection artist, track title, collection comment, and track comment as obtained from CDDB_File. Strings iC, iI are replaced by the CDDB and CDIndex ids as obtained from CDDB_File or Inf.
Strings ID3v1 and ID3v2 are replaced by the whole ID3v1/2 tag (interpolation of ID3v2 for an unmodified tag is subject to id3v2_recalculate configuration variable). (These may work as conditionals too, with :.)
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.
Several descriptors of the form FRAM(list,of,languages)[description]' discussed above may be combined together with &; the non-empty expansions are joined together with "; ". Example:
```
%{TXXX[pre-title]&TIT1&TIT2&TIT3&TXXX[post-title]}
```
dNUMBER is replaced by NUMBER-th component of the directory name (with 0 corresponding to the last component).
DNUMBER is replaced by the directory name with NUMBER components stripped.
UNUMBER is replaced by NUMBER-th component of the user scratch array.
If string starts with FNAME:: if frame FNAME does not exists, the escape is ignored; otherwise the rest of the string is reinterpreted.
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.
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||.
For strings of the form nmP[VALUE] or shP[VALUE], VALUE is interpolated, then normalized or shortened as a personal name (according to translate_person or short_person configuration setting).
composer or performer is replaced by the result of calling the corresponding method.
frames is replaced by space-separated list of "long names" of ID3v2 frames (see id3v2_frame_descriptors()). (To use a different separator, put it after slash, as in %{frames/, }, where separator is COMMA SPACE).
For strings of the form I(FLAGS)VALUE, VALUE is interpolated with flags in FLAGS (see "interpolate_with_flags"). If FLAGS does not contain i, VALUE should have {} and \ backwacked.
For strings of the form T[FORMAT], FORMAT is split on comma, and the resulting list of formats is used to convert the duration of the audio to a string using the method format_time().

The default for the fill character is SPACE. Fill character should preceed - if both are given. Example:

Title: %(/)-12.12t%{TIT3:; TIT3 is %\{TIT3\}}%{!TIT3:. No TIT3 is present}

will result in

Title: TITLE///////; TIT3 is Op. 16

if title is TITLE, and TIT3 is Op. 16, and

Title: TITLE///////. No TIT3 is present

if title is TITLE, but TIT3 is not present.

Fat content: %{COMM(eng,fra,fre,rus,)[FatContent]}

will print the comment field with Description FatContent prefering the description in English to one in French, Russian, or any other language (in this order). (I do not know which one of terminology/bibliography codes for French is used, so for safety include both.)

Composer: %{TCOM|a}

will use the ID3v2 field TCOM if present, otherwise uses %a (this is similar to

Composer: %{composer}

but the latter may be subject to (different) normalization, and/or configuration variables).

Interpolation of ID3v2 frames uses the minimal possible non-ambiguous backslashing rules: the only backslashes needed are to protect the innermost closing delimiter (] or }) appearing as a literal character, or to protect backslashes immediately preceeding such literal, or the closing delimiter. E.g., the pattern equal to

%{COMM(eng)[a\b\\c\}\]end\\\]\\\\]: comment `a\b\\c\\\}]end\]\\' present}

checks for the presence of comment with the descriptor a\b\\c\}]end\]\\. Note that if you want to write this string as a Perl literal, a lot of extra backslashes may be needed (unless you use <<'FOO' HERE-document).

%{T[?Hh,?{mL}m,{SML}s]}

for a file of duration 2345.62sec will result in 39m05.62s, while

%{T[?H:,?{mL}:,{SL},?{ML}]}sec

will result in 39:05.620sec.

interpolate_with_flags

@results = $mp3->interpolate_with_flags($pattern, $flags);

Processes $pattern according to directives in the string $flags; $flags is split into separate flag characters; the meanings (and order of application) of flags are

   i			interpolate via $mp3->interpolate
   f			interpret (the result) as filename, read from file
   F			if file does not exist, it is not an error
   B			read is performed in binary mode (otherwise
				in text mode, modified per
				'decode_encoding_files' configuration variable)
   l			split result per 'parse_split' configuration variable
   n			as l, using the track-number-th element (1-based)
				in the result
   I			interpolate (again) via $mp3->interpolate
   b			unless present, remove leading and trailing whitespace

With l, may produce multiple results.

parse_rex($pattern, $string)

Parse $string according to the regular expression $pattern with %-escapes %%, %a, %t, %l, %y, %g, %c, %n, %e, %E. The meaning of escapes is the same as for method "interpolate"(); but they are used not for expansion, but for matching a part of $string suitable to be a value for these fields. Returns false on failure, a hash reference with parsed fields otherwise.

Some more escapes are supported: %=a, %=t, %=l, %=y, %=g, %=c, %=n, %=e, %=E, %=A, %=B, %=D, %=f, %=F, %=N, %={WHATEVER} match substrings which are current values of artist/title/etc (%=n also matches leading 0s; actual file-name matches ignore the difference between / and \, between one and multiple consequent dots (if configuration variable parse_filename_merge_dots is true (default)) and are case-insensitive if configuration variable parse_filename_ignore_case is true (default); moreover, %n, %y, %=n, %=y will not match if the string-to-match is adjacent to a digit).

The escapes %{U<number>} and escapes of the forms %{ABCD}, %{ABCD<number>} match any string; the corresponding hash key in the result hash is what is inside braces; here ABCD is a 4-letter word possibly followed by 2-digit number (as in names of ID3v2 tags), or what can be put in '%{FRAM(lang,list)[description]}'.

  $res = $mp3->parse_rex( qr<^%a - %t\.\w{1,4}$>,
			  $mp3->filename_nodir ) or die;
  $author = $res->{author};

2-digit numbers, or number1/number2 with number1,2 up to 999 are allowed for the track number (the leading 0 is stripped); 4-digit years in the range 1000..2999 are allowed for year. Alternatively, if option year_is_timestamp is TRUE (default), year may be a range of timestamps in the format understood by ID3v2 method year() (see "year" in MP3::Tag::ID3v2).

Currently the regular expressions with capturing parens are not supported.

parse_rex_prepare($pattern)

Returns a data structure which later can be used by parse_rex_match(). These two are equivalent:

$mp3->parse_rex($pattern, $data);
$mp3->parse_rex_match($mp3->parse_rex_prepare($pattern), $data);

This call constitutes the "slow part" of the parse_rex() call; it makes sense to factor out this step if the parse_rex() with the same $pattern is called against multiple $data.

parse_rex_match($prepared, $data)

Matches $data against a data structure returned by parse_rex_prepare(). These two are equivalent:

$mp3->parse_rex($pattern, $data);
$mp3->parse_rex_match($mp3->parse_rex_prepare($pattern), $data);

parse($pattern, $string)

Parse $string according to the string $pattern with %-escapes %%, %a, %t, %l, %y, %g, %c, %n, %e, %E. The meaning of escapes is the same as for "interpolate". See "parse_rex($pattern, $string)" for more details. Returns false on failure, a hash reference with parsed fields otherwise.

$res = $mp3->parse("%a - %t.mp3", $mp3->filename_nodir) or die;
$author = $res->{author};

2-digit numbers are allowed for the track number; 4-digit years in the range 1000..2999 are allowed for year.

parse_prepare($pattern)

Returns a data structure which later can be used by parse_rex_match(). This is a counterpart of parse_rex_prepare() used with non-regular-expression patterns. These two are equivalent:

$mp3->parse($pattern, $data);
$mp3->parse_rex_match($mp3->parse_prepare($pattern), $data);

This call constitutes the "slow part" of the parse() call; it makes sense to factor out this step if the parse() with the same $pattern is called against multiple $data.

filename()

abs_filename()

filename_nodir()

filename_noextension()

filename_nodir_noextension()

abs_filename_noextension()

dirname([$strip_levels])

filename_extension()

filename_extension_nodot()

dir_component([$level])

$filename = $mp3->filename();
$abs_filename = $mp3->abs_filename();
$filename_nodir = $mp3->filename_nodir();
$abs_dirname = $mp3->dirname();
$abs_dirname = $mp3->dirname(0);
$abs_parentdir = $mp3->dirname(1);
$last_dir_component = $mp3->dir_component(0);

Return the name of the audio file: either as given to the new() method, or absolute, or directory-less, or originally given without extension, or directory-less without extension, or absolute without extension, or the directory part of the fullname only, or filename extension (with dot included, or not).

The extension is calculated using the config() value extension.

The dirname() method takes an optional argument: the number of directory components to strip; the dir_component($level) method returns one component of the directory (to get the last use 0 as $level; this is the default if no $level is specified).

The configuration option decode_encoding_filename can be used to specify the encoding of the filename; all these functions would use filename decoded from this encoding.

mpeg_version()

mpeg_layer()

mpeg_layer_roman()

is_stereo()

is_vbr()

bitrate_kbps()

frequency_Hz()

frequency_kHz()

size_bytes()

total_secs()

total_secs_int()

total_secs_trunc()

total_millisecs_int()

total_mins()

leftover_mins()

leftover_secs()

leftover_secs_float()

leftover_secs_trunc()

leftover_msec()

time_mm_ss()

is_copyrighted()

is_copyrighted_YN()

frames_padded()

frames_padded_YN()

channel_mode_int()

frames()

frame_len()

vbr_scale()

These methods return the information about the contents of the MP3 file. If this information is not cached in ID3v2 tags (not implemented yet), using these methods requires that the module MP3::Info is installed. Since these calls are redirectoed to the module MP3::Info, the returned info is subject to the same restrictions as the method get_mp3info() of this module; in particular, the information about the frame number and frame length is only approximate

vbr_scale() is from the VBR header; total_secs() is not necessarily an integer, but total_secs_int() and total_secs_trunc() are (first is rounded, second truncated); time_mm_ss() has format MM:SS; the *_YN flavors return the value as a string Yes or No; mpeg_layer_roman() returns the value as a roman numeral; channel_mode() takes values in 'stereo', 'joint stereo', 'dual channel', 'mono'.

format_time

$output = $mp3->format_time(67456.123, @format);

formats time according to @format, which should be a list of format descriptors. Each format descriptor is either a simple letter, or a string in braces appropriate to be put after % in an interpolated string. A format descriptor can be followed by a literal string to be put as a suffix, and can be preceeded by a question mark, which says that this part of format should be printed only if needed.

Leftover minutes, seconds are formated 0-padded to width 2 if they are preceeded by more coarse units. Similarly, leftover milliseconds are printed with leading dot, and 0-padded to width 3.

Two examples of useful @formats are

qw(?H: ?{mL}: {SML})
qw(?Hh ?{mL}m {SL} ?{ML})

Both will print hours, minutes, and milliseconds only if needed. The second one will use 3 digit-format after a point, the first one will not print the trailing 0s of milliseconds. The first one uses : as separator of hours and minutes, the second one will use h m.

update_tags( [ $data, [ $force2 ]] )

$mp3 = MP3::Tag->new($filename);
$mp3->update_tags();			# Fetches the info, and updates tags

$mp3->update_tags({});		# Updates tags if needed/changed

$mp3->update_tags({title => 'This is not a song'});	# Updates tags

This method updates ID3v1 and ID3v2 tags (the latter only if in-memory copy contains any data, or $data does not fit ID3v1 restrictions, or $force2 argument is given) with the the information about title, artist, album, year, comment, track, genre from the hash reference $data. The format of $data is the same as one returned from autoinfo() (with or without the optional argument 'from'). The fields which are marked as coming from ID3v1 or ID3v2 tags are not updated when written to the same tag.

If $data is not defined or missing, autoinfo('from') is called to obtain the data. Returns the object reference itself to simplify chaining of method calls.

This is probably the simplest way to set data in the tags: populate $data and call this method - no further tinkering with subtags is needed.

parse_cfg( [$filename] )

Reads configuration information from the specified file (defaults to the value of configuration variable local_cfg_file, which is ~-substituted). Empty lines and lines starting with # are ignored. The remaining lines should have format varname=value; leading and trailing whitespace is stripped; there may be several lines with the same varname; this sets list-valued variables.

ENVIRONMENT

Some defaults for the operation of this module (and/or scripts distributed with this module) are set from environment. Assumed encodings (0 or encoding name): for read access:

MP3TAG_DECODE_V1_DEFAULT		MP3TAG_DECODE_V2_DEFAULT
MP3TAG_DECODE_FILENAME_DEFAULT	MP3TAG_DECODE_FILES_DEFAULT
MP3TAG_DECODE_INF_DEFAULT		MP3TAG_DECODE_CDDB_FILE_DEFAULT

for write access:

MP3TAG_ENCODE_V1_DEFAULT		MP3TAG_ENCODE_FILES_DEFAULT

(if not set, default to corresponding DECODE options).

Defaults for the above:

MP3TAG_DECODE_DEFAULT			MP3TAG_ENCODE_DEFAULT

(if the second one is not set, the value of the first one is used). Value 0 for more specific variable will cancel the effect of the less specific variables.

These variables set default configuration settings for MP3::Tag; the values are read during the load time of the module. After load, one can use config()/get_config() methods to change/access these settings. See encode_encoding_* and encode_decoding_* in documentation of config method. (Note that FILES variant govern file read/written in non-binary mode by "ParseData" in MP3 module, as well as reading of control files of some scripts using this module, such as typeset_audio_dir.)

EXAMPLE

Assume that locally present CDDB files and .inf files are in encoding cp1251 (this is not supported by "standard", but since the standard supports only a handful of languages, this is widely used anyway), and that one wants ID3v1 fields to be in the same encoding, but ID3v2 have an honest (Unicode, if needed) encoding. Then set

MP3TAG_DECODE_INF_DEFAULT=cp1251
MP3TAG_DECODE_CDDB_FILE_DEFAULT=cp1251
MP3TAG_DECODE_V1_DEFAULT=cp1251

Since MP3TAG_DECODE_V1_DEFAULT implies MP3TAG_ENCODE_V1_DEFAULT, you will get the desired effect both for read and write of MP3 tags.

Additionally, the following (unsupported) variables are currently recognized by ID3v2 code:

MP3TAG_DECODE_UNICODE			MP3TAG_DECODE_UTF8

MP3TAG_DECODE_UNICODE (default 1) enables decoding; the target of decoding is determined by MP3TAG_DECODE_UTF8: if 0, decoded values are byte-encoded UTF-8 (every Perl character contains a byte of UTF-8 encoded string); otherwise (default) it is a native Perl Unicode string.

If MP3TAG_SKIP_LOCAL is true, local customization files are not loaded.

CUSTOMIZATION

Many aspects of operation of this module are subject to certain subtle choices. A lot of effort went into making these choices customizable, by setting global or per-object configuration variables.

A certain degree of customization of global configuration variables is available via the environment variables. Moreover, at startup the local customization file ~/.mp3tagprc is read, and defaults are set accordingly.

In addition, to make customization as flexible as possible, ALL aspects of operation of MP3::Tag are subject to local override. Three customization modules

MP3::Tag::User	MP3::Tag::Site		MP3::Tag::Vendor

are attempted to be loaded if present. Only the first module (of those present) is loaded directly; if sequential load is desirable, the first thing a customization module should do is to call

MP3::Tag->load_parents()

method.

The customization modules have an opportunity to change global configuration variables on load. To allow more flexibility, they may override any method defined in MP3::Tag; as usual, the overriden method may be called using SUPER modifier (see "Method invocation" in perlobj).

E.g., it is recommended to make a local customization file with

  eval 'require Music_Normalize_Fields';
  for my $elt ( qw( title track artist album comment year genre
		    title_track artist_collection person ) ) {
    no strict 'refs';
    MP3::Tag->config("translate_$elt", \&{"Music_Normalize_Fields::normalize_$elt"})
      if defined &{"Music_Normalize_Fields::normalize_$elt"};
  }
  MP3::Tag->config("short_person", \&Music_Normalize_Fields::short_person)
      if defined &Music_Normalize_Fields::short_person;

and install the (supplied, in the examples/modules) module Music_Normalize_Fields.pm which enables normalization of person names (to a long or a short form), and of music piece names to canonical forms.

To simplify debugging of local customization, it may be switched off completely by setting MP3TAG_SKIP_LOCAL to TRUE (in environment).

For example, putting

id3v23_unsync	= 0

into ~/.mp3tagprc will produce broken ID3v2 tags (but those required by ITunes).

EXAMPLE SCRIPTS

Some example scripts come with this module (either installed, or in directory examples in the distribution); they either use this module, or provide data understood by this module:

mp3info2

perform command line manipulation of audio tags (and more!);

audio_rename

rename audio files according to associated tags (and more!);

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

fulltoc_2fake_cddb

converts a CD's "full TOC" to a "fake" CDDB file (header only). Create this file with something like

readcd -fulltoc dev=0,1,0 -f=audio_cd >& nul

run similar to

fulltoc_2fake_cddb < audio_cd.toc | cddb2cddb > cddb.out

dir_mp3_2fake_cddb

tries to convert a directory of MP3 files to a "fake" CDDB file (header only); assumes that files are a rip from a CD, and that alphabetical sort gives the track order (works only heuristically, since quantization of duration of MP3 files and of CD tracks is so different).

Run similar to

dir_mp3_2fake_cddb | cddb2cddb > cddb.out

inf_2fake_cddb

tries to convert a directory of .inf files to a "fake" CDDB file (header only). (Still heuristic, since it can't guess the length of the leader.)

Run similar to

inf_2fake_cddb | cddb2cddb > cddb.out

cddb2cddb

Reads a (header of) CDDB file from STDIN, outputs (on STDOUT) the current version of the database record. Can be used to update a file, and/or to convert a fake CDDB file to a real one.

(Last four 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 method performer() (and 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).

FILES

There are many files with special meaning to this module and its dependent modules.

*.inf

Files with extension .inf and the same basename as the audio file are read by module MP3::Tag::Inf, and the extracted data is merged into the information flow according to configuration variable autoinfo.

It is assumed that these files are compatible in format to the files written by the program cdda2wav.

audio.cddb cddb.out cddb.in

in the same directory as the audio file are read by module MP3::Tag::CDDB_File, and the extracted data is merged into the information flow according to configuration variable autoinfo.

(In fact, the list may be customized by configuration variable cddb_files.)

audio_cd.toc

in the same directory as the audio file may be read by the method id3v2_frames_autofill() (should be called explicitly) to fill the TXXX[MCDI-fulltoc] frame. Depends on contents of configuration variable id3v2_frames_autofill.

~/.mp3tagprc

By default, this file is read on startup (may be customized by overriding the method parse_cfg()). By default, the name of the file is in the configuration variable local_cfg_file.

COPYRIGHT

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

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 930:

Expected text after =item, not a bullet

Around line 2708:

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

ENVIRONMENT

CUSTOMIZATION

EXAMPLE SCRIPTS

Problems with ID3 format

FILES

SEE ALSO

COPYRIGHT

Module Install Instructions