NAME

Net::CDDB - Communicate with CDDB Servers using CDDB Protocol


SYNOPSIS

  use Net::CDDB;

  my $disc_data = `discid`;
  chomp($disc_data);

  my($cat,$disc_id,$artist,$title) = cddb_query($disc_data);

  print "Category: $cat\n";
  print "DiscID  : $disc_id\n";
  print "Artist  : $artist\n";
  print "Title   : $title\n";

  my($title,@tracks) = cddb_read("$cat $disc_id");
  my $num_tracks = $#tracks + 1;

  print "Album: $title\n";
  print "$num_tracks tracks\n";
  foreach (@tracks) {
      $num++;
      print "$num. $_\n";
  }


DESCRIPTION

Net:CDDB provides an easy to use functional (non-OO) interface for communicating with Internet CDDB servers using the CDDB protocol (not CDDB over HTTP).

See the CDDB INFO section, below, for more info about CDDB itself.


VARIABLES

Net::CDDB exports a minimal number of variables into the user's namespace by default. They are all prefixed with `cddb' so as to prevent obvious naming clases. They all correspond to information that is required for a CDDB client to proivde to a CDDB server. They are:

$cddb_server

The fully qualified domain name (or IP address) of the CDDB server that you'd like to use. This will default to cddb.cddb.com if you don't specify one. Folks in other parts of the world will certainly want to change this to something closer.

$cddb_port

The port number on which the CDDB server is listening. This will default to 888 if you don't specify one. Since 888 is the CDDB standard port, it is unlikely that you'll need to change this unless you're talking to an experimental server.

$cddb_localuser

The username that you'd like to use to identify yourself with when Net::CDDB contacts the server. Though this will default to nobody, I hightly recommend that you supply a valid username.

$cddb_localhost

The hostname you'd like to use when identifying yourself with when Net::CDDB contacts the server. Most CDDB srevers combine $cddb_localuser and $cddb_localhost to come up with your e-mail address, so you should probably just use those values. This will default to localhost.localdomain if you don't specify.

$Net::CDDB::debug

Not exported by default, you may set $Net::CDDB::debug to a non-zero value if you'd like to enable debugging output. This would be helpful if you're trying to track down a problem.


METHODS

Net:CDDB exports a minimal number of methods into the user's namespace by default. Most of them correspond to CDDB protocol verbs. They are:

cddb_query($discinfo)

Performs a CDDB query on the given $discinfo. In this case, $discinfo is a string which contains:

  <discid> <track offsets> <disc length in seconds>

For example, the $discinfo string for Deep Forrest's Boheme CD looks like this: (line wrapped to improve readability)

  940a070c 12 150 8285 32097 51042 71992 86235 100345 105935 120932
  139472 158810 171795 2567

For more information about calcualting that information, see the TOOLS section late in this document.

cddb_query() returns the following sort of array:

  ($category,$discid,$artist,$title)

If the query is successful and an exact match is found, all of those variables will contain data. You will probably want to hang on to $category and $discid so that you can pass them to cddb_read() and get all the info you're really after.

If the query is successful but only finds inexact matches, $category will contain the word inexact and all the other values will be undef. You will probably want to call cddb_inexact() and pass it the same $discdata that you passed this function.

If the query fails for some reason (not found, corrupt database entry, or improper protocol handshake), all the values will be undef. There is currently no way to find out which of those three errors occurred.

cddb_read($category,$discid)

Performs a CDDB read command on a given category and discid. One would usually call

cddb_inexact($discdata)

Query on $discdata and retrieve the list of inexact matches so that you (or the user) can select the proper one. The $discdata argument is exactly the same as the one used in cddb_query().

cddb_inexact() returns a hash that looks like this:

  $discs{$discid} = "[$category] - $dtitle";

where $dtitle is the DTITLE record on the CDDB database.

This will eventually change to a list structure. I just haven't finished that part of the code yet.

cddb_lscat()

Retrieve a list of the music categories the server uses. cddb_lscat() requires no arguments and simply returns a list. It can't get much easier than that.

cddb_sites()

Retrieve a list of the sites the CDDB server knows about. cddb_sites() requires no arguments and simply returns a list. It really doesn't get any easier.


CDDB INFO

CDDB is an acronym for ``CD Database''. It also refers to the CDDB protocol (TCP port 888) which is used to query CDDB databases to retrieve and update information about music CDs.

For information about CDDB and the CDDB protocol spec, please visit http://www.cddb.com/ which is the official CDDB Web site.

This module implements most of the CDDB protocol version 1.


TOOLS

There are many tools for calculating the disc info needed to query the CDDB. Some of the more popular CD ``rippers'' (such as cdda2wav) can extract the needed informaton. However, not being happy with having to use a whole different software package to do the job, I wrote a small C program that does exactly what I need and no more. As a result, the program is quite small.

So, check your favorite CD ripper. If it doesn't do the job, grab my discid program and see if it does the trick for you. I will eventually re-write it in Perl and include it in this distribution, but untill then you can grab it from the following address:

  http://www.wcnet.org/~jzawodn/c/discid/


BUGS

We could have better error reporting.

When an album has multiple discids in the CDDB database, cddb_read() will return them as a comma separated list. We should handle that properly.

cddb_inexact() really needs to use arrary references in the hash it returns instead of the hackish approach we use now.

This module is ``read-only'' which is to say that it doesn't allow you to submit CDDB records to a server. I don't currently have a need for that functionality, so I haven't added it.


AUTHOR AND COPYRIGHT

Copyright 1998, Jeremy D. Zawodny <jzawodn@wcnet.org>

Net::CDDB is covered under the GNU Public License (GPL) version 2 or later.

The Net::CDDB Web site is located at:

  http://www.wcnet.org/~jzawodn/perl/Net-CDDB/