244 lines
9.6 KiB
Plaintext
244 lines
9.6 KiB
Plaintext
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.
|