Getting started

Probably the best way to get started though is to purchase an iTunes LP from the iTunes store. The official albums use a library called TuneKit which is an invaluable resource when trying to create your own LPs. You can look at our downloadable LPs but those do not, for various legal reasons, contain TuneKit. We also only use a small very specific part of the possibilities provided; to understand your options fully it's best to also look at the full TuneKit as provided in the LPs on the iTunes store.

Structure

An iTunesLP .itlp file is a Mac OS X file bundle. This is a folder that is recognised by the operating system as a single file which allows you to handle and manipulate it as if it were a single thing. Windows has no such facilities so it simply displays the folder as a folder.

To get at the bundle's insides right-click the file and select Show Package Contents. Inside you will find a lot of files which basically amount to a HTML application. The folder will contain a bunch of files and folders with roughly the following file-list; this may differ slightly per iTunes LP:

audio
This folder contains extra audio files used by the iTunes LP such as background audio loops.

controllers
This folder contains a set of Javascript files that contain the content of the iTunes LP and a set of controllers that tell application which views (.html files) to display and how to transition between them. It also contains data for controlling the visualizer if there is one. One of the most interesting files in there is the data.js which we will get to soon.

css
Contains the css styles for the iTunes LP.

fonts
Some iTunes LPs contain a fonts folder containing either an SVG font or a truetype font. This is curious because these fonts aren't actually used in the application. All text is prerendered to images.

images
Contains the images used in the iTunes LP.

index.html
This is the core application file. This html file is displayed when the iTunes LP is started.

iTunes LP - XXXXXX.itlp
A zero-byte file that has the same name as the bundle .itlp file.

iTunesArtwork
This contains the album artwork for the iTunes LP. This is simply either a PNG or a JPG without it's file-extension.

iTunesMetadata.plist
This file describes the metadata for displaying the iTunes LP in the music browser. It also contains a lot of information about your purchase of that iTunes LP, and a series of ids that link it to various items of the iTunes store. There is also a list of song-ids that are used to connect the tracks in the html application to iTunes tracks. This is explained in the section about XIDs.

manifest.xml
This file contains a mapping of the song-ids in the iTunesMetadata.plist to the XIDs used in the html application.

src
Contains the TuneKit javascript libraries. To keep things legal we avoid using this copyrighted code.

videos
Contains videos that are part of the iTunes LP.

views
Contains the various views used in the application. A view in this case is basically a collection of html markup which defines how a screen in the application looks.

XID and cid, pid, atom-ids ?

iTunes uses a set of unique identifiers on their iTunes store. Each artist, each album (referred to as a playlist) and each track has a unique id. Every purchased audiotrack from the iTunes store contains a set of these ids. It is these ids that are used to connect the code in the iTunes LPs to the tracks in your music library. This however is not done directly. The played tracks and playlists are referenced through XIDs. In the manifest.xml is a list of these XIDs and the track ids to which they are linked.

It would be possible to write these ids to your own .m4a tracks (the tags however are not compatible with id3 for mp3 files), but it requires a specifically modified version of AtomicParsley, which is too much hassle to be worth it. Also it could create conflicts with music purchased on the iTunes store. If for example you use a currently unused pid (playlist id) which later is used for a new album release, if that new release has an iTunes LP it could be referencing your songs, or your LP referencing their songs.

This approach is therefore problematic for any music that is not purchased from the iTunes store. If your intent is to use an LP with purchased music exclusively it might be an option to look into this, however for everyone else there is another option.

iTunes exposes several functions to search the music library for tracks. One is findTracksByXID() which is the default method used in currently published iTunes LPs. Another is findTracksByTextFields() which we will be using in our tutorials and downloadable LPs. This second method allows us to search and play tracks in the music library based on Albumname, Trackname and/or Artist.

What do we need?

When creating our own iTunes LPs only a few of those files are required. You need an index.html, an iTunesMetadata.plist, an iTunesArtwork and a manifest.xml file. Everything else is optional.

So to get started with creating a new iTunes LP simply create a folder with a name ending in .itlp . In that folder place your album artwork (a JPG or PNG) with the filename iTunesArtwork, the file must not have a file-extension. If on windows be sure to turn showing file-extensions on in Explorer, and remove the .jpg or .png extension.

Since iTunes 9.0.2 iTunes LPs require a manifest.xml file. This normally contains information about the songs used. This is only used from within TuneKit, however since we won't be using TuneKit we can leave this file empty except for the most basic structure. Fill the manifest.xml file with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns="http://apple.com/itunes/media_archive/manifest" version="1.0" media_archive_version="2.0">
    <requirements>
        <supported_platforms>
            <platform name="iTunes" minimum_version="9.0"/>
            <platform name="AppleTV" minimum_version="3.0"/>
        </supported_platforms>
    </requirements>
</manifest>

Then create a simple HTML file that displays some kind of greeting.

And finally create a new iTunesMetadata.plist file. This is an XML file containing info on the artist, albumartist, albumname and some other properties. An example of such a file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
	<dict>
		<key>Metadata</key>
		<dict>
			<key>artistName</key>
			<string>Joe's Garage Band</string>
			<key>compilation</key>
			<false/>
			<key>gapless</key>
			<false/>
			<key>genre</key>
			<string>Garage</string>
			<key>itemName</key>
			<string>iTunes LP - Getting Started</string>
			<key>kind</key>
			<string>song</string>
			<key>playlistArtistName</key>
			<string>Joe's Garage Band</string>
			<key>playlistName</key>
			<string>Getting Started</string>
		</dict>
		<key>Name File</key>
		<string>iTunes LP - Getting Started.itlp</string>
		<key>media-archive-version</key>
		<string>1.0</string>
	</dict>
</plist>

On Mac OS X when you double click this newly created .itlp bundle it will open in iTunes automatically, and you should be able to double-click it to see your greeting message.

On Windows you will first need to start iTunes and drag the folder into your music library, after which you should be able to double-click it to see your greeting message.

Example files

To try this out immediately download the example project for this tutorial.