NAME

CDDB.pm - a high-level interface to the Internet Compact Disc Database

SYNOPSIS

use CDDB;

### connect to the CDDB server
my $cddb = new CDDB( Host => 'www.cddb.com',          # default
                     Port => 8880,                    # default
                   ) or die $!;

### retrieve known genres
my @genres = $cddb->get_genres();

### calculate CDDB ID based on MSF info
my @toc = ( '1    0  2 37',           # track, CD-i MSF (space-delimited)
            '999  1 38 17',           # lead-out track MSF
            '1000 0  0 Error!',       # error track (don't include if ok)
          );
my ($cddb_id,       # used for further CDDB queries
    $track_numbers, # padded with 0's provided as a convenience
    $track_lengths, # length of each track, in MM:SS format
    $track_offsets, # absolute offsets (used for further CDDB queries)
    $total_seconds  # total play time, in MM:SS format
   ) = $cddb->calculate_id(@toc);

### query discs based on CDDB ID and other information
my @discs = $cddb->get_discs($cddb_id, $track_offsets, $total_seconds);
foreach my $disc (@discs) {
  my ($genre, $cddb_id, $title) = @$disc;
}

### query disc details (usually done with get_discs() information)
my $disc_info     = $cddb->get_disc_details($genre, $cddb_id);
my $disc_time     = $disc_info->{'disc length'};
my $disc_id       = $disc_info->{'discid'};
my $disc_title    = $disc_info->{'dtitle'};
my @track_offsets = @{$disc_info->{'offsets'}};
my @track_titles  = @{$disc_info->{'ttitles'}};
# other information may be returned... explore!

### submit a disc (via e-mail, requires MailTools)
$cddb->submit_disc
  ( 'Genre'       => 'classical',
    'Id'          => 'b811a20c',
    'Artist'      => 'Various',
    'DiscTitle'   => 'Cartoon Classics',
    'Offsets'     => $disc_info->{'offsets'}, # array reference
    'TrackTitles' => $disc_info->{'ttitles'}, # array reference
    'From'        => 'login@host.domain.etc', # will try to determine
  );

DESCRIPTION

The CDDB serves compact disc information for programs that need it. CDDB.pm provides a Perl interface to the CDDB server protocols. With it, a Perl program can identify a CD based on its "table of contents" (CD-i MSF information), list its track titles, and manage track times.

This information could be useful for generating CD catalogs, naming MP3 files, or even playing CDs in an automated jukebox.

PUBLIC METHODS

new(...)

Creates a CDDB server interface, returning a handle to it. This interface does not connect to the server until needed, and the CDDB protocol may require several separate connections (sometimes one per query).

new accepts these parameters: Host (defaults to www.cddb.com), Port (defaults to 8880) and Debug (defaults to boolean false) parameters.

get_genres()

Takes no parameters. Returns a list of genres known by the CDDB server, or undef if there is an error.

calculate_id(...)

The CDDB protocol defines an ID as a hash of track lengths and the number of tracks, with an added checksum. The most basic information required to calculate this is the CD table of contents (the CD-i track offsets, in MSF [Minutes, Seconds, Frames] format).

calculate_id(...) accepts TOC information as a list of strings. Each string contains four fields, separated by whitespace:

1. The track number, starting with 1.

Special track numbers are 999, for the CD lead-out information; and 1000, to indicate that an error has occurred while acquiring the CD information (error tracks modify the meaning of the other fields; look below).

2. The track start, in minutes (the M in MSF).

If a track starts at 01:23 and 5 frames, then this field is 1. In an error track, this field is ignored (but is expected to contain something; usually 0).

3. The track start, in seconds (the S in MSF).

If a track starts at 01:23 and 5 frames, then this field is 23. In an error track, this field is ignored (but is expected to contain something; usually 0).

4. The track start, in frames (the F in MSF).

If a track starts at 01:23 and 5 frames, then this field is 5. In an error track, this field contains an error message (which may contain spaces).

calculate_id(...) returns just the ID in scalar context. In array context, it returns an array containing the following values (in the order listed here):

$cddb_id

This is the hashed CDDB ID, required for any queries involving this CD, as well as submit_disc(...).

$track_numbers

This is a reference to an array containing the track numbers, padded to three characters with leading zeroes. It is provided for convenience and is not required by the CDDB.

$track_lengths

