TWO FORMS OF ACCESS TO THE FREEDB --------------------------------- In the following document we will refer to CDDB instead of freedb, since from a technical point of view, freedb is a CDDB-Server as it uses the CDDB-protocol. If you are interested in incorporating the use of freedb 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. 2. Remote access In this mode the software must connect to a freedb 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. You may choose to support either one, or both of these modes. CDDB DISCID ----------- Both forms of CDDB access requires that the software computes 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 the DISCID Howto. It is crucial that your software compute the disc ID correctly. If it does not generate the disc ID, it will not be compatible with the CDDB. Moreover, if your software submits CDDB entries with bad disc IDs to the freedb archives, it could compromise the integrity of the freedb. If you have access to a UNIX platform that xmcd supports, we suggest installing xmcd, and then test the disc ID code in your software by comparing the disc ID generated by xmcd with that of your software, for as large a number of CDs as possible. LOCAL CDDB ACCESS ----------------- There are two forms of the CDDB archive available, the standard form and the alternate form. Both forms are available for download from various servers. You can always find an actual list of mirrors on the freedb-homepage at http://freedb.freedb.org. The standard form of the CDDB archive is released to the public as a UNIX tar(1)-format archive, compressed with gzip. The alternate form archive is in the .zip format that is popular on the Windows platform. Standard Form: -------------- Each CD entry is a separate file in the xmcd CDDB. These files are organized in several directories, each directory is a category of music. Currently the "official" categories are listed as follows: blues classical country data folk jazz misc newage reggae rock soundtrack The individual CDDB files have a file name that is the 8-digit disc ID. For example, under the blues directory there may be the following files: 0511c012 060e7314 0c01e902 0f0c3112 ... fa0f6f10 fb0f8814 fd0e6013 To access the CDDB entry associated with a CD, your software simply opens the appropriate file and reads the information. The content of each of these files is in a format described in the database-format specification. Different pressings of a particular CD title may contain differences in timings that can cause the computed disc ID to be different. The CDDB allows this by having multiple file names be links to the same file. The links are implemented as actual filesystem links (see the ln(1) command) on UNIX systems. For example, the following files in the rock directory are all links to the same file, and refer to the CD "Pink Floyd / The Division Bell".: 850f740b 850f950b 850f970b 860f960b 890f970b Xmcd and the CD database server use this form of the CDDB archive. The benefit of the standard form of the CDDB archive is very fast access, and ease of add/delete/edit operations on entries. Alternate Form: --------------- Due to limitations in the FAT file system used on Windows 9x and Windows ME, it is unfeasible to use the standard format CDDB archive due to the large number of files. This is because such a filesystem operates on fixed-size clusters and even a small file (and most CDDB files are 1KB or less) would consume the space of a full cluster (Depending upon disk size, a cluster can range from 4KB to 32KB in size). Thus, a tremendous amount of disk space would be wasted on these systems if the CDDB archive is used in its standard form. An alternate form of the CDDB archives was created for use by software that must operate on a system with the FAT limitations. The alterate form still use the separate category directories as the standard form, but concatenates many files into a smaller number of files under each category. The first two digits of the CDDB file names is used as a key for concatenation, each file is allowed to grow to approximately 64KB in size before a new file is started. The file name indicates what range of the digits are included in that file. For example, under the blues category we may have the following files: 01to36 37to55 56to71 ... b2tod7 d8toff The 01to36 file contains all CDDB entries with disc ID 01xxxxxx, 02xxxxxx, 03xxxxxx and so on, up to 36xxxxxx. Each entry in the concatenated file begins with the keyword #FILENAME=xxxxxxxx where discid is the 8-digit hexadecimal disc ID of that entry. Your software must search through the appropriate file to locate the desired entry. The CDDB entry is in the format described in Appendix B below. The alternate form avoids the problem of inefficient disk space utilization on FAT-based filesystems, but is slower to access than the standard form, and it is much more cumbersome to perform add/delete/edit operations on a CDDB entry. REMOTE CDDB ACCESS ------------------ Your software must be able to communicate with a remote CD server system via TCP/IP or HTTP. There are a number of public freedb servers operating on the Internet. The current list of public servers is listed on the freedb web page at: http://freedb.freedb.org. It may also be obtained programmatically via the CDDB protocol "sites" command. TCP/IP access: All current freedb servers answer at TCP port 888. There may be future sites that deviate from this convention, however. HTTP access: The freedb-servers can be accessed via the cddb.cgi. This is resides at the following path: /~cddb/cddb.cgi Thus, the URL for accessing the server at freedb.freedb.org is: http://freedb.freedb.org/~cddb/cddb.cgi You should make the freedb server host (or hosts) and port numbers user-configurable 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 in the CDDB-protocol documentation. The CDDB entry returned from the server via a "cddb read" command is in the format described database-format specification. You may experiment with the freedb server by connecting to port 888 of the server host via the "telnet" program, and then typing the cddb protocol commands by hand. For example: telnet freedb.freedb.org 888 connects you to the freedb server at freedb.freedb.org. Some additional notes for accessing freedb over the Internet: Your application should always specify the highest documented protocol level. The highest level currently supported is "3". 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 with 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 clients should support close matches (aka "fuzzy" matches, or response code 211). The proper way to handle multiple 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 offer to get the list from freedb.freedb.org with the "sites" command the first time the user runs the program. Additionally the application should provide the user with some method of downloading the list on-demand. We do strongly suggest that you provide your users with the capability of choosing freedb 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 "freedb.freedb.org" in your application as the sole freedb 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.