plan9fox/acme/bin/source/acd/access

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.