ipodsync 0.1.0

Upload music to an iPod nano 6G/7G without iTunes: SQLite library, hashAB signing, cover art (pure-Python).

ipodsync

Upload music to an iPod nano 6G/7G without iTunes/Apple Music — straight from the terminal, on macOS and Linux. The iPod mounts as a plain volume; ipodsync edits its SQLite library, signs it (hashAB) and generates cover art itself.

⚠️ Alpha. Works on real hardware, but it writes to the player's binary database. Keep backups (the tool makes one before every edit) and don't open this iPod in iTunes.

Features

• list / export — inspect and download tracks from the device (with tags).
• add — upload an MP3, metadata from tags, cover art attached automatically (from an embedded APIC/covr): shown both in Now Playing and in list/Albums views.
• rm — remove a track (+file), re-sign.
• playlists — playlists / pl-create / pl-add / pl-rm / pl-del.
• cover — attach a cover to an already-uploaded track.
• works on an empty (wiped) library too — no iTunes needed to initialize it.

Install

pipx install ipodsync      # recommended (isolated), or: pip install ipodsync

Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.

Note: uploading currently supports MP3 only. FLAC/AAC → ALAC transcoding (which will need ffmpeg) is on the roadmap and not implemented yet.

Usage

ipodsync status                     # ready / no access / not connected
ipodsync list
ipodsync add "Song.mp3"             # + cover auto
ipodsync add "Song.mp3" --no-cover
ipodsync export ~/Music/ipod --by-album
ipodsync cover 123456789 --image cover.jpg
ipodsync rm 123456789 --delete-file

The iPod is discovered under /Volumes (macOS) and /media, /run/media, /mnt (Linux) by the presence of iPod_Control/. To point at it explicitly, set IPODSYNC_MOUNT=/path/to/mount.

How it works

• Transport — mass storage: files are written under iPod_Control/.
• Database — SQLite iTunes Library.itlp/*.itdb (not iTunesCDB, which the device regenerates on its own). Only Locations.itdb is hash-protected (.cbk).
• hashAB — anti-tamper .cbk signature (white-box AES). Pure-Python port of dstaley/hashab (public domain), 100/100 test vectors. No compiler or native lib — the package installs everywhere.
• Cover art — pure-Python writer for ArtworkDB + F<fmt>_1.ithmb (RGB565 LE, formats 1010/1013/1015/1016), appended incrementally.

Status / roadmap

	Status
Upload / remove / export / playlists (MP3)	✅ confirmed on nano 7G
Cover art (pure-Python)	✅ confirmed on nano 7G
Empty-library bootstrap	✅
Pure-Python hashAB (no native lib, installs everywhere)	✅ 100/100 vectors
Cross-platform device discovery (macOS + Linux)	✅
FLAC/AAC → ALAC	⬜

Development

git clone … && cd ipodsync
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT (see LICENSE). The vendored hashAB algorithm is public domain. Not affiliated with Apple; iPod and iTunes are trademarks of Apple.