1CDDB(3)               User Contributed Perl Documentation              CDDB(3)
2
3
4

NAME

6       CDDB.pm - a high-level interface to cddb protocol servers (freedb and
7       CDDB)
8

VERSION

10       version 1.222
11

SYNOPSIS

13         use CDDB;
14
15         ### 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
22         ### Retrieve known genres.
23         my @genres = $cddbp->get_genres();
24
25         ### 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
39         ### 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
45         ### 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
55         ### Submit a disc via e-mail. (Requires MailTools)
56
57         die "can't submit a disc (no mail modules; see README)"
58           unless $cddbp->can_submit_disc();
59
60         # 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
64         # 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

DESCRIPTION

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
81       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
86       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
90       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

PUBLIC METHODS

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
103           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
108           The new() constructor accepts several parameters, all of which have
109           reasonable defaults.
110
111           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
115           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
121           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
126           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
133           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
137           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
143           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
150       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
154       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
161           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
171           That said, see parse_cdinfo() for a routine to parse "cdinfo"
172           output into a table of contents list suitable for calculate_id().
173
174           calculate_id() accepts TOC information as a list of strings.  Each
175           string contains four fields, separated by whitespace:
176
177           offset 0: the track number
178
179           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
183           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
188           offset 1: the track start time, minutes field
189
190           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
194           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
197           offset 2: the track start time, seconds field
198
199           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
202           offset 3: the track start time, frames field
203
204           This field contains the F part of MSF.  For error tracks, it
205           contains a description of the error.
206
207           Example track file.  Note: the comments should not appear in the
208           file.
209
210                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
216           Track 1000 should not be present if everything is okay:
217
218             1000   0  0  Error reading TOC: no disc in drive
219
220           In scalar context, calculate_id() returns just the cddbp ID.  In a
221           list context, it returns an array containing the following values:
222
223             (
224               $cddbp_id,
225               $track_numbers,
226               $track_lengths,
227               $track_offsets,
228               $total_seconds
229             ) = $cddbp->calculate_id(@toc);
230
231             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
239           CDDBP_ID
240
241           The 0th returned value is the hashed cddbp ID, required for any
242           queries or submissions involving this disc.
243
244           TRACK_NUMBERS
245
246           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
251           TRACK_LENGTHS
252
253           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
258           TRACK_OFFSETS
259
260           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
264           TOTAL_SECONDS
265
266           The 4th and final value is the total playing time for the CD, in
267           seconds.  The get_discs() function needs it.
268
269       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
274             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
279           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
284             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
294           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
299           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
304           DISC_TITLE is the disc's title, which may help a human to pick the
305           correct disc out of several close mathches.
306
307       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
313       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
318           Cddb protocol query strings look like:
319
320             cddb query $cddbp_id $track_count @offsets $total_seconds
321
322       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
327           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
331             $disc_details = get_disc_details( $disc_genre, $cddbp_id );
332
333           $disc_details->{"disc length"}
334
335           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
339           $disc_details->{discid}
340
341           This is a rehash (get it?) of the cddbp ID.  It should match the
342           CDDBP_ID given to get_disc_details().
343
344           $disc_details->{dtitle}
345
346           This is the disc's title.  I do not know whether it will match the
347           one returned by get_discs().
348
349           $disc_details->{offsets}
350
351           This is a reference to a list of absolute disc track offsets,
352           similar to the TRACK_OFFSETS returned by calculate_id().
353
354           $disc_details->{seconds}
355
356           This is a reference to a list of track length, in seconds.
357
358           $disc_details->{ttitles}
359
360           This is a reference to a list of track titles.  These are the
361           droids you are looking for.
362
363           $disc_details->{"processed by"}
364
365           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
369           $disc_details->{revision}
370
371           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
377           $disc_details->{"submitted via"}
378
379           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
383           $disc_details->{xmcd_record}
384
385           The xmcd_record field contains a copy of the entire unprocessed
386           cddbp response that generated all the other fields.
387
388           $disc_details->{genre}
389
390           This is merely a copy of DISC_GENRE, since it's otherwise not
391           possible to determine it from the hash.
392
393       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
398       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
403       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
408             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
416             $cddbp->submit_disc(
417               ...,
418               From => $mail_from,
419             );
420
421       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
426             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
434             $cddbp->submit_disc(
435               ...,
436               Host => $mail_host,
437             );
438
439       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
444             my @toc = parse_cdinfo("cdinfo.txt"); # read cdinfo.txt
445             my @toc = parse_cdinfo("cdinfo|");    # run cdinfo directly
446
447           The table of contents can be passed directly to calculate_id().
448
449       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
455           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
462           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
466           Genre => DISC_GENRE
467
468           This is the disc's genre.  It must be one of the genres that the
469           server knows.  See get_genres().
470
471           Id => CDDBP_ID
472
473           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
477           Artist => DISC_ARTIST
478
479           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
484           DiscTitle => DISC_TITLE
485
486           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
491           Offsets => TRACK_OFFSETS
492
493           This is a reference to an array of absolute track offsets, as
494           provided by calculate_id().
495
496           TrackTitles => TRACK_TITLES
497
498           This is a reference to an array of track titles, either entered by
499           a human or provided by get_disc_details().
500
501           From => EMAIL_ADDRESS
502
503           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
507           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
512           Host => SMTP_HOST
513
514           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
519           Revision => REVISION
520
521           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

PRIVATE METHODS

527       Documented as being not documented.
528

EXAMPLES

530       Please see the cddb.t program in the t (tests) directory.  It exercises
531       every aspect of CDDB.pm, including submissions.
532

COMPATIBILITY

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
538         http://testers.cpan.org/search?request=dist&dist=CDDB
539
540       If you want to submit disc information to the CDDB, you will need to
541       install two other modules:
542
543         Mail::Internet will allow CDDB.pm to send email submissions, and it
544         automagically includes Mail::Header.
545
546         MIME::QuotedPrint will allow CDDB.pm to send non-ASCII text
547         unscathed.  Currently only ISO-8859-1 and ASCII are supported.
548
549       All other features will work without these modules.
550

KNOWN TEST FAILURES

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
558         make test TEST_VERBOSE=1
559
560       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
571   REPOSITORY
572       http://github.com/rcaputo/cddb-perl
573       http://gitorious.org/cddb-freedb-perl
574
575   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.
582
583
584
585perl v5.28.1                      2013-08-15                           CDDB(3)
Impressum