Subversion Repositories planix.SVN

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.