MP3::Tag::ID3v2 - Read / Write ID3v2.x.y tags from mp3 audio files

MP3::Tag::ID3v2 supports * Reading of ID3v2.2.0 and ID3v2.3.0 tags * Writing of ID3v2.3.0 tags

MP3::Tag::ID3v2 is designed to be called from the MP3::Tag module.

  use MP3::Tag;
  $mp3 = MP3::Tag->new($filename);

  # read an existing tag
  $mp3->get_tags();
  $id3v2 = $mp3->{ID3v2} if exists $mp3->{ID3v2};

  # or create a new tag
  $id3v2 = $mp3->new_tag("ID3v2");

See MP3::Tag for information on the above used functions.

* Reading a tag

  $frameIDs_hash = $id3v2->get_frame_ids('truename');

  foreach my $frame (keys %$frameIDs_hash) {
      my ($name, @info) = $id3v2->get_frame($frame);
      for my $info (@info) {  
          if (ref $info) {
              print "$name ($frame):\n";
              while(my ($key,$val)=each %$info) {
                  print " * $key => $val\n";
             }
          } else {
              print "$name: $info\n";
          }
      }
  }

* Adding / Changing / Removing / Writing a tag

  $id3v2->add_frame("TIT2", "Title of the song");
  $id3v2->change_frame("TALB","Greatest Album");
  $id3v2->remove_frame("TLAN");
  $id3v2->write_tag();

* Removing the whole tag

  $id3v2->remove_tag();

* Get information about supported frames

  %tags = $id3v2->supported_frames();
  while (($fname, $longname) = each %tags) {
      print "$fname $longname: ", 
            join(", ", @{$id3v2->what_data($fname)}), "\n";
  }

Thomas Geffert, thg@users.sourceforge.net

get_frame_ids()

  $frameIDs = $tag->get_frame_ids;
  $frameIDs = $tag->get_frame_ids('truename');

  [old name: getFrameIDs() . The old name is still available, but you should use the new name]

get_frame_ids loops through all frames, which exist in the tag. It returns a hash reference with a list of all available Frame IDs. The keys of the returned hash are 4-character-codes (short names), the internal names of the frames, the according value is the english (long) name of the frame. You can use this list to iterate over all frames to get their data, or to check if a specific frame is included in the tag. If there are multiple occurences of a frame in one tag, the first frame is returned with its normal short name, following frames of this type get a '00', '01', '02', ... appended to this name. These names can then used with CWget_frame to get the information of these frames. These fake frames are not returned if CW'truename' argument is set; one can still use CWget_frames() to extract the info for all of the frames with the given short name.

get_frame()

  ($info, $name, @rest) = $tag->get_frame($ID);
  ($info, $name, @rest) = $tag->get_frame($ID, 'raw');

  [old name: getFrame() . The old name is still available, but you should use the new name]

get_frame gets the contents of a specific frame, which must be specified by the 4-character-ID (aka short name). You can use CWget_frame_ids to get the IDs of the tag, or use IDs which you hope to find in the tag. If the ID is not found, CWget_frame returns empty list, so CW$info and CW$name become undefined. Otherwise it extracts the contents of the frame. Frames in ID3v2 tags can be very small, or complex and huge. That is the reason, that CWget_frame returns the frame data in two ways, depending on the tag. If it is a simple tag, with only one piece of data, this date is returned directly as ($info, CW$name), where CW$info is the text string, and CW$name is the long (english) name of the frame. If the frame consist of different pieces of data, CW$info is a hash reference, CW$name is again the long name of the frame. The hash, to which CW$info points, contains key/value pairs, where the key is always the name of the data, and the value is the data itself. If the name starts with a underscore (as eg '_code'), the data is probably binary data and not printable. If the name starts without an underscore, it should be a text string and printable. If the second parameter 'raw' is given, the whole frame data is returned, but not the frame header. If the second parameter is 'intact', no mangling of embedded CW"\0" and trailing spaces is performed. If the data was stored compressed, it is uncompressed before it is returned (even in raw mode). Then CW$info contains a string with all data (which might be binary), and CW$name the long frame name. See also MP3::Tag::ID3v2-Data for a list of all supported frames, and some other explanations of the returned data structure. If more than one frame with name CW$ID is present, CW@rest contains CW$info fields for all consequent frames with the same name. Note that after removal of frames there may be holes in the list of frame names (as in CWFRAM FRAM01 FRAM02) in the case when multiple frames of the given type were present; the removed frames are returned as CWundef. ! Encrypted frames are not supported yet ! ! Some frames are not supported yet, but the most common ones are supported !

