.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MP3::Tag::ID3v2_Data 3pm"
.TH MP3::Tag::ID3v2_Data 3pm "2022-12-30" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MP3::Tag::ID3v2_Data \- get_frame() data format and supported frames
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  $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, \*(Aqraw\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "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 
\&\fBMP3::Tag::ID3v2::get_frame()\fR.
.PP
It contains also a list of all supported ID3v2\-Frames.
.SS "\fBget_frame()\fP"
.IX Subsection "get_frame()"
.Vb 1
\& ($info, $long) = $id3v2\->get_frame($id);    # or
\& 
\& ($info, $long) = $id3v2\->get_frame($id, \*(Aqraw\*(Aq);
.Ve
.PP
\&\f(CW$id\fR has to be a name of a frame like \*(L"\s-1APIC\*(R".\s0  For more variants of calling
see \fBget_frame()\fR.
.PP
The names of all frames found in a tag can be retrieved with the \fBget_frame_ids()\fR function.
.SS "Using the returned data"
.IX Subsection "Using the returned data"
In the ID3v2.3 specifications 73 frames are defined, which can contain very
different information. That means that get_frame returns the information
of different frames also in different ways.
.IP "Simple Frames" 4
.IX Item "Simple Frames"
A lot of the tags contain only a text string and encoding information. If
you call ($info, \f(CW$long\fR) = \f(CW$id3v2\fR\->get_frame($id) for such a frame, \f(CW$info\fR will contain
the text string and \f(CW$long\fR will contain the english name of the frame.
.Sp
Example:
  get_frame(\*(L"\s-1TIT2\*(R"\s0);     # returns
.Sp
.Vb 1
\&  ("Birdhouse In Your Soul", "Title/songname/content description")
.Ve
.IP "Complex Frames" 4
.IX Item "Complex Frames"
For more complex frames the returned \f(CW$info\fR 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.
.Sp
Example:
  get_frame(\*(L"\s-1APIC\*(R"\s0);     # returns
.Sp
.Vb 6
\&  ( { "Description" => "Flood", 
\&      "MIME Type" => "/image/jpeg", 
\&      "Picture Type" => "Cover (front)",
\&      "_Data" => "..data of jpeg picture (binary).."
\&     },
\&   "Attached Picture");
.Ve
.IP "Other Frames" 4
.IX Item "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.
.Sp
Example:
  get_frame(\*(L"\s-1TIT2\*(R",\s0 'raw');    # returns
.Sp
.Vb 1
\&  ("\ex00Birdhouse In Your Soul", "Title/songname/content description")
.Ve
.PP
The frames which (in addition to \f(CW\*(C`Text\*(C'\fR/\f(CW\*(C`URL\*(C'\fR) contain only
\&\f(CW\*(C`Description\*(C'\fR and \f(CW\*(C`Language\*(C'\fR fields are in some intermediate position
between \*(L"simple\*(R" and \*(L"complex\*(R" frames.  They can be handled very similarly
to \*(L"simple\*(R" frames by using \*(L"long names\*(R", such as \f(CW\*(C`COMM[description]\*(C'\fR
or \f(CW\*(C`COMM(LANG)[description]\*(C'\fR, and the corresponding \*(L"quick\*(R" \s-1API\s0 such
as \fBframe_select()\fR.
.SS "List of Simple Frames"
.IX Subsection "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 \f(CW$id3v2\fR\->\fBget_frame()\fR:
.IP "\s-1IPLS :\s0 Involved people list" 4
.IX Item "IPLS : Involved people list"
.PD 0
.IP "\s-1MCDI :\s0 Music \s-1CD\s0 identifier" 4
.IX Item "MCDI : Music CD identifier"
.IP "\s-1PCNT :\s0 Play counter" 4
.IX Item "PCNT : Play counter"
.IP "\s-1TALB :\s0 Album/Movie/Show title" 4
.IX Item "TALB : Album/Movie/Show title"
.IP "\s-1TBPM : BPM\s0 (beats per minute)" 4
.IX Item "TBPM : BPM (beats per minute)"
.IP "\s-1TCOM :\s0 Composer" 4
.IX Item "TCOM : Composer"
.IP "\s-1TCON :\s0 Content type" 4
.IX Item "TCON : Content type"
.IP "\s-1TCOP :\s0 Copyright message" 4
.IX Item "TCOP : Copyright message"
.IP "\s-1TDAT :\s0 Date" 4
.IX Item "TDAT : Date"
.IP "\s-1TDLY :\s0 Playlist delay" 4
.IX Item "TDLY : Playlist delay"
.IP "\s-1TDRC :\s0 Recording time" 4
.IX Item "TDRC : Recording time"
.IP "\s-1TENC :\s0 Encoded by" 4
.IX Item "TENC : Encoded by"
.IP "\s-1TEXT :\s0 Lyricist/Text writer" 4
.IX Item "TEXT : Lyricist/Text writer"
.IP "\s-1TFLT :\s0 File type" 4
.IX Item "TFLT : File type"
.IP "\s-1TIME :\s0 Time" 4
.IX Item "TIME : Time"
.IP "\s-1TIPL :\s0 Involved people list" 4
.IX Item "TIPL : Involved people list"
.IP "\s-1TIT1 :\s0 Content group description" 4
.IX Item "TIT1 : Content group description"
.IP "\s-1TIT2 :\s0 Title/songname/content description" 4
.IX Item "TIT2 : Title/songname/content description"
.IP "\s-1TIT3 :\s0 Subtitle/Description refinement" 4
.IX Item "TIT3 : Subtitle/Description refinement"
.IP "\s-1TKEY :\s0 Initial key" 4
.IX Item "TKEY : Initial key"
.IP "\s-1TLAN :\s0 Language(s)" 4
.IX Item "TLAN : Language(s)"
.IP "\s-1TLEN :\s0 Length" 4
.IX Item "TLEN : Length"
.IP "\s-1TMCL :\s0 Musician credits list" 4
.IX Item "TMCL : Musician credits list"
.IP "\s-1TMED :\s0 Media type" 4
.IX Item "TMED : Media type"
.IP "\s-1TOAL :\s0 Original album/movie/show title" 4
.IX Item "TOAL : Original album/movie/show title"
.IP "\s-1TOFN :\s0 Original filename" 4
.IX Item "TOFN : Original filename"
.IP "\s-1TOLY :\s0 Original lyricist(s)/text writer(s)" 4
.IX Item "TOLY : Original lyricist(s)/text writer(s)"
.IP "\s-1TOPE :\s0 Original artist(s)/performer(s)" 4
.IX Item "TOPE : Original artist(s)/performer(s)"
.IP "\s-1TORY :\s0 Original release year" 4
.IX Item "TORY : Original release year"
.IP "\s-1TOWN :\s0 File owner/licensee" 4
.IX Item "TOWN : File owner/licensee"
.IP "\s-1TPE1 :\s0 Lead performer(s)/Soloist(s)" 4
.IX Item "TPE1 : Lead performer(s)/Soloist(s)"
.IP "\s-1TPE2 :\s0 Band/orchestra/accompaniment" 4
.IX Item "TPE2 : Band/orchestra/accompaniment"
.IP "\s-1TPE3 :\s0 Conductor/performer refinement" 4
.IX Item "TPE3 : Conductor/performer refinement"
.IP "\s-1TPE4 :\s0 Interpreted, remixed, or otherwise modified by" 4
.IX Item "TPE4 : Interpreted, remixed, or otherwise modified by"
.IP "\s-1TPOS :\s0 Part of a set" 4
.IX Item "TPOS : Part of a set"
.IP "\s-1TPUB :\s0 Publisher" 4
.IX Item "TPUB : Publisher"
.IP "\s-1TRCK :\s0 Track number/Position in set" 4
.IX Item "TRCK : Track number/Position in set"
.IP "\s-1TRDA :\s0 Recording dates" 4
.IX Item "TRDA : Recording dates"
.IP "\s-1TRSN :\s0 Internet radio station name" 4
.IX Item "TRSN : Internet radio station name"
.IP "\s-1TRSO :\s0 Internet radio station owner" 4
.IX Item "TRSO : Internet radio station owner"
.IP "\s-1TSIZ :\s0 Size" 4
.IX Item "TSIZ : Size"
.IP "\s-1TSRC : ISRC\s0 (international standard recording code)" 4
.IX Item "TSRC : ISRC (international standard recording code)"
.IP "\s-1TSSE :\s0 Software/Hardware and settings used for encoding" 4
.IX Item "TSSE : Software/Hardware and settings used for encoding"
.IP "\s-1TYER :\s0 Year" 4
.IX Item "TYER : Year"
.IP "\s-1WCOM :\s0 Commercial information" 4
.IX Item "WCOM : Commercial information"
.IP "\s-1WCOP :\s0 Copyright/Legal information" 4
.IX Item "WCOP : Copyright/Legal information"
.IP "\s-1WOAF :\s0 Official audio file webpage" 4
.IX Item "WOAF : Official audio file webpage"
.IP "\s-1WOAR :\s0 Official artist/performer webpage" 4
.IX Item "WOAR : Official artist/performer webpage"
.IP "\s-1WOAS :\s0 Official audio source webpage" 4
.IX Item "WOAS : Official audio source webpage"
.IP "\s-1WORS :\s0 Official internet radio station homepage" 4
.IX Item "WORS : Official internet radio station homepage"
.IP "\s-1WPAY :\s0 Payment" 4
.IX Item "WPAY : Payment"
.IP "\s-1WPUB :\s0 Publishers official webpage" 4
.IX Item "WPUB : Publishers official webpage"
.PD
.SS "List of Complex Frames"
.IX Subsection "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:
.IP "\s-1AENC :\s0 Audio encryption" 4
.IX Item "AENC : Audio encryption"
.Vb 1
\&  Keys: URL, Preview start, Preview length, _Data
.Ve
.IP "\s-1APIC :\s0 Attached picture" 4
.IX Item "APIC : Attached picture"
.Vb 1
\&  Keys: MIME type, Picture Type, Description, _Data
.Ve
.IP "\s-1COMM :\s0 Comments" 4
.IX Item "COMM : Comments"
.Vb 1
\&  Keys: Language, Description, Text
.Ve
.IP "\s-1COMR :\s0 Commercial frame" 4
.IX Item "COMR : Commercial frame"
.Vb 1
\&  Keys: Price, Valid until, URL, Received as, Name of Seller, Description, MIME type, _Logo
.Ve
.IP "\s-1ENCR :\s0 Encryption method registration" 4
.IX Item "ENCR : Encryption method registration"
.Vb 1
\&  Keys: Owner ID, Method symbol, _Data
.Ve
.IP "\s-1GEOB :\s0 General encapsulated object" 4
.IX Item "GEOB : General encapsulated object"
.Vb 1
\&  Keys: MIME type, Filename, Description, _Data
.Ve
.IP "\s-1GRID :\s0 Group identification registration" 4
.IX Item "GRID : Group identification registration"
.Vb 1
\&  Keys: Owner, Symbol, _Data
.Ve
.IP "\s-1LINK :\s0 Linked information" 4
.IX Item "LINK : Linked information"
.Vb 1
\&  Keys: ID, URL, Text
.Ve
.IP "\s-1OWNE :\s0 Ownership frame" 4
.IX Item "OWNE : Ownership frame"
.Vb 1
\&  Keys: Price payed, Date of purchase, Text
.Ve
.IP "\s-1POPM :\s0 Popularimeter" 4
.IX Item "POPM : Popularimeter"
.Vb 1
\&  Keys: URL, Rating, Counter
.Ve
.IP "\s-1PRIV :\s0 Private frame" 4
.IX Item "PRIV : Private frame"
.Vb 1
\&  Keys: Text, _Data
.Ve
.IP "\s-1RBUF :\s0 Recommended buffer size" 4
.IX Item "RBUF : Recommended buffer size"
.Vb 1
\&  Keys: Buffer size, Embedded info flag, Offset to next tag
.Ve
.IP "\s-1RVRB :\s0 Reverb" 4
.IX Item "RVRB : Reverb"
.Vb 1
\&  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
.Ve
.IP "\s-1SYTC :\s0 Synchronized tempo codes" 4
.IX Item "SYTC : Synchronized tempo codes"
.Vb 1
\&  Keys: Time Stamp Format, _Data
.Ve
.IP "\s-1TXXX :\s0 User defined text information frame" 4
.IX Item "TXXX : User defined text information frame"
.Vb 1
\&  Keys: Description, Text
.Ve
.IP "\s-1UFID :\s0 Unique file identifier" 4
.IX Item "UFID : Unique file identifier"
.Vb 1
\&  Keys: Text, _Data
.Ve
.IP "\s-1USER :\s0 Terms of use" 4
.IX Item "USER : Terms of use"
.Vb 1
\&  Keys: Language, Text
.Ve
.IP "\s-1USLT :\s0 Unsychronized lyric/text transcription" 4
.IX Item "USLT : Unsychronized lyric/text transcription"
.Vb 1
\&  Keys: Language, Description, Text
.Ve
.IP "\s-1WXXX :\s0 User defined \s-1URL\s0 link frame" 4
.IX Item "WXXX : User defined URL link frame"
.Vb 1
\&  Keys: Description, URL
.Ve
.SS "List of Other Frames"
.IX Subsection "List of Other Frames"
Following frames are only supported in raw mode:
.IP "\s-1CRM :\s0 Encrypted meta frame" 4
.IX Item "CRM : Encrypted meta frame"
.PD 0
.IP "\s-1EQUA :\s0 Equalization" 4
.IX Item "EQUA : Equalization"
.IP "\s-1ETCO :\s0 Event timing codes" 4
.IX Item "ETCO : Event timing codes"
.IP "\s-1LNK :\s0 Linked information" 4
.IX Item "LNK : Linked information"
.IP "\s-1MLLT : MPEG\s0 location lookup table" 4
.IX Item "MLLT : MPEG location lookup table"
.IP "\s-1PIC :\s0 Attached picture" 4
.IX Item "PIC : Attached picture"
.IP "\s-1POSS :\s0 Position synchronisation frame" 4
.IX Item "POSS : Position synchronisation frame"
.IP "\s-1RVAD :\s0 Relative volume adjustment" 4
.IX Item "RVAD : Relative volume adjustment"
.IP "\s-1SYLT :\s0 Synchronized lyric/text" 4
.IX Item "SYLT : Synchronized lyric/text"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MP3::Tag, MP3::Tag::ID3v2