[M] Gary
Vollink.com

iTunes itl Format

Contents

Introduction

Apple iTunes has long been able to automatically generate an XML version of the iTunes library every time it changes, and I built Playlister around this feature.  However, iTunes has been discontinued on macOS in favor of Apple Music.

At the end of 2019, I started working on figuring out the binary format of the Apple Music library files, but in doing so, I started with existing work on the iTunes library format so that I would be able to compare and contrast the differences. 

None of the other projects have the offsets laid down in a way that I find useful, so I decided to write this page as a companion to the Apple Music library page that I worked on for a few years.

itl File Format

The first four bytes of the file are hdfm. One thing to immediately note is that the itl format's outer envelope is arranged with big endian integer storage (Apple's G4 line and older processors used this encoding).  A near copy of this section, internal to the encrypted and compressed portion of this file is mfdh, (hdfm, backward) in which the repeated numeric values are in little endian format.  All of the internal sections I've seen have little endian format storage (Intel and AMD x86 processors store numbers this way natively). 

I suspect that iTunes itl files that were created and maintained on Apple computers that were made before Apple's switch to Intel processors (Apple G4 and older), were probably entirely stored in big endian byte order.  Evidence suggests that on any big endian formatted section, the section header name will be backwards, as it is for the envelope section noted above. 

It would make sense that any implementation that is meant to read these files would check each section header for endian-ness to have the greatest possible compatability. 

I have been doing this testing on two iTunes library files.  One that was created in iTunes on macOS Mojave (and subsequently imported into Apple Music after upgrade), and one that was created in iTunes on Windows. 

The sections listed in the Table of Contents above are in the approximate order of the first appearance of each of those file sections (or problems to solve) in the iTunes Music Library.itl file.  These headers are also listed in little Endian (x86) order, as that is the most common.

This may never be complete.  One thing to keep in mind is that, besides Music, iTunes includes Movies, TV Shows, Podcasts and Audiobooks.  I have never Purchased a Movie from the iTunes Store.  I only have one Podcast loaded into iTunes.  I have never put any Audiobook into iTunes.  So any specific data related to those things, I'm unlikely to find. 

Envelope Header

* Dates are expressed in Seconds since 1-Jan-1904 Midnight & should be converted with the TZ Offset.

Crypt Size

If Max Crypt Size is smaller than the File size, use the Max Crypt Size directly.

Crypt Size = File Size - Envelope Length - ((File Size - Envelope Length) mod 16)

Encrypted AND zlib Compressed Payload

Starting with the byte offset (Envelope length in Bytes), the Crypt Size of the file needs to be decrypted using the standard AES128-ECB algorythm.  OpenSSL and macOS built-in libraries can do this in C/C++.  In Perl, use Crypt::Cypher.  A key is necessary to successfully unencrypt this. 

Once unencrypted, the payload must be expanded/inflated via zlib, including the rest of the file (if any) larger than the initial Max Crypt Size.

Inner Library Sections

Almost all* sections follow this beginning pattern, with differences following these first 8 bytes.

These section headers follow the base pattern as described above:
msdh, mfdh, mhgh, mlah, miah, mlih, miih, mlth, mith, mlqh, miqh, stsh, mlph, miph, mtph, mlsh, msph, mlrh, mprh.

*NOTE: mhoh sections do not follow this pattern.

Back to Table of Contents.

msdh Section Boundary

This section appears multiple times through a library.

• Preceeded by: Anything
• Container of: All Types

Observed msdh SubTypes (contains):

• 0x0010 (16) - mfdh
• 0x000C (12) - mhgh
• 0x0009 (9) - mlah
• 0x000B (11) - mlih
• 0x0001 (1) - mlth
• 0x000D (13) - mlth
• 0x0014 (20) - mlqh
• 0x0017 (23) - stsh
• 0x0002 (2) - mlph
• 0x000E (14) - mlph
• 0x0003 (3) - ???? *See note below offset table
• 0x0015 (21) - mlsh
• 0x0013 (19) - XML Block *See note below offset table
• 0x0004 (4) - Library Location URI *See note below offset table
• 0x000F (15) - mlrh

Occurs multiple times.  Marks transitions between major sections of the file. 

NOTES: msdh SubType 3 ends at a section of just binary data.  This data has no self-identified length.
msdh SubType 0x0013 (19) ends at an XML block with no self-identified length.
msdh SubType 4 ends at an escaped URI string with no self-identified length.
These sections can only be parsed using the Associated Data Length which is an offset which points to the beginning of the next msdh section, from the begging of its containing msdh section.

In general, when parsing, if an msdh section is either marked with an unknown SubSection or followed by an otherwise unregistered signature, it would be best to use the Associated Data Length to skip the associated data (possibly registering a warning, or telemetry for a bug report).

