ref: 66b1a83b7468fe35e11996ca1b12d00fe41f75c5
dir: /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.