ipodsync 0.1.0__py3-none-any.whl

ipodsync/artwork_writer.py

@@ -0,0 +1,252 @@
+"""Pure-Python cover writer for the iPod nano 7G (without libgpod).
+
+The format was taken from the iTunes reference on the device (native/fixtures/itunes_artwork/):
+the nano 7G stores covers in `iPod_Control/Artwork/`:
+
+  - `ArtworkDB` — a binary container of atoms (mhfd → 3×mhsd → mhli/mhla/mhlf).
+    The image list (mhsd index=1) contains one `mhii` per track; each
+    `mhii` describes 4 thumbnails (per format 1010/1013/1015/1016) via
+    mhod(type=2)→mhni→mhod(type=3, file name), plus a service mhod(type=6, mhaf).
+  - `F<fmt>_1.ithmb` — raw RGB565-LE frames back to back, `slot` bytes per frame.
+
+Link to the SQLite library: `item.artwork_status=1`,
+`item.artwork_cache_id = mhii.image_id`; `mhii.song_id = unsigned(item.pid)`.
+
+The write strategy is a **surgical incremental append**: existing
+`mhii` and album/format lists are preserved byte-for-byte, new frames are
+appended to the end of `.ithmb`, and a new `mhii` is added to the list. This way we
+don't break the 700+ covers already generated by iTunes. `Locations.itdb` is not touched,
+so a cbk signature isn't needed.
+
+All structures are little-endian. Offsets were verified against the reference; the atom
+templates are real iTunes bytes, we only patch image_id/song_id/ithmb_offset.
+"""
+from __future__ import annotations
+
+import io
+import struct
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ._art_templates import (MHFD_TEMPLATE, MHII_HEADER, MHIF_ALL, MHLA_TEMPLATE,
+                             MHLF_TEMPLATE, MHLI_TEMPLATE, MHNI, MHOD_CONTAINER,
+                             MHOD_MHAF, STRMHOD)
+
+U64 = 1 << 64
+
+# --- nano 7G thumbnail formats (format_id, width, height, slot_bytes) -----------
+# slot == width*height*2, except 1016 (57×57=6498, slot 6612 = 57×58: the device
+# reads the top 57×57, the slot's tail is ignored -> we pad with zeros).
+FORMATS: list[tuple[int, int, int, int]] = [
+    (1010, 240, 240, 115200),   # Now Playing
+    (1013, 50, 50, 5000),
+    (1015, 58, 58, 6728),
+    (1016, 57, 57, 6612),
+]
+FORMAT_IDS = [f[0] for f in FORMATS]
+
+# Atom templates (MHII_HEADER/MHNI/STRMHOD/MHOD_*/MHFD/MHL*/MHIF_ALL) — real
+# bytes from the iTunes reference, see ipodsync/_art_templates.py. We only patch image_id/
+# song_id (in mhii) and ithmb_offset (in mhni).
+
+MHFD_HDR = 132
+MHSD_HDR = 96
+MHL_HDR = 92
+MHII_LEN = 928
+FIRST_IMAGE_ID = 101
+
+
+# --- encoding a cover to RGB565-LE ----------------------------------------------
+def to_rgb565(image_bytes: bytes, width: int, height: int, slot: int) -> bytes:
+    """Resize the cover to width×height, pack into RGB565-LE, pad to slot."""
+    from PIL import Image
+
+    im = Image.open(io.BytesIO(image_bytes)).convert("RGB").resize(
+        (width, height), Image.LANCZOS)
+    rgb = im.tobytes()  # width*height*3
+    out = bytearray(width * height * 2)
+    j = 0
+    for i in range(0, len(rgb), 3):
+        v = ((rgb[i] >> 3) << 11) | ((rgb[i + 1] >> 2) << 5) | (rgb[i + 2] >> 3)
+        out[j] = v & 0xFF
+        out[j + 1] = v >> 8
+        j += 2
+    if len(out) < slot:
+        out.extend(b"\x00" * (slot - len(out)))
+    return bytes(out)
+
+
+def encode_cover(image_bytes: bytes) -> dict[int, bytes]:
+    """Cover -> {format_id: rgb565_slot_bytes} for all 4 formats."""
+    return {fid: to_rgb565(image_bytes, w, h, slot) for fid, w, h, slot in FORMATS}
+
+
+# --- ArtworkDB model (surgical parse/build) -------------------------------------
+@dataclass
+class ArtworkDB:
+    """A parsed ArtworkDB. Existing records are kept as raw bytes."""
+    mhii_blocks: list[bytes] = field(default_factory=list)   # raw mhii (verbatim)
+    song_ids: set[int] = field(default_factory=set)          # already covered (unsigned)
+    next_id: int = FIRST_IMAGE_ID
+    mhsd_album: bytes = b""    # the whole mhsd(index=2) verbatim (or we synthesize it)
+    mhsd_file: bytes = b""     # the whole mhsd(index=3) verbatim (or we synthesize it)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "ArtworkDB":
+        p = Path(path)
+        if not p.exists():
+            return cls.empty()
+        return cls.parse(p.read_bytes())
+
+    @classmethod
+    def empty(cls) -> "ArtworkDB":
+        mhsd_album = _mhsd(2, MHSD_HDR + len(MHLA_TEMPLATE)) + MHLA_TEMPLATE
+        mhlf = MHLF_TEMPLATE + MHIF_ALL
+        mhsd_file = _mhsd(3, MHSD_HDR + len(mhlf)) + mhlf
+        return cls(next_id=FIRST_IMAGE_ID, mhsd_album=mhsd_album, mhsd_file=mhsd_file)
+
+    @classmethod
+    def parse(cls, data: bytes) -> "ArtworkDB":
+        if data[:4] != b"mhfd":
+            raise ValueError("not an ArtworkDB (no mhfd header)")
+        next_id = _i32(data, 28)
+        o = MHFD_HDR
+        mhii_blocks: list[bytes] = []
+        song_ids: set[int] = set()
+        mhsd_album = mhsd_file = b""
+        n_mhsd = _i32(data, 20)
+        for _ in range(n_mhsd):
+            total = _i32(data, o + 8)
+            index = struct.unpack_from("<h", data, o + 12)[0]
+            block = data[o:o + total]
+            if index == 1:  # image list: mhsd → mhli → mhii*
+                mhli_off = MHSD_HDR
+                num = _i32(block, mhli_off + 8)
+                q = mhli_off + MHL_HDR
+                for _i in range(num):
+                    mtot = _i32(block, q + 8)
+                    mhii = block[q:q + mtot]
+                    mhii_blocks.append(mhii)
+                    song_ids.add(struct.unpack_from("<Q", mhii, 20)[0])
+                    q += mtot
+            elif index == 2:
+                mhsd_album = block
+            elif index == 3:
+                mhsd_file = block
+            o += total
+        if not mhsd_album:
+            mhsd_album = _mhsd(2, MHSD_HDR + len(MHLA_TEMPLATE)) + MHLA_TEMPLATE
+        if not mhsd_file:
+            mhlf = MHLF_TEMPLATE + MHIF_ALL
+            mhsd_file = _mhsd(3, MHSD_HDR + len(mhlf)) + mhlf
+        return cls(mhii_blocks, song_ids, next_id, mhsd_album, mhsd_file)
+
+    def has(self, song_id: int) -> bool:
+        return (song_id % U64) in self.song_ids
+
+    def add_record(self, song_id: int, offsets: dict[int, int]) -> int:
+        """Add an mhii for a track. offsets: {format_id: ithmb_offset}. -> image_id."""
+        song_id %= U64
+        image_id = self.next_id
+        self.mhii_blocks.append(_build_mhii(image_id, song_id, offsets))
+        self.song_ids.add(song_id)
+        self.next_id += 1
+        return image_id
+
+    def serialize(self) -> bytes:
+        mhii_all = b"".join(self.mhii_blocks)
+        n = len(self.mhii_blocks)
+        mhli = bytearray(MHLI_TEMPLATE)
+        struct.pack_into("<i", mhli, 8, n)
+        mhsd_img = _mhsd(1, MHSD_HDR + MHL_HDR + len(mhii_all)) + bytes(mhli) + mhii_all
+
+        total = MHFD_HDR + len(mhsd_img) + len(self.mhsd_album) + len(self.mhsd_file)
+        mhfd = bytearray(MHFD_TEMPLATE)
+        struct.pack_into("<i", mhfd, 8, total)
+        struct.pack_into("<i", mhfd, 20, 3)          # num_children
+        struct.pack_into("<i", mhfd, 28, self.next_id)
+        return bytes(mhfd) + mhsd_img + self.mhsd_album + self.mhsd_file
+
+
+def _i32(b, o):
+    return struct.unpack_from("<i", b, o)[0]
+
+
+def _mhsd(index: int, total: int) -> bytes:
+    b = bytearray(MHSD_HDR)
+    b[0:4] = b"mhsd"
+    struct.pack_into("<i", b, 4, MHSD_HDR)
+    struct.pack_into("<i", b, 8, total)
+    struct.pack_into("<h", b, 12, index)
+    return bytes(b)
+
+
+def _build_mhii(image_id: int, song_id: int, offsets: dict[int, int]) -> bytes:
+    hdr = bytearray(MHII_HEADER)
+    struct.pack_into("<i", hdr, 16, image_id)
+    struct.pack_into("<Q", hdr, 20, song_id % U64)
+    body = bytearray()
+    for fid in FORMAT_IDS:
+        body += MHOD_CONTAINER
+        mhni = bytearray(MHNI[fid])
+        struct.pack_into("<i", mhni, 20, offsets[fid])
+        body += mhni
+        body += STRMHOD[fid]
+    body += MHOD_MHAF
+    out = bytes(hdr) + bytes(body)
+    assert len(out) == MHII_LEN, f"mhii len {len(out)} != {MHII_LEN}"
+    return out
+
+
+# --- appending to .ithmb --------------------------------------------------------
+def append_thumb(artwork_dir: Path, format_id: int, slot_bytes: bytes) -> int:
+    """Append a frame to F<fmt>_1.ithmb. Returns ithmb_offset (bytes from the start)."""
+    path = Path(artwork_dir) / f"F{format_id}_1.ithmb"
+    offset = path.stat().st_size if path.exists() else 0
+    with open(path, "ab") as f:
+        f.write(slot_bytes)
+    return offset
+
+
+# --- high-level operation -------------------------------------------------------
+def attach_cover(artwork_dir: str | Path, song_id: int, cover_bytes: bytes) -> int | None:
+    """Attach a cover to a track (song_id = unsigned pid).
+
+    Appends 4 thumbnails to .ithmb and an mhii to ArtworkDB (incrementally,
+    without breaking what exists). Returns the image_id for item.artwork_cache_id,
+    or None if the track already has a cover (we don't repeat).
+    """
+    artwork_dir = Path(artwork_dir)
+    artwork_dir.mkdir(parents=True, exist_ok=True)
+    db_path = artwork_dir / "ArtworkDB"
+    db = ArtworkDB.load(db_path)
+    if db.has(song_id):
+        return None
+
+    slots = encode_cover(cover_bytes)
+    offsets = {fid: append_thumb(artwork_dir, fid, slots[fid]) for fid in FORMAT_IDS}
+    image_id = db.add_record(song_id, offsets)
+
+    tmp = db_path.with_suffix(".tmp")
+    tmp.write_bytes(db.serialize())
+    tmp.replace(db_path)
+    return image_id
+
+
+# --- extracting the embedded cover from audio -----------------------------------
+def extract_embedded_cover(audio_path: str | Path) -> bytes | None:
+    """Extract the embedded cover bytes from MP3 (APIC) or M4A (covr)."""
+    p = Path(audio_path)
+    ext = p.suffix.lower()
+    try:
+        if ext == ".mp3":
+            from mutagen.id3 import ID3
+            apic = ID3(p).getall("APIC")
+            return apic[0].data if apic else None
+        if ext in (".m4a", ".mp4", ".aac", ".alac"):
+            from mutagen.mp4 import MP4
+            covr = MP4(p).tags.get("covr") if MP4(p).tags else None
+            return bytes(covr[0]) if covr else None
+    except Exception:
+        return None
+    return None