Back to Table of Contents.

mfdh Outer Envelope (partial copy)

This section appears once as the File Envelope, and once as the second section within the encrypted and compressed section of the file.

• Preceeded by: msdh
• SubType: 0x0010
• Container of: None

Back to Table of Contents.

mhgh Library Info

This section appears only once in a library.

• Preceeded by: msdh
• SubType: 0x000C
• Container of: mhoh
• SubType: 0x01FC - Library Share Name
• SubType: 0x0202 - XML Data Block
• SubType: 0x0205 - Unknown

Back to Table of Contents.

mlah Album/Collection Master

This section appears only once in a library.

• Preceeded by: msdh
• SubType: 0x0009
• Container of: mlih

Back to Table of Contents.

miah Album/Collection Item

This section appears the number of times as specified by the containing mlah section at offset 8.

• Preceeded by: mlah
• Container of: mhoh
• SubType: 0x012C - Album Name
• SubType: 0x012D - Album Artist
• SubType: 0x012E - Album Artist (2)
• SubType: 0x0130 - Series Title

Back to Table of Contents.

mlih Artist (miih) Master

This section appears only once in a library.

• Preceeded by: msdh
• SubType: 0x000B
• Container of: miih

Back to Table of Contents.

miih Artist Item

This section appears the number of times as specified by the containing mlih section at offset 8.

• Preceeded by: mlih
• Container of: mhoh
• SubType: 0x0190 - Artist Name
• SubType: 0x0191 - Sort Order Artist Name
• SubType: 0x0192 - Artist XML Block

Back to Table of Contents.

mlth Track Master

This section appears multiple times in an iTunes Library.

• Preceeded by: msdh
• SubType: 0x0001
• SubType: 0x000D
• Container of: mith

Back to Table of Contents.

mith Track Item

This section appears the number of times as specified by the containing mlth section at offset 8.

• Preceeded by: mlth
• Container of: mhoh
• SubType: 0x0002 - Track Title
• SubType: 0x0004 - Artist
• SubType: 0x001B - Album Artist
• SubType: 0x000C - Composer
• SubType: 0x0003 - Album Title
• SubType: 0x0005 - Genre
• SubType: 0x0006 - Kind
• SubType: 0x001E - Sort Order Track Title
• SubType: 0x001F - Sort Order Album Title
• SubType: 0x0020 - Sort Order Artist
• SubType: 0x0038 - XML Block (download related)
• SubType: 0x0036 - XML Block (art related)

NOTES:
Dates are in number of seconds since Jan 1 1904, midnight.
Movement only appears for classical tracks.
FairPlay Version was reported elsewhere, but I haven't been able to verify.

Back to Table of Contents.

mhoh Data Container (common)

This section appears frequently in most other sections.

• NOT preceeded by: msdh
• Container of: none

Every mhoh has a SubType, and what is inside each mhoh can be VERY different depending on that SubType.  The section length of a mhoh is indicated at a different offset from other section types.  The following table shows the portions that are common to ALL mhoh sections.

Back to Table of Contents.

mhoh Flex Character Container

• SubTypes:
  • 0x0002 - Track Title
  • 0x0003 - Album
  • 0x0004 - Artist/Show
  • 0x0005 - Genre
  • 0x0006 - Kind
  • 0x0008 - Comment
  • 0x0009 - Category
  • 0x000B - Local Path
  • 0x000C - Composer
  • 0x000D - Native Filepath
  • 0x000E - Grouping
  • 0x0012 - Short Description
  • 0x0016 - Full Description
  • 0x0018 - TV Show Title
  • 0x0019 - Episode ID
  • 0x001B - Album Artist
  • 0x001C - TV Rating
  • 0x001D - XML Block
  • 0x001E - Sort Order Track Name
  • 0x001F - Sort Order Album
  • 0x0020 - Sort Order Artist
  • 0x0021 - Sort Order Album Artist
  • 0x0022 - Sort Order Composer
  • 0x0022 - Sort Order TV Show Title
  • 0x0025 - Podcast RSS URL
  • 0x002B - ??EMI...??
  • 0x002E - Copyright Statement
  • 0x0033 - Alternate Description
  • 0x0034 - ??
  • 0x0039 - Podcast Episode URL (flex)
  • 0x003A - Podcast Feed URL
  • 0x003B - Purchaser Account (Email)
  • 0x003C - Purchaser Full Name
  • 0x003F - Work Name (for Classical Tracks)
  • 0x0040 - Movement Name (for Classical Tracks)
  • 0x0064 - Playlist Title
  • 0x00C8 - Podcast Title
  • 0x012C - Album (miah)
  • 0x012D - Album Artist (miah)
  • 0x012E - Album Artist (miah) (2)
  • 0x0130 - Series Title (miah)
  • 0x0131 - Feed URL (miah)
  • 0x0190 - Artist (miah)
  • 0x0191 - Sort Artist (miah)
  • 0x01F8 - unknown UUID
  • 0x01F9 - unknown UUID
  • 0x01FA - Library Owner (login)
  • 0x01FC - Library Share Name
  • 0x02BE - Track Title
  • 0x02BF - Artist — Album

