ref: 88181e1c5c8d19e61c76b93620abcbc7c2e57481
dir: /acme/bin/source/acd/submit/
CDDB SUBMISSION --------------- Your software may allow users to enter CDDB data and then submit them to the freedb archive. There are two methods of submission: <a href="#email">via e-mail</a> or <a href="#http">via http</a> using submit.cgi <a name="email"></a>1. Submission via e-mail ------------------------ Your software has to send the entry to the following address: freedb-submit@freedb.org You may implement a button or somesuch in your software's user-interface to facilitate this. The destination e-mail address should be made user-configurable. There should be one e-mail message per freedb entry. The mail Subject line should be in the form "cddb category discid". For example: Subject: cddb rock 850f970b The body of the e-mail message should be in the format of a CDDB file entry as described <a href="http://freedb.freedb.org/software/old/DBFORMAT">here</a>. The messages should contain only plain ASCII text. Do not attach encoded information or add special escape sequences. Note that the disc ID specified in the mail Subject line should also appear in the list of disc IDs in the DISCID= field of the CDDB file entry. If not, it is considered an error and the submission will be rejected. You should only allow categories that are currently supported by the freedb (blues, classical, country, data, folk, jazz, misc, newage, reggae, rock, soundtrack). Submissions specifying unsupported categories will be rejected. 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, or filled with useless default information like "track 1", "track 2", etc.). While the current CD database server checks and rejects submissions that have a blank DTITLE line, it doesn't (and can't feasibly) check the track titles effectively, nor can it check any of these fields if they are filled with a default string. If it were, it would have to be hacked to know about the default strings of every possible client. Thus, please design your client with this in mind. This is a somewhat tricky thing to do, as some CDs contain blank tracks with no titles and you need to allow for that. 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. Check that all of the tracks have a title filled in by the user (some (but not all!) may be blank, but not the default string). This should minimize the number of useless garbage being submitted into the CD database. Before you release your software, please be sure that it produces submissions that adheres 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 to the following e-mail address (rather than the real submission site at freedb-submit@freedb.org): test-submit@freedb.org The test address performs sanity checking on the CDDB submission and sends back pass/fail confirmation, but does not actually deposit the entry in the CD database. <a name="http"></a>2. Submission via http ---------------------- For submit via http, your application has to transmit the entry to the database through a CGI program at the following URL: http://freedb.freedb.org/~cddb/submit.cgi 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 (blues, classical, country, data, folk, jazz, misc, newage, reggae, rock, soundtrack). 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 "<a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=6">Discid howto</a>" section. 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 <a href="#testsubmission">below</a> 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 (but which are currently not used by the freedb): 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 # # 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 freedb 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 <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=28">CDDB server protocol</a> for more information on handling response codes. The body of the freedb entry being submitted should be sent verbatim as described in the <a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>. 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, or filled with useless default information like "track 1", "track 2", etc.). While the current CD database server checks and rejects submissions that have a blank DTITLE line, it doesn't (and can't feasibly) check the track titles effectively, nor can it check any of these fields if they are filled with a default string. If it were, it would have to be hacked to know about the default strings of every possible client. Thus, please design your client with this in mind. This is a somewhat tricky thing to do, as some CDs contain blank tracks with no titles and you need to allow for that. 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. Check that all of the tracks have a title filled in by the user. (some (but not all!) may be blank, but not the default string). 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". <a name="testsubmission"></a>CDDB submissions sent in test mode will be sanity-checked by the freedb 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 you have tested your program with several different CD's.