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