1#!/usr/bin/perl -w 2 3## data_pod.PL creates the documentation File MP3::Tag::ID3v2_Data 4 5use MP3::Tag; 6use MP3::Tag::ID3v2; 7 8$filename=shift || "./lib/MP3/Tag/ID3v2_Data.pod"; 9 10open(POD, ">$filename"); 11$std = select(POD); 12 13@frames = keys %{MP3::Tag::ID3v2::supported_frames()}; 14 15print <<"INTRO"; 16 17=head1 NAME 18 19MP3::Tag::ID3v2_Data - get_frame() data format and supported frames 20 21=head1 SYNOPSIS 22 23 \$mp3 = MP3::Tag->new(\$filename); 24 \$mp3->get_tags(); 25 \$id3v2 = \$mp3->{ID3v2} if exists \$mp3->{id3v2}; 26 27 (\$info, \$long) = \$id3v2->get_frame(\$id); # or 28 29 (\$info, \$long) = \$id3v2->get_frame(\$id, 'raw'); 30 31 32=head1 DESCRIPTION 33 34This document describes how to use the results of the get_frame function of 35MP3::Tag::ID3v2, thus the data format of frames retrieved with 36MP3::Tag::ID3v2::get_frame(). 37 38It contains also a list of all supported ID3v2-Frames. 39 40=head2 get_frame() 41 42 (\$info, \$long) = \$id3v2->get_frame(\$id); # or 43 44 (\$info, \$long) = \$id3v2->get_frame(\$id, 'raw'); 45 46\$id has to be a name of a frame like "APIC". For more variants of calling 47see L<get_frame()|MP3::Tag::ID3v2>. 48 49The names of all frames found in a tag can be retrieved with the L<get_frame_ids()|MP3::Tag::ID3v2> function. 50 51=head2 Using the returned data 52 53In the ID3v2.3 specifications $#frames frames are defined, which can contain very 54different information. That means that get_frame returns the information 55of different frames also in different ways. 56 57=over 4 58 59=item Simple Frames 60 61A lot of the tags contain only a text string and encoding information. If 62you call (\$info, \$long) = \$id3v2->get_frame(\$id) for such a frame, \$info will contain 63the text string and \$long will contain the english name of the frame. 64 65Example: 66 get_frame("TIT2"); # returns 67 68 ("Birdhouse In Your Soul", "Title/songname/content description") 69 70=item Complex Frames 71 72For more complex frames the returned \$info is a reference to a hash, where 73each entry of the hash decribes a part of the information found in the 74frame. The key of a hash entry contains the name of this part, the according 75value contains the information itself. 76 77Example: 78 get_frame("APIC"); # returns 79 80 ( { "Description" => "Flood", 81 "MIME Type" => "/image/jpeg", 82 "Picture Type" => "Cover (front)", 83 "_Data" => "..data of jpeg picture (binary).." 84 }, 85 "Attached Picture"); 86 87=item Other Frames 88 89Some frames are not supported at the moment, ie the data found in the frame 90is not returned in a descriptive way. But you can read the data of this 91frames (and also of all other frames too) in raw mode. Then the complete 92data field of the frame is returned, without any modifications. This means 93that the returned data will be almost binary data. 94 95Example: 96 get_frame("TIT2", 'raw'); # returns 97 98 ("\\x00Birdhouse In Your Soul", "Title/songname/content description") 99 100=back 101 102The frames which (in addition to C<Text>/C<URL>) contain only 103C<Description> and C<Language> fields are in some intermediate position 104between "simple" and "complex" frames. They can be handled very similarly 105to "simple" frames by using "long names", such as C<COMM[description]> 106or C<COMM(LANG)[description]>, and the corresponding "quick" API such 107as frame_select(). 108 109INTRO 110 111@frames = keys %MP3::Tag::ID3v2::long_names; 112@other = (); 113@text = (); 114@complex = (); 115 116foreach (@frames) { 117 $data = MP3::Tag::ID3v2::what_data("", $_); 118 if (ref $data) { 119 if ($#$data == 0 and ($$data[0] =~ /^(Text|URL)$/ or $_ eq 'MCDI')) { 120 push @text, $_; 121 } else { 122 push @complex, $_; 123 } 124 } else { 125 push @other, $_; 126 } 127} 128 129print "\n\n=head2 List of Simple Frames\n\nFollowing Frames are supported 130and return a single string (text). In the List you can find the frame IDs 131and the long names of the frames as returned by \$id3v2->get_frame():\n\n=over 4\n\n"; 132foreach (sort @text) { 133 $long = $MP3::Tag::ID3v2::long_names{$_}; 134 print "\n=item $_ : $long\n"; 135} 136print "\n=back\n\n"; 137 138print "\n\n=head2 List of Complex Frames\n\n"; 139print "Following frames are supported and return a reference to a hash. The 140list shows which keys can be found in the returned hash:\n"; 141print "\n=over 4\n\n"; 142foreach (sort @complex) { 143 $long = $MP3::Tag::ID3v2::long_names{$_}; 144 print "\n=item $_ : $long\n\n"; 145 $data = MP3::Tag::ID3v2::what_data("", $_); 146 print " Keys: ", join(", ",@$data), "\n"; 147} 148print "\n=back\n\n"; 149 150print "\n\n=head2 List of Other Frames\n\n"; 151print "Following frames are only supported in raw mode:\n"; 152print "\n=over 4\n\n"; 153foreach (sort @other) { 154 $long = $MP3::Tag::ID3v2::long_names{$_}; 155 print "\n=item $_ : $long\n"; 156} 157print "\n=back\n\n"; 158 159print <<END; 160 161=head1 SEE ALSO 162 163L<MP3::Tag>, L<MP3::Tag::ID3v2> 164 165END 166 167select($std); 168close POD; 169