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 PyPI (after you publish):

pip install 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`

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

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.

2.2 KiB Raw Blame History Unescape Escape