ipodsync/cbk.py

@@ -0,0 +1,44 @@
+"""Generate Locations.itdb.cbk — the anti-tamper signature of the nano 7G SQLite DB.
+
+The format was worked out from the tunesreloaded code (modules/hashAB.js) and
+verified byte-for-byte against the reference in native/fixtures/:
+
+    cbk = signature(57) + master_sha1(20) + block_sha1[i](20) * N
+
+  where Locations.itdb is split into 1024-byte blocks (the last one padded with
+  zeros to 1024), each block -> SHA1; the concatenation of all block-SHA1s -> SHA1 =
+  master; signature = calcHashAB(master, FirewireGuid, rnd=FIXED_RND).
+
+tunesreloaded/libgpod use the fixed rnd b"ABCDEFGHIJKLMNOPQRSTUVW"
+(the same one used in the hashab test vectors) — so cbk is fully deterministic.
+Only Locations.itdb is hash-protected; the other .itdb files are plain SQLite.
+"""
+from __future__ import annotations
+
+import hashlib
+
+from .hashab import HashAB
+
+CBK_BLOCK_SIZE = 1024
+FIXED_RND = b"ABCDEFGHIJKLMNOPQRSTUVW"   # 23 bytes, as in tunesreloaded/test vectors
+
+
+def build_cbk(locations_itdb: bytes, firewire_guid: bytes,
+              hasher: HashAB | None = None) -> bytes:
+    """Build the contents of Locations.itdb.cbk for a given Locations.itdb.
+
+    firewire_guid — 8 bytes (big-endian, as from sysinfo.read_firewire_guid).
+    """
+    h = hasher or HashAB()
+
+    digests = []
+    for i in range(0, len(locations_itdb), CBK_BLOCK_SIZE):
+        block = locations_itdb[i:i + CBK_BLOCK_SIZE]
+        if len(block) < CBK_BLOCK_SIZE:
+            block = block + b"\x00" * (CBK_BLOCK_SIZE - len(block))
+        digests.append(hashlib.sha1(block).digest())
+
+    concat = b"".join(digests)
+    master = hashlib.sha1(concat).digest()
+    signature = h.sign(master, firewire_guid, rnd_bytes=FIXED_RND)
+    return signature + master + concat

