Being inspired by the recent blog entry ‘Some Notes on iTunes LP‘ by blogger and webdeveloper Jay Robinson and the analysis by Roughlydrafted Magazine, I started to dig into the inner workings of the iTunes LP and TuneKit. I decided to share my findings here, and will update accordingly to any progress made.

Screenshot of iTunes LP - Blueprint 3

Getting our definitions right

iTunes LP – Technology to show a digital booklet with dvd-like extra’s combined with a full album bought from the iTunes Music Store.

Album – Tracks you get on the release, outside of the .itlp file. This is just the ‘regular album’.

TuneKit – JavaScript engine powering the visual presentation of the booklet and glue layer for iTunes.

Even more tutorials, background information and stuff the big fruit company doesn’t use yet.

Some points in advance

  • Roughly drafted points out nicely the metadata in the index.html showing features used by the Apple TV, but fails to mention the specific apple-tv style declarations found in the css/style.css (@media (-webkit-apple-tv))
  • Every LP contains the same codebase for TuneKit, for instance Tyrese Gibson’s Mayhem includes a comic, yet Jay-Z’s Blueprint 3 doesn’t but still contains the classes for the comic content. One could exclude this properly as it’s unused.
  • TuneKit is very well written and is very straightforward in its usage. It contains some helpful comments here and there, but lacks real documentation (as it should in a ‘release’).
  • Jay Robinson mentions, when talking about DRM, your store account being stored inside the plist. Don’t forget that all purchases from the iTunes store contain the copyright in the metadata tag cprt from your AAC/M4A, and your store account in apID.

Files and folder

  • controllers/ – iTunes LP specific controllers, used to manage the songlist/songplayback and all other album specific code
  • controllers/data.js – important file used to maintain the ‘datamodel’ from the application
  • index.html – main entry file, used to link in all controllers, TuneKit, and css files. Mostly contains a single DIV element to build a container for the application to run in
  • <album name>.itlp – 0 bytes, doesn’t do much, probably either a left over or used for a single check for validity
  • iTunesArtwork – High resolution jpeg image containing the album cover
  • iTunesMetadata.plist – Used to store all information about the buyer and track/album information, home of track/xid mappings
  • manifest.xml – unclear what this does, as it doesn’t get referenced inside the application code
  • src/ – TuneKit folder, contains all classes relevant to the library
  • views/ – All album specific views, clearly seperated from the application logic

Creating your digital enhanced album

The easiest way to get started is by creating a skeleton from a pre existing iTunes LP. You remove all files deemed not needed for your custom implementation. This basically means deleting data folders like audio/, stripping the css to only the first few selectors and removing all controllers and views. You might want to  keep song*.js inside the controller folder. You’ll end up with basically a small folder structure with TuneKit and a single html file and css file. You then start editing the iTunesMetadata.plist and manifest.xml according to your details. Make sure you remove your buyer information, or substitute it with dummy data. From here on its pretty straightforward webdevelopment, you just use TuneKit to manage your views and your controllers and use the provided SonglistController or your own management for playing the iTunes tracks (when the metadata is correct). It might be wise to look into the new features provided by webkit (such as CSS Animations, @font-face font embedding and those other neat tricks found in the current batch of iTunes LP’s).
Debugging can be done in Safari for the most part, unless you access the window.iTunes object, most of its data isn’t available then. Take notice of the fact that there is a build in debug feature, but we haven’t found a way to access that information yet. So document.write is your best friend here probably.

skeleton

Mapping tunes to the playlist based on analysis of metadata and xml files and some tinkering in the code

TuneKit uses the BookletController, SonglistController and SongPlaybackHelper to manage the songs delivered with the album. These songs are internally referenced with an XID (For example, Jay-Z’s Death Of Autotune is XID: Warner:isrc:USAT20902100). This XID is referenced by controllers/data.js and manifest.xml and leads back to the iTunesMetaData.plist, where it is mapped in the dict.key/xid-asset-mapping dictionary to the cnId found in the metadata of the m4a files delivered in the album. The plId found in all items points directly to the album in your playlist (used by the album feature of iTunes), this plId is the first id referenced in the dict.key/associated-adam-ids. Basically what happens when your viewController.js asks to play a song, is that it calls songplaybackHelper.playSong with the value from data.js. This causes the songlistController to call the TKNavigationController to jump to a song.

atomicparsley

When you want to create an iTunes LP for an existing album in the iTunes Store (assuming you bought it there), it should have these id’s in them. However, when you as an independent artist want to enrich your album, you must set these parameters yourself. It’s better to choose a value very low or very high in the same number range, so you don’t conflict with the library from your users. You can edit and see these metadata tags with a small modified version of the great AtomicParsley.

The window.iTunes object

Looks like you can access a whole load of functions using the window.iTunes object. For instance you can play a track using a relative url to the itlp, or play a track by the cnId in your metadata. We haven’t managed to expose all function signatures yet, but with a bit of trial and error you’ll manage to get the results your looking for. For instance you can build up a playlist usin window.iTunes.findTracksByXID(aXID:String), and play them using the play method. This way you do not need to do the full songlist building as seen in the SonglistController and SongplaybackHelper classes but do a simple management yourself. You could also go on and use the window.iTunes.findTracksByTextfields(aObject:Object) to list tracks without the XID metadata tag.

Publishing your digital enhanced album

The album itself can safely be distributed inside a zip file, people on all supported operating systems can extract these. On Mac OS X you get a resulting .itlp file, which launches iTunes when you double click on it. It should register your album immediatly.
On Windows your zip file file extract a folder, this is because Windows doesn’t do Application Bundles. But no worries here, you can just drag the folder onto iTunes and go with the flow.

Conclusion

Apple did a solid job of creating a nice and easy to use platform for digital booklets. We can only hope that Apple opens this format officially for others to implement and grant usage for the TuneKit library to the public. Where do we go on from here ? My ultimate goal is to let independ music artists enrich their album by providing an itlp free of charge with their digital albums. Other huge steps could be an authoring environment for independent artists, so they can drag and drop their assets and tunes, where a dedicated platform takes care of converting the formats and generating the metadata and code for the files. Think of a DIY booklet generator.

Credits

This guide is compiled by information found in the iTunes Music Store delivered iTunes LP files, research and a bunch of help from Daniël. A bit of credit goes to debdrup for being generally awesome and providing feedback.
Needless to say, iTunes, the iTunes Music Store and iTunes LP are trademarks from Apple, Inc.

Originally published: 2009/09/12.

Content written by Martijn de Boer. All content here may be quoted, linked to or summarized when linking to the original materials.