String Type (24): Is the encoding of String (28).
0 - URI: Is a UTF-8 (narrow) string representing a Universal Resource Identifier, usually starting with "http://", "https://", or "file://".
1 - Wide Characters: is a UTF-16 (wide) string.  Each character is represented by a 2-byte (16 bit) space, which IS subject to little endian byte swapping. 
2 - escaped URI: Is a UTF-8 string representing a URI.  Special characters are percent encoded.
3 - Narrow Characters: Is a UTF-8 string. 

String Length (28): Note that this value will always be 40 less than the Section Length (8).

Back to Table of Contents.

mhoh Narrow Character Container

• SubTypes:
  • 0x0013 - Podcast Episode URL
  • 0x0036 - Art related XML Block
  • 0x0038 - Download related XML Block
  • 0x006D - Display/Art Related XML Block
  • 0x0192 - Store Art URL XML Block
  • 0x0202 - Long XML Block
  • 0x02BC - SmartPlayist Criteria XML Block
  • 0x0320 - TV Display XML Block

String (24): Note that this string length is exactly 24 less than the Section Length (8).

Back to Table of Contents.

mhoh Video Resolution

• SubType:
  • 0x0024 - Resolution (and?)

Back to Table of Contents.

mhoh book

• SubType:
  • 0x0042

mhoh book sections contain numbers and strings.  Strings are marked by 0x0101.  The four bytes prior to the 0x0101 will indicate the length of the string.  The byte following the 0x0101 will start the first character of that string.  These strings might include the separate path components of the item. 

SubSection Length (28): Note that this length is exactly 24 less than the Section Length (8).

After reading each string, it is important to re-align to a 4 byte offset.  For the string shown above, 5 bytes were read.  That means 3 bytes must be discarded before the next four bytes can be read.

mhoh book sections are long, and most included data is repeated in another mhoh section (not separated). 

There is one string indicated by a 0x0901, with the same setup as the 0x0101 string, except it is further preceeded by a 0x01F5. 

There is one string indicated by a 0x0201, with the same setup as the 0x0101 string, except it is further preceeded by a 0x0501. 

Back to Table of Contents.

mhoh Unknown

• SubTypes:
  • 0x0015
  • 0x0065
  • 0x0066
  • 0x0067
  • 0x0069
  • 0x006C
  • 0x00C9
  • 0x00CA
  • 0x01F6
  • 0x01F7
  • 0x0205

Each of these subtypes have been found, but the data has not yet been identified. 

Back to Table of Contents.

Want To Help?

Since putting up this page, I have received a handful of submissions from folks who want to see this work further improved.  I have never found new insights to this ancient format.  As of 2022, I have put this project on a deep pause.

If you think you might be able to help, I make my personal diagnostic script available to you (though I do not publish the decryption key).  More information on my personal GitLab:

MusicDB-POC

If you run the above, and figure out some data-point that I've skipped in my layout above, send it to me.  I'll be happy to publish it here, and credit you (as I have others on the musicdb page).

Please send submissions to musicdb@vollink.com

This is a low traffic web site, and I will reply to any inquiry unless you specifically ask me not to reply.

Up to Table of Contents.

I Cannot Save Your Corrupted Library

After many e-mails asking if I can save a corrupted iTunes database file, the answer is no.  Apple decided to both compress the entire file PLUS encrypt the first large chunk of it.  If the start of the file is corrupted, then the encryption will be broken, and the uncompression will never be able to find its place.  If the file is corrupted later, the compression will lose it's place, leaving the remainder of the file unreadable.

I have published the program that I use to poke through my own musicdb files as well as submissions that I get, so feel free to go for it.

MusicdB-POC

Back to Table of Contents.

Acknowledgements

I would not have been able to get as far as I have without the fine work of Joseph Walton who produced titl.  That iTunes itl project in Java was key to my getting the iTunes file cracked.

I also would not have been able to get as far as I have without the fine work of Jean Thomas who produced libitlp for reading iTunes itl format in C.  While I had some issues with this library successfully reading the latest iTunes library output Jean's faithful approach to parsing the actual format (and not an interpretation) helped immensely on my taking this task on.  Once I'm closer to done, I hope to submit patches for this project to make it work on the latest iTunes libraries (though that may be some time off).

Back to Table of Contents.

Back to Table of Contents.