221 lines
9.8 KiB
Plaintext
221 lines
9.8 KiB
Plaintext
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.
|