MP3::Tag(3pm) | User Contributed Perl Documentation | MP3::Tag(3pm) |
MP3::Tag - Module for reading tags of MP3 audio files
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(); # Or: $comment = $mp3->comment(); $dedicated_to = $mp3->select_id3v2_frame_by_descr('COMM(fre,fra,eng,#0)[dedicated to]'); $mp3->title_set('New title'); # Edit in-memory copy $mp3->select_id3v2_frame_by_descr('TALB', 'New album name'); # Edit in memory $mp3->select_id3v2_frame_by_descr('RBUF', $n1, $n2, $n3); # Edit in memory $mp3->update_tags({year => 1866}); # Edit in-memory, and commit to file $mp3->update_tags(); # Commit to file
The following low-level access code is discouraged; better use title() etc., title_set() etc., update_tags(), select_id3v2_frame_by_descr() etc. methods on the wrapper $mp3:
# 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();
Please consider using the script mp3info2; it allows simple access to most features of this module via command-line options; see mp3info2.
Thomas Geffert, thg@users.sourceforge.net Ilya Zakharevich, ilyaz@cpan.org
"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).
$mp3 = MP3::Tag->new($filename);
Creates a mp3-object, which can be used to retrieve/set different 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, MP3::Tag::Cue to see what you can do with the tags.
$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.
[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}.
$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.
$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;
($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 = $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 = $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.
$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.
$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 = $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 = $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.
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:
$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.
The second argument may also have the form "[value, handler]", where "handler" is the string indentifying the handler which returned the value.
(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...)
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).
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".
[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.]
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".
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]".
$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.)
$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 = $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}").
$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.
$data = $mp3->get_user($n); # n-th piece of user scratch space
Queries an entry in a scratch array ($n=3 corresponds to "%{U3}").
$mp3->set_user($n, $data); # n-th piece of user scratch space
Sets an entry in a scratch array ($n=3 corresponds to "%{U3}").
$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.)
($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.
$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.
$frame = $mp3->is_id3v2_modified();
Returns TRUE if ID3v2 tag exists and was modified after creation.
$frame = $mp3->select_id3v2_frame($fname, $descrs, $langs [, $VALUE]);
Returns the specified frame(s); has the same API as "frame_select" in MP3::Tag::ID3v2 (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_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).
$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.
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 "get_frame_ids()" in MP3::Tag::ID3v2).
$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 "frame_select" in MP3::Tag::ID3v2.
$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).
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.
$format = $id3->_Data_to_MIME($data);
Currently, only the first 4 bytes of the string are inspected.
$string = $mp3->shorten_person($person_name);
shorten $person_name as a personal name (according to "short_person" configuration setting).
$string = $mp3->normalize_person($person_name);
normalize $person_name as a personal name (according to "translate_person" configuration setting).
$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.
$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:
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.
%{TXXX[pre-title]&TIT1&TIT2&TIT3&TXXX[post-title]}
$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.
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".
@results = $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}".
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 "year" in MP3::Tag::ID3v2).
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.
$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.
$mp3->parse_rex($pattern, $data); $mp3->parse_rex_match($mp3->parse_rex_prepare($pattern), $data);
$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.
$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 = $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.
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'.
$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 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 @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".
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 @formats above, but would print as 2 if rounded to seconds.)
$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.
$mp3->extension_is(@EXT_LIST)
returns TRUE if the extension of the filename coincides (case-insensitive) with one of the elements of the list.
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 MP3TAG_DECODE_CUE_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.
If the "LANG" environment variable indicates "UTF-8" encoding, then the ""FILES"" flavors default to "utf8" (unless this effect is already achieved by the "${^UNICODE}" variable). This may be disabled by setting "MP3TAG_DECODE_FILES_DEFAULT_RESET" true in the environment (likewise for "EN"-code flavor).
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.)
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.
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 overridden 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 Normalize::Text::Music_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", \&{"Normalize::Text::Music_Fields::normalize_$elt"}) if defined &{"Normalize::Text::Music_Fields::normalize_$elt"}; } MP3::Tag->config("short_person", \&Normalize::Text::Music_Fields::short_person) if defined &Normalize::Text::Music_Fields::short_person;
and install the (supplied, in the examples/modules) module Normalize::Text::Music_Fields 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).
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:
readcd -fulltoc dev=0,1,0 -f=audio_cd >& nul
run similar to
fulltoc_2fake_cddb < audio_cd.toc | cddb2cddb > cddb.out
Run similar to
dir_mp3_2fake_cddb | cddb2cddb > cddb.out
Run similar to
inf_2fake_cddb | cddb2cddb > cddb.out
(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
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"). (Since the upgrade [or a chain of upgrades] from the "ID3v1" tag to the "ID3v2" tag can result in any encoding of the "supposedly "iso-8859-1"" tag, one cannot trust the content of "ID3v2" tag even if it stored as Unicode strings.)
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 this propagation is in a form which is quite hard to undo (but still possible to do with suitable settings to this module; see "Examples on dealing with broken encodings" in mp3info2).
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., the 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).
There are many files with special meaning to this module and its dependent modules.
It is assumed that these files are compatible in format to the files written by the program cdda2wav.
(In fact, the list may be customized by configuration variable "cddb_files".)
MP3::Tag::ID3v1, MP3::Tag::ID3v2, MP3::Tag::File, MP3::Tag::ParseData, MP3::Tag::Inf, MP3::Tag::CDDB_File, MP3::Tag::Cue, MP3::Tag::ImageExifTool, MP3::Tag::ImageSize, MP3::Tag::LastResort, mp3info2, typeset_audio_dir.
Copyright (c) 2000-2016 Thomas Geffert, Ilya Zakharevich. 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.
Hey! The above document had some coding errors, which are explained below:
2022-12-30 | perl v5.36.0 |