Description :
\'MP3::Tag\' is a wrapper module to read different tags of mp3 files. It
provides an easy way to access the functions of separate 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::ImageExifTool, MP3::Tag::Inf, MP3::Tag::CDDB_File,
MP3::Tag::File, MP3::Tag::Cue, MP3::Tag::ImageSize, MP3::Tag::LastResort
are supported for read access (the information obtained by Image::ExifTool
(if present), parsing CDDB files, _.inf_ file, the filename, and _.cue_
file, and obtained via Image::Size) (if present).
* 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]
AATTtags = $mp3->get_tags;
Checks which tags can be found in the mp3-object. It returns a list AATTtags
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, MP3::Tag::Cue 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 \'Cue\' 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\'.
* title_set(), artist_set(), album_set(), year_set(), comment_set(),
track_set(), genre_set()
$mp3->title_set($newtitle, [$force_id3v2]);
Set the corresponding value in ID3v1 tag, and, if the value does not fit,
or force_id3v2 is TRUE, in the ID3v2 tag. Changes are made to in-memory
copy only. To propagate to the file, use update_tags() or similar methods.
* track1()
Same as track(), but strips trailing info: if track() returns \'3/12\' (which
means track 3 of 12), this method returns \'3\'.
* track2()
Returns the second part of track number (compare with track1()).
* track0()
Same as track1(), but pads with leading 0s to width of track2(); takes an
optional argument (default is 2) giving the pad width in absense of
track2().
* disk1(), disk2()
Same as track1(), track2(), but with disk-number instead of track-number
(stored in \'TPOS\' ID3v2 frame).
* disk_alphanum()
Same as disk1(), but encodes a non-empty result as a letter (1 maps to \'a\',
2 to \'b\', etc). If number of disks is more than 26, falls back to numeric
(e.g, \'3/888\' will be encoded as \'003\').
* mime_type( [$lazy] )
Returns the MIME type as a string. Returns \'application/octet-stream\' for
unrecognized types. If not $lazy, will try harder (via ExifTool, if
needed).
* mime_Pretype( [$lazy] )
Returns uppercased first component of MIME type.
* 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. The default is \'ParseData, ID3v2, ID3v1, ImageExifTool,
CDDB_File, Inf, Cue, ImageSize, filename, LastResort\'. Options can be
elements of the default list. 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 the same as for
\'autoinfo\'. 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
Old experimental flag to test why ITunes refuses to handle unsyncronized
tags (does not help, see id3v23_unsync). The idea was that version 2.3 of
the standard is not clear about frame size field, whether it is the size of
the frame after unsyncronization, or not. We assume that this size is one
before unsyncronization (as in v2.2). Setting this value to 1 will assume
another interpretation (as in v2.4) for write.
* id3v23_unsync
Some broken MP3 players (e.g., ITunes, at least up to v6) refuse to handle
unsyncronized (i.e., written as the standard requires it) tags; they may
need this to be set to FALSE. Default: TRUE.
(Some details: by definition, MP3 files should contain combinations of
bytes \'FF F*\' or \'FF E*\' only at the start of audio frames
(\"syncronization\" points). ID3v2 standards take this into account, and
supports storing raw tag data in a format which does not contain these
combinations of bytes [via \"unsyncronization\"]. Itunes etc do not only emit
broken MP3 files [which cause severe hiccups in players which do not know
how to skip ID3v2 tags, as most settop DVD players], they also refuse to
read ID3v2 tags written in a correct, unsyncronized, format.)
(Note also that the issue of syncronization is also applicable to ID3v1
tags; however, since this data is near the end of the file, many players
are able to recognize that the syncronization points in ID3v1 tag cannot
start a valid frame, since there is not enough data to read; some other
players would hiccup anyway if ID3v1 contains these combinations of
bytes...)
* encoded_v1_fits
If FALSE (default), data containing \"high bit characters\" is considered to
not fit ID3v1 tag if one of the following conditions hold:
* 1.
\'encode_encoding_v1\' is set (so the resulting ID3v1 tag is not
standard-complying, thus ambiguous without ID3v2), or
* 2.
\'encode_encoding_v1\' is not set, but \'decode_encoding_v1\' is set (thus
read+write operation is not idempotent for ID3v1 tag).
With the default setting, these problems are resolved as far as
(re)encoding of ID3v2 tag is non-ambiguous (which holds with the default
settings for ID3v2 encodeing).
* decode_encoding_v1
* encode_encoding_v1
* decode_encoding_v2
* decode_encoding_filename
* decode_encoding_inf
* decode_encoding_cddb_file
* decode_encoding_cue
* decode_encoding_files
* encode_encoding_files
Encodings of \'ID3v1\', non-Unicode frames of \'ID3v2\', filenames, external
files, _.inf_ files, \'CDDB\' files, _.cue_ files, and user-specified 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. One should
also keep in mind that the ID3v1 standard requires the encoding to be
\"latin1\" (so does not store the encoding anywhere); this does not make a
lot of sense, and a lot of effort of this module is spend to fix this
unfortunate flaw. See \"Problems with ID3 format\".
* 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).
* name_for_field_normalization
interpolation of this string is used as a person name to normalize
title-like fields. Defaults to \'%{composer}\'.
* extra_config_keys
List of extra config keys (default is empty); setting these would not cause
warnings, and would not affect operation of \'MP3::Tag\'. Applications using
this module may add to this list to allow their configuration by the same
means as configuration of \'MP3::Tag\'.
* is_writable
Contains a boolean value, or a method name and argument list to call
whether the tag may be added to the file. Defaults to
writable_by_extension().
* writable_extensions
Contains a list of extensions (case insensitive) for which the tag may be
added to the file. Current default is \'mp3 mp2 id3 tag ogg mpg mpeg mp4
aiff flac ape ram mpc\' (extracted from ExifTool docs; may be tuned later).
* 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.
* name_for_field_normalization
$name = $mp3->name_for_field_normalization;
Returns \"person name\" to use for normalization of title-like fields; it is
the result of interpolation of the configuration variable
\'name_for_field_normalization\' (defaults to \'%{composer}\' - which, by
default, expands the same as \'%{TCOM|a}\').
* 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, AATTvalues);
When called with only $name as the argument, removes the specified frame
(if it existed). Otherwise sets the frame passing the specified AATTvalues to
the add_frame() function of MP3::Tag::ID3v2. (The old value is removed.)
* get_id3v2_frames
($descr, AATTframes) = $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 the frame name, the list of wanted
Descriptors, list of wanted Languages, and possibly the new contents - with
\'undef\' meaning deletion). For read-only access it returns empty if no
ID3v2 tag is present, or no frame is found.
If new contents 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. The semantic is similar to
MP3::Tag::ID3v2::frame_select_by_descr_simpler.
It is allowed to have \'NAME\' of the form \'FRAMnn\'; \'nn\'-th frame with name
\'FRAM\' is chosen (\'-1\'-based: the first frame is \'FRAM\', the second
\'FRAM00\', the third \'FRAM01\' etc; for more user-friendly scheme, use
\'langs\' of the form \'#NNN\', with \'NNN\' 0-based; see
MP3::Tag::ID3v2/\"get_frame_ids()\").
$frame = $mp3->select_id3v2_frame_by_descr($descr [, $VALUE1, ...]);
$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\'.
$c = $mp3->select_id3v2_frame_by_descr(\"COMM(fre,fra,eng,#0)[]\");
$t = $mp3->select_id3v2_frame_by_descr(\"TIT2\");
$mp3->select_id3v2_frame_by_descr(\"TIT2\", \"MyT\"); # Set/Change
$mp3->select_id3v2_frame_by_descr(\"RBUF\", $n1, $n2, $n3); # Set/Change
$mp3->select_id3v2_frame_by_descr(\"RBUF\", \"$n1;$n2;$n3\"); # Set/Change
$mp3->select_id3v2_frame_by_descr(\"TIT2\", undef); # Remove
Remember that when select_id3v2_frame_by_descr() is used for modification,
*ALL* found frames are deleted before a new one is added. For gory details,
see MP3::Tag::ID3v2/frame_select.
* 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.
* copy_id3v2_frames($from, $to, $overwrite, [$keep_flags, $f_ids])
Copies specified frames between \'MP3::Tag\' objects $from, $to. Unless
$keep_flags, the copied frames have their flags cleared. If the array
reference $f_ids is not specified, all the frames (but \'GRID\' and \'TLEN\')
are considered (subject to $overwrite), otherwise $f_ids should contain
short frame ids to consider. Group ID flag is always cleared.
If $overwrite is \'\'delete\'\', frames with the same descriptors (as returned
by get_frame_descr()) in $to are deleted first, then all the specified
frames are copied. If $overwrite is FALSE, only frames with descriptors not
present in $to are copied. (If one of these two conditions is not met, the
result may be not conformant to standards.)
Returns count of copied frames.
* _Data_to_MIME
Internal method to extract MIME type from a string the image file content.
Returns \'application/octet-stream\' for unrecognized data (unless extra TRUE
argument is given).
$format = $id3->_Data_to_MIME($data);
Currently, only the first 4 bytes of the string are inspected.
* 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 short 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
h height (these 3 for image files, Image::Size or Image::ExifData required)
w width
iT img_type
mT mime_type
mP mime_Pretype (the capitalized first part of mime_type)
aR aspect_ratio (width/height)
a3 aspect_ratio3 (3 decimal places after the dot)
aI aspect_ratio_inverted (height/width)
bD bit_depth
aC collection artist (from CDDB_File)
tT track title (from CDDB_File)
cC collection comment (from CDDB_File)
cT track comment (from CDDB_File)
iC CDDB id
iI CDIndex id
(Multi-char escapes must be inclosed in braces, as in \'%{SML}\' or
\'%.5{aR}\'.
Additional multi-char escapes are interpretated is follows:
* Names of ID3v2 frames are replaced by their text values (empty for missing
frames).
* Strings \'n1\' and \'n2\' are replaced by \"pure track number\" and \"max track
number\" (this allows for both formats \'N1\' and \'N1/N2\' of \"track\", the
latter meaning track N1 of N2); use \'n0\' to pad \'n1\' with leading 0 to the
width of \'n2\' (in absense of n2, to 2). Likewise for \'m1\', \'m2\' but with
disk (media) number instead of track number; use \'mA\' to encode \'m1\' as a
letter (see disk_alphanum()).
* 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 the value of configuration variable
\'ampersand_joiner\' (default \'\"; \"\'). Example:
%{TXXX[pre-title]&TIT1&TIT2&TIT3&TXXX[post-title]}
* Strings of the form \'method(list,of,packages)[arg1][arg2]\' are replaced by
the result of \'method\' (with the given arguments) in one of the specified
known subpackages (e.g., for \'Inf\', \'MP3::Tag::Inf\' is used). Arbitrary
number of arguments is supported. Instead of a long name \'method\' one can
use its standard shortcut (e.g., \'t\' for \'title\'). For example,
$mp3->interpolate(\'%{t(ID3v1,Cue)}\')
returns the title from the ID3v1 tag, or (if not there) from a cue sheet.
One can use this in conditionals etc as well.
* \'d\'_NUMBER_ is replaced by _NUMBER_-th component of the directory name
(with 0 corresponding to the last component).
* \'D\'_NUMBER_ is replaced by the directory name with NUMBER components
stripped.
* \'U\'_NUMBER_ 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. Same applies to non-time related 2-char
escapes and user variables.
* 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).
* \'_out_frames[QQPRE//QQPOST]\' is replaced by a verbose listing of frames.
\"simple\" frames are output one-per-line (with the value surrounded by
\'QQPRE\' and \'QQPOST\'); fields of other frames are output one-per-line. If
one omits the leading \'_\', then \'__binary_DATA__\' replaces the value of
binary fields.
* \'ID3v2-size\', \'ID3v2-pad\', and \'ID3v2-stripped\' are replaced by size of
ID3v2 tag in bytes, the amount of 0-padding at the end of the tag (not
counting one extra 0 byte at the end of tag which may be needed for
unsyncing if the last char is \\xFF), and size without padding. Currently,
for modified ID3v2 tag, what is returned reflect the size on disk (i.e.,
before modification).
* \'ID3v2-modified\' is replaced by \'\'modified\'\' if ID3v2 is present and is
modified in memory; otherwise is replaced by an empty string.
* 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(). (E.g., \'%{T[=>m,?H:,{mL}]}\' would
print duration in (optional) hours and minutes rounded to the closest
minute.)
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_ preceding 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
AATTresults = $mp3->interpolate_with_flags($text, $flags);
Processes $text 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. May be accessed via interpolation
of \'%{I(flags)text}\'.
* parse_rex($pattern, $string)
Parse $string according to the regular expression $pattern with \'%\'-escapes
\'%, %a, %t, %l, %y, %g, %c, %n, %e, %E\' etc. The meaning of escapes is the
same as for method \"interpolate\"(); but (with the exception of \'%\') 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 (with \'%a\' setting the field \'author\', etc).
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). Double \'=\' if you want to match to fail when the
corresponding conditional \'%\'-escape would fail (a missing field, or a
zero-length field for required fields).
The escapes \'%{U< number>}\' and escapes of the forms \'%{ABCD}\' 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 MP3::Tag::ID3v2/\"year\").
The escape \'%E\' matches the REx in the configuration variable \'extension\';
the escape \'%e\' matches the part of %E after the leading dot.
In list context, also returns an array reference with %{handler} groups
parsed (if present). Such groups can match everything, and a successful
match gives an array element with \'[$method, $packages, $args, $matched]\'.
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, AATTformat);
formats time according to AATTformat, 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 preceded 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
preceded by more coarse units. Similarly, leftover milliseconds are printed
with leading dot, and 0-padded to width 3.
Two examples of useful \'AATTformat\'s 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\'.
Optionally, the first element of the array may be of the form \'=>U\', here
\'U\' is one of \'h m s\'. In this case, duration is rounded to closest hours,
min or second before processing. (E.g., 1.7sec would print as \'1\' with
\'AATTformat\'s above, but would print as \'2\' if rounded to seconds.)
* can_write()
checks permission to write per the configuration variable \'is_writable\'.
* can_write_or_die($mess)
as can_write(), but die()s on non-writable files with meaningful error
message ($mess is prepended to the message).
* die_cant_write($mess)
die() with the same message as can_write_or_die().
* writable_by_extension()
Checks that extension is (case-insensitively) in the list given by
configuration variable \'writable_extensions\'.
* 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.
* extension_is
$mp3->extension_is(AATTEXT_LIST)
returns TRUE if the extension of the filename coincides (case-insensitive)
with one of the elements of the list.
* \'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.
|
