1 2 USE OF CDDB SERVICE IN YOUR SOFTWARE 3 ------------------------------------ 4 Copyright (c) CDDB, Inc. 5 6 @(#)cddb.howto 1.27 98/12/09 7 8 9 10 In this document: 11 12 - WHAT IS THE CDDB 13 - CDDB USE RESTRICTIONS 14 - TWO FORMS OF ACCESS TO THE CDDB 15 - CDDB DISCID 16 - REMOTE CDDB ACCESS 17 - CDDB SUBMISSION 18 - QUESTIONS? 19 - APPENDIX A - CDDB DISCID ALGORITHM 20 - APPENDIX B - CDDB FILE FORMAT 21 - APPENDIX C - CDDB SERVER PROTOCOL 22 - APPENDIX D - OFFICIAL CDDB SOFTWARE DISTRIBUTION SITES 23 24 25 26WHAT IS THE CDDB 27---------------- 28 29CDDB (CD database) is an information database containing artist, disc 30title, track titles, and other information for digital audio compact 31discs. Over time, this archive has grown to contain a substantial 32collection of CD information and is continuing to grow at a rapid rate. 33This database can be accessed by applications via the CDDB server hosts 34that have been set up on the Internet around the world. 35 36The CDDB data format and the CDDB servers are designed to be open, and 37are used by many client applications requiring CD information. CDDB has 38become the de facto standard for Internet access of compact disc 39information. 40 41 42CDDB USE RESTRICTIONS 43--------------------- 44 45Users of CDDB-capable freeware and shareware applications may use the 46public CDDB servers for free. Commercial uses of CDDB data and/or servers 47are subject to negotiations with CDDB Inc. Please write to us at 48licensing@cddb.com for more information. 49 50If you plan to use CDDB and/or the CDDB servers in your software, please 51notify support@cddb.com of your intent. Also, we appreciate that you 52keep us posted as to your development/test progress and release schedules. 53Before you release your CDDB application we must verify that it properly 54implements the CDDB functionality. You must provide us with a copy of your 55software for testing when it is ready. Please do not release your software 56with CDDB functionality until it has been tested. 57 58You must explicitly give credit to CDDB, Inc. in your application, both in 59all documentation that mentions the CDDB functionality in any way, and when 60the product is operating. The exact details should be obtained from 61licensing@cddb.com before you release your software. 62 63 64 65TWO FORMS OF ACCESS TO THE CDDB 66------------------------------- 67 68If you are interested in incorporating the use of CDDB in your 69software, there are two forms of access that you may consider. 70 711. Local access 72 73 In this mode your software simply attempts to open local files on 74 the computer to access the CDDB. 75 76 You may store the CD information in the CDDB-native format (See 77 Appendix B), or another format of your choice (for example, the 78 Win95 cdplayer.ini format). Users appreciate a the ability to import 79 CDDB data from and export to a variety of formats. 80 81 Note that the CDDB archive is not available for downloads, therefore 82 this mode is only useful to retrieve CD data that is entered by the 83 user and saved to disk. 84 852. Remote access 86 87 In this mode the software must connect to a CDDB server on the 88 network to access the CDDB. There is a CDDB server protocol that 89 the software (also known as the "client") must use to converse with 90 the server. 91 92 This mode allows the client application full access to the entire 93 CD database over the Internet. The data returned is in the CDDB 94 native file format as described in Appendix B. 95 96You may choose to support only remote access mode, or both remote and 97local. We do not recommend a local-only application, since it is not 98very useful. 99 100 101CDDB DISCID 102----------- 103 104Both forms of CDDB access require that the software compute a "disc 105ID" which is an identifier that is used to access the CDDB. The disc 106ID is a 8-digit hexadecimal (base-16) number, computed using data from 107a CD's Table-of-Contents (TOC) in MSF (Minute Second Frame) form. The 108algorithm is listed below in Appendix A. 109 110It is crucial that your software compute the disc ID correctly. If it 111does not generate the correct disc ID, it will not be compatible with CDDB. 112Moreover, if your software submits CDDB entries with bad disc IDs to the 113CDDB archives, it could compromise the integrity of the CDDB. 114 115We suggest installing one of the disc ID checker programs listed on the 116CDDB web page at http://www.cddb.com/downloads, and then testing the disc 117ID code in your software by comparing the disc ID generated by the program 118with that of your software for as large a number of CDs as possible. Bugs 119in disc ID calculation can be subtle, and history shows that it sometimes 120takes hundreds of discs to find problems. 121 122 123REMOTE CDDB ACCESS 124------------------ 125 126In order to perform remote access of CDDB servers, your software must be 127able to communicate with a remote CD server system via HTTP. There are a 128number of public CDDB servers operating on the Internet. The current list 129of public servers may be obtained programmatically via the CDDB protocol 130"sites" command. The permanent server site, cddb.cddb.com has been 131established in order to provide a reliable source of server site information 132via the "sites" command. This address may be safely hard-wired into client 133software for this purpose, as it is guaranteed to exist on a permanent basis. 134Furthermore, the "cddb.cgi" program is guaranteed to always reside at the 135following path: /~cddb/cddb.cgi 136 137Thus, the URL for accessing the server at cddb.cddb.com is: 138 139http://cddb.cddb.com/~cddb/cddb.cgi 140 141You should make the CDDB server host (or hosts) user-selectable in your 142software. DO NOT hard-wire the list of CD database servers into your code. 143The list of active servers changes over time. 144 145The CDDB server protocol is described below in Appendix C. 146 147The CDDB entry returned from the server via a "cddb read" command is in 148the format described in Appendix B below. 149 150Some additional notes for accessing CDDB over the Internet: 151 152Your application should always specify the highest documented protocol 153level in the "proto=" field of the HTTP command. The highest level currently 154specified is "4". Lower protocol levels will work, but are only provided 155for compatibility with older CDDB applications. If you do not use the 156highest available protocol level, certain important features will not be 157available to your application. 158 159Make sure to use the proper arguments in the "hello=" command. The user 160and hostname arguments should be that of the user's email address, not 161some fixed hard-coded value. The application name and version should be 162that of your application, not that of another existing application. 163 164We consider the use of the "cddb query" command mandatory for all CDDB 165clients. It is not valid to issue a "cddb read" command without issuing 166a prior "cddb query" and receiving a good response, as it may yield incorrect 167results. In addition, it is required that clients support close matches 168(aka "fuzzy" matches, or response code 211) and multiple exact matches 169(response code 210) in response to a query. 170 171The proper way to handle multiple exact/fuzzy matches is to present the 172entire list of matches to the user and to let the user choose between them. 173Matches are listed in the order of best fit for the user's disc, so they 174should be presented to the user in the order they are listed by the server. 175 176The suggested algorithm for obtaining the list of server sites is 177as follows. The application should attempt to get the list from 178cddb.cddb.com with the "sites" command the first time the user runs the 179program. After the initial download of the site list, the application 180should periodically attempt to download the site list, or at least 181provide the user with some method of downloading the list on-demand. 182Should the user be unable to subsequently download the list of sites 183due to temporary network perturbation, the application should attempt 184to download the site list from one of the sites in its current list. All 185of the official CDDB server sites will contain a valid list of servers, 186though cddb.cddb.com is the only site which is guaranteed to always exist. 187 188We do strongly suggest that you provide your users with the capability of 189choosing CDDB server sites as described above. However, for some applications 190this may not be feasible. If you do not wish to offer this functionality, 191you may safely hard-code "cddb.cddb.com" in your application as the sole 192CDDB site to access. This will deprive your users of the option to choose 193a site near their locale for optimal response, but that is your choice. 194 195PLEASE NOTE: older versions of the CDDB specification describe two methods 196of accessing the CDDB servers: HTTP mode and CDDBP mode. CDDBP mode is 197being deprecated in favor of HTTP mode, so new applications should be sure 198to only implement the HTTP mode of access. All text describing CDDBP 199mode has been removed from this document. 200 201 202CDDB SUBMISSION 203--------------- 204 205Your software may allow users to enter CDDB data and then submit it to the 206CDDB archives. The method of submission is to transmit the entry to the 207database through a CGI program at the following URL: 208 209http://hostname.cddb.com/~cddb/submit.cgi 210 211where "hostname.cddb.com" is one of the hosts listed in the CDDB server 212"sites" command, and also cddb.cddb.com. 213 214Submissions are made through the CGI program as follows. You must only use 215the "POST" method of sending data; "GET" is not supported. There are several 216HTTP "Entity-Header" fields that must be included in the data followed by a 217blank line, followed by the "Entity-Body" (a.k.a the CDDB entry) in the 218format described in Appendix B below. The required header fields are: 219 220Category: CDDB_category 221Discid: CDDB_discid 222User-Email: user@domain 223Submit-Mode: test_or_submit 224Content-Length: length_of_CDDB_entry 225 226Where: 227 228- "CDDB_category" is one of the valid CDDB categories listed by the CDDB 229 server "cddb lscat" command. Invalid categories will result in the entry 230 being rejected. 231 232- "CDDB_discid" is the 8-digit hex CDDB disc ID of the entry as described in 233 the "CDDB Discid" section below. This must be the same disc ID that appears 234 in the "DISCID=" section of the entry being submitted. If not, the entry 235 will be rejected. 236 237- "user@domain" is the valid email address of the user submitting the entry. 238 This is required in case a submission failure notice must be sent to the 239 user. 240 241- "test_or_submit" is the word "test" or "submit" (without the surrounding 242 quotes) to indicate whether the submission is a test submission or a real 243 submission to the database, respectively. See below for an explanation of 244 test submissions. 245 246- "length_of_CDDB_entry" is the size in bytes of the CDDB entry being 247 submitted. This number does not include the length of the header or the 248 blank line separating the HTTP header and the CDDB entry. 249 250There are several additional optional HTTP header fields that may also 251be specified: 252 253Charset: character_set_of_CDDB_entry 254X-Cddbd-Note: message for user 255 256Where: 257 258- "character_set_of_CDDB_entry" is one of ISO-8859-1 or US-ASCII (lower case 259 may be used if desired). This specifies to the CDDB server which character 260 set the CDDB entry has been encoded in. If your application knows the 261 user's character set, then you should specify it here. Only these two 262 character sets are supported currently. DO NOT specify the character set 263 if your application does not have any way of verifying the user's character 264 set (i.e. do not guess; it's better not to specify it at all). 265 266- "message for user" is an arbitrary message to be included at the top of 267 any rejection notice that may be sent to the submitting user. 268 269An example submission showing the HTTP command, "Entity-Header" and "Entity- 270Body" follows: 271 272POST /~cddb/submit.cgi HTTP/1.0 273Category: rock 274Discid: 2a09310a 275User-Email: joe@joeshost.joesdomain.com 276Submit-Mode: submit 277Charset: ISO-8859-1 278X-Cddbd-Note: Problems with Super CD Player? Send email to support@supercd.com. 279Content-Length: 820 280 281# xmcd 282# Copyright (c) 1998 CDDB Inc. 283# 284# Track frame offsets: 285[ data omitted in this example for brevity ] 286PLAYORDER= 287 288Note the blank line between the "Content-Length" header field and the 289"# xmcd" which marks the beginning of the CDDB entry. 290 291When your application submits an entry through the CGI program, it will 292respond with a 3-digit response code indicating whether or not the entry has 293been forwarded to the CDDB server for inclusion in the database, followed 294by a textual description of the response code. For example: 295 296200 OK, submission has been sent. 297400 Internal error: failed to forward submission. 298500 Missing required header information. 299 300These are but a few of the possible responses. See the description of the 301CDDB server protocol in Appendix C for more information on handling response 302codes. 303 304The body of the CDDB entry being submitted should be sent verbatim as 305described in Appendix B. DO NOT encode the data in any way before transmitting 306it; data must be sent as raw text. For example, Windows programmers should not 307use the Windows URL encode function prior to calling the submit CGI program. 308Doing so may lead to corrupt data being sent and also possibly to rejected 309submissions. 310 311You may implement a button or somesuch in your software's user interface 312to initiate submissions. Rejected submissions are automatically returned 313via email to the sender specified in the "User-Email" header field with an 314explanation of the reason for the rejection. 315 316Please do not allow a user to submit CD database entries that have 317completely unfilled contents (i.e., blank information in the disc 318artist/title as well as the track titles). Please design your client 319with this in mind. An example minimum requirement that a CD player client 320should meet is listed below: 321 3221. Don't allow the "send" or "submit" feature to be activated if 323 the CD database information form is not edited at all. 3242. Check that the disc artist/title contains something (that the user 325 typed in). 3263. Don't submit a default string if a field is not filled in 327 (e.g. If track 3 is not filled in, submit a blank "TTITLE3=" line.) 328 If you must use a default string, please use "track N" where N 329 is the track number. 330 331Before you release your software, please be sure that it produces 332submissions that adhere to the CDDB file format, and that the frame 333offset, disc length, and disc ID information are correctly computed. 334For testing, please make your software send submissions with the 335"Submit-Mode" HTTP header field set to "test". 336 337CDDB submissions sent in test mode will be sanity-checked by the CDDB server 338and pass/fail confirmation sent back to the submitter, but will not actually 339be deposited in the CD database. Please DO NOT send submisions in "submit" 340mode until your application has been approved by the CDDB support group. 341 342When you feel your application is ready to support submissions, please contact 343us at support@cddb.com. We will provide you with our qualification 344procedure, which involves submitting a number of entries of different types. 345Once qualified, your application will be permitted to submit to the database. 346 347 348QUESTIONS? 349---------- 350 351Please send any questions or comments to support@cddb.com. 352 353APPENDIX A - CDDB DISCID ALGORITHM 354---------------------------------- 355 356The following is a C code example that illustrates how to generate the 357CDDB disc ID. Examples in other programming languages may be found on 358the CDDB web site at http://www.cddb.com/downloads. A text description 359of the algorithm follows, which should contain the necessary information 360to code the algorithm in any programming language. 361 362 363struct toc { 364 int min; 365 int sec; 366 int frame; 367}; 368 369struct toc cdtoc[100]; 370 371int 372read_cdtoc_from_drive(void) 373{ 374 /* Do whatever is appropriate to read the TOC of the CD 375 * into the cdtoc[] structure array. 376 */ 377 return (tot_trks); 378} 379 380int 381cddb_sum(int n) 382{ 383 int ret; 384 385 /* For backward compatibility this algorithm must not change */ 386 387 ret = 0; 388 389 while (n > 0) { 390 ret = ret + (n % 10); 391 n = n / 10; 392 } 393 394 return (ret); 395} 396 397unsigned long 398cddb_discid(int tot_trks) 399{ 400 int i, 401 t = 0, 402 n = 0; 403 404 /* For backward compatibility this algorithm must not change */ 405 406 i = 0; 407 408 while (i < tot_trks) { 409 n = n + cddb_sum((cdtoc[i].min * 60) + cdtoc[i].sec); 410 i++; 411 } 412 413 t = ((cdtoc[tot_trks].min * 60) + cdtoc[tot_trks].sec) - 414 ((cdtoc[0].min * 60) + cdtoc[0].sec); 415 416 return ((n % 0xff) << 24 | t << 8 | tot_trks); 417} 418 419main() 420{ 421 int tot_trks; 422 423 tot_trks = read_cdtoc_from_drive(); 424 printf("The discid is %08x", cddb_discid(tot_trks)); 425} 426 427 428This code assumes that your compiler and architecture support 32-bit 429integers. 430 431The cddb_discid function computes the discid based on the CD's TOC data 432in MSF form. The frames are ignored for this purpose. The function is 433passed a parameter of tot_trks (which is the total number of tracks on 434the CD), and returns the discid integer number. 435 436It is assumed that cdtoc[] is an array of data structures (records) 437containing the fields min, sec and frame, which are the minute, second 438and frame offsets (the starting location) of each track. This 439information is read from the TOC of the CD. There are actually 440tot_trks + 1 "active" elements in the array, the last one being the 441offset of the lead-out (also known as track 0xAA). 442 443The function loops through each track in the TOC, and for each track 444it takes the (M * 60) + S (total offset in seconds) of the track and 445feeds it to cddb_sum() function, which simply adds the value of each digit 446in the decimal string representation of the number. A running sum of this 447result for each track is kept in the variable n. 448 449At the end of the loop: 4501. t is calculated by subtracting the (M * 60) + S offset of the lead-out 451minus the (M * 60) + S offset of first track (yielding the length of 452the disc in seconds). 453 4542. The result of (n modulo FFh) is left-shifted by 24 bits. 455 4563. t is left shifted by 8. 457 458The bitwise-OR operation of result 2., 3. and the tot_trks number is 459used as the discid. 460 461The discid is represented in hexadecimal form for the purpose of 462xmcd cddb file names and the DISCID= field in the xmcd cddb file itself. 463If the hexadecimal string is less than 8 characters long, it is 464zero-padded to 8 characters (i.e., 3a8f07 becomes 003a8f07). All 465alpha characters in the string should be in lower case, where 466applicable. 467 468Important note for clients using the MS-Windows MCI interface: 469 470The Windows MCI interface does not provide the MSF location of the 471lead-out. Thus, you must compute the lead-out location by taking the 472starting position of the last track and add the length of the last track 473to it. However, the MCI interface returns the length of the last track 474as ONE FRAME SHORT of the actual length found in the CD's TOC. In most 475cases this does not affect the disc ID generated, because we truncate 476the frame count when computing the disc ID anyway. However, if the 477lead-out track has an actual a frame count of 0, the computed quantity 478(based on the MSF data returned from the MCI interface) would result in 479the seconds being one short and the frame count be 74. For example, 480a CD with the last track at an offset of 48m 32s 12f and having a 481track length of 2m 50s 63f has a lead-out offset of 51m 23s 0f. Windows 482MCI incorrectly reports the length as 2m 50s 62f, which would yield a 483lead-out offset of 51m 22s 74f, which causes the resulting truncated 484disc length to be off by one second. This will cause an incorrect disc 485ID to be generated. You should thus add one frame to the length of the 486last track when computing the location of the lead-out. 487 488The easiest way for Windows clients to compute the lead-out given information 489in MSF format is like this: 490 491(offset_minutes * 60 * 75) + (offset_seconds * 75) + offset_frames + 492(length_minutes * 60 * 75) + (length_seconds * 75) + length_frames + 1 = X 493 494Where X is the offset of the lead-out in frames. To find the lead-out in 495seconds, simply divide by 75 and discard the remainder. 496 497 498APPENDIX B - CDDB FILE FORMAT 499----------------------------- 500 501Database entries must be in the ISO-8859-1 character set (the 8-bit ASCII 502extension also known as "Latin alphabet #1" or ISO-Latin-1). Lines must 503always be terminated by a newline/linefeed (ctrl-J, or 0Ah) character 504or a carriage return character (ctrl-M, or 0Dh) followed by a newline/linefeed 505character. All lines in a database entry must be less than or equal to 80 506bytes in length, including the terminating character(s). Database entries 507with lines that are longer will be considered invalid. There must be no 508blank lines in a database entry. 509 510Lines that begin with # are comments. Comments should appear only at the 511top of the file before any keywords. Comments in the body of the file are 512subject to removal when submitted for inclusion to the database. Comments 513may consist only of characters in the set: 514 515{ tab (09h); space (20h) through tilde (7Eh) inclusive } 516 517Comments should be ignored by applications using the database file, with 518several exceptions described below. 519 520The beginning of the first line in a database entry should consist of the 521string "# xmcd". This string identifies the file as an xmcd format CD 522database file. More text can appear after the "xmcd", but is unnecessary. 523 524The comments should also contain the string "# Track frame offsets:" followed 525by the list of track offsets (the # of frames from the beginning of the CD) 526obtained from the table of contents on the CD itself, with any amount of white 527space between the "#" and the offset. There should be no other comments 528interspersed between the list of track offsets. This list must follow the 529initial identifier string described above. Following the offset list should 530be at least one blank comment. 531 532After the offset list, the following string should appear: 533 534"# Disc length: N seconds" 535 536where the number of seconds in the CD's play length is substituted for "N". 537The number of seconds should be computed by dividing the total number of 5381/75th second frames in the CD by 75 and truncating any remainder. This number 539should not be rounded. 540 541Note for Windows programmers: 542 543The disc length provided by the Windows MCI interface should not be used here. 544Instead, the lead-out (address of the N+1th track) should be used. Since the 545MCI interface does not provide the address of the lead-out, it should be 546computed by adding the length of the last track to the offset of the last 547track and truncating (not rounding) any remaining fraction of a second. Note 548that the MCI interface yields an incorrect track offset which must be 549corrected by adding one frame to the total frame count when performing the 550disc length computation. For more information, see Appendix A. 551 552After the disc length, the following string should appear: 553 554"# Revision: N" 555 556where the database entry revision (decimal integer) is substituted for "N". 557 558Files missing a revision are assumed to have a revision revision level of 0. 559The revision is used for database management when comparing two entries in 560order to determine which is the most recent. Client programs which allow the 561user to modify a database entry should increment the revision when the user 562submits a modified entry for inclusion in the database. 563 564After the revision, the following string should appear: 565 566"# Submitted via: client_name client_version optional_comments" 567 568where the name of the client submitting the entry is substituted for 569"client_name", the version of the client is substituted for "client_version", 570and "optional_comments" is any sequence of legal characters. Clients which 571allow users to modify database entries read from the database should update 572this string with their own information before submitting. 573 574The "client_version" field has a very specific format which should be observed: 575 576[leading text]version_number[release type][level] 577 578Where: 579 580 Leading text: is any string which does not include numbers. 581 Version number and level: is any (possibly) decimal-separated list of 582 positive numbers. 583 Release type: is a string of the form: 584 alpha, a, beta, b, patchlevel, patch, pl 585 Level: is a positive number. 586 587For example: 588 589 release:2.35.1alpha7 590 v4.0PL0 591 2.4 592 593The only required portion of the version field is the version number. The 594other parts are optional, though it is strongly recommended that the release 595type field be filled in if relevant. Strict version checking may be 596applied by software which evaluates the submitter revision, so it is wise 597to make it clear when a release is beta, etc. 598 599Following the comments is the disc data. Each line of disc data consists 600of the format "KEYWORD=data", where "KEYWORD" is a valid keyword as described 601below and "data" is any string consisting of characters in the set: 602 603{ space (20h) through tilde (7Eh) inclusive; no-break-space (A0h) through 604 y-umlaut (FFh) inclusive } 605 606Newlines (0Ah), tabs (09h) and backslashes (2Fh) may be represented by the 607two-character sequences "\n", "\t" and "\\" respectively. Client programs must 608translate these sequences to the appropriate characters when displaying 609disc data. 610 611All of the applicable keywords must be present in the file. They must appear 612in the file in the order shown below. Multiple occurrences of the same keyword 613indicate that the data contained on those lines should be concatenated; this 614applies to any of the textual fields. There is no practical limit to the size 615of any of the textual fields or a database entry itself, though the CDDB server 616software may place a restriction on especially large entries. Valid keywords 617are as follows: 618 619DISCID: The data following this keyword should contain the 8-byte disc ID. 620 indicated by the track offsets in the comment section. The algorithm 621 for generating the disc ID is explained in Appendix A. 622 623DTITLE: Technically, this may consist of any data, but by convention contains 624 the artist and disc title (in that order) separated by a "/" with a 625 single space on either side to separate it from the text. If the "/" 626 is absent, it is implied that the artist and disc title are the same. 627 628TTITLEN:There must be one of these for each track in the CD. The track 629 number should be substituted for the "N", starting with 0. This field 630 should contain the title of the Nth track on the CD. 631 632EXTD: This field contains the "extended data" for the CD. This is intended 633 to be used as a place for interesting information related to the CD, 634 such as credits, et cetera. If there is more than one of these lines 635 in the file, the data is concatenated. This allows for extended data 636 of arbitrary length. 637 638EXTTN: This field contains the "extended track data" for track "N". There 639 must be one of these for each track in the CD. The track number 640 should be substituted for the "N", starting with 0. This field is 641 intended to be used as a place for interesting information related to 642 the Nth track, such as the author and other credits, or lyrics. If 643 there is more than one of these lines in the file, the data is 644 concatenated. This allows for extended data of arbitrary length. 645 646PLAYORDER: 647 This field contains a comma-separated list of track numbers which 648 represent a programmed track play order. This field is generally 649 stripped of data in non-local database entries. Applications that 650 submit entries for addition to the main database should strip this 651 keyword of data. 652 653 654An example database entry follows: 655 656# xmcd 657# Copyright (C) 1993-1998 CDDB, Inc. 658# 659# Track frame offsets: 660# 150 661# 47275 662# 76072 663# 89507 664# 117547 665# 136377 666# 157530 667# 668# Disc length: 2663 seconds 669# 670# Revision: 2 671# Submitted via: xmcd 2.3beta PL0 672# 673DISCID=470a6507 674DTITLE=Led Zeppelin / Presence 675TTITLE0=Achilles' Last Stand 676TTITLE1=For Your Life 677TTITLE2=Royal Orleans 678TTITLE3=Nobody's Fault But Mine 679TTITLE4=Candy Store Rock 680TTITLE5=Hots On For Nowhere 681TTITLE6=Tea For One 682EXTD=Producer: Jimmy Page\nExecutive Producer: Peter Gr 683EXTD=ant\n\nUPC: 7567-90329-2\nLABEL: Atlantic Recordin 684EXTD=g Corporation\nYEAR: 1976 685EXTT0=Jimmy Page and Robert Plant 686EXTT1=Jimmy Page and Robert Plant 687EXTT2=John Bonham, John Paul Jones, Jimmy Page and\nRob 688EXTT2=ert Plant 689EXTT3=Jimmy Page and Robert Plant 690EXTT4=Jimmy Page and Robert Plant 691EXTT5=Jimmy Page and Robert Plant 692EXTT6=Jimmy Page and Robert Plant 693PLAYORDER= 694 695Please note that the EXTD section above is split into three pieces. When 696displayed to the user, it should appear like this: 697 698Producer: Jimmy Page 699Executive Producer: Peter Grant 700 701UPC: 7567-90329-2 702LABEL: Atlantic Recording Corporation 703YEAR: 1976 704 705 706APPENDIX C - CDDB SERVER PROTOCOL 707--------------------------------- 708 709 710 CDDB Protocol 711 ------------- 712 713 714Notation: 715-> : client to server 716<- : server to client 717 718terminating marker: `.' character in the beginning of a line 719 720 721Server response code (three digit code): 722 723First digit: 7241xx Informative message 7252xx Command OK 7263xx Command OK so far, continue 7274xx Command OK, but cannot be performed for some specified reasons 7285xx Command unimplemented, incorrect, or program error 729 730Second digit: 731x0x Ready for further commands 732x1x More server-to-client output follows (until terminating marker) 733x2x More client-to-server input follows (until terminating marker) 734x3x Connection will close 735 736Third digit: 737xx[0-9] Command-specific code 738 739It is best if client applications treat response codes generically when 740possible, rather than having hard-coded "expected" or known codes in the 741application. Here is the suggested method for generically handling error 742codes: 743 74420x - OK, command successful. No action necessary. 74521x - OK, prepare to read data from the server. If unexpected you can 746 disconnect, but it's probably an error on the app's part so retrying 747 in that case is not indicated. 74822x - OK, prepare to give the server data. If unexpected, treat as above. 74923x - OK, connection closing at client's request. 750 75140x - Command failed due to server error or permission problem. Reconnecting 752 to a different server might help. 75341x - Command failed, as above. Information follows regarding the problem, 754 so client should read it and perhaps display it. Reconnect as above. 75543x - Command failed, as 40x. Connection is dropped by the server. Reconnect 756 as 40x. 757 75850x - Command failed due to client error. Retrying in any fashion is probably 759 pointless, because a bug in the client is usually indicated. 76051x - As above, with explanatory information following. 76153x - Some sort of client error forced the server to disconnect. Connection is 762 dropped. Retry might help, because this code is often due to a timeout 763 condition or some other limit that gets reset upon reconnect. 764 765It is okay to ignore the 'x' portion of an error code, but if there are 766specific ones that you want to react to, you can. Just don't preclude 767reacting to general codes at any time. Any 2-level codes that don't appear 768here, such as "42x" are either not possible or will not be seen by clients. 769You might want to have a general default case for these; consider them a 770server error indicating a serious problem. 771 772 773CDDB Protocol Level 1: 774---------------------- 775 776Initial client-server handshake: 777-------------------------------- 778Note: This command is not used directly in HTTP mode. It is implied by 779the "hello=" field in the HTTP query. See Addendum A below for more 780information. It is described here only as a reference. 781 782Client command: 783-> cddb hello username hostname clientname version 784 785 username: 786 Login name of user. Example: johndoe 787 hostname: 788 Host name of client. Example: abc.fubar.com 789 clientname: 790 The name of the connecting client. Example: xmcd, cda, EasyCD, 791 et cetera. Do not use the name of another client which already 792 exists. 793 version: 794 Version number of client software. Example: v1.0PL0 795 796Server response: 797<- code hello and welcome username@hostname running clientname version 798 799 code: 800 200 Handshake successful 801 431 Handshake not successful, closing connection 802 402 Already shook hands 803 804 805CDDB lscat: 806---------- 807Client command: 808-> cddb lscat 809 810Server response: 811<- code Okay category list follows 812<- category 813<- category 814<- (more categories...) 815<- . 816 817 code: 818 210 Okay category list follows (until terminating marker) 819 category: 820 CD category. Example: rock 821 822 823CDDB query: 824----------- 825Client command: 826-> cddb query discid ntrks off1 off2 ... nsecs 827 828 discid: 829 CD disc ID number. Example: f50a3b13 830 ntrks: 831 Total number of tracks on CD. 832 off1, off2, ...: 833 Frame offset of the starting location of each track. 834 nsecs: 835 Total playing length of CD in seconds. 836 837Server response: 838<- code categ discid dtitle 839 or 840<- code close matches found 841<- categ discid dtitle 842<- categ discid dtitle 843<- (more matches...) 844<- . 845 846 code: 847 200 Found exact match 848 211 Found inexact matches, list follows (until terminating marker) 849 202 No match found 850 403 Database entry is corrupt 851 409 No handshake 852 categ: 853 CD category. Example: rock 854 discid: 855 CD disc ID number of the found entry. Example: f50a3b13 856 dtitle: 857 The Disc Artist and Disc Title (The DTITLE line). For example: 858 Pink Floyd / The Dark Side of the Moon 859 860 861CDDB read: 862---------- 863Client command: 864-> cddb read categ discid 865 866 categ: 867 CD category. Example: rock 868 discid: 869 CD disc ID number. Example: f50a3b13 870 871Server response: 872<- code categ discid 873<- # xmcd CD database file 874<- # ... 875<- (CDDB data...) 876<- . 877 or 878<- code categ discid No such CD entry in database 879 880 code: 881 210 OK, CDDB database entry follows (until terminating marker) 882 401 Specified CDDB entry not found. 883 402 Server error. 884 403 Database entry is corrupt. 885 409 No handshake. 886 417 Access limit exceeded, explanation follows (until marker) 887 categ: 888 CD category. Example: rock 889 discid: 890 CD disc ID number. Example: f50a3b13 891 892 893Help information: 894----------------- 895Client command: 896-> help 897 or 898-> help cmd 899 900 cmd: 901 CDDB command. Example: quit 902 903 or 904 905-> help cmd subcmd 906 907 cmd: 908 CDDB command. Example: cddb 909 subcmd: 910 CDDB command argument. Example: query 911 912Server response: 913<- code Help information follows 914<- (help data ...) 915<- . 916 or 917<- code no help information available 918 919 code: 920 210 OK, help information follows (until terminating marker) 921 401 No help information available 922 923 924Message of the day: 925------------------ 926Client command: 927-> motd 928 929Server response: 930<- code Last modified: date MOTD follows (until terminating marker) 931<- (message text) 932<- . 933 934 code: 935 210 Last modified: 05/31/96 06:31:14 MOTD follows (until terminating marker) 936 401 No message of the day available 937 date: 938 The date the text of the message of the day was modified. The date 939 appears in the following format: 940 941 05/31/96 06:31:14 942 943 This value may be used by client software as a message timestamp 944 for purposes of determining if it has already been displayed. This 945 format was chosen because it is more easily parsed than the standard 946 ctime() format. 947 948 949Server protocol level: 950---------------------- 951Note: This command is not used directly in HTTP mode. It is implied by 952the "proto=" field in the HTTP query. See Addendum A below for more 953information. It is described here only as a reference. 954 955Client command: 956-> proto [level] 957 958 level: 959 The (numerical) protocol level to set the server to. 960 961Server response: 962<- code CDDB protocol level: current cur_level, supported supported_level 963 or 964<- code OK, protocol version now: cur_level 965 966 code: 967 200 CDDB protocol level: current cur_level, supported supp_level 968 201 OK, protocol version now: cur_level 969 501 Illegal protocol level. 970 502 Protocol level already cur_level. 971 cur_level: 972 The current protocol level at which the server is running. 973 supported_level: 974 The maximum supported protocol level. 975 976 977Server sites: 978-------------- 979Client command: 980-> sites 981 982Server response: 983<- code OK, site information follows (until terminating `.') 984<- (data) 985<- . 986 987 code: 988 210 Ok, site information follows 989 401 No site information available. 990 991 The data format is as follows: 992 site port latitude longitude description 993 994 The fields are as follows: 995 site: 996 The Internet address of the remote site. 997 port: 998 The port at which the server resides on that site. 999 latitude: 1000 The latitude of the server site. The format is as follows: 1001 CDDD.MM 1002 Where "C" is the compass direction (N, S), "DDD" is the 1003 degrees, and "MM" is the minutes. 1004 longitude: 1005 The longitude of the server site. Format is as above, except 1006 the compass direction must be one of (E, W). 1007 description: 1008 A short description of the geographical location of the site. 1009 1010 Example: 1011 ca.us.cddb.com 888 N037.23 W122.01 Fremont, CA USA 1012 1013 1014Server status: 1015-------------- 1016Client command: 1017-> stat 1018 1019Server response: 1020<- code OK, status information follows (until terminating `.') 1021<- (data) 1022<- . 1023 1024 code: 1025 210 Ok, status information follows 1026 1027 The possible data is as follows: 1028 current proto: <current_level> 1029 An integer representing the server's current operating protocol 1030 level. 1031 max proto: <max_level> 1032 The maximum supported protocol level. 1033 gets: <yes | no> 1034 Whether or not the client is allowed to get log information, 1035 according to the string "yes" or "no". 1036 updates: <yes | no> 1037 Whether or not the client is allowed to initiate a database 1038 update, according to the string "yes" or "no". 1039 posting: <yes | no> 1040 Whether or not the client is allowed to post new entries, 1041 according to the string "yes" or "no". 1042 quotes: <yes | no> 1043 Whether or not quoted arguments are enabled, according to 1044 the string "yes" or "no". 1045 current users: <num_users> 1046 The number of users currently connected to the server. 1047 max users: <num_max_users> 1048 The number of users that can concurrently connect to the server. 1049 strip ext: <yes | no> 1050 Whether or not extended data is stripped by the server before 1051 presented to the user. 1052 Database entries: <num_db_entries> 1053 The total number of entries in the database. 1054 Database entries by category: 1055 This field is followed by a list of catgories and the number 1056 of entries in that category. Each entry is of the following 1057 format: 1058 1059 <white space>catgory: <num_db_entries> 1060 1061 The list of entries is terminated by the first line that does 1062 not begin with white space. 1063 1064 Pending file transmissions: 1065 This field is followed by a list of sites that are fed new 1066 database entries at periodic intervals, and the number of 1067 entries that have yet to be transmitted to that site. 1068 Each entry is of the following format: 1069 1070 <white space>site: <num_db_entries> 1071 1072 The list of entries is terminated by the first line that does 1073 not begin with white space. 1074 1075 This list may grow as needed, so clients must expect possible 1076 unrecognizable data. Also, additional fields may be added to 1077 the currently existing lines, although no existing fields will 1078 be removed or change position. 1079 1080 1081Server version: 1082--------------- 1083Client command: 1084-> ver 1085 1086Server response: 1087<- code servername version copyright 1088 or 1089<- code Version information follows 1090 1091 code: 1092 200 Version information. 1093 211 OK, version information follows (until terminating marker) 1094 version: 1095 Server version. Example: v1.0PL0 1096 copyright: 1097 Copyright string. Example: Copyright (c) 1996 Steve Scherf 1098 1099 1100Server users: 1101------------- 1102Client command: 1103-> whom 1104 1105Server response: 1106<- code User list follows 1107 1108 code: 1109 210 OK, user list follows (until terminating marker) 1110 401 No user information available. 1111 1112 1113Reserved errors: 1114---------------- 1115 1116The following error codes are reserved, and will never be returned as a 1117response to a CDDB protocol command. They are intended to be used internally 1118by clients that have a need for generating pseudo-responses. 1119 1120 600-699 1121 1122 1123CDDB Protocol Level 2: 1124---------------------- 1125 1126In all respects, protocol level 2 is the same as level 1, with the exceptions 1127listed below. 1128 1129Arguments to commands may be surrounded by double quotes. All characters 1130within the quotes, including white space, are included in the argument. All 1131white space is replaced by the `_' (2Dh) character by the server. White space 1132is defined as ` ' (20h) and `^I' (control-I, or 09h). 1133 1134Arguments containing quotes that should not be interpreted with the special 1135meaning described above should be escaped with a preceding backslash character, 1136or '\' (5Ch). If an actual backslash appears in an argument, it should be 1137escaped with a preceding backslash. In both cases, the preceding backslash 1138will be removed from the input before being interpreted. 1139 1140 1141CDDB Protocol Level 3: 1142---------------------- 1143 1144Protocol level 3 is the same as level 2, with the exception listed below. 1145 1146The output of the "sites" command has changed to meet the folowing description: 1147 1148 The data format is as follows: 1149 site protocol port address latitude longitude description 1150 1151 The fields are as follows: 1152 site: 1153 The Internet address of the remote site. 1154 protocol: 1155 The transfer protocol used to access the site. Sites specified 1156 as "cddbp" protocol sites are listed only for compatibility 1157 with older clients. Newer clients should ignore these and 1158 only pay attention to "http" sites. 1159 port: 1160 The port at which the server resides on that site. 1161 address: 1162 Any additional addressing information needed to access the 1163 server. For example, for HTTP protocol servers, this would be 1164 the path to the CDDB server CGI script. This field will be 1165 "-" if no additional addressing information is needed. 1166 latitude: 1167 The latitude of the server site. The format is as follows: 1168 CDDD.MM 1169 Where "C" is the compass direction (N, S), "DDD" is the 1170 degrees, and "MM" is the minutes. 1171 longitude: 1172 The longitude of the server site. Format is as above, except 1173 the compass direction must be one of (E, W). 1174 description: 1175 A short description of the geographical location of the site. 1176 1177 Example: 1178 ca.us.cddb.com cddbp 888 - N037.23 W122.01 Fremont, CA USA 1179 ca.us.cddb.com http 80 /~cddb/cddb.cgi N037.23 W122.01 Fremont, CA USA 1180 1181Note that a site may appear once for each type of protocol it supports for 1182accessing the server. 1183 1184 1185CDDB Protocol Level 4: 1186---------------------- 1187 1188Protocol level 4 is the same as level 3, with the exception listed below. 1189 1190The output of the "cddb query" command may result in multiple exact matches. 1191A new response code, 210, has been added to indicate that more than one 1192exact match has been found. 1193 1194Server response: 1195---------------- 1196<- code exact matches found 1197<- categ discid dtitle 1198<- categ discid dtitle 1199<- (more matches...) 1200<- . 1201 1202 code: 1203 210 Found exact matches, list follows (until terminating marker) 1204 417 Database access limit exceeded, explanation follows (until marker) 1205 1206 1207Addendum A: CDDB Protocol Under HTTP: 1208------------------------------------- 1209 1210Accessing a CDDB server CGI script is done by encapsulating the CDDB protocol 1211command in the HTTP protocol. The only limitation is that a single command 1212may be executed per connection, since HTTP is not truly interactive. For the 1213server to be accessed in this way, it must reside on the target host at a 1214known URL which is accessible by the host HTTP server. The client program 1215must connect to the HTTP server on the target host and issue an HTTP command 1216with the appropriate CDDB protocol command encapsulated within. 1217 1218Commands may be submitted to servers in CGI mode using either the "GET" or 1219"POST" HTTP commands. Both methods are supported, and there is no real 1220difference between how both are to be used other than the syntactical 1221difference between the two methods. The "POST" method may provide the ability 1222to issue longer commands, though, depending on the architecture of the HTTP 1223server on the remote system. 1224 1225The server command must be sent as part of the "Request-URI" in the case 1226of the "GET" method, and as the "Entity-Body" in the case of the "POST" 1227method. In both cases, the command must be of the following form: 1228 1229cmd=server+command&hello=joe+my.host.com+clientname+version&proto=1 1230 1231Where the text following the "cmd=" represents the CDDB Protocol command to 1232be executed, the text following the "hello=" represents the arguments to 1233the "cddb hello" command that is implied by this operation, and the 1234text following the "proto=" represents the argument to the "proto" command 1235that is implied by this operation. 1236 1237The "+" characters in the input represent spaces, and will be translated 1238by the server before performing the request. Special characters may be 1239represented by the sequence "%XX" where "XX" is a two-digit hex number 1240corresponding to the ASCII (ISO-8859-1) sequence of that character. The 1241"&" characters denote separations between the command, hello and proto 1242arguments. Newlines and carriage returns must not appear anywhere in the 1243string except at the end. 1244 1245For example, should user "joe" on system "my.host.com" be running CDclient 1246version 2.1, a read request for his currenly playing CD might look like this: 1247 1248cmd=cddb+read+rock+12345678&hello=joe+my.host.com+CDclient+2.1&proto=4 1249 1250The server will perform the implied "proto" and "cddb hello" commands, 1251and then perform the requested "cddb read" command. 1252 1253Server response to the command is encapsulated in the HTTP server response, 1254and appears in the "Entity-Body". Note that the HTTP response "Entity-Header" 1255is not guaranteed to contain a "Content-Length" field, so clients should be 1256prepared to accept variable length input. The header will always contain a 1257Mime "Content-Type" field which describes the body of data as "text/plain". 1258 1259Here is an example HTTP-mode request, including the necessary HTTP protocol: 1260 1261GET /~cddb/cddb.cgi?cmd=help&hello=steve+cddb.com+CDclient+2.1&proto=4 HTTP/1.0 1262 1263For more detailed information on HTTP and Mime, see RFC 1945 and RFC 1521, 1264as well as later amendments to those RFCs. 1265 1266 1267APPENDIX D - OFFICIAL CDDB SOFTWARE DISTRIBUTION SITES 1268------------------------------------------------------ 1269 1270All CDDB-related software and other files are distributed via the 1271CDDB web page (under "Downloads"): 1272 1273 http://www.cddb.com/ 1274