xref: /dports/audio/mp3c/mp3c-0.31/CDDB_HOWTO

	    USE OF CDDB SERVICE IN YOUR SOFTWARE
	    ------------------------------------
		  Copyright (c) CDDB, Inc.

		  @(#)cddb.howto	1.27 98/12/09



	In this document:

	- WHAT IS THE CDDB
	- CDDB USE RESTRICTIONS
	- TWO FORMS OF ACCESS TO THE CDDB
	- CDDB DISCID
	- REMOTE CDDB ACCESS
	- CDDB SUBMISSION
	- QUESTIONS?
	- APPENDIX A - CDDB DISCID ALGORITHM
	- APPENDIX B - CDDB FILE FORMAT
	- APPENDIX C - CDDB SERVER PROTOCOL
	- APPENDIX D - OFFICIAL CDDB SOFTWARE DISTRIBUTION SITES



WHAT IS THE CDDB
----------------

CDDB (CD database) is an information database containing artist, disc
title, track titles, and other information for digital audio compact
discs. Over time, this archive has grown to contain a substantial
collection of CD information and is continuing to grow at a rapid rate.
This database can be accessed by applications via the CDDB server hosts
that have been set up on the Internet around the world.

The CDDB data format and the CDDB servers are designed to be open, and
are used by many client applications requiring CD information. CDDB has
become the de facto standard for Internet access of compact disc
information.


CDDB USE RESTRICTIONS
---------------------

Users of CDDB-capable freeware and shareware applications may use the
public CDDB servers for free. Commercial uses of CDDB data and/or servers
are subject to negotiations with CDDB Inc. Please write to us at
licensing@cddb.com for more information.

If you plan to use CDDB and/or the CDDB servers in your software, please
notify support@cddb.com of your intent. Also, we appreciate that you
keep us posted as to your development/test progress and release schedules.
Before you release your CDDB application we must verify that it properly
implements the CDDB functionality. You must provide us with a copy of your
software for testing when it is ready. Please do not release your software
with CDDB functionality until it has been tested.

You must explicitly give credit to CDDB, Inc. in your application, both in
all documentation that mentions the CDDB functionality in any way, and when
the product is operating. The exact details should be obtained from
licensing@cddb.com before you release your software.



TWO FORMS OF ACCESS TO THE CDDB
-------------------------------

If you are interested in incorporating the use of CDDB in your
software, there are two forms of access that you may consider.

1. Local access

   In this mode your software simply attempts to open local files on
   the computer to access the CDDB.

   You may store the CD information in the CDDB-native format (See
   Appendix B), or another format of your choice (for example, the
   Win95 cdplayer.ini format). Users appreciate a the ability to import
   CDDB data from and export to a variety of formats.

   Note that the CDDB archive is not available for downloads, therefore
   this mode is only useful to retrieve CD data that is entered by the
   user and saved to disk.

2. Remote access

   In this mode the software must connect to a CDDB 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.

   This mode allows the client application full access to the entire
   CD database over the Internet.  The data returned is in the CDDB
   native file format as described in Appendix B.

You may choose to support only remote access mode, or both remote and
local. We do not recommend a local-only application, since it is not
very useful.


CDDB DISCID
-----------

Both forms of CDDB access require that the software compute 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 Appendix A.

It is crucial that your software compute the disc ID correctly.  If it
does not generate the correct disc ID, it will not be compatible with CDDB.
Moreover, if your software submits CDDB entries with bad disc IDs to the
CDDB archives, it could compromise the integrity of the CDDB.

We suggest installing one of the disc ID checker programs listed on the
CDDB web page at http://www.cddb.com/downloads, and then testing the disc
ID code in your software by comparing the disc ID generated by the program
with that of your software for as large a number of CDs as possible. Bugs
in disc ID calculation can be subtle, and history shows that it sometimes
takes hundreds of discs to find problems.


REMOTE CDDB ACCESS
------------------

In order to perform remote access of CDDB servers, your software must be
able to communicate with a remote CD server system via HTTP. There are a
number of public CDDB servers operating on the Internet. The current list
of public servers may be obtained programmatically via the CDDB protocol
"sites" command. The permanent server site, cddb.cddb.com has been
established in order to provide a reliable source of server site information
via the "sites" command. This address may be safely hard-wired into client
software for this purpose, as it is guaranteed to exist on a permanent basis.
Furthermore, the "cddb.cgi" program is guaranteed to always reside at the
following path: /~cddb/cddb.cgi

Thus, the URL for accessing the server at cddb.cddb.com is:

http://cddb.cddb.com/~cddb/cddb.cgi

You should make the CDDB server host (or hosts) user-selectable 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 below in Appendix C.

The CDDB entry returned from the server via a "cddb read" command is in
the format described in Appendix B below.

Some additional notes for accessing CDDB over the Internet:

Your application should always specify the highest documented protocol
level in the "proto=" field of the HTTP command. The highest level currently
specified is "4". 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 in 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 required that clients support close matches
(aka "fuzzy" matches, or response code 211) and multiple exact matches
(response code 210) in response to a query.

The proper way to handle multiple exact/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 attempt to get the list from
cddb.cddb.com with the "sites" command the first time the user runs the
program. After the initial download of the site list, the application
should periodically attempt to download the site list, or at least
provide the user with some method of downloading the list on-demand.
Should the user be unable to subsequently download the list of sites
due to temporary network perturbation, the application should attempt
to download the site list from one of the sites in its current list. All
of the official CDDB server sites will contain a valid list of servers,
though cddb.cddb.com is the only site which is guaranteed to always exist.

We do strongly suggest that you provide your users with the capability of
choosing CDDB 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 "cddb.cddb.com" in your application as the sole
CDDB 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.

PLEASE NOTE: older versions of the CDDB specification describe two methods
of accessing the CDDB servers: HTTP mode and CDDBP mode. CDDBP mode is
being deprecated in favor of HTTP mode, so new applications should be sure
to only implement the HTTP mode of access. All text describing CDDBP
mode has been removed from this document.


CDDB SUBMISSION
---------------

Your software may allow users to enter CDDB data and then submit it to the
CDDB archives. The method of submission is to transmit the entry to the
database through a CGI program at the following URL:

http://hostname.cddb.com/~cddb/submit.cgi

where "hostname.cddb.com" is one of the hosts listed in the CDDB server
"sites" command, and also cddb.cddb.com.

Submissions are made through the CGI program as follows. You must only use
the "POST" method of sending data; "GET" is not supported. There are several
HTTP "Entity-Header" fields that must be included in the data followed by a
blank line, followed by the "Entity-Body" (a.k.a the CDDB entry) in the
format described in Appendix B below. The required header fields are:

Category: CDDB_category
Discid: CDDB_discid
User-Email: user@domain
Submit-Mode: test_or_submit
Content-Length: length_of_CDDB_entry

Where:

- "CDDB_category" is one of the valid CDDB categories listed by the CDDB
  server "cddb lscat" command. Invalid categories will result in the entry
  being rejected.

- "CDDB_discid" is the 8-digit hex CDDB disc ID of the entry as described in
  the "CDDB Discid" section below. This must be the same disc ID that appears
  in the "DISCID=" section of the entry being submitted. If not, the entry
  will be rejected.

- "user@domain" is the valid email address of the user submitting the entry.
  This is required in case a submission failure notice must be sent to the
  user.

- "test_or_submit" is the word "test" or "submit" (without the surrounding
  quotes) to indicate whether the submission is a test submission or a real
  submission to the database, respectively. See below for an explanation of
  test submissions.

- "length_of_CDDB_entry" is the size in bytes of the CDDB entry being
  submitted. This number does not include the length of the header or the
  blank line separating the HTTP header and the CDDB entry.

There are several additional optional HTTP header fields that may also
be specified:

Charset: character_set_of_CDDB_entry
X-Cddbd-Note: message for user

Where:

- "character_set_of_CDDB_entry" is one of ISO-8859-1 or US-ASCII (lower case
  may be used if desired). This specifies to the CDDB server which character
  set the CDDB entry has been encoded in. If your application knows the
  user's character set, then you should specify it here. Only these two
  character sets are supported currently. DO NOT specify the character set
  if your application does not have any way of verifying the user's character
  set (i.e. do not guess; it's better not to specify it at all).

- "message for user" is an arbitrary message to be included at the top of
  any rejection notice that may be sent to the submitting user.

An example submission showing the HTTP command, "Entity-Header" and "Entity-
Body" follows:

POST /~cddb/submit.cgi HTTP/1.0
Category: rock
Discid: 2a09310a
User-Email: joe@joeshost.joesdomain.com
Submit-Mode: submit
Charset: ISO-8859-1
X-Cddbd-Note: Problems with Super CD Player? Send email to support@supercd.com.
Content-Length: 820

# xmcd
# Copyright (c) 1998 CDDB Inc.
#
# Track frame offsets:
[ data omitted in this example for brevity ]
PLAYORDER=

Note the blank line between the "Content-Length" header field and the
"# xmcd" which marks the beginning of the CDDB entry.

When your application submits an entry through the CGI program, it will
respond with a 3-digit response code indicating whether or not the entry has
been forwarded to the CDDB server for inclusion in the database, followed
by a textual description of the response code. For example:

200 OK, submission has been sent.
400 Internal error: failed to forward submission.
500 Missing required header information.

These are but a few of the possible responses. See the description of the
CDDB server protocol in Appendix C for more information on handling response
codes.

The body of the CDDB entry being submitted should be sent verbatim as
described in Appendix B. DO NOT encode the data in any way before transmitting
it; data must be sent as raw text. For example, Windows programmers should not
use the Windows URL encode function prior to calling the submit CGI program.
Doing so may lead to corrupt data being sent and also possibly to rejected
submissions.

You may implement a button or somesuch in your software's user interface
to initiate submissions. Rejected submissions are automatically returned
via email to the sender specified in the "User-Email" header field with an
explanation of the reason for the rejection.

Please do not allow a user to submit CD database entries that have
completely unfilled contents (i.e., blank information in the disc
artist/title as well as the track titles).  Please design your client
with this in mind.  An example minimum requirement that a CD player client
should meet is listed below:

1. Don't allow the "send" or "submit" feature to be activated if
   the CD database information form is not edited at all.
2. Check that the disc artist/title contains something (that the user
   typed in).
3. Don't submit a default string if a field is not filled in
   (e.g. If track 3 is not filled in, submit a blank "TTITLE3=" line.)
   If you must use a default string, please use "track N" where N
   is the track number.

Before you release your software, please be sure that it produces
submissions that adhere to the CDDB file format, and that the frame
offset, disc length, and disc ID information are correctly computed.
For testing, please make your software send submissions with the
"Submit-Mode" HTTP header field set to "test".

CDDB submissions sent in test mode will be sanity-checked by the CDDB server
and pass/fail confirmation sent back to the submitter, but will not actually
be deposited in the CD database. Please DO NOT send submisions in "submit"
mode until your application has been approved by the CDDB support group.

When you feel your application is ready to support submissions, please contact
us at support@cddb.com. We will provide you with our qualification
procedure, which involves submitting a number of entries of different types.
Once qualified, your application will be permitted to submit to the database.


QUESTIONS?
----------

Please send any questions or comments to support@cddb.com.

APPENDIX A - CDDB DISCID ALGORITHM
----------------------------------

The following is a C code example that illustrates how to generate the
CDDB disc ID. Examples in other programming languages may be found on
the CDDB web site at http://www.cddb.com/downloads. A text description
of the algorithm follows, which should contain the necessary information
to code the algorithm in any programming language.


struct toc {
	int	min;
	int	sec;
	int	frame;
};

struct toc cdtoc[100];

int
read_cdtoc_from_drive(void)
{
	/* Do whatever is appropriate to read the TOC of the CD
	 * into the cdtoc[] structure array.
	 */
	return (tot_trks);
}

int
cddb_sum(int n)
{
	int	ret;

	/* For backward compatibility this algorithm must not change */

	ret = 0;

	while (n > 0) {
		ret = ret + (n % 10);
		n = n / 10;
	}

	return (ret);
}

unsigned long
cddb_discid(int tot_trks)
{
	int	i,
		t = 0,
		n = 0;

	/* For backward compatibility this algorithm must not change */

	i = 0;

	while (i < tot_trks) {
		n = n + cddb_sum((cdtoc[i].min * 60) + cdtoc[i].sec);
		i++;
	}

	t = ((cdtoc[tot_trks].min * 60) + cdtoc[tot_trks].sec) -
	    ((cdtoc[0].min * 60) + cdtoc[0].sec);

	return ((n % 0xff) << 24 | t << 8 | tot_trks);
}

main()
{
	int tot_trks;

	tot_trks = read_cdtoc_from_drive();
	printf("The discid is %08x", cddb_discid(tot_trks));
}


This code assumes that your compiler and architecture support 32-bit
integers.

The cddb_discid function computes the discid based on the CD's TOC data
in MSF form.  The frames are ignored for this purpose.  The function is
passed a parameter of tot_trks (which is the total number of tracks on
the CD), and returns the discid integer number.

It is assumed that cdtoc[] is an array of data structures (records)
containing the fields min, sec and frame, which are the minute, second
and frame offsets (the starting location) of each track.  This
information is read from the TOC of the CD.  There are actually
tot_trks + 1 "active" elements in the array, the last one being the
offset of the lead-out (also known as track 0xAA).

The function loops through each track in the TOC, and for each track
it takes the (M * 60) + S (total offset in seconds) of the track and
feeds it to cddb_sum() function, which simply adds the value of each digit
in the decimal string representation of the number. A running sum of this
result for each track is kept in the variable n.

At the end of the loop:
1. t is calculated by subtracting the (M * 60) + S offset of the lead-out
minus the (M * 60) + S offset of first track (yielding the length of
the disc in seconds).

2. The result of (n modulo FFh) is left-shifted by 24 bits.

3. t is left shifted by 8.

The bitwise-OR operation of result 2., 3. and the tot_trks number is
used as the discid.

The discid is represented in hexadecimal form for the purpose of
xmcd cddb file names and the DISCID= field in the xmcd cddb file itself.
If the hexadecimal string is less than 8 characters long, it is
zero-padded to 8 characters (i.e., 3a8f07 becomes 003a8f07).  All
alpha characters in the string should be in lower case, where
applicable.

Important note for clients using the MS-Windows MCI interface:

The Windows MCI interface does not provide the MSF location of the
lead-out.  Thus, you must compute the lead-out location by taking the
starting position of the last track and add the length of the last track
to it.  However, the MCI interface returns the length of the last track
as ONE FRAME SHORT of the actual length found in the CD's TOC.  In most
cases this does not affect the disc ID generated, because we truncate
the frame count when computing the disc ID anyway.  However, if the
lead-out track has an actual a frame count of 0, the computed quantity
(based on the MSF data returned from the MCI interface) would result in
the seconds being one short and the frame count be 74.  For example,
a CD with the last track at an offset of 48m 32s 12f and having a
track length of 2m 50s 63f has a lead-out offset of 51m 23s 0f. Windows
MCI incorrectly reports the length as 2m 50s 62f, which would yield a
lead-out offset of 51m 22s 74f, which causes the resulting truncated
disc length to be off by one second.  This will cause an incorrect disc
ID to be generated. You should thus add one frame to the length of the
last track when computing the location of the lead-out.

The easiest way for Windows clients to compute the lead-out given information
in MSF format is like this:

(offset_minutes * 60 * 75) + (offset_seconds * 75) + offset_frames +
(length_minutes * 60 * 75) + (length_seconds * 75) + length_frames + 1 = X

Where X is the offset of the lead-out in frames. To find the lead-out in
seconds, simply divide by 75 and discard the remainder.


APPENDIX B - CDDB FILE FORMAT
-----------------------------

Database entries must be in the ISO-8859-1 character set (the 8-bit ASCII
extension also known as "Latin alphabet #1" or ISO-Latin-1). Lines must
always be terminated by a newline/linefeed (ctrl-J, or 0Ah) character
or a carriage return character (ctrl-M, or 0Dh) followed by a newline/linefeed
character. All lines in a database entry must be less than or equal to 80
bytes in length, including the terminating character(s). Database entries
with lines that are longer will be considered invalid. There must be no
blank lines in a database entry.

Lines that begin with # are comments. Comments should appear only at the
top of the file before any keywords. Comments in the body of the file are
subject to removal when submitted for inclusion to the database. Comments
may consist only of characters in the set:

{ tab (09h); space (20h) through tilde (7Eh) inclusive }

Comments should be ignored by applications using the database file, with
several exceptions described below.

The beginning of the first line in a database entry should consist of the
string "# xmcd". This string identifies the file as an xmcd format CD
database file. More text can appear after the "xmcd", but is unnecessary.

The comments should also contain the string "# Track frame offsets:" followed
by the list of track offsets (the # of frames from the beginning of the CD)
obtained from the table of contents on the CD itself, with any amount of white
space between the "#" and the offset. There should be no other comments
interspersed between the list of track offsets. This list must follow the
initial identifier string described above. Following the offset list should
be at least one blank comment.

After the offset list, the following string should appear:

"# Disc length: N seconds"

where the number of seconds in the CD's play length is substituted for "N".
The number of seconds should be computed by dividing the total number of
1/75th second frames in the CD by 75 and truncating any remainder. This number
should not be rounded.

Note for Windows programmers:

The disc length provided by the Windows MCI interface should not be used here.
Instead, the lead-out (address of the N+1th track) should be used. Since the
MCI interface does not provide the address of the lead-out, it should be
computed by adding the length of the last track to the offset of the last
track and truncating (not rounding) any remaining fraction of a second. Note
that the MCI interface yields an incorrect track offset which must be
corrected by adding one frame to the total frame count when performing the
disc length computation. For more information, see Appendix A.

After the disc length, the following string should appear:

"# Revision: N"

where the database entry revision (decimal integer) is substituted for "N".

Files missing a revision are assumed to have a revision revision level of 0.
The revision is used for database management when comparing two entries in
order to determine which is the most recent. Client programs which allow the
user to modify a database entry should increment the revision when the user
submits a modified entry for inclusion in the database.

After the revision, the following string should appear:

"# Submitted via: client_name client_version optional_comments"

where the name of the client submitting the entry is substituted for
"client_name", the version of the client is substituted for "client_version",
and "optional_comments" is any sequence of legal characters. Clients which
allow users to modify database entries read from the database should update
this string with their own information before submitting.

The "client_version" field has a very specific format which should be observed:

[leading text]version_number[release type][level]

Where:

	Leading text: is any string which does not include numbers.
	Version number and level: is any (possibly) decimal-separated list of
	    positive numbers.
	Release type: is a string of the form:
	    alpha, a, beta, b, patchlevel, patch, pl
	Level: is a positive number.

For example:

	release:2.35.1alpha7
	v4.0PL0
	2.4

The only required portion of the version field is the version number. The
other parts are optional, though it is strongly recommended that the release
type field be filled in if relevant. Strict version checking may be
applied by software which evaluates the submitter revision, so it is wise
to make it clear when a release is beta, etc.

Following the comments is the disc data. Each line of disc data consists
of the format "KEYWORD=data", where "KEYWORD" is a valid keyword as described
below and "data" is any string consisting of characters in the set:

{ space (20h) through tilde (7Eh) inclusive; no-break-space (A0h) through
  y-umlaut (FFh) inclusive }

Newlines (0Ah), tabs (09h) and backslashes (2Fh) may be represented by the
two-character sequences "\n", "\t" and "\\" respectively. Client programs must
translate these sequences to the appropriate characters when displaying
disc data.

All of the applicable keywords must be present in the file. They must appear
in the file in the order shown below. Multiple occurrences of the same keyword
indicate that the data contained on those lines should be concatenated; this
applies to any of the textual fields. There is no practical limit to the size
of any of the textual fields or a database entry itself, though the CDDB server
software may place a restriction on especially large entries. Valid keywords
are as follows:

DISCID: The data following this keyword should contain the 8-byte disc ID.
	indicated by the track offsets in the comment section. The algorithm
	for generating the disc ID is explained in Appendix A.

DTITLE: Technically, this may consist of any data, but by convention contains
	the artist and disc title (in that order) separated by a "/" with a
	single space on either side to separate it from the text. If the "/"
	is absent, it is implied that the artist and disc title are the same.

TTITLEN:There must be one of these for each track in the CD. The track
	number should be substituted for the "N", starting with 0. This field
	should contain the title of the Nth track on the CD.

EXTD:	This field contains the "extended data" for the CD. This is intended
	to be used as a place for interesting information related to the CD,
	such as credits, et cetera. If there is more than one of these lines
	in the file, the data is concatenated. This allows for extended data
	of arbitrary length.

EXTTN:	This field contains the "extended track data" for track "N". There
	must be one of these for each track in the CD. The track number
	should be substituted for the "N", starting with 0. This field is
	intended to be used as a place for interesting information related to
	the Nth track, such as the author and other credits, or lyrics. If
	there is more than one of these lines in the file, the data is
	concatenated. This allows for extended data of arbitrary length.

PLAYORDER:
	This field contains a comma-separated list of track numbers which
	represent a programmed track play order. This field is generally
	stripped of data in non-local database entries. Applications that
	submit entries for addition to the main database should strip this
	keyword of data.


An example database entry follows:

# xmcd
# Copyright (C) 1993-1998  CDDB, Inc.
#
# Track frame offsets:
#	150
#	47275
#	76072
#	89507
#	117547
#	136377
#	157530
#
# Disc length: 2663 seconds
#
# Revision: 2
# Submitted via: xmcd 2.3beta PL0
#
DISCID=470a6507
DTITLE=Led Zeppelin / Presence
TTITLE0=Achilles' Last Stand
TTITLE1=For Your Life
TTITLE2=Royal Orleans
TTITLE3=Nobody's Fault But Mine
TTITLE4=Candy Store Rock
TTITLE5=Hots On For Nowhere
TTITLE6=Tea For One
EXTD=Producer: Jimmy Page\nExecutive Producer: Peter Gr
EXTD=ant\n\nUPC: 7567-90329-2\nLABEL: Atlantic Recordin
EXTD=g Corporation\nYEAR: 1976
EXTT0=Jimmy Page and Robert Plant
EXTT1=Jimmy Page and Robert Plant
EXTT2=John Bonham, John Paul Jones, Jimmy Page and\nRob
EXTT2=ert Plant
EXTT3=Jimmy Page and Robert Plant
EXTT4=Jimmy Page and Robert Plant
EXTT5=Jimmy Page and Robert Plant
EXTT6=Jimmy Page and Robert Plant
PLAYORDER=

Please note that the EXTD section above is split into three pieces. When
displayed to the user, it should appear like this:

Producer: Jimmy Page
Executive Producer: Peter Grant

UPC: 7567-90329-2
LABEL: Atlantic Recording Corporation
YEAR: 1976


APPENDIX C - CDDB SERVER PROTOCOL
---------------------------------


				CDDB Protocol
				-------------


Notation:
-> : client to server
<- : server to client

terminating marker: `.' character in the beginning of a line


Server response code (three digit code):

First digit:
1xx	Informative message
2xx	Command OK
3xx	Command OK so far, continue
4xx	Command OK, but cannot be performed for some specified reasons
5xx	Command unimplemented, incorrect, or program error

Second digit:
x0x	Ready for further commands
x1x	More server-to-client output follows (until terminating marker)
x2x	More client-to-server input follows (until terminating marker)
x3x	Connection will close

Third digit:
xx[0-9]	Command-specific code

It is best if client applications treat response codes generically when
possible, rather than having hard-coded "expected" or known codes in the
application. Here is the suggested method for generically handling error
codes:

20x - OK, command successful. No action necessary.
21x - OK, prepare to read data from the server. If unexpected you can
        disconnect, but it's probably an error on the app's part so retrying
        in that case is not indicated.
22x - OK, prepare to give the server data. If unexpected, treat as above.
23x - OK, connection closing at client's request.

40x - Command failed due to server error or permission problem. Reconnecting
        to a different server might help.
41x - Command failed, as above. Information follows regarding the problem,
        so client should read it and perhaps display it. Reconnect as above.
43x - Command failed, as 40x. Connection is dropped by the server. Reconnect
        as 40x.

50x - Command failed due to client error. Retrying in any fashion is probably
        pointless, because a bug in the client is usually indicated.
51x - As above, with explanatory information following.
53x - Some sort of client error forced the server to disconnect. Connection is
        dropped. Retry might help, because this code is often due to a timeout
        condition or some other limit that gets reset upon reconnect.

It is okay to ignore the 'x' portion of an error code, but if there are
specific ones that you want to react to, you can. Just don't preclude
reacting to general codes at any time. Any 2-level codes that don't appear
here, such as "42x" are either not possible or will not be seen by clients.
You might want to have a general default case for these; consider them a
server error indicating a serious problem.


CDDB Protocol Level 1:
----------------------

Initial client-server handshake:
--------------------------------
Note: This command is not used directly in HTTP mode. It is implied by
the "hello=" field in the HTTP query. See Addendum A below for more
information. It is described here only as a reference.

Client command:
-> cddb hello username hostname clientname version

    username:
	Login name of user.  Example: johndoe
    hostname:
	Host name of client.  Example: abc.fubar.com
    clientname:
	The name of the connecting client.  Example: xmcd, cda, EasyCD,
	et cetera. Do not use the name of another client which already
	exists.
    version:
	Version number of client software.  Example: v1.0PL0

Server response:
<- code hello and welcome username@hostname running clientname version

    code:
	200	Handshake successful
	431	Handshake not successful, closing connection
	402	Already shook hands


CDDB lscat:
----------
Client command:
-> cddb lscat

Server response:
<- code Okay category list follows
<- category
<- category
<- (more categories...)
<- .

    code:
	210	Okay category list follows (until terminating marker)
    category:
	CD category.  Example: rock


CDDB query:
-----------
Client command:
-> cddb query discid ntrks off1 off2 ... nsecs

    discid:
	CD disc ID number.  Example: f50a3b13
    ntrks:
	Total number of tracks on CD.
    off1, off2, ...:
	Frame offset of the starting location of each track.
    nsecs:
	Total playing length of CD in seconds.

Server response:
<- code categ discid dtitle
	or
<- code close matches found
<- categ discid dtitle
<- categ discid dtitle
<- (more matches...)
<- .

    code:
	200	Found exact match
	211	Found inexact matches, list follows (until terminating marker)
	202	No match found
	403	Database entry is corrupt
	409	No handshake
    categ:
	CD category.  Example: rock
    discid:
	CD disc ID number of the found entry.  Example: f50a3b13
    dtitle:
	The Disc Artist and Disc Title (The DTITLE line).  For example:
	Pink Floyd / The Dark Side of the Moon


CDDB read:
----------
Client command:
-> cddb read categ discid

    categ:
	CD category.  Example: rock
    discid:
	CD disc ID number.  Example: f50a3b13

Server response:
<- code categ discid
<- # xmcd CD database file
<- # ...
<- (CDDB data...)
<- .
	or
<- code categ discid No such CD entry in database

    code:
	210	OK, CDDB database entry follows (until terminating marker)
	401	Specified CDDB entry not found.
	402	Server error.
	403	Database entry is corrupt.
	409	No handshake.
	417     Access limit exceeded, explanation follows (until marker)
    categ:
	CD category.  Example: rock
    discid:
	CD disc ID number.  Example: f50a3b13


Help information:
-----------------
Client command:
-> help
	or
-> help cmd

    cmd:
	CDDB command.  Example: quit

	or

-> help cmd subcmd

    cmd:
	CDDB command.  Example: cddb
    subcmd:
	CDDB command argument.  Example: query

Server response:
<- code Help information follows
<- (help data ...)
<- .
	or
<- code no help information available

    code:
	210	OK, help information follows (until terminating marker)
	401	No help information available


Message of the day:
------------------
Client command:
-> motd

Server response:
<- code Last modified: date MOTD follows (until terminating marker)
<- (message text)
<- .

    code:
	210	Last modified: 05/31/96 06:31:14 MOTD follows (until terminating marker)
	401	No message of the day available
    date:
	The date the text of the message of the day was modified. The date
	appears in the following format:

		05/31/96 06:31:14

	This value may be used by client software as a message timestamp
	for purposes of determining if it has already been displayed. This
	format was chosen because it is more easily parsed than the standard
	ctime() format.


Server protocol level:
----------------------
Note: This command is not used directly in HTTP mode. It is implied by
the "proto=" field in the HTTP query. See Addendum A below for more
information. It is described here only as a reference.

Client command:
-> proto [level]

    level:
	The (numerical) protocol level to set the server to.

Server response:
<- code CDDB protocol level: current cur_level, supported supported_level
	or
<- code OK, protocol version now: cur_level

    code:
	200	CDDB protocol level: current cur_level, supported supp_level
	201	OK, protocol version now: cur_level
	501	Illegal protocol level.
	502	Protocol level already cur_level.
    cur_level:
	The current protocol level at which the server is running.
    supported_level:
	The maximum supported protocol level.


Server sites:
--------------
Client command:
-> sites

Server response:
<- code OK, site information follows (until terminating `.')
<- (data)
<- .

    code:
	210	Ok, site information follows
	401	No site information available.

    The data format is as follows:
	site port latitude longitude description

    The fields are as follows:
	site:
	    The Internet address of the remote site.
	port:
	    The port at which the server resides on that site.
	latitude:
	    The latitude of the server site. The format is as follows:
		CDDD.MM
	    Where "C" is the compass direction (N, S), "DDD" is the
	    degrees, and "MM" is the minutes.
	longitude:
	    The longitude of the server site. Format is as above, except
	    the compass direction must be one of (E, W).
	description:
	    A short description of the geographical location of the site.

    Example:
	ca.us.cddb.com 888 N037.23 W122.01 Fremont, CA USA


Server status:
--------------
Client command:
-> stat

Server response:
<- code OK, status information follows (until terminating `.')
<- (data)
<- .

    code:
	210	Ok, status information follows

    The possible data is as follows:
	current proto: <current_level>
	    An integer representing the server's current operating protocol
	    level.
	max proto:     <max_level>
	    The maximum supported protocol level.
	gets:          <yes | no>
	    Whether or not the client is allowed to get log information,
	    according to the string "yes" or "no".
	updates:       <yes | no>
	    Whether or not the client is allowed to initiate a database
	    update, according to the string "yes" or "no".
	posting:       <yes | no>
	    Whether or not the client is allowed to post new entries,
	    according to the string "yes" or "no".
	quotes:        <yes | no>
	    Whether or not quoted arguments are enabled, according to
	    the string "yes" or "no".
	current users: <num_users>
	    The number of users currently connected to the server.
	max users:     <num_max_users>
	    The number of users that can concurrently connect to the server.
	strip ext:	<yes | no>
	    Whether or not extended data is stripped by the server before
	    presented to the user.
	Database entries: <num_db_entries>
	    The total number of entries in the database.
	Database entries by category:
	    This field is followed by a list of catgories and the number
	    of entries in that category. Each entry is of the following
	    format:

		<white space>catgory: <num_db_entries>

	    The list of entries is terminated by the first line that does
	    not begin with white space.

	Pending file transmissions:
	    This field is followed by a list of sites that are fed new
	    database entries at periodic intervals, and the number of
	    entries that have yet to be transmitted to that site.
	    Each entry is of the following format:

		<white space>site: <num_db_entries>

	    The list of entries is terminated by the first line that does
	    not begin with white space.

	This list may grow as needed, so clients must expect possible
	unrecognizable data. Also, additional fields may be added to
	the currently existing lines, although no existing fields will
	be removed or change position.


Server version:
---------------
Client command:
-> ver

Server response:
<- code servername version copyright
	or
<- code Version information follows

    code:
	200	Version information.
	211	OK, version information follows (until terminating marker)
    version:
	Server version.  Example: v1.0PL0
    copyright:
	Copyright string.  Example: Copyright (c) 1996 Steve Scherf


Server users:
-------------
Client command:
-> whom

Server response:
<- code User list follows

    code:
	210	OK, user list follows (until terminating marker)
	401	No user information available.


Reserved errors:
----------------

The following error codes are reserved, and will never be returned as a
response to a CDDB protocol command. They are intended to be used internally
by clients that have a need for generating pseudo-responses.

	600-699


CDDB Protocol Level 2:
----------------------

In all respects, protocol level 2 is the same as level 1, with the exceptions
listed below.

Arguments to commands may be surrounded by double quotes. All characters
within the quotes, including white space, are included in the argument. All
white space is replaced by the `_' (2Dh) character by the server. White space
is defined as ` ' (20h) and `^I' (control-I, or 09h).

Arguments containing quotes that should not be interpreted with the special
meaning described above should be escaped with a preceding backslash character,
or '\' (5Ch). If an actual backslash appears in an argument, it should be
escaped with a preceding backslash. In both cases, the preceding backslash
will be removed from the input before being interpreted.


CDDB Protocol Level 3:
----------------------

Protocol level 3 is the same as level 2, with the exception listed below.

The output of the "sites" command has changed to meet the folowing description:

    The data format is as follows:
	site protocol port address latitude longitude description

    The fields are as follows:
	site:
	    The Internet address of the remote site.
	protocol:
	    The transfer protocol used to access the site. Sites specified
	    as "cddbp" protocol sites are listed only for compatibility
	    with older clients. Newer clients should ignore these and
	    only pay attention to "http" sites.
	port:
	    The port at which the server resides on that site.
	address:
	    Any additional addressing information needed to access the
	    server. For example, for HTTP protocol servers, this would be
	    the path to the CDDB server CGI script. This field will be
	    "-" if no additional addressing information is needed.
	latitude:
	    The latitude of the server site. The format is as follows:
		CDDD.MM
	    Where "C" is the compass direction (N, S), "DDD" is the
	    degrees, and "MM" is the minutes.
	longitude:
	    The longitude of the server site. Format is as above, except
	    the compass direction must be one of (E, W).
	description:
	    A short description of the geographical location of the site.

    Example:
	ca.us.cddb.com cddbp 888 - N037.23 W122.01 Fremont, CA USA
	ca.us.cddb.com http 80 /~cddb/cddb.cgi N037.23 W122.01 Fremont, CA USA

Note that a site may appear once for each type of protocol it supports for
accessing the server.


CDDB Protocol Level 4:
----------------------

Protocol level 4 is the same as level 3, with the exception listed below.

The output of the "cddb query" command may result in multiple exact matches.
A new response code, 210, has been added to indicate that more than one
exact match has been found.

Server response:
----------------
<- code exact matches found
<- categ discid dtitle
<- categ discid dtitle
<- (more matches...)
<- .

    code:
        210 Found exact matches, list follows (until terminating marker)
	417 Database access limit exceeded, explanation follows (until marker)


Addendum A: CDDB Protocol Under HTTP:
-------------------------------------

Accessing a CDDB server CGI script is done by encapsulating the CDDB protocol
command in the HTTP protocol. The only limitation is that a single command
may be executed per connection, since HTTP is not truly interactive. For the
server to be accessed in this way, it must reside on the target host at a
known URL which is accessible by the host HTTP server. The client program
must connect to the HTTP server on the target host and issue an HTTP command
with the appropriate CDDB protocol command encapsulated within.

Commands may be submitted to servers in CGI mode using either the "GET" or
"POST" HTTP commands. Both methods are supported, and there is no real
difference between how both are to be used other than the syntactical
difference between the two methods. The "POST" method may provide the ability
to issue longer commands, though, depending on the architecture of the HTTP
server on the remote system.

The server command must be sent as part of the "Request-URI" in the case
of the "GET" method, and as the "Entity-Body" in the case of the "POST"
method. In both cases, the command must be of the following form:

cmd=server+command&hello=joe+my.host.com+clientname+version&proto=1

Where the text following the "cmd=" represents the CDDB Protocol command to
be executed, the text following the "hello=" represents the arguments to
the "cddb hello" command that is implied by this operation, and the
text following the "proto=" represents the argument to the "proto" command
that is implied by this operation.

The "+" characters in the input represent spaces, and will be translated
by the server before performing the request. Special characters may be
represented by the sequence "%XX" where "XX" is a two-digit hex number
corresponding to the ASCII (ISO-8859-1) sequence of that character. The
"&" characters denote separations between the command, hello and proto
arguments. Newlines and carriage returns must not appear anywhere in the
string except at the end.

For example, should user "joe" on system "my.host.com" be running CDclient
version 2.1, a read request for his currenly playing CD might look like this:

cmd=cddb+read+rock+12345678&hello=joe+my.host.com+CDclient+2.1&proto=4

The server will perform the implied "proto" and "cddb hello" commands,
and then perform the requested "cddb read" command.

Server response to the command is encapsulated in the HTTP server response,
and appears in the "Entity-Body". Note that the HTTP response "Entity-Header"
is not guaranteed to contain a "Content-Length" field, so clients should be
prepared to accept variable length input. The header will always contain a
Mime "Content-Type" field which describes the body of data as "text/plain".

Here is an example HTTP-mode request, including the necessary HTTP protocol:

GET /~cddb/cddb.cgi?cmd=help&hello=steve+cddb.com+CDclient+2.1&proto=4 HTTP/1.0

For more detailed information on HTTP and Mime, see RFC 1945 and RFC 1521,
as well as later amendments to those RFCs.


APPENDIX D - OFFICIAL CDDB SOFTWARE DISTRIBUTION SITES
------------------------------------------------------

All CDDB-related software and other files are distributed via the
CDDB web page (under "Downloads"):

	http://www.cddb.com/