Subversion Repositories planix.SVN

TWO FORMS OF ACCESS TO THE FREEDB

---------------------------------

In the following document we will refer to CDDB instead of freedb, since 

from a technical point of view, freedb is a CDDB-Server as it uses the 

CDDB-protocol.

If you are interested in incorporating the use of freedb in your

software, there are two forms of access that you may consider.

1. <a href="#local">Local access</a>

   In this mode your software simply attempts to open local files on

   the computer to access the CDDB.

2. <a href="#remote">Remote access</a>

   In this mode the software must connect to a freedb server on the

   network to access the CDDB.  There is a CDDB server protocol that

   the software (also known as the "client") must use to converse with

   the server.

You may choose to support either one, or both of these modes.

CDDB DISCID

-----------

Both forms of CDDB access requires that the software computes a "disc

ID" which is an identifier that is used to access the CDDB.  The disc

ID is a 8-digit hexadecimal (base-16) number, computed using data from

a CD's Table-of-Contents (TOC) in MSF (Minute Second Frame) form.  The

algorithm is listed below in the <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=6">DISCID Howto</a>.

It is crucial that your software compute the disc ID correctly.  If it

does not generate the disc ID, it will not be compatible with the

CDDB.  Moreover, if your software submits CDDB entries with bad disc

IDs to the freedb archives, it could compromise the integrity of the

freedb.

If you have access to a UNIX platform that xmcd supports, we suggest 

installing xmcd, and then test the disc ID code in your software by

comparing the disc ID generated by xmcd with that of your software,

for as large a number of CDs as possible.

<a name="local"></a>LOCAL CDDB ACCESS

-----------------

There are two forms of the CDDB archive available, the standard form

and the alternate form.  Both forms are available for download from 

various servers. You can always find an actual list of mirrors on the 

freedb-homepage at <a href="http://freedb.freedb.org">http://freedb.freedb.org</a>.

The standard form of the CDDB archive is released to the public as 

a UNIX tar(1)-format archive, compressed with gzip.  The alternate 

form  archive is in the .zip format that is popular on the Windows 

platform.

Standard Form:

--------------

Each CD entry is a separate file in the xmcd CDDB.  These files are

organized in several directories, each directory is a category of

music.  Currently the "official" categories are listed as follows:

	blues

	classical

	country

	data

	folk

	jazz

	misc

	newage

	reggae

	rock

	soundtrack

The individual CDDB files have a file name that is the 8-digit disc

ID. For example, under the blues directory there may be the following

files:

	0511c012

	060e7314

	0c01e902

	0f0c3112

	...

	fa0f6f10

	fb0f8814

	fd0e6013

To access the CDDB entry associated with a CD, your software simply

opens the appropriate file and reads the information.

The content of each of these files is in a format described in the 

<a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>.

Different pressings of a particular CD title may contain differences

in timings that can cause the computed disc ID to be different.

The CDDB allows this by having multiple file names be links to

the same file.  The links are implemented as actual filesystem links

(see the ln(1) command) on UNIX systems.  For example, the following

files in the rock directory are all links to the same file, and

refer to the CD "Pink Floyd / The Division Bell".:

	850f740b

	850f950b

	850f970b

	860f960b

	890f970b

Xmcd and the CD database server use this form of the CDDB archive.  The

benefit of the standard form of the CDDB archive is very fast access,

and ease of add/delete/edit operations on entries.

Alternate Form:

---------------

Due to limitations in the FAT file system used on Windows 9x and 

Windows ME, it is unfeasible to use the standard format CDDB archive 

due to the large number of files.  This is because such a filesystem 

operates on fixed-size clusters and even a small file (and most CDDB

files are 1KB or less) would consume the space of a full cluster

(Depending upon disk size, a cluster can range from 4KB to 32KB in 

size).  Thus, a tremendous amount of disk space would be wasted on

these systems if the CDDB archive is used in its standard form.

An alternate form of the CDDB archives was created for use by software

