AMG: itunesdb is a Tcl library for reading iTunesDB files.

If you have an iPod, this library may be of use to you. An iPod uses an iTunesDB file to store all information about its music and playlists. Most importantly, the iTunesDB file associates song titles with files in the iPod's filesystem.

Get the source code at .

(RFox 2012-09-26 - Fixed the link above where junkdrome was mis-spelled jundrome).

itunesdb uses Snit.

I wrote itunesdb for tclpod. Right now tclpod's just a collection of GUI ideas cribbed from competing programs. Earlier versions cross-referenced itunesdb's output to allow for filtering by artist, album, etc. But I think I might switch to sqlite or TclDOM to do this work. At any rate, I don't plan to do any work on tclpod until I'm happy with itunesdb's API.

I relied heavily on the source code for gtkpod [L1 ] and GNUpod [L2 ] to help me figure out the iTunesDB file format. Unlike itunesdb, both of these programs are capable of writing iTunesDB files. I might add iTunesDB writing capability if someone needs it. But since tclpod is only intended to list and extract songs, it wasn't in the original design.

While itunesdb isn't as fast as these other programs, I think its source code is easier to read. And it has the advantage of being a Tcl program. In the particular case of tclpod this was crucial because I didn't want to force the target user (my brother, as it turns out) to figure out how to compile and install some library on his iBook, whereas he already has Tcl/Tk.

Anyone care to help out?

Sample Usage

  % package require itunesdb
  % set db [itunesdb /mnt/ipod/iPod_Control/iTunes/iTunesDB]
  % $db seek track
  % while {[$db remaining]} {
       array set track [$db read]
       puts "$track(artist) - $track(title)"
  % $db destroy

[dict] should make this easier and faster. :^)

If anyone wants to see more, the (incomplete) source code to tclpod is available upon request.

WJR March 13, 2005: On my OS X laptop, the sample usage above outputs several lines of this:

 ÄÄÄÄʧÄÊ\prodÄʨÄ'ÄÄ 0/00òÄÊinftyÄʺÄÁ§ÄÊêÄ - ÄÄÄÄʧÄÊúÄÁåÄ'ÄÄʺÄÊ\prodÄ'ÄÄÁêÄÊ/-ÄÊîÄ'ÄÄÄÄúÄʧÄÊ\prodÄÊúÄ'inftyÄ'ÄÄÄÄÄÄÁêÄ'\prodÄ'ÄÄ"ÑÄ

This is from an iTunesDB file generated from iTunes 4.7.1. Tcl version 8.4, snit version .94.

AMG: Hrrm, try again with 0.02, updated just today. (I don't expect this to fix anything, but at least it'll be a hell of a lot faster!!) Also I'd appreciate it if you emailed me the iTunesDB file. I don't actually have iTunes or an iPod so I have a hard time testing this thing myself. :^)

It might be a byte ordering issue. itunesdb.tcl uses [encoding convertfrom unicode $data] to get a string from a byte array read with [binary scan $buffer a$length data].

AMG: Okay, I (hopefully) fixed it in 0.03. <grumble> stupid "unicode" encoding... </grumble>

To Do

  • Revamp API for use in Real programs.
  • More testing, particularly of the error handling and resynchronization mechanism. Also test with iTunesDB files generated by various programs, including iTunes itself.

Wish List

  • Documentation.
  • More speedups.
  • Write support.
  • Smart Playlist support.


11 August 2004 - version 0.01 (renamed from 0.1.0)

  • Initial release.

15 March 2005 - version 0.02

  • Minor tweak to API. Not backward-compatible.
  • Major speedups.
  • Workaround for weird playlists made by iTunes.

17 March 2005 - version 0.03

  • Support for group, samp_rate, volume, add_time, and bpm.
  • Fixed bad file format reporting.
  • Workaround for incorrect UTF-16 byte order on big-endian machines.
  • Support for iPod Shuffle. (AMG: Actually itunesdb has always had iPod Shuffle read support--- we just didn't know until now.)

 What: itunesdb
 Description: Tcl library for reading iTunesDB files.
 Version: 0.03
 Updated: 17 March 2004
 Contact: Andy Goth <[email protected]>

AMG: There's a version 0.04 at the same location, but it's highly experimental and is possibly neither backward- nor forward-compatible. If you do play with it, please tell me what you think. I will re-add the old API in version 0.05, and it remains to be seen whether 0.05 will contain the new API as well.

AMG 8 Dec 2005: After doing nothing with itunesdb for a while, on the grounds that I don't believe it's heading in the right direction, I have decided that I should correct the situation by, well, changing its direction. Making a truly nice interface to a database system isn't easy, but it has been done before, and it's called SQLite! That's one wheel I don't care to reinvent. Therefore...

Any future work I do on itunesdb will be focused on making it translate between iTunesDB, etc. files and SQLite databases (in memory or cached on disk), and queries/updates will be performed using SQL statements.


UKo 2006-02-14: I tried to figure out the format of the CD Info.cidb -- the database itunes uses for information about every inserted CD. It looks a bit like what is expected by itunesdb, but the library gives an error when trying to parse a cidb file. I wasn't able to find any documentation (or even mentioning) of the CD Info.cidb fileformat. With a little bit of research I have made something like a structure of the cidb file, but it's only a start. And the only application able to read and write this file is iCDc. Is there anyone out there with some more insight?

I want to make a (Tcl) application that is able to merge two cidb files or add information from a freedb proxy -- without this functionality every single user has to request every single CD from the internet and this is very unconvenient with a modem ... Beware - FreeDB Access


Jeremy Miller - generating a playlist using itunesdb

Pierre Coueffin 2006-05-17: appears to be down. Has anyone still got a copy of itunesdb?

Jeremy Miller 2006-05-19: Andy seems to be encountering issues with his domain registration. Here are the links to the various versions he has hosted:

I'll remove these once this issue is remedied.

Pierre Coueffin 2006-05-19: Thanks a lot, I was starting to get frustrated trying to find a mirror site.

AMG: Or just go to my site, which is back. I updated links elsewhere on this page.