ITunesDB/Misc. Files
From iPodLinux
iTunesSD file
First to second/third generation Shuffle
The iTunesSD file is in a big-endian byte order. It consists of a header followed by a bunch of entries, one after the other. The format is much simpler than the iTunesDB. Only the iPod Shuffle is known to use this file at the moment. The Shuffle uses only this file for playing songs, but nevertheless a valid iTunesDB must be present on the device. When connecting to iTunes, only the iTunesDB is read back, not the iTunesSD.
| field | size | value |
|---|---|---|
| num songs | 3 | Number of song entries in the file. |
| unknown | 3 | 0x010600? iTunes 7.2 puts 0x010800 here |
| header size | 3 | size of the header (0x12, 18 byte header) |
| unknown | 9 | possibly zero padding |
| rest of header is NOT zero padded | ||
| field | size | value |
|---|---|---|
| size of entry | 3 | Always 0x22e (558 bytes) |
| unk1 | 3 | unknown (always 0x5aa501 ?) |
| starttime | 3 | Start Time, in 256 millisecond increments - e.g. 60 seconds = 0xea (234 dec). The reason for this is that the iPodShuffle has only a simplistic "clock". Every millisecond it increments an 8 bit counter. When the counter overflows, this causes an interrupt or something like that which causes it to increment this "clock" value. Very simple clock, easy to do in a an 8-bit register. Basically multiply whatever value you find here by 0.256 to convert it to seconds. Leaving this as zero means it plays from the beginning of the file. |
| unk2 | 3 | unknown (always 0?) |
| unk3 | 3 | Unknown, but seems to be associated with start time (start time of 0xea resulted in unk3 = 0x1258ee) |
| stoptime | 3 | Stop Time, also in 256 millisecond increments - e.g. 120 seconds = 0x1d4 (468 dec). Leaving this as zero means it'll play to the end of the file. |
| unk4 | 3 | unknown |
| unk5 | 3 | Unknown, but seems to be associated with stop time (stop time of 0x1d4 resulted in unk5 = 0x24a830) |
| volume | 3 | Volume - In the earliest firmware versions it ranges from 0x00 (-100%) to 0x64 (0%) to 0xc8 (100%) and represented the Volume adjustment slider in iTunes. Current firmware versions read this field as volume adjustment in dB, expressed as a signed integer ( eg 0xfffffb = -5dB or 0x000003 = +3dB). The value is derived from iTunes' soundcheck attribute. |
| file_type | 3 | 0x01 = MP3, 0x02 = AAC, 0x04 = WAV |
| unk6 | 3 | 0x200? |
| filename | 522 | filename of the song, padded at the end with 0's, in UTF-16. Note: forward slashs are used here, not colons like in the iTunesDB - for example "/iPod_Control/Music/F00/Song.mp3". |
| shuffleflag | 1 | If this value is 0x00, the song will be skipped in while the player is in shuffle mode. Any other value (iTunes uses 0x01) will allow it be played in both normal and shuffle modes. By default, iTunes 4.7.1 sets this flag to 0x00 for audiobooks (.m4b and .aa), so they aren't played in shuffle mode. |
| bookmarkflag | 1 | If this value is 0x00, the song will not be bookmarkable (i.e. its playback position won't be saved when switching to a different song). Any other value will make it bookmarkable. Unlike hard drive based iPods, all songs can be marked as bookmarkable - not just .m4b and .aa. However, iTunes might not use this bookmark information for songs other than actual audiobooks. By default, iTunes 4.7.1 sets this flag to 0x01 for audiobooks (.m4b and .aa), and 0x00 for everything else. |
| unknownflag | 1 | This has never been observed to be anything other than 0x00, and setting it other values seemed to no effect. |
Third/forth generation Shuffle
The new generation iPod has a slightly more complicated iTunesSD format that looks more like the iTunesDB format, but has less different elements.
Just like in the iTunesDB the default size for integer numbers seems to be 32 bit. In the earlier iTunesSD files it was a rather odd 24 bit.
Like the iTunesDB new third generation shuffle's iTunesSD is little endian. Earlier iTunesSD files were big endian.
The ongoing decoding of the new iTunesSD is documented on http://shuffle3db.wikispaces.com/ .
iTunesStats File
This seems to be the equivalent of the "Play Counts" file, where the Shuffle stores data that iTunes reads back in. Strangely, this file *is* byte reversed (little-endian). So a decimal 18 would be represented as 0x12 0x00 0x00, for example.
| offset | field | size | value |
|---|---|---|---|
| 0 | num songs | 3 | Number of song entries in the file (same as number of songs on the iPod Shuffle). |
| 3 | unknown | 3 | zero padding? |
| offset | field | size | value |
|---|---|---|---|
| 0 | size of entry | 3 | 0x12 (18 bytes) |
| 3 | bookmarktime | 3 | Bookmarked position in the song in 256 millisecond increments (e.g. 0xee -> 60928 milliseconds = 60.928 seconds). If a song's playcount is zero, this field is 0xffffff. Otherwise, it is 0x0 or the bookmarked time. |
| 6 | unk1 | 3 | Somehow associated with bookmarktime (bookmarktime of 0x15f results in unk1 = 0x16db19, 0x1e4 -> unk1 = 0x1f3215). Probably the same formatting as seen in iTunesSD unk3 & unk5... Whatever the purpose, it doesn't seem to be used on the Shuffle - just supplying a valid bookmarktime works fine. |
| 9 | unk2 | 3 | always 0? |
| 12 | playcount | 3 | Number of times this track has played to the end. |
| 15 | skippedcount | 3 | Number of times that the user has skipped past this song before its end. |
iTunesShuffle File
This file contains a list of the track index numbers, one after another. Each number is 3 bytes in length, and in little endian byte order (reverse byte order).
The reason for this file is that it ensures that although the tracks are shuffled, they remain in the same order until you resync the iPodShuffle. That way you can turn the device on and off as many times as you like, and although the songs are shuffled, you can still back up and so forth.
iTunesShuffle can either be created by the application, or the iPod Shuffle will automatically create it when necessary. It can also be recreated on the Shuffle by pressing the play/pause button three times within one second, thus reshuffling the order of songs on the fly.
It also appears that the songs are automatically reshuffled if, while in shuffle playback mode, the player reaches the end of the playlist. So even if an application creates the iTunesShuffle file, the iPod Shuffle can and will replace it.
iTunesPState File
This file keeps track of the current playback state of the iPod shuffle. It contains seven 24-bit little endian values (i.e. 3 bytes per number, reverse byte order). The iPod re-creates the file with default if it is missing.
| field | size | value |
|---|---|---|
| volume | 3 | The current playback volume. 0x1d (29) is the default value. The maximum value is 0x26 (38), at least for the European model. |
| shufflepos | 3 | Current track number in the shuffle order. Value 0x00 denotes the first song. In normal playback mode, this value is equal to the entry number in the iTunesSD file (see next field). |
| trackno | 3 | Current track number in iTunesSD file order. Value 0x00 denotes the first song. |
| shuffleflag | 3 | 0x00 in ordered playback mode, 0x01 in shuffle mode. |
| trackpos | 3 | Current playback position inside the track, in bytes(?) |
| unk1 | 3 | high bits for trackpos? |
| unk2 | 3 | Always 0x01? |
On some models this file is slightly different: it is 32 byte long and the volume field is 1 byte, not 3 (the rest - shifted accordingly). What's contained in the remainder of the file is unclear.
iTunesControl File
It is quite big (several MB), and has no obvious header identifier.
It seems to have a single data section written over and over again which equals 256 bytes each.
You can see a pattern in the hex data section of growing word values.
iTunesPrefs File
It seems to have a fixed length of 236 bytes.
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | frpd (0x66 0x72 0x70 0x64) |
| 4 | unk1 | 1 | 01? |
| 5 | unk2 | 1 | 00? |
| 6 | unk3 | 1 | 03? |
| 7 | unk4 | 1 | 00? |
| 8 | iPod set up | 1 | 0x00: iTunes has not set up iPod, 0x01: iTunes has set up iPod. Checked by iTunes to determine whether to present iPod set up dialog box. |
| 9 | Open iTunes when attached | 1 | Open iTunes when iPod is Attached, 01 for checked. |
| 10 | Manual/Automatic Sync flag | 1 | 00 appears to be "Manually manage my songs", 01 appears to be "Automatic Sync" |
| 11 | Sync Type | 1 | 01 Entire Library, 02 Selected Playlists |
| 12 | iTunes Music Library Link Identifier | 8 | 8 byte identifier of the last iTunes library synced to this iPod. Checked by iTunes to prevent automatic updates when you connect the iPod to other computers with iTunes/Libraries |
| 20 | unk10 | 4 | unknown, possibly part of unk11 |
| 24 | unk11 | 4 | unknown, possibly part of unk10 |
| 28 | unk12 | 1 | 00? Various flags of some kind? |
| 29 | unk13 | 1 | 00? |
| 30 | unk14 | 1 | 01? |
| 31 | Enable Disk Use | 1 | 00 for disabling disk use, 01 to enabling disk use. |
| 32 | unk16 | 1 | 00? |
| 33 | unk17 | 1 | 01? |
| 34 | Update Checked | 1 | 01 for only update checked songs. |
| 35 | unk19 | 1 | 01? |
| 36 | unk20 | 1 | 01? |
| 37 | padding? | 12 | zero padding? |
| 49 | Show Artwork | 1 | 1 for Show Artwork in Ipod |
| 50 | padding? | 2 | zero padding? |
| 52 | Synchronize Photos | 1 | Synchronize Photos with iPod |
| 53 | unk21 | 2 | 0x2010? |
| 55 | Store Hi-res photos on iPod | 1 | 1 for yes, 0 for no. |
| 56 | padding? | 16 | zero padding? |
| 72 | Transcode | 1 | 01 For Transcode higher bitrate songs to 128 AAC (Shuffle only) |
| 73 | Keep Ipod in the source list | 1 | Keep this ipod in the source list, 1 for true (Shuffle only?) |
| 74 | unk23 | 15 | A bunch of other flags? |
| 89 | Selected Podcast Sync Only | 1 | 0x01 = Sync All Podcasts, 0x02 = Sync Selected Podcasts Only |
| 90 | Manual/Automatic Podcast Sync | 1 | 0x00 = Manually Manage Podcasts (selected flag is meaningless in this case), 0x01 = Autosync podcasts |
| 91 | unk24 | 5 | Five other flags? |
| 96 | Identifier? | 8 | Same 8 byte ID as before |
| 104 | songs on ipod | 2 | Somehow related to the songs / disc space allowed on the shuffle. Setting songs to 0 or setting filespace to 0 sets this to 0. (0x2000 for non-shuffles?) |
| 106 | filespace saved on ipod | 2 | Somehow related to the songs / disc space allowed on the shuffle. Setting filespace to 0 sets this to 0. (0x0000 for non-shuffles?) |
| 108 | padding? | 8 | zero padding? |
| 116 | Do not ask again flags | 4 | Various flags set when user checks "Do not ask again" in warning dialogs |
| 120 | padding? | 4 | zero padding? |
| 124 | Sound Check | 1 | Use sound Check (shuffle only setting? Perhaps for transcoding purposes?) |
| 125 | padding? | 111 | zero padding? undetermined flags? |
winPrefs File
It seems to have a fixed length of 16 bytes.
| field | size | value |
|---|---|---|
| header identifier | 4 | frpw (0x66 0x72 0x70 0x77) |
| unk1 | 4 | Unknown. |
| unk2 | 4 | Unknown. |
| unk3 | 4 | Unknown. |
DeviceInfo File
This file has info on the iPod user's computer.
It seems to have a fixed length of 1536 bytes.
Each field is zero padded and in UTF-16LE text format.
| field | size | value |
|---|---|---|
| Length of iPod name | 2 | The length in symbols (not in bytes) of the string immediately following. |
| iPod name | 510 | The ipod name as defined in iTunes. |
| Length of User name | 2 | The length in symbols (not in bytes) of the string immediately following. |
| User name | 510 | The logged on username who last used the iPod with iTunes. |
| Length of Computer name | 2 | The length in symbols (not in bytes) of the string immediately following. |
| Computer name | 510 | The name of the computer who used the iPod. |
iEKInfo File
New file I found recently on a 3G iPod. Unknown purpose. The file looks to be big endian, and similar to the chapter info records found inside podcasts with chapters (as well as similar to the chapter info structures found in the iTunesDB file. One odd characteristic is that the file appears to contain no 4 character identifier at the beginning. Similar in structure to standard MPEG 4 metadata layouts.
some more information on the structure of this file
Info copied from above webpage (adg.us):
FILE HEADER:
============
<uint32> - Size of file data (excluding this 64-byte header)
<60-zero-bytes> - Padding?
FILE DATA BEGINS HERE:
======================
<12-zero-bytes> - Padding?
<ATOM:"sean">
<uint32> - ID/number (should be 1)
<uint32> - No. of subatoms (should be at least 3)
<uint32> - Four zero bytes
<ATOM:"sym ">
<uint32> - ID/number (should be 1)
<uint32> - No. of subatoms ("sess" subatoms) - I expect it should be
at least 1
<uint32> - Four zero bytes
ONE OR MORE "sess" ATOMS:
=========================
<ATOM:"sess">
<uint32> - Session ID - Used to identify which keys are encrypted
with this session
<uint32> - No. of subatoms - Should be 2 (one "valu" subatom, one
"index" subatom)
<uint32> - Four zero bytes
<ATOM:"valu">
<uint32> - ID/number (should be 1)
<uint32> - No. of subatoms (should be zero)
<uint32> - Four zero bytes
<128 bytes of binary data> - The session key or something???
<128 zero bytes> - I don't know if all sessions are structured
this way or not... These last 128 bytes
are ignored for playback purposes.
--- ("valu")
<ATOM:"indx">
<uint32> - ID/number (should be 1)
<uint32> - No. of subatoms (should be zero)
<uint32> - Four zero bytes
<uint32> - Every index I've seen thus far has the value six
('6') here. Changing this broke playback on my
iPod, so it's important for playback.
--- ("indx")
--- ("sess")
===
--- ("sym ")
<ATOM:"user">
<uint32> - User ID (a.k.a. DSID)
<uint32> - Number of keys, or no. of "key " subatoms
<uint32> - Four zero bytes
ONE OR MORE "key " ATOMS:
=========================
<ATOM:"key ">
<uint32> - Key ID or key number
<uint32> - Number of subatoms (should be 1)
<uint32> - Four zero bytes
<ATOM:"valu">
<uint32> - Session ID used to encrypt this key's contents
<uint32> - No. of subatoms (Should be zero)
<uint32> - Four zero bytes
<16 bytes of binary data> - The key data, encrypted with the
specified session?
--- ("valu")
--- ("key")
===
--- ("user")
THREE "guid" ATOMS: (Are there ever more?)
===================
<ATOM:"guid">
<uint32> - GUID ID or number (should be one)
<uint32> - Number of subatoms (should be zero)
<uint32> - Four zero bytes
<GUID Data Bytes> - 256 bytes for the first 'guid' atom...
The first 9 bytes, if changed, appear to break playback on my
iPod. The next three bytes contained data, but I could change
it without breaking playback. Byte number 12 (position 11 if
the first byte is at position zero) was 1 for a while on my
iPod, but later was 2. I didn't check to see if this changed
when I moved the iPod from one host computer to another.
On a 4G iPod, the first 8 bytes of this field are the iPod's FireWire ID.
--- ("guid")
<ATOM:"guid">
<uint32> - GUID ID or number (should be two)
<uint32> - Number of subatoms (should be zero)
<uint32> - Four zero bytes
<GUID Data Bytes> - 256 bytes for the second 'guid' atom...
This has got to be a global unique identifier based on which
host computer installation of iTunes the iPod is associated
with. It changed when I moved my iPod from one of my host
computers to another. But it didn't change when other
playlist and/or authorization changes changed the 'sess'
session atom. The last 128 bytes are all zero-bytes, and
are ignored during playback. I was able to randomly change
the last 128 bytes to anything without affecting playback.
--- ("guid")
<ATOM:"guid">
<uint32> - GUID ID or number (should be three)
<uint32> - Number of subatoms (should be zero)
<uint32> - Four zero bytes
<GUID Data Bytes> - 4 bytes
This is the final 'guid' atom, the last one, and yes, it's
only 4 bytes long, containing probably a <uint32> value.
It has been value six on my iPod. Changing it broke my
iPod's ability to play audio files. I see that the value
six shows up here, as well in the above 'indx' atom within
the 'sess' atom. I can't help but think these two values
may be related somehow.
--- ("guid")
===
--- ("sean")
=== FILE DATA ENDS HERE
WABContactsGroup File
New file I found recently on a 3G iPod. Unknown purpose, although probably related to the new Contacts sync, given the name. Assuming that this may be different for people syncing to Outlook instead of to the Windows Address Book (WAB). The file is 56 bytes in size.
| field | size | value |
|---|---|---|
| header identifier | 4 | frpd (0x66 0x72 0x70 0x64) (Yes, this matches the iTunesPrefs file identifier) |
| padding? | 8 | zero padding |
| unk1 | 4 | 0x04 02 00 00. Setting flags, perhaps? |
| padding? | 40 | zero padding? |
iTunesLock File
This file is created right before iTunes modifies or reads anything on the iPod, and is deleted when it is finished. Does not contain any data, and is probably only used to make sure only one program at a time tries accessing the important files on the iPod at one time.
PhotosFolderName
Lists the watched folders watched and syncronized with the Ipod. Found on the iPod video (probably on the Photo as well). It is a very simple format with the length of the folder name, preceeded by the folder name in unicode letters.
PhotoFolderPrefs
Stores Photo Folder preferences.
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | frpd same as iTunesPrefs |
| 4 | unk1 | 4 | 01? |
| 8 | unk2 | 4 | 01? |
| 12 | unk3 | 4 | ? |
| 16 | unk3 | 80 | zero padding? |
| 96 | folder name | ?? | The watch folders names |
PhotoFolderAlbums
Stores Photo Albums .
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | frpd same as iTunesPrefs |
| 4 | unk1 | 2 | 01? |
| 6 | unk2 | 2 | 01? |
| 8 | unk3 | 1 | 01? |
| 9 | unk4 | 1 | 01? |
| 10 | unk5 | 2 | 00? |
| 12 | Number of Folders | 4 | Number of folders to that are directly below the folder pointed out in PhotoFolderPrefs. From offset 100 on, the folder name datastructure will repeat this many times. |
| 16 | unk7 | 1 | 01? |
| 17 | unk8 | 1 | 01? |
| 18 | unk9 | 2 | 00? |
| 20 | unk10 | 4 | 01? |
| 26 | unk11 | 74 | zero padding? |
| 100 | is synched | 4 | Whether or not the folder is synched. 1 if is, 0 if it isn't. |
| 104 | string legnth | 2 | Length of the name of the albums to follow |
| 106 | album name | 510 | Name of the album to follow |
| From 100-514 repeats as many times as in Number of folders (see offset 12) | |||
iTunesPlaylists
Keeps track of the iTunesPlaylists???
iTunesPodcasts
Keeps track of the iTunesPodcasts???
iTunesVideoPlaylists
Keeps track of the iTunesVideoPlaylists???
Preferences
Located at /iPod_Control/Device/Preferences.
| offset | field | size | value |
|---|---|---|---|
| 0x6BC (1724) | DST-Setting (3g nano) | 1 | Set to 0x3C (=60) if DST is set. Otherwise 0x00 |
| 2808 | Language Selection | 1 | Defines the menu language selected in your iPod doing Settings->Language. English is 0. |
| 2832 | Timezone Information | 1 | Timezone information. |
| 0xB50 (2896) | Volume Limit | 1 | Volume limit value on firmware 1.1.1 for 5G and nano. Range: 0-64 |
| 0xB70 (2928) | Region (3g nano) | 1 | Selected region/timezone: 0x4f = London, 0x55 = Zurich, 0x5d = Geneva ... Seen on 3g-Nano. This might also be used to calculate the timezone offset because changing the timezone from Geneva to London only changes this offset. (Or is it a bug? The Nano displays London as UTC-1 (!) |
I'm unsure what is the best way to parse the timezone information field, but the previous explanation that it's the timezone information in 30 minutes steps is wrong, it doesn't hold up during DST. Something that works is to substract 0x19 (this corresponds to UTC+0) to that value. The resulting value divided by 2 gives the timezone (in hours), and the less significant bit (ie the resulting value modulo 2) indicates if DST is active or not (1 => DST active). When the DST bit is set, 1 hour must be added to the timezone value.
Example:Selecting Paris (DST) will set this offset to 0x1c: (0x1c - 0x19) = 0x03
0x03 / 2 = 1
0x03 % 2 = 1
which gives us a GMT+2 timezone
_volumelocked
Located at /iPod_Control/Device/
Exists when a 4-digit combination has been set for the Volume Limit on 5Gs and nanos (firmware 1.1.1). File length is 0x20. Appears to be encrypted? However, deleting the file removes the volume limit :-)