ipodsync/cli.py

@@ -0,0 +1,314 @@
+"""CLI `ipodsync` for managing an iPod nano 6G/7G library.
+
+    ipodsync list                     # show tracks
+    ipodsync export DEST [--by-album] [--no-tag]   # download everything from the iPod
+    ipodsync export DEST --pid PID     # download a single track
+    ipodsync add FILE [--no-cover]     # upload a track (+cover auto)
+    ipodsync rm PID [--delete-file]    # remove a track (+resign)
+    ipodsync cover PID [--image IMG]   # attach a cover to a track
+
+Export is read-only for the device. add/rm/cover write to the database (they back up .itlp).
+Do not open this iPod in iTunes.
+"""
+from __future__ import annotations
+
+import argparse
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+MAC_EPOCH = 978307200
+
+
+def _mac_now() -> int:
+    return int(datetime.now(timezone.utc).timestamp()) - MAC_EPOCH
+
+
+from ipodsync.export import export_track
+from ipodsync.importer import add_mp3_to_library, copy_audio_to_ipod
+from ipodsync.library import ItlpLibrary
+from ipodsync.sysinfo import read_firewire_guid
+from ipodsync.transport import (NO_ACCESS_HINT, Access, IPodNotFound, find_ipod,
+                                probe_ipods, wait_for_ipod)
+
+
+def _lib(ipod):
+    return ItlpLibrary(ipod.itunes_dir / "iTunes Library.itlp")
+
+
+def cmd_list(ipod, args):
+    lib = _lib(ipod)
+    tracks = lib.list_tracks()
+    for t in tracks:
+        dur = t["duration_ms"] // 1000
+        print(f"  [{t['pid']:>20}] {t['artist'] or '—'} — {t['title'] or '—'}"
+              f"  ({t['album'] or '—'}, {dur//60}:{dur % 60:02d})  {t['location']}")
+    print(f"\nTotal: {len(tracks)} tracks")
+    lib.close()
+
+
+def cmd_export(ipod, args):
+    lib = _lib(ipod)
+    tracks = lib.list_tracks()
+    if args.pid is not None:
+        tracks = [t for t in tracks if t["pid"] == args.pid]
+    dest = Path(args.dest)
+    layout = "artist_album" if args.by_album else "flat"
+    ok = 0
+    for t in tracks:
+        if not t["location"]:
+            continue
+        try:
+            dst = export_track(ipod.music_dir, t, dest, tag=not args.no_tag, layout=layout)
+            print(f"  ✓ {dst.relative_to(dest)}")
+            ok += 1
+        except Exception as e:  # noqa: BLE001
+            print(f"  ✗ {t.get('title')!r}: {e}")
+    print(f"\nDownloaded {ok}/{len(tracks)} to {dest}")
+    lib.close()
+
+
+def cmd_rm(ipod, args):
+    itlp = ipod.itunes_dir / "iTunes Library.itlp"
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = Path.home() / "ipod-backups" / f"itlp-{stamp}"
+    backup.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(itlp, backup)
+    print(f".itlp backup: {backup}")
+
+    guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo)
+    lib = ItlpLibrary(itlp)
+    music = ipod.music_dir if args.delete_file else None
+    loc = lib.remove_track(args.pid, music_dir=music)
+    lib.resign(guid)
+    lib.close()
+    print(f"Removed track pid={args.pid} (file: {loc or '—'}"
+          f"{', deleted' if args.delete_file else ''}). Eject iPod.")
+    print(f"Rollback: rm -rf '{itlp}' && cp -r '{backup}' '{itlp}'")
+
+
+def _edit_library(ipod, fn, *, label: str):
+    """Back up .itlp, edit a copy via fn(lib), copy Library/Dynamic.itdb back.
+
+    Playlist operations don't touch Locations.itdb, so we don't rebuild cbk.
+    """
+    itlp = ipod.itunes_dir / "iTunes Library.itlp"
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = Path.home() / "ipod-backups" / f"itlp-{stamp}"
+    backup.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(itlp, backup)
+    work = Path("/tmp") / f"itlp_{label}_{stamp}"
+    shutil.copytree(itlp, work)
+
+    lib = ItlpLibrary(work)
+    try:
+        result = fn(lib)
+    finally:
+        lib.close()
+    for name in ("Library.itdb", "Dynamic.itdb"):
+        shutil.copy2(work / name, itlp / name)
+    print(f".itlp backup: {backup}. Eject iPod.")
+    return result
+
+
+def cmd_playlists(ipod, args):
+    lib = _lib(ipod)
+    for p in lib.list_playlists():
+        tag = " [master]" if p["is_master"] else (" [hidden]" if p["hidden"] else "")
+        print(f"  [{p['pid']:>20}] {p['name']}  ({p['count']} tracks){tag}")
+    lib.close()
+
+
+def cmd_pl_create(ipod, args):
+    pid = _edit_library(ipod, lambda lib: lib.create_playlist(args.name, date=_mac_now()),
+                        label="plcreate")
+    print(f"Created playlist '{args.name}' pid={pid}")
+
+
+def cmd_pl_add(ipod, args):
+    _edit_library(ipod, lambda lib: [lib.add_to_playlist(args.playlist, t) for t in args.track],
+                  label="pladd")
+    print(f"Tracks added: {len(args.track)} → playlist {args.playlist}")
+
+
+def cmd_pl_rm(ipod, args):
+    _edit_library(ipod, lambda lib: lib.remove_from_playlist(args.playlist, args.track),
+                  label="plrm")
+    print(f"Track {args.track} removed from playlist {args.playlist}")
+
+
+def cmd_pl_del(ipod, args):
+    _edit_library(ipod, lambda lib: lib.delete_playlist(args.playlist), label="pldel")
+    print(f"Playlist {args.playlist} deleted")
+
+
+def cmd_status(args):
+    st, ipod, blocked = probe_ipods()
+    if st is Access.READY:
+        lib = _lib(ipod)
+        try:
+            n = len(lib.list_tracks())
+        finally:
+            lib.close()
+        print(f"✅ iPod ready: {ipod.root}  ({n} tracks)")
+    elif st is Access.NO_ACCESS:
+        print("⛔ " + NO_ACCESS_HINT.format(vols=", ".join(v.name for v in blocked)))
+    else:
+        print("❌ iPod not connected (no volume in /Volumes). Enable Disk Use.")
+
+
+def cmd_wait(args):
+    print("⏳ Waiting for iPod…")
+    last = {"s": None}
+
+    def on_wait(status, blocked):
+        if status != last["s"]:
+            last["s"] = status
+            note = " (no access — see Full Disk Access)" if status is Access.NO_ACCESS else ""
+            print(f"   …{status.value}{note}")
+
+    ipod = wait_for_ipod(timeout=args.timeout, interval=args.interval, on_wait=on_wait)
+    print(f"✅ iPod ready: {ipod.root}")
+
+
+def cmd_add(ipod, args):
+    """Upload an MP3 to the iPod: audio -> Fxx/ (onto the device), .itlp -> edit a copy -> back."""
+    itlp = ipod.itunes_dir / "iTunes Library.itlp"
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = Path.home() / "ipod-backups" / f"itlp-{stamp}"
+    backup.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(itlp, backup)
+    print(f".itlp backup: {backup}")
+
+    guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo)
+    location, abs_path = copy_audio_to_ipod(ipod, args.file)
+    print(f"File copied: {location}")
+
+    work = Path("/tmp") / f"itlp_add_{stamp}"
+    shutil.copytree(itlp, work)
+    overrides = {"title": args.title, "artist": args.artist, "album": args.album}
+    art_dir = None if args.no_cover else ipod.control / "Artwork"
+    if art_dir is not None:
+        _backup_artwork(ipod, stamp)
+    pid = add_mp3_to_library(work, location, args.file, abs_path.stat().st_size,
+                             guid, overrides=overrides, artwork_dir=art_dir)
+    for name in ("Library.itdb", "Locations.itdb", "Dynamic.itdb",
+                 "Extras.itdb", "Locations.itdb.cbk"):
+        shutil.copy2(work / name, itlp / name)
+    print(f"Track added pid={pid}"
+          f"{'' if args.no_cover else ' (cover attached if one was embedded)'}."
+          " Eject iPod and check Songs.")
+    print(f"Rollback: rm -rf '{itlp}' && cp -r '{backup}' '{itlp}'")
+
+
+def _backup_artwork(ipod, stamp: str) -> None:
+    """Back up iPod_Control/Artwork before appending covers (ithmb append)."""
+    art = ipod.control / "Artwork"
+    if art.exists():
+        dst = Path.home() / "ipod-backups" / f"Artwork-{stamp}"
+        shutil.copytree(art, dst)
+        print(f"Artwork backup: {dst}")
+
+
+def cmd_cover(ipod, args):
+    """Attach a cover to an already-uploaded track (pid). Source is the track file on the iPod
+    (embedded APIC) or an explicit --image."""
+    from ipodsync.artwork_writer import U64, attach_cover, extract_embedded_cover
+    from ipodsync.library import ItlpLibrary
+
+    itlp = ipod.itunes_dir / "iTunes Library.itlp"
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    _backup_artwork(ipod, stamp)
+
+    if args.image:
+        cover = Path(args.image).read_bytes()
+    else:
+        lib = ItlpLibrary(itlp)
+        try:
+            t = next((t for t in lib.list_tracks() if t["pid"] == args.pid), None)
+        finally:
+            lib.close()
+        if not t or not t["location"]:
+            print(f"⚠️  track pid={args.pid} not found"); return
+        cover = extract_embedded_cover(ipod.music_dir / t["location"])
+        if not cover:
+            print("⚠️  the track file has no embedded cover (APIC/covr). "
+                  "Provide an image via --image."); return
+
+    image_id = attach_cover(ipod.control / "Artwork", args.pid % U64, cover)
+    if image_id is None:
+        print(f"Track pid={args.pid} already has a cover — skipping."); return
+
+    work = Path("/tmp") / f"itlp_cover_{stamp}"
+    shutil.copytree(itlp, work)
+    lib = ItlpLibrary(work)
+    try:
+        lib.set_track_artwork(args.pid, image_id)
+        album_pid = lib.album_pid_of(args.pid)
+        if album_pid:
+            lib.set_album_artwork(album_pid, args.pid)
+    finally:
+        lib.close()
+    shutil.copy2(work / "Library.itdb", itlp / "Library.itdb")
+    print(f"Cover attached to pid={args.pid} (cache_id={image_id}, "
+          f"album{'+' if album_pid else ' —'}). Eject iPod.")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("list")
+    pe = sub.add_parser("export")
+    pe.add_argument("dest")
+    pe.add_argument("--pid", type=int)
+    pe.add_argument("--by-album", action="store_true")
+    pe.add_argument("--no-tag", action="store_true")
+    pr = sub.add_parser("rm")
+    pr.add_argument("pid", type=int)
+    pr.add_argument("--delete-file", action="store_true")
+    pa = sub.add_parser("add")
+    pa.add_argument("file", help="path to MP3")
+    pa.add_argument("--title")
+    pa.add_argument("--artist")
+    pa.add_argument("--album")
+    pa.add_argument("--no-cover", action="store_true",
+                    help="don't attach the embedded cover")
+    sub.add_parser("status")
+    pw = sub.add_parser("wait")
+    pw.add_argument("--timeout", type=float, default=120)
+    pw.add_argument("--interval", type=float, default=2)
+
+    sub.add_parser("playlists")
+    pc = sub.add_parser("pl-create"); pc.add_argument("name")
+    ppa = sub.add_parser("pl-add")
+    ppa.add_argument("playlist", type=int); ppa.add_argument("track", type=int, nargs="+")
+    ppr = sub.add_parser("pl-rm")
+    ppr.add_argument("playlist", type=int); ppr.add_argument("track", type=int)
+    ppd = sub.add_parser("pl-del"); ppd.add_argument("playlist", type=int)
+    pcv = sub.add_parser("cover")
+    pcv.add_argument("pid", type=int)
+    pcv.add_argument("--image", help="cover image file (otherwise the track's APIC is used)")
+    args = ap.parse_args()
+
+    # commands that don't require a ready iPod
+    if args.cmd == "status":
+        return cmd_status(args)
+    if args.cmd == "wait":
+        return cmd_wait(args)
+
+    try:
+        ipod = find_ipod()
+    except IPodNotFound as e:
+        print(f"⚠️  {e}")
+        return 2
+    handlers = {
+        "list": cmd_list, "export": cmd_export, "rm": cmd_rm, "add": cmd_add,
+        "playlists": cmd_playlists, "pl-create": cmd_pl_create, "pl-add": cmd_pl_add,
+        "pl-rm": cmd_pl_rm, "pl-del": cmd_pl_del, "cover": cmd_cover,
+    }
+    handlers[args.cmd](ipod, args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())