1TWO FORMS OF ACCESS TO THE FREEDB 2--------------------------------- 3 4In the following document we will refer to CDDB instead of freedb, since 5from a technical point of view, freedb is a CDDB-Server as it uses the 6CDDB-protocol. 7 8If you are interested in incorporating the use of freedb in your 9software, there are two forms of access that you may consider. 10 111. <a href="#local">Local access</a> 12 13 In this mode your software simply attempts to open local files on 14 the computer to access the CDDB. 15 162. <a href="#remote">Remote access</a> 17 18 In this mode the software must connect to a freedb server on the 19 network to access the CDDB. There is a CDDB server protocol that 20 the software (also known as the "client") must use to converse with 21 the server. 22 23You may choose to support either one, or both of these modes. 24 25 26CDDB DISCID 27----------- 28 29Both forms of CDDB access requires that the software computes a "disc 30ID" which is an identifier that is used to access the CDDB. The disc 31ID is a 8-digit hexadecimal (base-16) number, computed using data from 32a CD's Table-of-Contents (TOC) in MSF (Minute Second Frame) form. The 33algorithm is listed below in the <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=6">DISCID Howto</a>. 34 35It is crucial that your software compute the disc ID correctly. If it 36does not generate the disc ID, it will not be compatible with the 37CDDB. Moreover, if your software submits CDDB entries with bad disc 38IDs to the freedb archives, it could compromise the integrity of the 39freedb. 40 41If you have access to a UNIX platform that xmcd supports, we suggest 42installing xmcd, and then test the disc ID code in your software by 43comparing the disc ID generated by xmcd with that of your software, 44for as large a number of CDs as possible. 45 46 47<a name="local"></a>LOCAL CDDB ACCESS 48----------------- 49 50There are two forms of the CDDB archive available, the standard form 51and the alternate form. Both forms are available for download from 52various servers. You can always find an actual list of mirrors on the 53freedb-homepage at <a href="http://freedb.freedb.org">http://freedb.freedb.org</a>. 54The standard form of the CDDB archive is released to the public as 55a UNIX tar(1)-format archive, compressed with gzip. The alternate 56form archive is in the .zip format that is popular on the Windows 57platform. 58 59Standard Form: 60-------------- 61 62Each CD entry is a separate file in the xmcd CDDB. These files are 63organized in several directories, each directory is a category of 64music. Currently the "official" categories are listed as follows: 65 66 blues 67 classical 68 country 69 data 70 folk 71 jazz 72 misc 73 newage 74 reggae 75 rock 76 soundtrack 77 78The individual CDDB files have a file name that is the 8-digit disc 79ID. For example, under the blues directory there may be the following 80files: 81 82 0511c012 83 060e7314 84 0c01e902 85 0f0c3112 86 ... 87 fa0f6f10 88 fb0f8814 89 fd0e6013 90 91To access the CDDB entry associated with a CD, your software simply 92opens the appropriate file and reads the information. 93 94The content of each of these files is in a format described in the 95<a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>. 96 97Different pressings of a particular CD title may contain differences 98in timings that can cause the computed disc ID to be different. 99The CDDB allows this by having multiple file names be links to 100the same file. The links are implemented as actual filesystem links 101(see the ln(1) command) on UNIX systems. For example, the following 102files in the rock directory are all links to the same file, and 103refer to the CD "Pink Floyd / The Division Bell".: 104 105 850f740b 106 850f950b 107 850f970b 108 860f960b 109 890f970b 110 111Xmcd and the CD database server use this form of the CDDB archive. The 112benefit of the standard form of the CDDB archive is very fast access, 113and ease of add/delete/edit operations on entries. 114 115Alternate Form: 116--------------- 117 118Due to limitations in the FAT file system used on Windows 9x and 119Windows ME, it is unfeasible to use the standard format CDDB archive 120due to the large number of files. This is because such a filesystem 121operates on fixed-size clusters and even a small file (and most CDDB 122files are 1KB or less) would consume the space of a full cluster 123(Depending upon disk size, a cluster can range from 4KB to 32KB in 124size). Thus, a tremendous amount of disk space would be wasted on 125these systems if the CDDB archive is used in its standard form. 126 127An alternate form of the CDDB archives was created for use by software 128that must operate on a system with the FAT limitations. 129 130The alterate form still use the separate category directories as the 131standard form, but concatenates many files into a smaller number of 132files under each category. The first two digits of the CDDB file names 133is used as a key for concatenation, each file is allowed to grow to 134approximately 64KB in size before a new file is started. The file name 135indicates what range of the digits are included in that file. For 136example, under the blues category we may have the following files: 137 138 01to36 139 37to55 140 56to71 141 ... 142 b2tod7 143 d8toff 144 145The 01to36 file contains all CDDB entries with disc ID 01xxxxxx, 14602xxxxxx, 03xxxxxx and so on, up to 36xxxxxx. 147 148Each entry in the concatenated file begins with the keyword 149 150#FILENAME=xxxxxxxx 151 152where discid is the 8-digit hexadecimal disc ID of that entry. Your 153software must search through the appropriate file to locate the desired 154entry. The CDDB entry is in the format described in Appendix B below. 155 156The alternate form avoids the problem of inefficient disk space 157utilization on FAT-based filesystems, but is slower to access than the 158standard form, and it is much more cumbersome to perform add/delete/edit 159operations on a CDDB entry. 160 161 162<a name="remote"></a>REMOTE CDDB ACCESS 163------------------ 164 165Your software must be able to communicate with a remote CD server 166system via TCP/IP or HTTP. 167There are a number of public freedb servers operating 168on the Internet. The <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=9">current list of public servers</a> is listed on the 169freedb web page at: 170 171 http://freedb.freedb.org. 172 173It may also be obtained programmatically via the CDDB protocol "sites" 174command. 175 176TCP/IP access: 177 178All current freedb servers answer at TCP port 888. There may be future 179sites that deviate from this convention, however. 180 181HTTP access: 182 183The freedb-servers can be accessed via the cddb.cgi. This is resides at the 184following path: /~cddb/cddb.cgi 185Thus, the URL for accessing the server at freedb.freedb.org is: 186http://freedb.freedb.org/~cddb/cddb.cgi 187 188You should make the freedb server host (or hosts) and port numbers 189user-configurable in your software. Do not hard-wire the list of 190CD database servers into your code. The list of active servers changes 191over time. 192 193The CDDB server protocol is described in the <a href="http://freedb.freedb.org/sections.php?op=viewarticle&artid=28">CDDB-protocol documentation</a>. 194 195The CDDB entry returned from the server via a "cddb read" command is in 196the format described <a href="http://freedb.freedb.org/software/old/DBFORMAT">database-format specification</a>. 197 198You may experiment with the freedb server by connecting to port 888 of 199the server host via the "telnet" program, and then typing the cddb 200protocol commands by hand. For example: 201 202 telnet freedb.freedb.org 888 203 204connects you to the freedb server at freedb.freedb.org. 205 206Some additional notes for accessing freedb over the Internet: 207 208Your application should always specify the highest documented protocol 209level. The highest level currently supported is "3". Lower protocol 210levels will work, but are only provided for compatibility with older 211CDDB applications. If you do not use the highest available protocol 212level, certain important features will not be available to your 213application. 214 215Make sure to use the proper arguments with the "hello" command. The user 216and hostname arguments should be that of the user's email address, not 217some fixed hard-coded value. The application name and version should be 218that of your application, not that of another existing application. 219 220We consider the use of the "cddb query" command mandatory for all CDDB 221clients. It is not valid to issue a "cddb read" command without issuing 222a prior "cddb query" and receiving a good response, as it may yield incorrect 223results. In addition, it is clients should support close matches 224(aka "fuzzy" matches, or response code 211). 225 226The proper way to handle multiple fuzzy matches is to present the 227entire list of matches to the user and to let the user choose between them. 228Matches are listed in the order of best fit for the user's disc, so they 229should be presented to the user in the order they are listed by the server. 230 231The suggested algorithm for obtaining the list of server sites is 232as follows. The application should offer to get the list from 233freedb.freedb.org with the "sites" command the first time the user runs 234the program. Additionally the application should provide the user with 235some method of downloading the list on-demand. 236 237We do strongly suggest that you provide your users with the capability of 238choosing freedb server sites as described above. However, for some 239applications this may not be feasible. If you do not wish to offer this 240functionality, you may safely hard-code "freedb.freedb.org" in your 241application as the sole freedb site to access. This will deprive your users 242of the option to choose a site near their locale for optimal response, but 243that is your choice. 244