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: An integer representing the server's current operating protocol level. max proto: The maximum supported protocol level. gets: Whether or not the client is allowed to get log information, according to the string "yes" or "no". updates: Whether or not the client is allowed to initiate a database update, according to the string "yes" or "no". posting: Whether or not the client is allowed to post new entries, according to the string "yes" or "no". quotes: Whether or not quoted arguments are enabled, according to the string "yes" or "no". current users: The number of users currently connected to the server. max users: The number of users that can concurrently connect to the server. strip ext: Whether or not extended data is stripped by the server before presented to the user. Database 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: catgory: 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: site: 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/