From kJams Wiki
Jump to navigation Jump to search


The "freedb" is a user-created remote online database that contains meta info for CDs. That is, it contains entries that specify, for each CD, all the artist, album, track title, genre and various other information. Presently there are over 1.8 million entries in the database. kJams incorporates access to this database so that, when you insert a CD, the database is queried for the CD's meta info, so that you don't have to type it in. If, however, no information is found, you are encouraged to enter it manually, then submit your work to the database, so that others may benefit.

Local and Remote Access

kJams will always attempt to find the information about a disc using a local copy of the database. If nothing is found, will then attempt to reach the database over the internet (if you have this option enabled). The Local database is entirely optional and most people will choose not have the local database installed, as it is quite large and does not automatically stay up to date like the internet database. It does come in handy, however, if you plan to play discs when you do not have access to the internet (eg: if you're a Pro KJ and you're taking your laptop to a venue with no internet access). To install the local database, see below. You may also choose to run a freedb server on your LAN, which would be able to service any computer connected to it. Note that even tho this would be technically "local" to you, for the purposes of kJams this would be considered a "remote", or internet database.

Get and Submit

At any time you can attempt to get or submit disc info using the database. When you go to the "Advanced" menu and choose "Get CD Tracks from freedb...", kJams will attempt to find the info in the database, and if found, update the copy that kJams keeps for that disc. Note you will loose any info currently stored for that disc.

If you have entered new info or changed or corrected info for a disc, you are encouraged to go to the "Advanced" menu and choose "Submit CD Tracks to freedb...". When you do, kJams will contact, over the internet, the freedb server and submit the entries for that disc. If there are any problems with your submission, you should get an email explaining the problem, so you can correct it and resubmit. Note that submitting does NOT update your local database, if you have one.

Get meta data for a PlayList

This also works for playlists with less than 30 songs in them. The songs MUST be in the correct track order and MUST contain every song in the album. Sort the playlist by "#" first (NOT by track number), and drag-reorder them to get them into the correct order. Then follow the directions for Fetching Metadata.

Installing the Local Access database

This is entirely optional. Skip this section if you don't care. First you must downlaod the full database. There are two options. PICK ONE!

Option 1: Mac .dmg

The initial download is about 1.8 GB. It is a compressed AND zipped disk image file, it'll be about 3 GB (after unzipping), and it's ready to use as soon as you download, unzip and mount the image. (First time you mount is slow while it verifies, but you can "Skip" that)

To download, click here (based on the Feb 2015 distribution)

To use it, just mount the disc image (double click it), then kJams will automatically find it. kJams will not automatically mount the image, but you can place the disc image into Apple->System Preferences->Accounts->(your account)->Login Items, that way it will always be there even if you restart your computer,

Option 2: .tar.bz2

The initial download is about 850 MB, but then it needs to be decompressed. Uncompressed it will take about 15 GB (that's Gigabytes) of your physical hard drive space (even though the logical space taken is only 3.6 GB). Decompressing can take several hours on an older computer.

To download, go to the download page, and select a mirror site that is closest to you geographically (currently I see only Germany, but that list may expand later). Then find the file that says "freedb-complete-YyyyMmDd.tar.bz2" (where Yyyy is year, Mm is month and Dd is day, you want the most recent one, of course), and download it.

To use it, uncompress it to the location you would like to keep it. It doesn't matter where you put the final folder, it is fine to keep it on an external or even a network volume. Once it is decompressed (and it takes more than an hour, by the way), you will have a main folder that contains sub folders with the familiar category names. Select this main folder in the finder and choose "Make Alias" from the file menu. Rename this alias "freedb", it must be named exactly that. Now, drag this alias into your "~/Music/kJams/" folder. Alternately, you could move (or decompress) the original to this location, and give the main folder the name "freedb".



  • Use Internet Database (checkbox) This instructs kJams to search the database via the internet. You must have an active internet connection for this to work. Note that kJams will always attempt to search the local database first, if present, even if this checkbox is not checked.
  • Update List (button) This causes kJams to contact the freedb (over the internet), in order to get a list of servers to use to search the database. It then puts this list into the popup menu (see "Site List Popup", below), replacing it's former contents. Keep in mind that this list can change periodically, I recommend pressing this button at least once a year to keep the list fresh.
  • freedb Site (text edit) 'Experts Only!' This is where you can manually edit the URL that kJams will use to query the freedb. You can choose which site to query by entering it in this box. Note: 99% of users will never type into this box, this is only for expert users. What you probably want to do is use the "Site List Popup", see below. For example, you may choose to run a freedb server locally or on your LAN, or your company may do so. You can manually specify host, port and path. For example you could type "localhost:777/~freedb/path/to/db/cddb.cgi
  • Site List Popup (pop-up menu) This menu contains a list of sites that kJams can use to query and submit. The freedb is not just in one place, it is spread out geographically in many countries, to help balance the load. Choose "Random freedb server" to have a different server used each time, or pick the one that is geographically closest to you.
  • Server Timeout (Seconds) (number edit) If you are on a slower internet connection, it may take some time before you are able to receive a response from the freedb server. In this case, try increasing the number of seconds to wait before giving up. Default is 10 seconds.
  • E-Mail address (text edit) When you submit a CD to the database, if there is any problem with your submission this address will be used to notify you of the nature of the trouble, so you can correct it and re-submit.

Submission Problems

By far the most common problem is you get a message something like this:

Your freedb submission was rejected for the following reason:
Discid collision in category <foo>

Where <foo> is the category under which you submitted. Quick solution: Double click on the CD in the sources list and pick another category, then try submitting again. Any category, it practically doesn't matter.

You're not doing anything wrong, and you're right on target to think there's something amiss with how freedb is implemented. It is based on CDDB, which is a very old standard. Before the dawn of time folks thought that DiscID collisions would be so rare as to be almost non-existant. To solve the problem of the super rare cases where the DiscID's actually do collide, they created "categories". Which unfortunately is not a very robust solution because there are only 11 categories, and you can have disc1 that is Rock, and disc2 that is also Rock, and they resolve to the same DiscID. In that case you have to put disc2 under something other than Rock. It gets worse if you have move than 11 discs that resolve to the same ID. Then you're just utterly screwed, you just can't add more than 11 discs with the same ID into the freedb. Here's the explanation from the horse's mouth.