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

AUTHOR

Thomas Geffert, thg@users.sourceforge.net

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 C<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 L<MP3::Tag::ParseData> handler; each option is an array
reference of the form C<[$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 C<n> or C<l> flags.

* parse_filename_ignore_case

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

* parse_filename_merge_dots

If true (default), calling parse() and parse_rex() with match-filename
escapes (such as C<%=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 C<'; '>.  E.g., parsing C<'1988-1992, Homer (LP)'> with pattern
C<'%c, %a (%c)'> results in comment set to C<'1988-1992; LP'> with the
default value of C<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 C<%y>;
for example, C<2001-10-23--30,2002-02-28> is a range from 23rd to 30th of
October 2001, I<and> 28th of February of 2002.  According to ISO, C<--> can
be replaced by C</> 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., C<Recorded on 2014-3-23>) if TRUE.
Current default: FALSE.

* translate_*

A subroutine used to munch a field C<*> (out of C<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 C<[value, handler]>, where C<handler>
is the string indentifying the handler which returned the value.

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

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

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

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

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

• Strings aC, tT, cC, cT are replaced for collection artist, track title, collection comment, and track comment as obtained from CDDB_File.

  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.

  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 interpolate. Also supported are escapes %=a, %=t, %=l, %=y, %=g, %=c, %=n, %=e, %=E, %=A, %=B, %=D, %=f, %=F, %=N, %={WHATEVER}; they match substrings which are actual 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). Returns false on failure, a hash reference with parsed fields otherwise; the escape %{U<number>} matches any string, and corresponds to the hash key U<numbergt.

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

  2-digit numbers 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. 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).

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

  leftover_secs()

  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. Useing 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() is; 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'.

SEE ALSO

MP3::Tag::ID3v1, MP3::Tag::ID3v2, MP3::Tag::File, MP3::Tag::ParseData, MP3::Tag::Inf, MP3::Tag::CDDB_File.

COPYRIGHT

Copyright (c) 2000-2004 Thomas Geffert. All rights reserved.

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