NAME

MP3::TAG::ID3v2 - Read / Write ID3v2.3 tags from MP3 audio files

SYNOPSIS

MP3::TAG::ID3v2 is designed to be called from the MP3::Tag module. It then returns a ID3v2-tag-object, which can be used in a users program.

$id3v2 = MP3::TAG::ID3v2->new($mp3obj);

$mp3obj is a object from MP3::Tag. See according documentation. $tag is undef when no tag is found in the $mp3obj.

* Reading a tag

  @frameIDs = $id3v2->getFrameIDS;

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

* Changing / Writing a tag

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

$id3v2->write_tag();

* Get information about supported frames

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

AUTHOR

Thomas Geffert, thg@users.sourceforge.net

DESCRIPTION

new()

$tag = new($mp3obj);

new() needs as parameter a mp3obj, as created by MP3::Tag (see documentation of MP3::Tag). new tries to find a ID3v2 tag in the mp3obj. If it does not find a tag it returns undef. Otherwise it reads the tag header, as well 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 not CRC check is done at the moment. The ID3v2-object can then be used to extract information from the tag.

getFrameIDs()

@frameIDs = $tag->getFrameIDs;

getFrameIDs loops through all frames, which exist in the tag. It returns a list of all available Frame IDs. These are 4-character-codes (short names), the internal names of the frames.

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 expanded names can then used with getFrame to get the information of these frames.

getFrame()

($info, $name) = getFrame($ID);
($info, $name) = getFrame($ID, 'raw');

getFrame gets the contents of a specific frame, which must be specified by the 4-character-ID (aka short name). You can use getFrameIDs to get the IDs of the tag, or use IDs which you hope to find in the tag. If the ID is not found, getFrame returns (undef, undef).

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 getFrame 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, $name), where $info is the text string, and $name is the long (english) name of the frame.

If the frame consist of different pieces of data, $info is a hash reference, $name is again the long name of the frame.

The hash, to which $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 there exists a second parameter like raw, the whole frame data is returned, but not the frame header. If the data was stored compressed, it is also in raw mode uncompressed before it is returned. Then $info contains a string with all data (which might be binary), and $name against the long frame name.

! Encrypted frames are not supported yet !

! Some frames are not supported yet, but the most common ones are supported !

write_tag()

$id3v2->write_tag;

Saves a frame to the file. It tries to update the file in place, when the space of the old tag is big enoug for the new tag. Otherwise it creates a temp file (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.

At the moment the tag is automatically unsynchronized.

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.

add_frame()

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

Add a new frame, identified by the short name $fname. The $data must consist from so much elements, as described in the ID3v2.3 standard. If there is need to give an encoding parameter and you would like standard ascii encoding, you can omit the parameter or set it to 0. Any other encoding is not supported yet, and thus ignored.

Examples:

add_frame("TIT2", 0, "Abba");   # both the same, but
add_frame("TIT2", "Abba");      # this one with implicit encoding
add_frame("COMM", "ENG", "Short text", "This is a comment");

change_frame()

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

Change an existing frame, which is identified by its short name $fname. @data must be same as in add_frame;

remove_frame()

$id3v2->remove_frame($fname);

Remove an existing frame. $fname is the short name of a frame, eg as returned by getFrameIDs.

supported_frames()

%frames = $id3v2->supported_frames();

Returns a hash 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 = $id3v2->what_data($fname);

Returns for a frame the needed data fields to write this tag. 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.

This will change hopefully later on...

SEE ALSO

MP3::Tag, MP3::TAG::ID3v1

ID3v2 standard - http://www.id3.org