The MSF information provided to calculate_id(...) refers to track offsets. This is a reference to an array containing the track lengths in MM:SS format, as computed from the MSF offsets. This information is provided for convenience and is not required by the CDDB.

$track_offsets

These are absolute frame offsets as calculated by the MSF information. They are required by get_discs(...) and submit_disc(...).

$total_seconds

This is the calculated total playing time for the CD. It is required by get_discs(...).

get_discs(...)

get_discs(...) asks the CDDB server for all its CDs that match the given ID, track offsets list, and total seconds (combined). The CDDB performs "fuzzy" matching and may return more than one disc.

get_discs(...) takes three parameters:

$cddb_id

This is the CDDB ID, as generated by calculate_id(...).

$track_offsets

This may be in two formats.

The first format is a reference to an array of absolute track offsets, similar to ones generated by calculate_id(...).

The second format is a string containing the track count and the absolute offsets, separated by whitespace.

$total_seconds

The total playing time for the CD, as generated by calculate_id(...).

get_discs(...) returns an array of matching discs, each of which is represented by an array reference.

Each disc record contains three elements, two of which can be used later on:

$genre

The genre this disc falls into, as determined by whoever submitted the disc in the first place (see get_genres()).

$cddb_id

The actual CDDB ID, which may be different than the one supplied to get_discs(...) due to fuzzy matching.

$title

The title of this disc.

get_disc_details(...)

This function fetches the detailed information for a CD. It takes two parameters: the disc $genre and the $cddb_id.

It returns a hash reference containing as much information as it can. The information includes data normally stored in comments. The most common entries this function returns include:

'disc length'

This is the total playing time for the disc, as recorded in the CDDB. Commonly it is in the form "somenumber seconds", but since the CDDB stores it in a comment, it could say just about anything.

'discid'

This is a rehash (get it?) of the CDDB ID, and should match the $cddb_id parameter to get_disc_details(...).

'dtitle'

This is the disc title, again.

'offsets'

This is a reference to an array of absolute disc track offsets, in CD frames.

'ttitles'

This is a reference to an array of track titles. These are the droids you are looking for.

'processed by'

This is a comment field, identifying the CDDB server name and version.

'revision'

This is the version number for the CD record. Revisions start at 1 and are incremented for every correction. It is the responsibility of the submitter to provide a correct revision number, as sort of a sanity check.

'submitted via' is the name and version of the software that submitted this CDDB record. The main intention is to identify records that are submitted by broken software so they can be purged or corrected.

submit_disc(...)

submit_disc(...) submits a disc record to the CDDB. The CDDB accepts disc submissions through e-mail, so this function requires MailTools to operate. The rest of CDDB.pm will operate without MailTools being installed (since CDDB submissions are relatively rare), but submit_disc(...) will croak if MailTools are not installed.

submit_disc(...) takes six required parameters and two optional parameters. The parameters are in pairs, like 'Parameter' = $value>, and can appear in any order. Here goes:

'Genre'

This is the disc genre. It must be one of the genres that the server knows (see get_genres()).

'Id'

This is the CDDB ID, as calculated from calculate_id(...).

'Artist'

This is the disc artist, gleaned from the CD liner, and entered by a human.

'DiscTitle'

This is the disc title, gleaned from the CD liner, and entered by a human.

'Offsets'

This is a reference to an array of absolute track offsets, as provided by calculate_id(...).

'TrackTitles'

This is a reference to an array of track titles, gleaned from the CD liner, and entered by a human.

'From'

This is the disc submitter's e-mail address. It is not required, and will default to the current user's login ID at the current machine. The CDDB will send this person a return receipt, including the full headers and body of the submitted e-mail.

The default return address may not be a deliverable address, especially if CDDB.pm is being used on a dial-up machine that isn't running its own MTA. If the current machine has its own MTA, problems still may occur if the machine's Internet address changes.

'Host'

This is the SMTP host to contact when sending mail. It is not required, and if omitted will default to the SMTPHOSTS environment variable. If SMTPHOSTS is not defined, it will fall back to 'mail'. If 'mail' is not a machine running an SMTP daemon, then submit_disc(...) will croak.

PRIVATE METHODS

Documented as being not documented.

EXAMPLES

Please see the cddb.t program in the t (tests) directory. It exercises every aspect of CDDB.pm.

BUGS

There are no known bugs, but see the README for things that need to be done.

CONTACT AND COPYRIGHT

Copyright 1998 Rocco Caputo <troc@netrus.net>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.