1CDDB(3) User Contributed Perl Documentation CDDB(3)
2
3
4
6 CDDB.pm - a high-level interface to cddb protocol servers (freedb and
7 CDDB)
8
10 use CDDB;
11
12 ### Connect to the cddbp server.
13 my $cddbp = new CDDB(
14 Host => 'freedb.freedb.org', # default
15 Port => 8880, # default
16 Login => $login_id, # defaults to %ENV's
17 ) or die $!;
18
19 ### Retrieve known genres.
20 my @genres = $cddbp->get_genres();
21
22 ### Calculate cddbp ID based on MSF info.
23 my @toc = (
24 '1 0 2 37', # track, CD-i MSF (space-delimited)
25 '999 1 38 17', # lead-out track MSF
26 '1000 0 0 Error!', # error track (don't include if ok)
27 );
28 my (
29 $cddbp_id, # used for further cddbp queries
30 $track_numbers, # padded with 0's (for convenience)
31 $track_lengths, # length of each track, in MM:SS format
32 $track_offsets, # absolute offsets (used for further cddbp queries)
33 $total_seconds # total play time, in seconds (for cddbp queries)
34 ) = $cddbp->calculate_id(@toc);
35
36 ### Query discs based on cddbp ID and other information.
37 my @discs = $cddbp->get_discs($cddbp_id, $track_offsets, $total_seconds);
38 foreach my $disc (@discs) {
39 my ($genre, $cddbp_id, $title) = @$disc;
40 }
41
42 ### Query disc details (usually done with get_discs() information).
43 my $disc_info = $cddbp->get_disc_details($genre, $cddbp_id);
44 my $disc_time = $disc_info->{'disc length'};
45 my $disc_id = $disc_info->{discid};
46 my $disc_title = $disc_info->{dtitle};
47 my @track_offsets = @{$disc_info->{offsets}};
48 my @track_seconds = @{$disc_info->{seconds}};
49 my @track_titles = @{$disc_info->{ttitles}};
50 # other information may be returned... explore!
51
52 ### Submit a disc via e-mail. (Requires MailTools)
53
54 die "can't submit a disc (no mail modules; see README)"
55 unless $cddbp->can_submit_disc();
56
57 # These are useful for prompting the user to fix defaults:
58 print "I will send mail through: ", $cddbp->get_mail_host(), "\n";
59 print "I assume your e-mail address is: ", $cddbp->get_mail_address(), "\n";
60
61 # Actually submit a disc record.
62 $cddbp->submit_disc(
63 Genre => 'classical',
64 Id => 'b811a20c',
65 Artist => 'Various',
66 DiscTitle => 'Cartoon Classics',
67 Offsets => $disc_info->{offsets}, # array reference
68 TrackTitles => $disc_info->{ttitles}, # array reference
69 From => 'login@host.domain.etc', # will try to determine
70 );
71
73 CDDB protocol (cddbp) servers provide compact disc information for
74 programs that need it. This allows such programs to display disc and
75 track titles automatically, and it provides extended information like
76 liner notes and lyrics.
77
78 This module provides a high-level Perl interface to cddbp servers.
79 With it, a Perl program can identify and possibly gather details about
80 a CD based on its "table of contents" (the disc's track times and
81 offsets).
82
83 Disc details have been useful for generating CD catalogs, naming mp3
84 files, printing CD liners, or even just playing discs in an automated
85 jukebox.
86
88 new PARAMETERS
89 Creates a high-level interface to a cddbp server, returning a
90 handle to it. The handle is not a filehandle. It is an object.
91 The new() constructor provides defaults for just about everything,
92 but everything is overrideable if the defaults aren't appropriate.
93
94 The interface will not actually connect to a cddbp server until
95 it's used, and a single cddbp interface may actually make several
96 connections (to possibly several servers) over the course of its
97 use.
98
99 The new() constructor accepts several parameters, all of which have
100 reasonable defaults.
101
102 Host and Port describe the cddbp server to connect to. These
103 default to 'freedb.freedb.org' and 8880, which is a multiplexor for
104 all the other freedb servers.
105
106 Utf8 is a boolean flag. If true, utf-8 will be used when submitting
107 CD info, and for interpreting the data reveived. This requires the
108 Encode module (and probably perl version at least 5.8.0). The
109 default is true if the Encode module can be loaded. Otherwise, it
110 will be false, meaning we fall back to ASCII.
111
112 Protocol_Version sets the cddbp version to use. CDDB.pm will not
113 connect to servers that don't support the version specified here.
114 The requested protocol version defaults to 1 if Utf8 is off, and to
115 6 if it is on.
116
117 Login is the login ID you want to advertise to the cddbp server.
118 It defaults to the login ID your computer assigns you, if that can
119 be determined. The default login ID is determined by the presence
120 of a LOGNAME or USER environment variable, or by the getpwuid()
121 function. On Windows systems, it defaults to "win32usr" if no
122 default method can be found and no Login parameter is set.
123
124 Submit_Address is the e-mail address where new disc submissions go.
125 This defaults to 'freedb-submit@freedb.org'. Note, that testing
126 submissions should be done via "test-submit@freedb.org".
127
128 Client_Name and Client_Version describe the client software used to
129 connect to the cddbp server. They default to 'CDDB.pm' and
130 CDDB.pm's version number. If developers change this, please
131 consult freedb's web site for a list of client names already in
132 use.
133
134 Debug enables verbose operational information on STDERR when set to
135 true. It's normally not needed, but it can help explain why a
136 program is failing. If someone finds a reproduceable bug, the
137 Debug output and a test program would be a big help towards having
138 it fixed. In case of submission, if this flag is on, a copy of the
139 submission e-mail will be sent to the From address.
140
141 get_genres
142 Takes no parameters. Returns a list of genres known by the cddbp
143 server, or undef if there is a problem retrieving them.
144
145 calculate_id TOC
146 The cddb protocol defines an ID as a hash of track lengths and the
147 number of tracks, with an added checksum. The most basic
148 information required to calculate this is the CD table of contents
149 (the CD-i track offsets, in "MSF" [Minutes, Seconds, Frames]
150 format).
151
152 Note however that there is no standard way to acquire this
153 information from a CD-ROM device. Therefore this module does not
154 try to read the TOC itself. Instead, developers must combine
155 CDDB.pm with a CD library which works with their system. The
156 AudioCD suite of modules is recommended: it has system specific
157 code for MacOS, Linux and FreeBSD. CDDB.pm's author has used
158 external programs like dagrab to fetch the offsets. Actual CDs
159 aren't always necessary: the author has heard of people generating
160 TOC information from mp3 file lengths.
161
162 That said, see parse_cdinfo() for a routine to parse "cdinfo"
163 output into a table of contents list suitable for calculate_id().
164
165 calculate_id() accepts TOC information as a list of strings. Each
166 string contains four fields, separated by whitespace:
167
168 offset 0: the track number
169
170 Track numbers start with 1 and run sequentially through the number
171 of tracks on a disc. Note: data tracks count on hybrid audio/data
172 CDs.
173
174 CDDB.pm understands two special track numbers. Track 999 holds the
175 lead-out information, which is required by the cddb protocol.
176 Track 1000 holds information about errors which have occurred while
177 physically reading the disc.
178
179 offset 1: the track start time, minutes field
180
181 Tracks are often addressed on audio CDs using "MSF" offsets. This
182 stands for Minutes, Seconds, and Frames (fractions of a second).
183 The combination pinpoints the exact disc frame where a song starts.
184
185 Field 1 contains the M part of MSF. It is ignored for error
186 tracks, but it still must contain a number. Zero is suggested.
187
188 offset 2: the track start time, seconds field
189
190 This field contains the S part of MSF. It is ignored for error
191 tracks, but it still must contain a number. Zero is suggested.
192
193 offset 3: the track start time, frames field
194
195 This field contains the F part of MSF. For error tracks, it
196 contains a description of the error.
197
198 Example track file. Note: the comments should not appear in the
199 file.
200
201 1 0 2 37 # track 1 starts at 00:02 and 37 frames
202 2 1 38 17 # track 2 starts at 01:38 and 17 frames
203 3 11 57 30 # track 3 starts at 11:57 and 30 frames
204 ...
205 999 75 16 5 # leadout starts at 75:16 and 5 frames
206
207 Track 1000 should not be present if everything is okay:
208
209 1000 0 0 Error reading TOC: no disc in drive
210
211 In scalar context, calculate_id() returns just the cddbp ID. In a
212 list context, it returns an array containing the following values:
213
214 (
215 $cddbp_id,
216 $track_numbers,
217 $track_lengths,
218 $track_offsets,
219 $total_seconds
220 ) = $cddbp->calculate_id(@toc);
221
222 print(
223 "cddbp ID = $cddbp_id\n", # b811a20c
224 "track numbers = @$track_numbers\n", # 001 002 003 ...
225 "track lengths = @$track_lengths\n", # 01:36 10:19 04:29 ...
226 "track offsets = @$track_offsets\n", # 187 7367 53805 ...
227 "total seconds = $total_seconds\n", # 4514
228 );
229
230 CDDBP_ID
231
232 The 0th returned value is the hashed cddbp ID, required for any
233 queries or submissions involving this disc.
234
235 TRACK_NUMBERS
236
237 The 1st returned value is a reference to a list of track numbers,
238 one for each track (excluding the lead-out), padded to three
239 characters with leading zeroes. These values are provided for
240 convenience, but they are not required by cddbp servers.
241
242 TRACK_LENGTHS
243
244 The 2nd returned value is a reference to a list of track lengths,
245 one for each track (excluding the lead-out), in HH:MM format.
246 These values are returned as a convenience. They are not required
247 by cddbp servers.
248
249 TRACK_OFFSETS
250
251 The 3rd returned value is a reference to a list of absolute track
252 offsets, in frames. They are calculated from the MSF values, and
253 they are required by get_discs() and submit_disc().
254
255 TOTAL_SECONDS
256
257 The 4th and final value is the total playing time for the CD, in
258 seconds. The get_discs() function needs it.
259
260 get_discs CDDBP_ID, TRACK_OFFSETS, TOTAL_SECONDS
261 get_discs() asks the cddbp server for a summary of all the CDs
262 matching a given cddbp ID, track offsets, and total playing time.
263 These values can be retrieved from calculade_id().
264
265 my @id_info = $cddbp->calculate_id(@toc);
266 my $cddbp_id = $id_info->[0];
267 my $track_offsets = $id_info->[3];
268 my $total_seconds = $id_info->[4];
269
270 get_discs() returns an array of matching discs, each of which is
271 represented by an array reference. It returns an empty array if
272 the query succeeded but did not match, and it returns undef on
273 error.
274
275 my @discs = $cddbp->get_discs( $cddbp_id, $track_offsets, $total_seconds );
276 foreach my $disc (@discs) {
277 my ($disc_genre, $disc_id, $disc_title) = @$disc;
278 print(
279 "disc id = $disc_id\n",
280 "disc genre = $disc_genre\n",
281 "disc title = $disc_title\n",
282 );
283 }
284
285 DISC_GENRE is the genre this disc falls into, as determined by
286 whoever submitted or last edited the disc. The genre is required
287 when requesting a disc's details. See get_genres() for how to
288 retrieve a list of cddbp genres.
289
290 CDDBP_ID is the cddbp ID of this disc. Cddbp servers perform fuzzy
291 matches, returning near misses as well as direct hits on a cddbp
292 ID, so knowing the exact ID for a disc is important when submitting
293 changes or requesting a particular near-miss' details.
294
295 DISC_TITLE is the disc's title, which may help a human to pick the
296 correct disc out of several close mathches.
297
298 get_discs_by_toc TOC
299 This function acts as a macro, combining calculate_id() and
300 get_discs() calls into one function. It takes the same parameters
301 as calculate_id(), and it returns the same information as
302 get_discs().
303
304 get_discs_by_query QUERY_STRING
305 Fetch discs by a pre-built cddbp query string. Some disc querying
306 programs report this string, and get_discs_by_query() is a
307 convenient way to use that.
308
309 Cddb protocol query strings look like:
310
311 cddb query $cddbp_id $track_count @offsets $total_seconds
312
313 get_disc_details DISC_GENRE, CDDBP_ID
314 This function fetches a disc's detailed information from a cddbp
315 server. It takes two parameters: the DISC_GENRE and the CDDP_ID.
316 These parameters usually come from a call to get_discs().
317
318 The disc's details are returned in a reference to a fairly complex
319 hash. It includes information normally stored in comments. The
320 most common entries in this hash include:
321
322 $disc_details = get_disc_details( $disc_genre, $cddbp_id );
323
324 $disc_details->{"disc length"}
325
326 The disc length is commonly stored in the form "### seconds", where
327 ### is the disc's total playing time in seconds. It may hold other
328 time formats.
329
330 $disc_details->{discid}
331
332 This is a rehash (get it?) of the cddbp ID. It should match the
333 CDDBP_ID given to get_disc_details().
334
335 $disc_details->{dtitle}
336
337 This is the disc's title. I do not know whether it will match the
338 one returned by get_discs().
339
340 $disc_details->{offsets}
341
342 This is a reference to a list of absolute disc track offsets,
343 similar to the TRACK_OFFSETS returned by calculate_id().
344
345 $disc_details->{seconds}
346
347 This is a reference to a list of track length, in seconds.
348
349 $disc_details->{ttitles}
350
351 This is a reference to a list of track titles. These are the
352 droids you are looking for.
353
354 $disc_details->{"processed by"}
355
356 This is a comment field identifying the name and version of the
357 cddbp server which accepted and entered the disc record into the
358 database.
359
360 $disc_details->{revision}
361
362 This is the disc record's version number, used as a sanity check
363 (semaphore?) to prevent simultaneous revisions. Revisions start at
364 0 for new submissions and are incremented for every correction. It
365 is the responsibility of the submitter (be it a person or a program
366 using CDDB.pm) to provide a correct revision number.
367
368 $disc_details->{"submitted via"}
369
370 This is the name and version of the software that submitted this
371 cddbp record. The main intention is to identify records that are
372 submitted by broken software so they can be purged or corrected.
373
374 $disc_details->{xmcd_record}
375
376 The xmcd_record field contains a copy of the entire unprocessed
377 cddbp response that generated all the other fields.
378
379 $disc_details->{genre}
380
381 This is merely a copy of DISC_GENRE, since it's otherwise not
382 possible to determine it from the hash.
383
384 parse_xmcd_file XMCD_FILE_CONTENTS, [GENRE]
385 Parses an array ref of lines read from an XMCD file into the
386 disc_details hash described above. If the GENRE parameter is set
387 it will be included in disc_details.
388
389 can_submit_disc
390 Returns true or false, depending on whether CDDB.pm has enough
391 dependent modules to submit discs. If it returns false, you are
392 missing Mail::Internet, Mail::Header, or MIME::QuotedPrint.
393
394 get_mail_address
395 Returns what CDDB.pm thinks your e-mail address is, or what it was
396 last set to. It was added to fetch the default e-mail address so
397 users can see it and have an opportunity to correct it.
398
399 my $mail_from = $cddb->get_mail_address();
400 print "New e-mail address (or blank to keep <$mail_from>): ";
401 my $new_mail_from = <STDIN>;
402 $new_mail_from =~ s/^\s+//;
403 $new_mail_from =~ s/\s+$//;
404 $new_mail_from =~ s/\s+/ /g;
405 $mail_from = $new_mail_from if length $new_mail_from;
406
407 $cddbp->submit_disc(
408 ...,
409 From => $mail_from,
410 );
411
412 get_mail_host
413 Returns what CDDB.pm thinks your SMTP host is, or what it was last
414 set to. It was added to fetch the default e-mail transfer host so
415 users can see it and have an opportunity to correct it.
416
417 my $mail_host = $cddb->get_mail_host();
418 print "New e-mail host (or blank to keep <$mail_host>): ";
419 my $new_mail_host = <STDIN>;
420 $new_mail_host =~ s/^\s+//;
421 $new_mail_host =~ s/\s+$//;
422 $new_mail_host =~ s/\s+/ /g;
423 $mail_host = $new_mail_host if length $new_mail_host;
424
425 $cddbp->submit_disc(
426 ...,
427 Host => $mail_host,
428 );
429
430 parse_cdinfo CDINFO_FILE
431 Generates a table of contents suitable for calculate_id() based on
432 the output of a program called "cdinfo". CDINFO_FILE may either be
433 a text file, or it may be the cdinfo program itself.
434
435 my @toc = parse_cdinfo("cdinfo.txt"); # read cdinfo.txt
436 my @toc = parse_cdinfo("cdinfo|"); # run cdinfo directly
437
438 The table of contents can be passed directly to calculate_id().
439
440 submit_disc DISC_DETAILS
441 submit_disc() submits a disc record to a cddbp server. Currently
442 it only uses e-mail, although it will try different ways to send
443 that. It returns true or false depending on whether it was able to
444 send the submission e-mail.
445
446 The rest of CDDB.pm will work without the ability to submit discs.
447 While cddbp submissions are relatively rare, most CD collections
448 will have one or two discs not present in the system. Please
449 submit new discs to the system: the amazing number of existing
450 discs got there because others submitted them before you needed
451 them.
452
453 submit_disc() takes six required parameters and two optional ones.
454 The parameters are named, like hash elements, and can appear in any
455 order.
456
457 Genre => DISC_GENRE
458
459 This is the disc's genre. It must be one of the genres that the
460 server knows. See get_genres().
461
462 Id => CDDBP_ID
463
464 This is the cddbp ID that identifies the disc. It should come from
465 calculate_id() if this is a new submission, or from
466 get_disc_details() if this is a revision.
467
468 Artist => DISC_ARTIST
469
470 This is the disc's artist, a freeform text field describing the
471 party responsible for the album. It will need to be entered from
472 the disc's notes for new submissions, or it can come from
473 get_disc_details() on subsequent revisions.
474
475 DiscTitle => DISC_TITLE
476
477 This is the disc's title, a freeform text field describing the
478 album. It must be entered from the disc's notes for new
479 submissions. It can come from get_disc_details() on subsequent
480 revisions.
481
482 Offsets => TRACK_OFFSETS
483
484 This is a reference to an array of absolute track offsets, as
485 provided by calculate_id().
486
487 TrackTitles => TRACK_TITLES
488
489 This is a reference to an array of track titles, either entered by
490 a human or provided by get_disc_details().
491
492 From => EMAIL_ADDRESS
493
494 This is the disc submitter's e-mail address. It's not required,
495 and CDDB.pm will try to figure one out on its own if an address is
496 omitted. It may be more reliable to provide your own, however.
497
498 The default return address may not be a deliverable one, especially
499 if CDDB.pm is being used on a dial-up machine that isn't running
500 its own MTA. If the current machine has its own MTA, problems
501 still may occur if the machine's Internet address changes.
502
503 Host => SMTP_HOST
504
505 This is the SMTP host to contact when sending mail. It's not
506 required, and CDDB.pm will try to figure one out on its own. It
507 will look at the SMTPHOSTS environment variable is not defined, it
508 will try 'mail' and 'localhost' before finally failing.
509
510 Revision => REVISION
511
512 The revision number. Should be 1 for new submissions, and one
513 higher than the previous one for updates. The previous revision
514 number is available as the "revision" field in the hash returned by
515 get_disc_details().
516
518 Documented as being not documented.
519
521 Please see the cddb.t program in the t (tests) directory. It exercises
522 every aspect of CDDB.pm, including submissions.
523
525 BUG TRACKER
526 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=CDDB
527
528 REPOSITORY
529 http://thirdlobe.com/svn/cddb/
530
531 OTHER RESOURCES
532 http://search.cpan.org/dist/CDDB/
533
535 Copyright 1998-2009 Rocco Caputo. All rights reserved. This program
536 is free software; you can redistribute it and/or modify it under the
537 same terms as Perl itself.
538
539
540
541perl v5.12.0 2010-03-08 CDDB(3)