get_frame_option()

  $options = get_frame_option($ID);

  Option is a hash reference, the hash contains all possible options.
  The value for each option is 0 or 1.

  groupid    -- not supported yet
  encryption -- not supported yet
  compression -- Compresses frame before writing tag; 
                 compression/uncompression is done automatically
  read_only   -- Ignored by this library, should be obeyed by application
  file_preserv -- Ignored by this library, should be obeyed by application
  tag_preserv -- Ignored by this library, should be obeyed by application

set_frame_option()

  $options = set_frame_option($ID, $option, $value);

  Set $option to $value (0 or 1). If successfull the new set of
  options is returned, undef otherwise.

  groupid    -- not supported yet
  encryption -- not supported yet
  compression -- Compresses frame before writing tag; 
                 compression/uncompression is done automatically
  read_only   -- Ignored by this library, should be obeyed by application
  file_preserv -- Ignored by this library, should be obeyed by application
  tag_preserv -- Ignored by this library, should be obeyed by application

get_frames()

  ($name, @info) = get_frames($ID);
  ($name, @info) = get_frames($ID, 'raw');

Same as get_frame() with different order of the returned values. CW$name and elements of the array CW@info have the same semantic as for get_frame(); each frame with id CW$ID produces one elements of array CW@info.

as_bin()

  $tag2 = $id3v2->as_bin($ignore_error, $update_file);

Returns the the current content of the ID3v2 tag as a string good to write to a file; it contains all the necessary footers and headers. If CW$ignore_error is TRUE, the frames the module does not know how to write are skipped; otherwise it is an error to have such a frame. Returns undef on error. If the optional argument CW$update_file is TRUE, an additional action is performed: if the audio file does not contain an ID3v2 tag, or the tag in the file is smaller than the built ID3v2 tag, the necessary 0-padding is inserted before the audio content of the file so that it is able to accomodate the build tag (and the CWtagsize field of CW$id3v2 is updated correspondingly); in any case the header length of CW$tag2 is set to reflect the space in the beginning of the audio file. Keep in mind that the actual length of the string CW$tag2 is not modified, so if it is smaller than the reserved place in the file, one needs to add some 0 padding at the end.

write_tag()

  $id3v2->write_tag($ignore_error);

Saves all frames to the file. It tries to update the file in place, when the space of the old tag is big enough for the new tag. Otherwise it creates a temp file with a new tag (i.e. copies the whole mp3 file) and renames/moves it to the original file name. An extended header with CRC checksum is not supported yet. Encryption of frames and group ids are not supported. If CW$ignore_error is set, these options are ignored and the frames are saved without these options. If CW$ignore_error is not set and a tag with an unsupported option should be save, the tag is not written and a 0 is returned. If a tag with an encrypted frame is read, and the frame is not changed it can be saved encrypted again. ID3v2.2 tags are converted automatically to ID3v2.3 tags during writing. If a frame cannot be converted automatically (PIC; CMR), writing aborts and returns a 0. If CW$ignore_error is true, only not convertable frames are ignored and not written, but the rest of the tag is saved as ID3v2.3. At the moment the tag is automatically unsynchronized. If the tag is written successfully, 1 is returned.

remove_tag()

  $id3v2->remove_tag();

Removes the whole tag from the file by copying the whole mp3-file to a temp-file and renaming/moving that to the original filename. Do not use remove_tag() if you only want to change a header, as otherwise the file is copied unneccessary. Use write_tag() directly, which will override an old tag.

add_frame()

  $fn = $id3v2->add_frame($fname, @data);

