Mercurial > ~darius > hgwebdir.cgi > cddb-stuff
diff cddb_howto.txt @ 2:5cead4da1db9
Initial import.
Seems to work nicely.
| author | darius |
|---|---|
| date | Wed, 09 Aug 2000 02:18:47 +0000 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/cddb_howto.txt Wed Aug 09 02:18:47 2000 +0000 @@ -0,0 +1,1273 @@ + + 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/