ITunesDB/iTunesDB File/Section1

From iPodLinux

Revision as of 07:51, 17 November 2009

Structure

The iTunesDB file consists of a sort of tree structure arranged into a flat file. Each "object" contains a header followed by some other objects. The header contains a couple of size fields that are used to define where the header ends and other objects begin. Here's the basic structure of it:

<mhbd> - This is a database
  <mhsd> - This is a list holder, which holds a mhla
    <mhla> - This holds a list of albums
      <mhia> - This describes a particular Album Item
        <mhod> - These hold strings associated with an album title
        <mhod> - These hold strings associated with an artist name/title
      <mhia> - This is another album. And so on.
        <mhod>...
        <mhod>...
  <mhsd> - This is a list holder, which holds a mhli
    <mhli> - This holds a list of artists
      <mhii> - This describes a particular Artist Item
        <mhod> - These hold strings associated with an artist name
      <mhii> - This is another artist. And so on.
        <mhod>...
      ...
  <mhsd> - This is a list holder, which holds either a mhlt or an mhlp
    <mhlt> - This holds a list of all the songs on the iPod
      <mhit> - This describes a particular song
        <mhod>... - These hold strings associated with a song
        <mhod>... - Things like Artist, Song Title, Album, etc.
      <mhit> - This is another song. And so on.
        <mhod>...
        <mhod>...
      ...
  <mhsd> - Here's the list holder again.. This time, it's holding an mhlp
    <mhlp> - This holds a bunch of playlists. In fact, all the playlists.
      <mhyp> - This is a playlist.
        <mhod>... - These mhods hold info about the playlists like the name of the list.
        <mhip>... - This mhip holds a reference to a particular song on the iPod.
        ...
      <mhyp> - This is another playlist. And so on.
        <mhod>... - Note that the mhods also hold other things for smart playlists
        <mhip>...
        ...
      ...

And so on. What follows is a detailed description of these various headers.

Chunk Encoding

Each chunk of the file is encoded in the follow form:

The Chunk Type Identifier is intuitive: it's a 4-byte string letting you know what you're working with.

The End of Type-specific Header tells you where, relative to offset 0, the header section for this chunk ends. The header starts at offset 12 and runs through to the end of the type-specific header.

The End of Chunk or Number of Children is slightly confusing. Usually, it's an "End of Chunk" offset: what the last offset in the current chunk is. That is, it tells you how long this chunk and all its children are. There are two big exceptions to this: "mhlt" and "mhlp" chunks. In both of these, this number is how many top-level children the mhl[pt] chunk has.

Database Object

The Database Object has two to six children depending on iTunes version, which are all Data Sets.

DataSet

1 = Track list - contains an MHLT
2 = Playlist List - contains an MHLP
3 = Podcast List - optional, probably. Contains an MHLP also.  
This MHLP is basically the same as the full playlist section, 
except it contains the podcasts in a slightly different way. 
See the Playlists section.
4 = Album List, first seen with iTunes 7.1.
5 = New Playlist List with Smart Playlists, first seen with iTunes 7.3.
6 = Unknown; contains an MHLT; can have an empty MHLT but apparently must be there. (Version 0x25)
8 = Artist List, first seen with iTunes 8.
9 = Unknown; contains no known record but instead a possible hash. Seen on 6-Gen iPod Classics at 
the very end of the iTunesDB file. The possible value begins at the end of the header, where 
the internal record should begin. (Version 0x29)

Depending on the type of Data Set, it will contain either a Track List child or a Playlist List child. Order is not guaranteed. Example files have contained the type 3 MHSD before the type 2 MHSD. In order for the iPod to list podcasts the type 3 Data Set MUST come between the type 1 and type 2 Data Sets.

TrackList

The Track List has Track Items as its children. The number of Track Items is the same as the number of songs.

Track Item

The MHIT is followed by several Data Objects which have string types. At minimum, it must have a Location type MHOD, in order to tell the iPod where the file is located on the iPod itself. It always has a FileType MHOD as well, although it's not totally necessary.

Playlist List

The Playlist List has all the playlists as its children. The very first playlist *must* be the Library playlist. This is a normal playlist, but it has the special "hidden" bit set in it, and it contains all the songs on the iPod (in no particular order).

Playlist

The structure of the Playlists are different than most others. Each Playlist looks like this, conceptually:

   <mhyp>
      <mhod type=1>Playlist Name</mhod>
      <mhod type=50>Smart Playlist Info</mhod> (optional)
      <mhod type=51>Smart Playlist Rules</mhod> (optional)
      ...
      <mhip>Playlist Item</mhip>
             <mhod type=100>Position Indicator</mhod>
      <mhip>Playlist Item</mhip>
             <mhod type=100>Position Indicator</mhod>
      ...
   </mhyp>

The point being that these are all considered in the MHYP for the size calculations. However, in the "Data Object" child count, ONLY those MHODs that come before the first MHIP are counted. The "position indicators" are children of the MHIPs (older firmwares had a bug in this respect).

List Sort Order

1 - playlist order (manual sort order)
2 - ???
3 - songtitle
4 - album
5 - artist
6 - bitrate
7 - genre
8 - kind
9 - date modified
10 - track number
11 - size
12 - time
13 - year
14 - sample rate
15 - comment
16 - date added
17 - equalizer
18 - composer
19 - ???
20 - play count
21 - last played
22 - disc number
23 - my rating
24 - release date (I guess, it's the value for the "Podcasts" list)
25 - BPM
26 - grouping
27 - category
28 - description
29 - show
30 - season
31 - episode number

Podcasts

The podcasts playlist is organized slightly differently, in the Type 3 MHSD. For example:

mhyp (MHODs: 2, MHIPs: 5, hidden: 0, list sort order: 0x18)
  mhod (type: 1, string: 'Podcasts')
  mhod (type: 100)
  mhip (MHODs: 1, groupflag: 256, groupid: 8232, trackid: 0, timestamp: 0, groupref: 0)
    mhod (type: 1, string: 'Example podcast')
  mhip (MHODs: 1, groupflag: 0, groupid: 8233, trackid: 8230, timestamp: 3206828281, groupref: 8232)
    mhod (type: 100)
  mhip (MHODs: 1, groupflag: 0, groupid: 8234, trackid: 8226, timestamp: 3206828379, groupref: 8232)
    mhod (type: 100)
  mhip (MHODs: 1, groupflag: 0, groupid: 8235, trackid: 8228, timestamp: 3206828327, groupref: 8232)
    mhod (type: 100)
  mhip (MHODs: 1, groupflag: 0, groupid: 8236, trackid: 8224, timestamp: 3206828394, groupref: 8232)
    mhod (type: 100)

The first mhip (probably identified by groupflag==256) contains the name of a podcast which will then appear as a submenu of the Podcasts menu on the iPod. The other mhips (which reference the episodes in that podcast) seem to use the groupref field to link to their 'parent' mhip (using the groupid field). At the same time the groupids of the episodes are unique as well, but don't seem to be used anywhere else.

Playlist Item

For purposes of size calculations, Playlist Items have no children. However, every Playlist Item is invariably followed by a Data Object of type 100, which contains nothing but a number that is used to order/sort the playlist. See the Playlist description above for more information.

Please note that starting with iTunes 4.9 (mhbd file version number 0x0d) the Type 100 MHOD following the Playlist Item is considered a child of the Playlist Item and is included into the size calculation. The old behaviour was probably a bug in iTunes.