iPod Internals

This document covers the internal structure of iPod devices, focusing on the database format, file organization, and artwork handling. This is primarily useful for debugging and development.

Directory Structure

iPod_Control/
├── Device/
│   ├── SysInfo              # Device model information
│   └── SysInfoExtended      # Detailed device capabilities (iTunes-created)
├── iTunes/
│   ├── iTunesDB             # Main track database (binary)
│   ├── iTunesPrefs          # Device preferences
│   └── iTunesShuffle        # Shuffle state
├── Music/
│   ├── F00/                 # Music files (distributed across Fxx folders)
│   ├── F01/
│   ├── ...
│   └── F49/
└── Artwork/
    ├── F1028_1.ithmb        # Artwork database files
    ├── F1029_1.ithmb
    └── ...

SysInfo File

The SysInfo file in iPod_Control/Device/ identifies the iPod model to software. This is critical for libgpod to determine supported features.

Format

ModelNumStr: MA147
FirewireGuid: XXXXXXXXXXXXXXXX

Model Numbers

Model Number	Device	Capacity	Generation
MA002	iPod Video	30GB White	5th
MA003	iPod Video	60GB White	5th
MA146	iPod Video	30GB Black	5th
MA147	iPod Video	60GB Black	5th
MA450	iPod Video	30GB	5.5th
MA448	iPod Video	80GB	5.5th
MB147	iPod Classic	80GB Silver	6th
MB150	iPod Classic	80GB Black	6th
MB565	iPod Classic	120GB Black	6th
MC297	iPod Classic	160GB Black	7th

Model Number Parsing

libgpod parses model numbers with this logic:

// Skip leading letter if alphabetic
if (isalpha(model_number[0])) {
    model_number++;
}
// Look up remaining string in model table
return g_hash_table_lookup(model_table, model_number);

Important: Use format MA147 (with M prefix) in SysInfo. libgpod will:

Skip the ‘M’
Look up ‘A147’ in the model table

Using just A147 would skip ‘A’ and look for ‘147’, which doesn’t exist.

Creating SysInfo Manually

If an iPod doesn’t have a SysInfo file (common after reformatting):

IPOD="/media/username/IPOD"
echo "ModelNumStr: MA147" > "$IPOD/iPod_Control/Device/SysInfo"

iTunesDB Format

The iTunesDB is a binary database format storing track metadata, playlists, and other iPod data.

Structure Overview

iTunesDB
├── Header (mhbd)
├── Track List (mhlt)
│   └── Track Items (mhit) × N
│       └── Strings (mhod) - title, artist, album, etc.
├── Playlist List (mhlp)
│   └── Playlist Items (mhyp) × N
│       └── Playlist Tracks (mhip)
└── Album List (mhla) - newer iPods only

Binary Format

All multi-byte integers are little-endian.

File Types

Type1/Type2	Meaning
0, 0	AAC
1, 1	MP3
2, 2	WAV
4, 4	ALAC

Why Not Parse Directly?

While the format is documented, there are many reasons to use libgpod instead:

Version variations - Format differs between iPod generations
Checksum fields - Newer iPods validate database integrity
Artwork database - Separate complex format
Edge cases - Years of bug fixes in libgpod
Two-way sync - Reading and writing both needed

Music File Storage

File Organization

iPod stores music files in iPod_Control/Music/Fxx/ directories where xx is 00-49. Files are distributed using a hash to balance across folders.

File names are generated by libgpod:

libgpod<random>.m4a

Why Random Names?

Filesystem limits - Distributes across directories
Prevents conflicts - No naming collisions
Security through obscurity - Harder to browse directly

Path Format

Paths in iTunesDB use colon separators:

:iPod_Control:Music:F01:libgpod123456.m4a

libgpod converts these to Unix paths when needed.

Artwork Database

Overview

iPod stores album artwork in a separate database (Artwork/) in a device-specific format.

Artwork Formats

Each iPod model supports specific artwork sizes and formats:

Format ID	Width	Height	Format	Used By
1028	100	100	RGB565 LE	iPod Video (small)
1029	200	200	RGB565 LE	iPod Video (large)
1055	128	128	JPEG	iPod Classic
1060	320	320	JPEG	iPod Classic (full)

RGB565 Format

iPod Video uses RGB565 little-endian format:

5 bits red
6 bits green
5 bits blue
2 bytes per pixel
No alpha channel

// Convert RGB888 to RGB565
uint16_t rgb565 = ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3);

Artwork Files

Artwork is stored in .ithmb files:

Artwork/F1028_1.ithmb  # Format 1028, file 1
Artwork/F1029_1.ithmb  # Format 1029, file 1

Each file contains concatenated images for multiple tracks.

Artwork Requirements

SysInfo must exist - libgpod needs model info for format selection
Artwork directory must exist - Create iPod_Control/Artwork/ if missing
Source image - JPEG or PNG, any size (libgpod resizes)

Fixing Missing Artwork

If artwork isn’t syncing:

IPOD="/media/username/IPOD"

# 1. Ensure SysInfo exists
cat "$IPOD/iPod_Control/Device/SysInfo"
# Should show: ModelNumStr: MA147 (or your model)

# 2. Create Artwork directory
mkdir -p "$IPOD/iPod_Control/Artwork"

# 3. Sync filesystem
sync

Device Detection

USB Identification

iPods identify as USB Mass Storage devices:

Vendor ID	Product ID	Device
0x05ac	0x1209	iPod (Mass Storage)
0x05ac	0x1261	iPod Classic 6th Gen
0x05ac	0x1263	iPod Classic 7th Gen

Mount Point Detection

# Find mounted iPods
lsblk -o NAME,LABEL,MOUNTPOINT | grep -i ipod

# Or by looking for iTunesDB
find /media -name "iTunesDB" 2>/dev/null

Compatibility Notes

For the complete device compatibility list, see Supported Devices.

Quick Reference

Device	Generation	Support Level
iPod Classic	6th, 7th	Full
iPod Video	5th, 5.5th	Full
iPod Nano	1st-5th	Full
iPod Mini	1st, 2nd	Full
iPod Shuffle	1st-2nd	Music only (no artwork, no screen)

Unsupported Devices

Device	Reason
iPod Touch (all)	Uses iOS protocols; iTunesDB requires cryptographic signing
iPhone (all)	Uses iOS protocols
iPad (all)	Uses iOS protocols
iPod Nano 6th/7th	Different database format (not iTunesDB)
iPod Shuffle 3rd/4th	Buttonless design; requires iTunes authentication hash

Troubleshooting

Database Corruption

Symptoms:

iPod shows “No Music”
Tracks missing after sync
iPod freezes when browsing

Fix:

# Backup existing database
cp "$IPOD/iPod_Control/iTunes/iTunesDB" ~/iTunesDB.bak

# Remove and re-sync
rm "$IPOD/iPod_Control/iTunes/iTunesDB"
# Then re-add all tracks with podkit

Filesystem Issues

# Check filesystem (must be unmounted)
sudo fsck.vfat -n /dev/sdX1

# Repair if needed
sudo fsck.vfat -a /dev/sdX1