Provided by: libmp3-tag-perl_1.16-1_all bug

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

AUTHORS

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

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]

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

       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 absence 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, @values);

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

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

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

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

           $tag should be either "ID3v1" or "ID3v2".  Deletes the tag if it is present.  Returns
           FALSE if the tag is not present.

       is_id3v2_modified
             $frame = $mp3->is_id3v2_modified();

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

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

           Returns the specified frame(s); has the same API as "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_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 "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.

       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
               absence 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
             @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}".

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

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

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

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

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

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

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

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

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

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

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

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

       filename()
       abs_filename()
       filename_nodir()
       filename_noextension()
       filename_nodir_noextension()
       abs_filename_noextension()
       dirname([$strip_levels])
       filename_extension()
       filename_extension_nodot()
       dir_component([$level])
             $filename = $mp3->filename();
             $abs_filename = $mp3->abs_filename();
             $filename_nodir = $mp3->filename_nodir();
             $abs_dirname = $mp3->dirname();
             $abs_dirname = $mp3->dirname(0);
             $abs_parentdir = $mp3->dirname(1);
             $last_dir_component = $mp3->dir_component(0);

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

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

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

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

       mpeg_version()
       mpeg_layer()
       mpeg_layer_roman()
       is_stereo()
       is_vbr()
       bitrate_kbps()
       frequency_Hz()
       frequency_kHz()
       size_bytes()
       total_secs()
       total_secs_int()
       total_secs_trunc()
       total_millisecs_int()
       total_mins()
       leftover_mins()
       leftover_secs()
       leftover_secs_float()
       leftover_secs_trunc()
       leftover_msec()
       time_mm_ss()
       is_copyrighted()
       is_copyrighted_YN()
       frames_padded()
       frames_padded_YN()
       channel_mode_int()
       frames()
       frame_len()
       vbr_scale()
           These methods return the information about the contents of the MP3 file.  If this
           information is not cached in ID3v2 tags (not implemented yet), using these methods
           requires that the module MP3::Info is installed.  Since these calls are redirectoed to
           the module MP3::Info, the returned info is subject to the same restrictions as the
           method get_mp3info() of this module; in particular, the information about the frame
           number and frame length is only approximate.

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

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

           formats time according to @format, which should be a list of format descriptors.  Each
           format descriptor is either a simple letter, or a string in braces appropriate to be
           put after "%" in an interpolated string.  A format descriptor can be followed by a
           literal string to be put as a suffix, and can be 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.)

       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(@EXT_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.

ENVIRONMENT

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

         MP3TAG_DECODE_V1_DEFAULT              MP3TAG_DECODE_V2_DEFAULT
         MP3TAG_DECODE_FILENAME_DEFAULT        MP3TAG_DECODE_FILES_DEFAULT
         MP3TAG_DECODE_INF_DEFAULT             MP3TAG_DECODE_CDDB_FILE_DEFAULT
         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.)

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

              MP3TAG_DECODE_INF_DEFAULT=cp1251
              MP3TAG_DECODE_CDDB_FILE_DEFAULT=cp1251
              MP3TAG_DECODE_V1_DEFAULT=cp1251

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

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

         MP3TAG_DECODE_UNICODE                 MP3TAG_DECODE_UTF8

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

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

CUSTOMIZATION

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

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

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

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

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

         MP3::Tag->load_parents()

       method.

       The customization modules have an opportunity to change global configuration variables on
       load.  To allow more flexibility, they may override any method defined in "MP3::Tag"; as
       usual, the 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).

EXAMPLE SCRIPTS

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

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

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

       typeset_mp3_dir
           write LaTeX files suitable for CD covers and normal-size sheet descriptions of
           hierarchy of audio files;

       mp3_total_time
           Calculate total duration of audio files;

       eat_wav_mp3_header
           remove WAV headers from MP3 files in WAV containers.

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

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

           run similar to

             fulltoc_2fake_cddb < audio_cd.toc | cddb2cddb > cddb.out

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

           Run similar to

             dir_mp3_2fake_cddb | cddb2cddb > cddb.out

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

           Run similar to

             inf_2fake_cddb | cddb2cddb > cddb.out

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

       (Last four do not use these modules!)

       Some more examples:

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

Problems with ID3 format

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

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

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

FILES

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

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

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

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

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

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

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

SEE ALSO

       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

       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.

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 1192:
           Expected text after =item, not a bullet