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