Creates a high-level interface to a cddbp server, returning a handle
to it. The handle is not a filehandle. It is an object. The new()
constructor provides defaults for just about everything, but
everything is overrideable if the defaults arent appropriate.
The new() constructor accepts several parameters, all of which have reasonable defaults.
<B>Utf8B> is a boolean flag. If true, utf-8 will be used when submitting CD info, and for interpreting the data reveived. This requires the Encode module (and probably perl version at least 5.8.0). The default is true if the Encode module can be loaded. Otherwise, it will be false, meaning we fall back to ASCII.
<B>Protocol_VersionB> sets the cddbp version to use. CDDB.pm will not connect to servers that dont support the version specified here. The requested protocol version defaults to 1 if <B>Utf8B> is off, and to 6 if it is on.
<B>LoginB> is the login ID you want to advertise to the cddbp server. It defaults to the login ID your computer assigns you, if that can be determined. The default login ID is determined by the presence of a LOGNAME or USER environment variable, or by the getpwuid() function. On Windows systems, it defaults to win32usr if no default method can be found and no Login parameter is set.
<B>Client_NameB> and <B>Client_VersionB> describe the client software used to connect to the cddbp server. They default to CDDB.pm and CDDB.pms version number. If developers change this, please consult freedbs web site for a list of client names already in use.
<B>DebugB> enables verbose operational information on STDERR when set to true. Its normally not needed, but it can help explain why a program is failing. If someone finds a reproduceable bug, the Debug output and a test program would be a big help towards having it fixed. In case of submission, if this flag is on, a copy of the submission e-mail will be sent to the From address.
|get_genres||Takes no parameters. Returns a list of genres known by the cddbp server, or undef if there is a problem retrieving them.|
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).
Note however that there is no standard way to acquire this information from a CD-ROM device. Therefore this module does not try to read the TOC itself. Instead, developers must combine CDDB.pm with a CD library which works with their system. The AudioCD suite of modules is recommended: it has system specific code for MacOS, Linux and FreeBSD. CDDB.pms author has used external programs like dagrab to fetch the offsets. Actual CDs arent always necessary: the author has heard of people generating TOC information from mp3 file lengths.
That said, see parse_cdinfo() for a routine to parse cdinfo output into a table of contents list suitable for calculate_id().
calculate_id() accepts TOC information as a list of strings. Each string contains four fields, separated by whitespace:
offset 0: the track number
Track numbers start with 1 and run sequentially through the number of tracks on a disc. Note: data tracks count on hybrid audio/data CDs.
CDDB.pm understands two special track numbers. Track 999 holds the lead-out information, which is required by the cddb protocol. Track 1000 holds information about errors which have occurred while physically reading the disc.
offset 1: the track start time, minutes field
Tracks are often addressed on audio CDs using MSF offsets. This stands for Minutes, Seconds, and Frames (fractions of a second). The combination pinpoints the exact disc frame where a song starts.
Field 1 contains the M part of MSF. It is ignored for error tracks, but it still must contain a number. Zero is suggested.
offset 2: the track start time, seconds field
This field contains the S part of MSF. It is ignored for error tracks, but it still must contain a number. Zero is suggested.
offset 3: the track start time, frames field
This field contains the F part of MSF. For error tracks, it contains a description of the error.
Example track file. Note: the comments should not appear in the file.
Track 1000 should not be present if everything is okay:
In scalar context, calculate_id() returns just the cddbp ID. In a list context, it returns an array containing the following values:
The 0th returned value is the hashed cddbp ID, required for any queries or submissions involving this disc.
The 1st returned value is a reference to a list of track numbers, one for each track (excluding the lead-out), padded to three characters with leading zeroes. These values are provided for convenience, but they are not required by cddbp servers.
The 2nd returned value is a reference to a list of track lengths, one for each track (excluding the lead-out), in HH:MM format. These values are returned as a convenience. They are not required by cddbp servers.
The 3rd returned value is a reference to a list of absolute track offsets, in frames. They are calculated from the MSF values, and they are required by get_discs() and submit_disc().
The 4th and final value is the total playing time for the CD, in seconds. The get_discs() function needs it.
|get_discs CDDBP_ID, TRACK_OFFSETS, TOTAL_SECONDS||
get_discs() asks the cddbp server for a summary of all the CDs
matching a given cddbp ID, track offsets, and total playing time.
These values can be retrieved from calculade_id().
get_discs() returns an array of matching discs, each of which is represented by an array reference. It returns an empty array if the query succeeded but did not match, and it returns undef on error.
DISC_GENRE is the genre this disc falls into, as determined by whoever submitted or last edited the disc. The genre is required when requesting a discs details. See get_genres() for how to retrieve a list of cddbp genres.
CDDBP_ID is the cddbp ID of this disc. Cddbp servers perform fuzzy matches, returning near misses as well as direct hits on a cddbp ID, so knowing the exact ID for a disc is important when submitting changes or requesting a particular near-miss details.
DISC_TITLE is the discs title, which may help a human to pick the correct disc out of several close mathches.
|get_discs_by_toc TOC||This function acts as a macro, combining calculate_id() and get_discs() calls into one function. It takes the same parameters as calculate_id(), and it returns the same information as get_discs().|
Fetch discs by a pre-built cddbp query string. Some disc querying
programs report this string, and get_discs_by_query() is a convenient
way to use that.
Cddb protocol query strings look like:
|get_disc_details DISC_GENRE, CDDBP_ID||
This function fetches a discs detailed information from a cddbp
server. It takes two parameters: the DISC_GENRE and the CDDP_ID.
These parameters usually come from a call to get_discs().
The discs details are returned in a reference to a fairly complex hash. It includes information normally stored in comments. The most common entries in this hash include:
The disc length is commonly stored in the form ### seconds, where ### is the discs total playing time in seconds. It may hold other time formats.
This is a rehash (get it?) of the cddbp ID. It should match the CDDBP_ID given to get_disc_details().
This is the discs title. I do not know whether it will match the one returned by get_discs().
This is a reference to a list of absolute disc track offsets, similar to the TRACK_OFFSETS returned by calculate_id().
This is a reference to a list of track length, in seconds.
This is a reference to a list of track titles. These are the droids you are looking for.
This is a comment field identifying the name and version of the cddbp server which accepted and entered the disc record into the database.
This is the disc records version number, used as a sanity check (semaphore?) to prevent simultaneous revisions. Revisions start at 0 for new submissions and are incremented for every correction. It is the responsibility of the submitter (be it a person or a program using CDDB.pm) to provide a correct revision number.
This is the name and version of the software that submitted this cddbp record. The main intention is to identify records that are submitted by broken software so they can be purged or corrected.
The xmcd_record field contains a copy of the entire unprocessed cddbp response that generated all the other fields.
This is merely a copy of DISC_GENRE, since its otherwise not possible to determine it from the hash.
|parse_xmcd_file XMCD_FILE_CONTENTS, [GENRE]||Parses an array ref of lines read from an XMCD file into the disc_details hash described above. If the GENRE parameter is set it will be included in disc_details.|
|can_submit_disc||Returns true or false, depending on whether CDDB.pm has enough dependent modules to submit discs. If it returns false, you are missing Mail::Internet, Mail::Header, or MIME::QuotedPrint.|
Returns what CDDB.pm thinks your e-mail address is, or what it was
last set to. It was added to fetch the default e-mail address so
users can see it and have an opportunity to correct it.
Returns what CDDB.pm thinks your SMTP host is, or what it was last set
to. It was added to fetch the default e-mail transfer host so users
can see it and have an opportunity to correct it.
Generates a table of contents suitable for calculate_id() based on the
output of a program called cdinfo. CDINFO_FILE may either be a text
file, or it may be the cdinfo program itself.
The table of contents can be passed directly to calculate_id().
submit_disc() submits a disc record to a cddbp server. Currently it
only uses e-mail, although it will try different ways to send that.
It returns true or false depending on whether it was able to send the
The rest of CDDB.pm will work without the ability to submit discs. While cddbp submissions are relatively rare, most CD collections will have one or two discs not present in the system. Please submit new discs to the system: the amazing number of existing discs got there because others submitted them before you needed them.
submit_disc() takes six required parameters and two optional ones. The parameters are named, like hash elements, and can appear in any order.
Genre => DISC_GENRE
This is the discs genre. It must be one of the genres that the server knows. See get_genres().
Id => CDDBP_ID
Artist => DISC_ARTIST
This is the discs artist, a freeform text field describing the party responsible for the album. It will need to be entered from the discs notes for new submissions, or it can come from get_disc_details() on subsequent revisions.
DiscTitle => DISC_TITLE
This is the discs title, a freeform text field describing the album. It must be entered from the discs notes for new submissions. It can come from get_disc_details() on subsequent revisions.
Offsets => TRACK_OFFSETS
This is a reference to an array of absolute track offsets, as provided by calculate_id().
TrackTitles => TRACK_TITLES
This is a reference to an array of track titles, either entered by a human or provided by get_disc_details().
From => EMAIL_ADDRESS
This is the disc submitters e-mail address. Its not required, and CDDB.pm will try to figure one out on its own if an address is omitted. It may be more reliable to provide your own, however.
The default return address may not be a deliverable one, especially if CDDB.pm is being used on a dial-up machine that isnt running its own MTA. If the current machine has its own MTA, problems still may occur if the machines Internet address changes.
Host => SMTP_HOST
This is the SMTP host to contact when sending mail. Its not required, and CDDB.pm will try to figure one out on its own. It will look at the SMTPHOSTS environment variable is not defined, it will try mail and localhost before finally failing.
Revision => REVISION
The revision number. Should be 1 for new submissions, and one higher than the previous one for updates. The previous revision number is available as the revision field in the hash returned by get_disc_details().
Documented as being not documented.
Please see the cddb.t program in the t (tests) directory. It exercises every aspect of CDDB.pm, including submissions.
CDDB.pm uses standard Perl modules. It has been tested at one point or another on OS/2, MacOS and FreeBSD systems, as well as the systems listed at:
If you want to submit disc information to the CDDB, you will need to install two other modules:
Mail::Internet will allow CDDB.pm to send email submissions, and it automagically includes Mail::Header. MIME::QuotedPrint will allow CDDB.pm to send non-ASCII text unscathed. Currently only ISO-8859-1 and ASCII are supported.
All other features will work without these modules.
The last test in the make test suite will try to send a sample submission to the CDDB if MailTools is present. It expects to find an SMTP host in the SMTPHOST environment variable. It will fall back to mail if SMTPHOST doesnt exist. If neither works, the test will be skipped. To see why its skipped:
make test TEST_VERBOSE=1
Some of the tests (most notably numbers 25, 27 and 29) compare data returned by a cddbp server against a stored copy of a previous query. These tests fail occasionally since the database is constantly in flux. Starting with version 1.00, the test program uses fuzzy comparisons that should fail less. Version 1.04 saw even fuzzier comparisons. Please report any problems so they can be fixed.
Copyright 1998-2013 Rocco Caputo. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
|perl v5.20.3||CDDB (3)||2013-08-15|