ipodsync 0.1.2

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, so keep backups (the tool makes one before every edit). Browsing the iPod in Finder or the Music app is fine — just don't let Apple's software auto-sync it: a sync rebuilds the library from your computer and would drop manually-added tracks (keep the iPod in "manually manage music" mode).

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

ipodsync is a command-line tool, so install it with pipx — it lands in an isolated environment while the ipodsync command stays available everywhere:

pipx install ipodsync

No pipx yet? brew install pipx (macOS) or sudo apt install pipx (Debian/Ubuntu), then pipx ensurepath.

pip install ipodsync fails with externally-managed-environment?

On modern Debian/Ubuntu (PEP 668) the system Python is locked, so a plain pip install into it is refused — that's an OS guard, not an ipodsync issue. Use pipx (above), or a virtualenv:

python3 -m venv ~/.venvs/ipodsync
~/.venvs/ipodsync/bin/pip install ipodsync
~/.venvs/ipodsync/bin/ipodsync --help

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.