Add a new frame, identified by the short name CW$fname. The number of elements of array CW@data should be as described in the ID3v2.3 standard. (See also MP3::Tag::ID3v2-Data.) There are two exceptions: if CW@data is empty, it is filled with necessary number of CW""); if one of required elements is encoding, it may be omitted (meaning latin1 encoding, or CW0). (Any other encoding is not supported yet, and thus ignored.) It returns the the short name CW$fn, which can differ from CW$fname, when there existed already such a frame. If no other frame of this kind is allowed, an empty string is returned. Otherwise the name of the newly created frame is returned (which can have a 01 or 02 or ... appended). You have to call write_tag() to save the changes to the file. Examples:

 $f = add_frame("TIT2", 0, "Abba");   # $f="TIT2"
 $f = add_frame("TIT2", "Abba");      # $f="TIT201", encoding=0 implicit

 $f = add_frame("COMM", "ENG", "Short text", "This is a comment");

 $f = add_frame("COMM");              # creates an empty frame

 $f = add_frame("COMM", "ENG");       # ! wrong ! $f=undef, becaues number 
                                      # of arguments is wrong

change_frame()

  $id3v2->change_frame($fname, @data);

Change an existing frame, which is identified by its short name CW$fname. CW@data must be same as in add_frame; If the frame CW$fname does not exist, undef is returned. You have to call write_tag() to save the changes to the file.

remove_frame()

  $id3v2->remove_frame($fname);

Remove an existing frame. CW$fname is the short name of a frame, eg as returned by CWget_frame_ids. You have to call write_tag() to save the changes to the file.

is_modified()

  $id3v2->is_modified;

Returns true if the tag was modified after it was created.

supported_frames()

  $frames = $id3v2->supported_frames();

Returns a hash reference with all supported frames. The keys of the hash are the short names of the supported frames, the according values are the long (english) names of the frames.

what_data()

  ($data, $res_inp) = $id3v2->what_data($fname);

Returns an array reference with the needed data fields for a given frame. At this moment only the internal field names are returned, without any additional information about the data format of this field. Names beginning with an underscore (normally '_data') can contain binary data. $resp_inp is a reference to an array, which contains information about a restriction for the content of the data field ( coresspodending to the same array field in the @$data array). If the entry is undef, no restriction exists. Otherwise it is a hash. The keys of the hash are the allowed input, the correspodending value is the value which should stored later in that field. If the value is undef then the key itself is valid for saving. If the hash contains an entry with _FREE, the hash contains only suggestions for the input, but other input is also allowed. Example for picture types of the APIC frame: CW {"Other" = \x00, 32x32 pixels 'file icon' (PNG only) => \x01, Other file icon => \x02, ...}>

title( [@new_title] )

Returns the title composed of the tags configured via CWMP3::Tag-config('v2title')> call (with default 'Title/Songname/Content description' (TIT2)) from the tag. (For backward compatibility may be called by deprecated name song() as well.) Sets TIT2 frame if given the optional arguments CW@new_title. If this is an empty string, the frame is removed.

_comment([$language])

Returns the file comment (COMM with an empty 'Description') from the tag, or Subtitle/Description refinement (TIT3) frame (unless it is considered a part of the title).

comment()

   $val = $id3v2->comment();
   $newframe = $id3v2->comment('Just a comment for freddy', 'personal', 'eng');

Returns the file comment (COMM frame with an empty 'Description' field) from the tag, or Subtitle/Description refinement (TIT3) frame (unless it is considered a part of the title). If optional arguments ($comment, CW$short, CW$language) are present, sets the comment frame. If CW$language is omited, uses CWXXX (otherwise it should be lowercase 3-letter abbreviation according to ISO-639-2); if CW$short is omited, sets to CW''. If CW$comment is an empty string, the frame is removed.

   # Select short-description='', prefere language 'eng', then 'rus', then
   # the first COMM frame, then any COMM frame
   $val = $id3v2->frame_select('COMM', '', ['eng', 'rus', '#0', '']);
   $new = $id3v2->frame_select('COMM', '', ['eng', 'rus', '#0'],
                               'Comment with empty "Description" and "eng"');

