ipodutils

Rebuild the on-disk database for 1st- and 2nd-generation Apple iPod shuffle players (iTunesSD, shuffle order, playback state, and related files) so you can manage music by copying files—without iTunes—for each sync.

Python 3 port of KeyJ’s rebuild_db (Martin J. Fiedler).

Supported hardware

Supported	Not supported
iPod shuffle (1st gen), iPod shuffle (2nd gen)	3rd-gen shuffle and later (VoiceOver, different DB format)

The volume must already contain iPod_Control/ (typically after one-time setup with iTunes or an equivalent).

Requirements

Python ≥ 3.14
Write access to the iPod’s mounted volume

Install

From a checkout:

uv sync

From this package index (HTTPS):

Download URL (simple index): https://barrys.cloud/pypi/simple/

pip install --index-url https://barrys.cloud/pypi/simple/ ipodutils

uv pip install --index-url https://barrys.cloud/pypi/simple/ ipodutils

The console entry point is rebuild-db (implements main:cli).

Usage

Run with the working directory set to the iPod root, or pass --ipod-path:

# From repo / env that has the package installed
uv run rebuild-db --ipod-path /run/media/$USER/IPOD

# Or: cd to the mount, then
rebuild-db

Full options:

rebuild-db --help

Common options

Option	Meaning
`--ipod-path DIR`	Use `DIR` as the iPod root (mount point)
`-s` / `--nosmart`	Plain random shuffle instead of “smart shuffle”
`-i` / `--interactive`	Confirm each directory while scanning
`-v N`	Playback volume (0–38)
`-f` / `--force`	Rebuild DB entries from scratch (do not reuse old entries; useful for `.aa` only if you understand the trade-offs)
`-r` / `--rename`	Rename unsafe paths outside `iPod_Control`
`-l` / `--nolog`	Do not write `rebuild_db.log.txt`
`--shuffle-all`	Force `shuffle=1` on every track (overrides audiobook-style rules)
`--verbose`	Log each file as it is written (`type`, `shuffle`, `bookmark`), like the original KeyJ tool

Optional rules file: rebuild_db.rules in the iPod root (see --help and original rebuild_db documentation for the rule syntax).

WAV, M4A, and “not showing up”

Hardware: Apple’s specs for the 1st- and 2nd-gen iPod shuffle list MP3, AAC (M4A/M4P/M4B), Audible, and WAV (and AIFF on 2nd gen) as supported formats. The shuffle has no screen—tracks do not “appear” anywhere except through playback order and, on disk, under iPod_Control/Music/.

Database: This tool assigns type 1 (MP3), type 2 (AAC/M4A), type 4 (WAV) in iTunesSD, matching KeyJ’s rebuild_db. If something still will not play:

Run with --verbose and confirm every file is listed with type=4 and shuffle=1 for WAV. If shuffle=0, a rule matched (e.g. *.book.??? treats names like anything.book.wav as audiobooks). Use --shuffle-all or adjust rebuild_db.rules.
PCM format: The device is picky like many portables. Prefer 44.1 kHz, 16-bit, stereo, PCM WAV. Float WAV, 24/32-bit, or very high sample rates may fail silently. Re-encode if needed, e.g. ffmpeg -i in.wav -ar 44100 -ac 2 -sample_fmt s16 out.wav.
M4A usually works because AAC matches what iTunes typically synced; if only M4A plays, format (2) vs WAV (4) on the wire is a good clue to try re-encoding WAV to AAC/MP3 as a test.

Converting a folder of audio for the shuffle

Install ffmpeg, then (from a checkout or after pip install ipodutils):

shuffle-convert /path/to/music
# writes 44.1 kHz / 16-bit / stereo WAV under /path/to/music/shuffle_ready/
shuffle-convert /path/to/music -o /path/to/out -f mp3
shuffle-convert /path/to/music --dry-run

By default, conversion uses high-quality resampling (SoXR when your ffmpeg supports it), MP3 V0, and AAC 256 kbps. If you hear ringing or “digital” grain, avoid --fast (that mode uses lighter resampling and lower bitrates). For the cleanest WAV, keep the default; re-encode from lossless sources when possible—transcoding MP3 → WAV cannot remove existing compression artifacts.

Logging

By default, output is also written to rebuild_db.log.txt on the iPod root. Use --nolog to disable.

License

GPL v2 — see License.txt.

4.5 KiB Raw Blame History Unescape Escape