that must operate on a system with the FAT limitations.

The alterate form still use the separate category directories as the

standard form, but concatenates many files into a smaller number of

files under each category.  The first two digits of the CDDB file names

is used as a key for concatenation, each file is allowed to grow to

approximately 64KB in size before a new file is started.  The file name

indicates what range of the digits are included in that file.  For

example, under the blues category we may have the following files:

	01to36

	37to55

	56to71

	...

	b2tod7

	d8toff

The 01to36 file contains all CDDB entries with disc ID 01xxxxxx,

02xxxxxx, 03xxxxxx and so on, up to 36xxxxxx.

Each entry in the concatenated file begins with the keyword

#FILENAME=xxxxxxxx

where discid is the 8-digit hexadecimal disc ID of that entry.  Your

software must search through the appropriate file to locate the desired

entry.  The CDDB entry is in the format described in Appendix B below.

The alternate form avoids the problem of inefficient disk space

utilization on FAT-based filesystems, but is slower to access than the

standard form, and it is much more cumbersome to perform add/delete/edit

operations on a CDDB entry.

<a name="remote"></a>REMOTE CDDB ACCESS

------------------

Your software must be able to communicate with a remote CD server

system via TCP/IP or HTTP.  

There are a number of public freedb servers operating

on the Internet.  The <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=9">current list of public servers</a> is listed on the

freedb web page at:

    http://freedb.freedb.org.

It may also be obtained programmatically via the CDDB protocol "sites" 

command.

TCP/IP access:

All current freedb servers answer at TCP port 888.  There may be future

sites that deviate from this convention, however.

HTTP access:

The freedb-servers can be accessed via the cddb.cgi. This is resides at the

following path: /~cddb/cddb.cgi 

Thus, the URL for accessing the server at freedb.freedb.org is:

http://freedb.freedb.org/~cddb/cddb.cgi

You should make the freedb server host (or hosts) and port numbers

user-configurable in your software.  Do not hard-wire the list of

CD database servers into your code.  The list of active servers changes

over time.

The CDDB server protocol is described in the <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=28">CDDB-protocol documentation</a>.

The CDDB entry returned from the server via a "cddb read" command is in

the format described <a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>.

You may experiment with the freedb server by connecting to port 888 of

the server host via the "telnet" program, and then typing the cddb

protocol commands by hand.  For example:

	telnet freedb.freedb.org 888

connects you to the freedb server at freedb.freedb.org.

Some additional notes for accessing freedb over the Internet:

Your application should always specify the highest documented protocol

level. The highest level currently supported is "3". Lower protocol 

levels will work, but are only provided for compatibility with older 

CDDB applications. If you do not use the highest available protocol 

level, certain important features will not be available to your 

application.

Make sure to use the proper arguments with the "hello" command. The user

and hostname arguments should be that of the user's email address, not

some fixed hard-coded value. The application name and version should be

that of your application, not that of another existing application.

We consider the use of the "cddb query" command mandatory for all CDDB

clients. It is not valid to issue a "cddb read" command without issuing

a prior "cddb query" and receiving a good response, as it may yield incorrect

results. In addition, it is clients should support close matches

(aka "fuzzy" matches, or response code 211).

The proper way to handle multiple fuzzy matches is to present the

entire list of matches to the user and to let the user choose between them.

Matches are listed in the order of best fit for the user's disc, so they

should be presented to the user in the order they are listed by the server.

The suggested algorithm for obtaining the list of server sites is

as follows.  The application should offer to get the list from

freedb.freedb.org with the "sites" command the first time the user runs 

the program. Additionally the application should provide the user with 

some method of downloading the list on-demand.

We do strongly suggest that you provide your users with the capability of

choosing freedb server sites as described above. However, for some 

applications this may not be feasible. If you do not wish to offer this 

functionality, you may safely hard-code "freedb.freedb.org" in your 

application as the sole freedb site to access. This will deprive your users

of the option to choose a site near their locale for optimal response, but

that is your choice.