Returns the contents of the first frame named CW$fname with a 'Description' field in the specified array reference CW$descrs and the language in the list of specified languages CW$languages. If the frame is a simple frame, the frame is returned as a string, otherwise as a hash reference; a simple frame should consist of one of Text/URL/_Data fields, with possible addition of Language and Description fields (if the corresponding arguments were defined). The lists CW$descrs and CW$languages of one element can be flattened to become this element (as with CW'' above). If the lists are not defined, no restriction is applied. Language of CW'' means no restriction on language. If optional argument CW$newtext is given, the found frames are removed; if CW$newtext is defined, a new frame is created (the first elements of CW$descrs and CW$languages are used as the short description and the language, default to CW'' and CWXXX).

frame_have()

Same as frame_select(), but returns the count of found frames.

year( [@new_year] )

Returns the year (TYER/TDRC) from the tag. Sets TYER and TDRC frames if given the optional arguments CW@new_year. If this is an empty string, the frame is removed. The format is similar to timestamps of IDv2.4.0, but ranges can be separated by CW- or CW--, and non-contiguous dates are separated by CW, (comma). If periods need to be specified via duration, then one needs to use the ISO 8601 CW/-notation (e.g., see

  http://www.mcs.vuw.ac.nz/technical/software/SGML/doc/iso8601/ISO8601.html

); the CWduration/end_timestamp is not supported. On output, ranges of timestamps are converted to CW- or CW-- separated format depending on whether the timestamps are years, or have additional fields. If configuration variable CWyear_is_timestamp is false, the return value is always the year only (of the first timestamp of a composite timestamp). Recall that ID3v2.4.0 timestamp has format yyyy-MM-ddTHH:mm:ss (year, -, month, -, day, T, hour (out of 24), :, minutes, :, seconds), but the precision may be reduced by removing as many time indicators as wanted. Hence valid timestamps are yyyy, yyyy-MM, yyyy-MM-dd, yyyy-MM-ddTHH, yyyy-MM-ddTHH:mm and yyyy-MM-ddTHH:mm:ss. All time stamps are UTC. For durations, use the slash character as described in 8601, and for multiple noncontiguous dates, use multiple strings, if allowed by the frame definition.

track( [$new_track] )

Returns the track number (TRCK) from the tag. Sets TRCK frame if given the optional arguments CW@new_track. If this is an empty string or 0, the frame is removed. Returns the artist name; it is the first existing frame from the list of

  TPE1      Lead artist/Lead performer/Soloist/Performing group
  TPE2      Band/Orchestra/Accompaniment
  TCOM      Composer
  TPE3      Conductor
  TEXT      Lyricist/Text writer

Sets TPE1 frame if given the optional arguments CW@new_artist. If this is an empty string, the frame is removed. Returns the album name (TALB) from the tag. If none is found, returns the Content group description (TIT1) frame (unless it is considered a part of the title). Sets TALB frame if given the optional arguments CW@new_album. If this is an empty string, the frame is removed. Returns the genre string from TCON frame of the tag. Sets TCON frame if given the optional arguments CW@new_genre. If this is an empty string, the frame is removed.

version()

  $version = $id3v2->version();
  ($major, $revision) = $id3v2->version();

Returns the version of the ID3v2 tag. It returns a formatted string like 3.0 or an array containing the major part (eg. 3) and revision part (eg. 0) of the version number.

new()

  $tag = new($mp3fileobj);

CWnew() needs as parameter a mp3fileobj, as created by CWMP3::Tag::File. CWnew tries to find a ID3v2 tag in the mp3fileobj. If it does not find a tag it returns undef. Otherwise it reads the tag header, as well as an extended header, if available. It reads the rest of the tag in a buffer, does unsynchronizing if neccessary, and returns a ID3v2-object. At this moment only ID3v2.3 is supported. Any extended header with CRC data is ignored, so no CRC check is done at the moment. The ID3v2-object can be used to extract information from the tag. Please use

   $mp3 = MP3::Tag->new($filename);
   $mp3->get_tags();                 ## to find an existing tag, or
   $id3v2 = $mp3->new_tag("ID3v2");  ## to create a new tag

instead of using this function directly

MP3::Tag, MP3::Tag::ID3v1, MP3::Tag::ID3v2-Data ID3v2 standard - http://www.id3.org

Copyright (c) 2000-2004 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.