ITunesDB/Photo Database
From iPodLinux
Contents |
Photo Database
The Photo Database is created by iTunes, and is stored in "/Photos/Photo Database". The Photo Database looks similar to the ArtworkDB but has additional entries in the mhla object (mhba and mhia, see below) as well as different Thumbnails. The mhiis in the Photo Database look like this for example:
mhii (children: 5, id: 117, srcimgsize: 0)
mhod (type: 5)
mhni (children: 1, corrid: 1, ithmb offset: 0, imgsize: 1567395, imgdim: 0x0)
mhod (type: 3, length: 80, string: u':Full Resolution:2005:08:06:simg3609.jpg')
mhod (type: 2)
mhni (children: 1, corrid: 1019, ithmb offset: 7603200, imgsize: 691200, imgdim: 0x2c801e0)
mhod (type: 3, length: 42, string: u':Thumbs:F1019_1.ithmb')
mhod (type: 2)
mhni (children: 1, corrid: 1020, ithmb offset: 851840, imgsize: 77440, imgdim: 0xa500e1)
mhod (type: 3, length: 42, string: u':Thumbs:F1020_1.ithmb')
mhod (type: 2)
mhni (children: 1, corrid: 1009, ithmb offset: 27720, imgsize: 2520, imgdim: 0x29001f)
mhod (type: 3, length: 42, string: u':Thumbs:F1009_1.ithmb')
mhod (type: 2)
mhni (children: 1, corrid: 1015, ithmb offset: 251680, imgsize: 22880, imgdim: 0x7b0058)
mhod (type: 3, length: 42, string: u':Thumbs:F1015_1.ithmb')
The type 5 mhod references the full resolution image and is probably only there if the corresponding check box in iTunes was checked. The type 2 mhods reference different types of thumbnail versions:
- The first thumbnail (imgdim: 0x2c801e0, which decodes as 712x480) is of dimension 720x480 and in YUV 4:2:2 format, interlaced. It consists of two half-frames concatenated together. This is probably used for the TV-out (dimension, color format and interlacing look like NTSC).
- The second thumbnail (imgdim: 0xa500e1, which decodes as 165x225) is of dimension 176x220 and in RGB 565 format, but rotated 90° CCW. This is the image that is actually displayed on the iPod screen.
- The third thumbnail (imgdim: 0x29001f(41x31)) is 42x30, RGB 565 with swapped bytes (e.g. it's more like GBRG 3553). This is the image that is used as a thumbnail.
- The fourth thumbnail (imgdim: 0x7b0058(123x88)) is 130x88, RGB 565 with swapped bytes
There is a *.ithmb file per resolution (in the directory "/Photos/Thumbs/"), that concatenates all thumbnails with that resolution.
On an iPod video (5G) there are 4 different thumbnails type:
- 720x480 interlaced UYVY (YUV 4:2:2) - used for TV output - 691200 bytes each single thumbnail
- 320x240 byte swapped RGB565 - used for fullscreen on the iPod - 153600 bytes each single thumbnail
- 130x88 byte swapped RGB565 - used on the iPod during slideshow, when current photo is displayed on TV - 22880 bytes each single thumbnail
- 50x41 byte swapped RGB565 - used on the iPod when listing and during slideshow - 4100 bytes each single thumbnail
Dimensions of the fields in the Photo Database are very important. Only one total length field or one padding field with wrong value could be enough to make the Photo Database file completely unusable: then nothing will be displayed on the iPod, no photo albums, no photos.
Here follows a complete structure for a Photo Database file working on an iPod video 5G:
'mhfd', 132, 1384, 0, 1, 3, 0, 102, 0, 0, 0, 0, 2, 0, 0, 0, 0 'mhsd', 96, 1276, 1 'mhli', 92, 1 'mhii', 152, 1088, 5, 100, 102, 0, 0, 0, 0, 3221487006, 3221487006, 0 'mhod', 24, 216, 5, 0, 0 'mhni', 76, 192, 1, 1, 0, 0, 0, 0, 0, 0 'mhod', 24, 116, 3, 0, 2 78, 2, 0, ':Full Resolution:2006:01:22:DSC00090.JPG' 'mhod', 24, 180, 2, 0, 0 'mhni', 76, 156, 1, 1019, 0, 691200, 0, 0, 480, 712 'mhod', 24, 80, 3, 0, 2 42, 2, 0, ':Thumbs:F1019_1.ithmb' 'mhod', 24, 180, 2, 0, 0 'mhni', 76, 156, 1, 1024, 0, 153600, 0, 0, 240, 320 'mhod', 24, 80, 3, 0, 2 42, 2, 0, ':Thumbs:F1024_1.ithmb' 'mhod', 24, 180, 2, 0, 0 'mhni', 76, 156, 1, 1015, 0, 22880, 0, 0, 88, 123 'mhod', 24, 80, 3, 0, 2 42, 2, 0, ':Thumbs:F1015_1.ithmb' 'mhod', 24, 180, 2, 0, 0 'mhni', 76, 156, 1, 1036, 0, 4100, 0, 0, 41, 53 'mhod', 24, 80, 3, 0, 2 42, 2, 0, ':Thumbs:F1036_1.ithmb' 'mhsd', 96, 660, 2 'mhla', 92, 2 'mhba', 148, 232, 1, 1, 101, 0, 65536, 0, 0, 0, 0, 0, 0, 0, 100 'mhod', 24, 44, 1, 0, 1 7, 1, 0, 'Library' 'mhia', 40, 40, 0, 100 'mhba', 148, 240, 1, 1, 102, 0, 393216, 0, 0, 0, 0, 0, 0, 0, 101 'mhod', 24, 52, 1, 0, 3 13, 1, 0, 'A Photo Album' 'mhia', 40, 40, 0, 100 'mhsd', 96, 684, 3 'mhlf', 92, 4 'mhif', 124, 124, 0, 1019, 691200 'mhif', 124, 124, 0, 1015, 22880 'mhif', 124, 124, 0, 1024, 153600 'mhif', 124, 124, 0, 1036, 4100
Data File Object
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | mhfd |
| 4 | header length | 4 | size of the mhfd header (0x84) |
| 8 | total length | 4 | size of the header and all child records (since everything is a child of MHFD, this will always be the size of the entire file) |
| 12 | unknown1 | 4 | always seem to be 2 for iTunes 7/8; 0 (?) for earlier iTunes versions. |
| 16 | unknown2 | 4 | always seem to be 1 for older databases, in an ArtworkDB generated by iTunes 4.9 or above, it's 2. Caution: iTunes7 removes the whole database if this field is 1 |
| 20 | number of children | 4 | always 3 since there are 3 list holders |
| 24 | unknown3 | 4 | always seem to be 0 |
| 28 | next id for mhii | 4 | The id of last mhii + 1. (is probably used as the id of a newly added mhii and then incremented). On an iPod video seems to be the id of the last mhii + the total number of photo albums (mhba) + 1. |
| 32 | unknown5 | 8 | |
| 40 | unknown6 | 8 | |
| 48 | unknown7 | 4 | always seem to be 2 |
| 52 | unknown8 | 4 | always seem to be 0 |
| 56 | unknown9 | 4 | always seem to be 0 |
| 60 | unknown10 | 4 | |
| 64 | unknown11 | 4 | |
| 68 | rest of header is zero padded | ||
DataSet
This is basically the same as the MHSD element in the iTunes DB.
| field | size | value |
|---|---|---|
| header identifier | 4 | mhsd |
| header length | 4 | size of the mhsd header (0x60) |
| total length | 4 | size of the header and all child records |
| index | 4 | An index number. This value is 1 if the child is an Image List, 2 if the child is an Album List, or 3 if it's a File List. |
| rest of header is zero padded | ||
Depending on the index, the Data Set either contains an Image List (mhli) child, an Album List (mhla) child or a File List child (mhlf).
Image List
| field | size | value |
|---|---|---|
| header identifier | 4 | mhli |
| header length | 4 | size of the mhli header (0x5c) |
| number of images | 4 | the total number of images in the Image List |
| rest of header is zero padded | ||
The Image List has Image Items as its children. The number of Image Items is the same as the number of images.
Image Item
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | mhii |
| 4 | header length | 4 | size of the mhii header (0x98) |
| 8 | total length | 4 | size of the header and all child records |
| 12 | number of children | 4 | In ArtworkDB there are 2 children: one mhod type 2 record for the full sized thumbnail, and one mhod type 2 record for the now-playing sized thumbnail. In Photo Database there are: a child for every thumbnail type (2 on Nanoes, 4 on Photo/Color/Video iPods) + a child for the reference to the full resolution image (if chosen to include it). In Photo Database files generated on Macs, probably by iPhoto, sometimes there could be an additional child, a type-1 string MHOD containing an UTF-8 string of a label for the image, usually found as first child just after the MHII header. |
| 16 | id | 4 | First mhii is 0x40, second is 0x41, ... (on mobile phones the first mhii appears to be 0x64, second 0x65, ...) |
| 20 | Song ID | 8 | Unique ID corresponding to the 'dbid' field in the iTunesDB mhit record, this is used to map ArtworkDB items to iTunesDB items. |
| 28 | unknown4 | 4 | Seems to always be 0 |
| 32 | rating | 4 | Rating from iPhoto * 20 |
| 36 | unknown6 | 4 | Seems to always be 0 |
| 40 | originalDate | 4 | Seems to always be 0 in ArtworkDB; timestamp in Photo Database (creation date of file) |
| 44 | digitizedDate | 4 | Seems to always be 0 in ArtworkDB; timestamp in Photo Database (date when the picture was taken, probably from EXIF information) |
| 48 | source image size | 4 | Size in bytes of the original source image |
| rest of header is zero padded | |||
MHOD type 2, Annoyingly, not a string like it is in iTunesDB... but still defines location of the file in question, sorta: its mhni child record contains everything that is needed about the image file.
header_size = 0x18 total_size type = 2 unk1 = 0 unk2 = 0
Image Name
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | mhni |
| 4 | header length | 4 | size of the mhni header (0x4c) |
| 8 | total length | 4 | size of the header and all child records |
| 12 | number of children | 4 | mhni headers have one mhod type 3 child |
| 16 | correlation ID | 4 | corresponds to mhif's correlation id, it's used to generate the name of the file containing the image, see below |
| 20 | ithmb offset | 4 | offset where the start of image data can be found in the .ithmb file corresponding to this image |
| 24 | image size | 4 | size of the image in bytes |
| 28 | vertical padding | 2 | approximate difference between scaled image height and pixmap height (signed) |
| 30 | horizontal padding | 2 | approximate difference between scaled image width and pixmap width (signed) |
| 32 | image height | 2 | The height of the image. |
| 34 | image width | 2 | The width of the image. |
| 36 | unknown | 4 | Always zero? |
| 40 | image size | 4 | size of the image in bytes (same as 0x18), written by iTunes 7.4 |
| rest of header is zero padded | |||
The correlation ID gives us the name of the file containing the image. For example, if the correlation ID is 1016 in decimal, then the corresponding filename will be F1016_1.ithmb.
In general, (vertical padding +image height) ~ pixmap height - usually within one or two pixels, probably due to rounding error. For instance, on a PhotoPod, an original image with dimensions 1200h x 1600v will have an NTSC image with image height=480, image width=558, vertical padding=0, and horizontal padding=162, with 558+162 = 720, the actual width of the pixel map. For an image scaled to be contained entirely within the pixel map, such as the video image or the full-screen image the padding values are basically the total width of the black bars.
For the smallest thumbnails, you can have negative values for padding, because the pixel map is scaled to be contained within the image - you get a central "slice" with no black bars.
As noted, there appear to be some rounding errors when the padding values are calculated, as the sums are sometimes off by 1 to 2.
There is no indication in this object what the pixel format, actual pixel map dimensions or rotation of images will be, so this must be entirely derived from the image size.
Here are the dimensions and formats for all known image sizes:
| size | height | width | format | description |
| 691200 | 480 | 720 | UYVY | PhotoPod and VideoPod NTSC image |
| 307200 | 240 | 320 | RGB 24 bit LE | Classic & Nano 3G (FW 1.0-1.0.2) full screen |
| 153600 | 240 | 320 | RGB565_LE | VideoPod, Classic & Nano 3G (FW 1.0.3-...) full screen |
| 80000 | 200 | 200 | RGB565_LE | VideoPod album art big version |
| 77440 | 176 | 220 | RGB565_BE_90 | PhotoPod full screen |
| 46464 | 132 | 176 | RGB565_BE | Nano full screen |
| 39200 | 140 | 140 | RGB565_LE | PhotoPod album art big version |
| 22880 | 88 | 130 | RGB565_LE | PhotoPod and VideoPod video preview |
| 20000 | 100 | 100 | RGB565_LE | VideoPod album art small version, Nano album art big version |
| 8192 | 64 | 64 | RGB565_LE | Classic & Nano 3G album art small version |
| 6272 | 56 | 56 | RGB565_LE | PhotoPod album art small version |
| 4100 | 41 | 50 | RGB565_LE | VideoPod list thumbnail |
| 3528 | 42 | 42 | RGB565_LE | Nano album art small version |
| 3108 | 37 | 42 | RGB565_LE | Nano list thumbnail |
| 2520 | 30 | 42 | RGB565_LE | PhotoPod list thumbnail |
where:
- UYVY is a byte stream where U,Y0,V,Y1 creates two YUV pixels of Y0,U,V and Y1,U,V, interlaced, all even fields, then all odd fields.
- RGB565_LE is a stream of byte-swapped 16-bit pixels ordered from top->bottom, left->right
- RGB565_BE_90 is a stream of 16-bit pixels ordered right to left, top to bottom
The "full screen" images are rotated because the iPod displays used are actually portrait, not landscape, and this format is just a memory dump of the frame buffer memory.
Album List
| field | size | value |
|---|---|---|
| header identifier | 4 | mhla |
| header length | 4 | size of the mhla header (0x5c) |
| number of children | 4 | the total number of children in the Album List (no children in ArtworkDB, 1 or more children in Photo Database) |
| rest of header is zero padded | ||
The Album List has no children in the case of the ArtworkDB file, and 1 or more children for the Photo Database: 1 child for the Photo Library and possible some more children for additional photo albums.
For the Photo Database the layout looks like this, for example:
mhsd (type: 2)
mhla (children: 3)
mhba (number of mhods: 1, number of mhias: 5, unk3: 0x10000)
mhod (string: "My Pictures")
mhia (image id: 100)
mhia (image id: 101)
mhia (image id: 102)
mhia (image id: 103)
mhia (image id: 104)
mhba (number of mhods: 1, number of mhias: 2, unk3: 0x60000)
mhod (string: "Folder A")
mhia (image id: 100)
mhia (image id: 101)
mhba (number of mhods: 1, number of mhias: 3, unk3: 0x60000)
mhod (string: "Folder B")
mhia (image id: 102)
mhia (image id: 103)
mhia (image id: 104)
In this case "My Pictures" was the folder that was selected in iTunes to synchronize photos with, and it contained 2 folders "Folder A" and "Folder B" with 2 and 3 photos respectively. The iPod will show this on its Photo menu as a submenu called "Photo Library" (containing all 5 photos), a submenu called "Folder A" with the first 2 photos and a submenu "Folder B" with the other 3 photos.
Note that the string MHODs are zero-padded to a length that is a multiple of 4 so that in the Photo Database all objects start on a 4-byte boundary. The iPod won't list any photo or photo album otherwise.
Photo Album
An MHBA allows you to setup an Album of photos (grouping photos together in an album). The MHBA is implemented similar to playlist.
These are only supported on models that support photos.
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | mhba |
| 4 | header length | 4 | size of the mhba header (0x94) |
| 8 | total length | 4 | size of the header and all child records |
| 12 | Data Object Child Count | 4 | number of Data Objects in the List, probably always 1. Sometimes seems to be 2 in the new video iPods' Photo Database, see below. |
| 16 | Album Item Count | 4 | number of pictures in the album |
| 20 | playlist id | 4 | a unique integer for each playlist - starts out at $64 and increments by 1. Really seems to be the total number of pictures (MHII) + photo album number (+1 for the first album, +2 for the second, etc. etc.) |
| 24 | unk2 | 4 | unknown, seems to be always 0 |
| 28 | unk3 | 2 | unknown, seems to be always 0 |
| 30 | Album Type | 1 | 1 = master photo list ("Photo Library"), 2 = normal album, sometimes 4 and 5 |
| 31 | playMusic | 1 | play music during slideshow (from iPhoto setting) |
| 32 | repeat | 1 | repeat the slideshow (from iPhoto setting) |
| 33 | random | 1 | show the slides in random order (from iPhoto setting) |
| 34 | showTitles | 1 | show slide captions (from iPhoto setting) |
| 35 | transitionDirection | 1 | 0=none, 1=left-to-right, 2=right-to-left, 3=top-to-bottom, 4=bottom-to-top (from iPhoto setting) |
| 36 | slideDuration | 4 | in seconds (from iPhoto setting) |
| 40 | transitionDuration | 4 | in milliseconds (from iPhoto setting) |
| 44 | unk7 | 4 | unknown, seems to always be 0 |
| 48 | unk8 | 4 | unknown, seems to always be 0 |
| 52 | dbid2 | 8 | dbid2 of track in iTunesDB to play during slideshow (from iPhoto setting) | 60 | prev playlist id | 4 | the id of the previous playlist Seems generated by this formula: value of the same field in the previous photo album MHBA + number of photos of the previous photo album + 1 | </tr>
| rest of header is zero | |||
The MHBA has several children: The first is a MHOD containing the album name (which is ignored if the MHBA is the Photo Library). After that there are several MHIAs that define which image to show in that album. The MHBA that is marked as Photo Library contains one MHIA record for every photo on the iPod.
On the new video iPods and nanos of recent vintage, the MHBA has a second MHOD as a child which contains a string of which specifies the transition effect configured in iPhoto for the slideshow associated with this album. Apparently, the iPod ignores the slideshow settings that come from iPhoto, except for the slideshow soundtrack.
Album Item
| field | size | value |
|---|---|---|
| header identifier | 4 | mhia |
| header length | 4 | size of the mhia header (0x28) |
| total length? | 4 | probably the size of the header and all child records; as there aren't any child records this is equal to header length (40) |
| unk1 | 4 | seems to be zero |
| image id | 4 | the id of the mhii record this mhia refers to |
| rest of header is zero | ||
File List
| field | size | value |
|---|---|---|
| header identifier | 4 | mhlf |
| header length | 4 | size of the mhlf header (0x5c) |
| number of files | 4 | the total number of files in the File List |
| rest of header is zero padded | ||
The File List has Files (Images) as its children.
File (Image)
| field | size | value |
|---|---|---|
| header identifier | 4 | mhif |
| header length | 4 | size of the mhif header (0x7c) |
| total length | 4 | size of the header and all child records |
| unknown1 | 4 | always seems to be 0 |
| correlation id | 4 | used to link this entry with a file and an Image Name, see Image Name for more details. |
| image size | 4 | size of the image in bytes. A full sized thumbnail is 39,200 bytes, a 'Now Playing' thumbnail is 6,272 bytes on the iPod Photo/Color. On the iPod Nano, a full sized thumbnail is 20,000 bytes while a 'Now Playing' thumbnail is 3,528 bytes. |
| rest of header is zero padded | ||
Data Object
The MHODs found in the ArtworkDB and Photo Database files are significantly different than those found in the normal iTunesDB files.
| offset | field | size | value |
|---|---|---|---|
| 0 | header identifier | 4 | mhod |
| 4 | header length | 4 | size of the MHOD header (0x18) |
| 8 | total length | 4 | size of the header and content, including child records |
| 12 | type | 2 | type of the MHOD, see below |
| 14 | unknown | 1 | unknown, always 0 so far |
| 15 | padding length | 1 | all MHODs must be zero-padded so that the length is a multiple of 4, this field contains the number of padding bytes added (e.g. 0, 1, 2 or 3). WARNING! This field was always set to 2 for a while. To avoid parser crash, the best way is to ignore it when parsing. |
| 16 | rest of header is zero padded | ||
There are 2 groups of types of MHODs in the ArtworkDB: container MHODs contain a MHNI as a child, while 'normal' string MHODs contain a string.
Attention: Sometimes seems that the MHBAs in the new video and nano iPods' Photo Database have a second MHOD child which, although being identified by a type of 2, is a string (and not container) MHOD. This second string MHOD in photo album is usually found in Photo Database files generated on Macs, probably by iPhoto, and contains an UTF-8 string describing a transition effect such as "Dissolve". However in Photo Database files generated on PCs for example by iTunes 6 for an iPod video 30Gb this does not happen, and there is only one type-1 string MHOD as child, just like with iPod Photo/Color Photo Database files.
| type | group | description |
|---|---|---|
| 1 | string | Album name (in the Photo Database) |
| 2 | container | Thumbnail image |
| 3 | string | File name |
| 5 | container | Full Resolution image (in the Photo Database) |
Container MHODs
MHODs with type 2 contain a MHNI that (contains a type 3 MHOD that) references a thumbnail. MHODs with type 5 contain a MHNI that (contains a type 3 MHOD that) references a full resolution image (in the Photo Database).
String MHODs
The content of string MHODs (probably all types except 2 and 5, although only 1 and 3 have been observed so far) is structured again with something like a sub-header:
| field | size | value |
|---|---|---|
| string length | 4 | length in bytes of the string (e.g. after encoding) |
| unknown | 4 | might be the string encoding: 0,1 == UTF-8; 2 == UTF-16-LE. Observed values are: 1 in type 1 MHODs and 2 in type 3 MHODs. |
| unknown | 4 | always zero? |
| content | variable | the actual, encoded string content |
| padding | 0..3 | zero to three bytes of padding to get the length of the whole MHOD to a multiple of 4, note that this is not included in the string length but is included in the total length |
