NAME

MP3::Tag::ID3v2-Data - get_frame() data format and supported frames

SYNOPSIS

$mp3 = MP3::Tag->new($filename);
$mp3->get_tags();
$id3v2 = $mp3->{ID3v2} if exists $mp3->{id3v2};

($info, $long) = $id3v2->get_frame($id);    # or

($info, $long) = $id3v2->get_frame($id, 'raw');

DESCRIPTION

This document describes how to use the results of the get_frame function of MP3::Tag::ID3v2, thus the data format of frames retrieved with MP3::Tag::ID3v2::get_frame().

It contains also a list of all supported ID3v2-Frames.

get_frame()

($info, $long) = $id3v2->get_frame($id);    # or

($info, $long) = $id3v2->get_frame($id, 'raw');

$id has to be a name of a frame like "APIC". For more variants of calling see get_frame().

The names of all frames found in a tag can be retrieved with the get_frame_ids() function.

Using the returned data

In the ID3v2.3 specifications 72 frames are defined, which can contain very different information. That means that get_frame returns the information of different frames also in different ways.

Simple Frames

A lot of the tags contain only a text string and encoding information. If you call ($info, $long) = $id3v2->get_frame($id) for such a frame, $info will contain the text string and $long will contain the english name of the frame.

Example: get_frame("TIT2"); # returns

("Birdhouse In Your Soul", "Title/songname/content description")

Complex Frames

For more complex frames the returned $info is a reference to a hash, where each entry of the hash decribes a part of the information found in the frame. The key of a hash entry contains the name of this part, the according value contains the information itself.

Example: get_frame("APIC"); # returns

( { "Description" => "Flood", 
    "MIME Type" => "/image/jpeg", 
    "Picture Type" => "Cover (front)",
    "_Data" => "..data of jpeg picture (binary).."
   },
 "Attached Picture");

Other Frames

Some frames are not supported at the moment, ie the data found in the frame is not returned in a descriptive way. But you can read the data of this frames (and also of all other frames too) in raw mode. Then the complete data field of the frame is returned, without any modifications. This means that the returned data will be almost binary data.

Example: get_frame("TIT2", 'raw'); # returns

("\x00Birdhouse In Your Soul", "Title/songname/content description")

The frames which (in addition to Text/URL) contain only Description and Language fields are in some intermediate position between "simple" and "complex" frames. They can be handled very similarly to "simple" frames by using "long names", such as COMM[description] or COMM(LANG)[description], and the corresponding "quick" API such as frame_select().

List of Simple Frames

Following Frames are supported and return a single string (text). In the List you can find the frame IDs and the long names of the frames as returned by $id3v2->get_frame():

IPLS : Involved people list

MCDI : Music CD identifier

PCNT : Play counter

TALB : Album/Movie/Show title

TBPM : BPM (beats per minute)

TCOM : Composer

TCON : Content type

TCOP : Copyright message

TDAT : Date

TDLY : Playlist delay

TENC : Encoded by

TEXT : Lyricist/Text writer

TFLT : File type

TIME : Time

TIPL : Involved people list

TIT1 : Content group description

TIT2 : Title/songname/content description

TIT3 : Subtitle/Description refinement

TKEY : Initial key

TLAN : Language(s)

TLEN : Length

TMCL : Musician credits list

TMED : Media type

TOAL : Original album/movie/show title

TOFN : Original filename

TOLY : Original lyricist(s)/text writer(s)

TOPE : Original artist(s)/performer(s)

TORY : Original release year

TOWN : File owner/licensee

TPE1 : Lead performer(s)/Soloist(s)

TPE2 : Band/orchestra/accompaniment

TPE3 : Conductor/performer refinement

TPE4 : Interpreted, remixed, or otherwise modified by

TPOS : Part of a set

TPUB : Publisher

TRCK : Track number/Position in set

TRDA : Recording dates

TRSN : Internet radio station name

TRSO : Internet radio station owner

TSIZ : Size

TSRC : ISRC (international standard recording code)

TSSE : Software/Hardware and settings used for encoding

TYER : Year

WCOM : Commercial information

WCOP : Copyright/Legal information

WOAF : Official audio file webpage

WOAR : Official artist/performer webpage

WOAS : Official audio source webpage

WORS : Official internet radio station homepage

WPAY : Payment

WPUB : Publishers official webpage

List of Complex Frames

Following frames are supported and return a reference to a hash. The list shows which keys can be found in the returned hash:

AENC : Audio encryption

Keys: URL, Preview start, Preview length

APIC : Attached picture

Keys: MIME type, Picture Type, Description, _Data

COMM : Comments

Keys: Language, Description, Text

COMR : Commercial frame

Keys: Price, Valid until, URL, Received as, Name of Seller, Description, MIME type, _Logo

ENCR : Encryption method registration

Keys: Owner ID, Method symbol, _Data

GEOB : General encapsulated object

Keys: MIME type, Filename, Description, _Data

GRID : Group identification registration

Keys: Owner, Symbol, _Data

LINK : Linked information

Keys: ID, URL, Text

OWNE : Ownership frame

Keys: Price payed, Date of purchase, Text

POPM : Popularimeter

Keys: URL, Rating, Counter

PRIV : Private frame

Keys: Text, _Data

RBUF : Recommended buffer size

Keys: Buffer size, Embedded info flag, Offset to next tag

RVRB : Reverb

Keys: Reverb left (ms), Reverb right (ms), Reverb bounces (left), Reverb bounces (right), Reverb feedback (left to left), Reverb feedback (left to right), Reverb feedback (right to right), Reverb feedback (right to left), Premix left to right, Premix right to left

SYTC : Synchronized tempo codes

Keys: Time Stamp Format, _Data

TXXX : User defined text information frame

Keys: Description, Text

UFID : Unique file identifier

Keys: Text, _Data

USER : Terms of use

Keys: Language, Text

USLT : Unsychronized lyric/text transcription

Keys: Language, Description, Text

WXXX : User defined URL link frame

Keys: Description, URL

List of Other Frames

Following frames are only supported in raw mode:

CRM : Encrypted meta frame

EQUA : Equalization

ETCO : Event timing codes

LNK : Linked information

MLLT : MPEG location lookup table

PIC : Attached picture

POSS : Position synchronisation frame

RVAD : Relative volume adjustment

SYLT : Synchronized lyric/text

SEE ALSO

MP3::Tag, MP3::Tag::ID3v2