ipodsync 0.1.0__py3-none-any.whl

ipodsync/export.py

@@ -0,0 +1,91 @@
+"""Download tracks FROM the iPod to the computer (read-only for the device).
+
+The iPod stores files as iPod_Control/Music/Fxx/libgpodNNN.mp3 (obfuscated names),
+with metadata in SQLite. Export = copy the file under a normal name
+"Artist - Title.ext" and set ID3/MP4 tags from the database.
+
+Tags are written via mutagen (gracefully — if the package isn't installed, just a copy).
+"""
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+_BAD = re.compile(r'[/\\:*?"<>|\x00-\x1f]')
+
+
+def safe_name(name: str) -> str:
+    return _BAD.sub("_", (name or "").strip()).strip(". ") or "track"
+
+
+def _ext_from_location(location: str) -> str:
+    suf = Path(location).suffix
+    return suf if suf else ".mp3"
+
+
+def _write_tags(path: Path, track: dict) -> bool:
+    try:
+        import mutagen
+        from mutagen.easyid3 import EasyID3
+        from mutagen.easymp4 import EasyMP4
+    except Exception:
+        return False
+
+    ext = path.suffix.lower()
+    try:
+        if ext == ".mp3":
+            try:
+                audio = EasyID3(path)
+            except mutagen.id3.ID3NoHeaderError:  # type: ignore[attr-defined]
+                audio = mutagen.File(path, easy=True)
+                audio.add_tags()
+        elif ext in (".m4a", ".mp4", ".aac", ".alac"):
+            audio = EasyMP4(path)
+        else:
+            return False
+        for key, val in (("title", track.get("title")), ("artist", track.get("artist")),
+                         ("album", track.get("album")), ("genre", track.get("genre"))):
+            if val:
+                audio[key] = str(val)
+        if track.get("track_number"):
+            audio["tracknumber"] = str(track["track_number"])
+        if track.get("year"):
+            audio["date"] = str(track["year"])
+        audio.save()
+        return True
+    except Exception:
+        return False
+
+
+def export_track(music_dir: Path, track: dict, dest_dir: Path, *,
+                 tag: bool = True, layout: str = "flat") -> Path:
+    """Copy a single track from the device into dest_dir.
+
+    music_dir — iPod_Control/Music on the device (ipod.music_dir).
+    layout: "flat" -> "Artist - Title.ext"; "artist_album" -> Artist/Album/…
+    """
+    src = Path(music_dir) / track["location"]
+    ext = _ext_from_location(track["location"])
+    artist = safe_name(track.get("artist") or "Unknown Artist")
+    title = safe_name(track.get("title") or "Untitled")
+
+    if layout == "artist_album":
+        album = safe_name(track.get("album") or "Unknown Album")
+        out_dir = Path(dest_dir) / artist / album
+        base = f"{track.get('track_number') or 0:02d} {title}" if track.get("track_number") else title
+    else:
+        out_dir = Path(dest_dir)
+        base = f"{artist} - {title}"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    dst = out_dir / (safe_name(base) + ext)
+    n = 1
+    while dst.exists():
+        dst = out_dir / (safe_name(base) + f" ({n})" + ext)
+        n += 1
+
+    shutil.copy2(src, dst)
+    if tag:
+        _write_tags(dst, track)
+    return dst

ipodsync/hashab.py

@@ -0,0 +1,44 @@
+"""hashAB — anti-tamper signature for the iPod nano 6G/7G SQLite database.
+
+Pure-Python (no native lib): the algorithm (white-box AES, reverse-engineered
+from dstaley/hashab, public domain) is ported into `_hashab_py`/`_hashab_gen*`.
+Verified against 100/100 test vectors. API preserved: HashAB().sign(sha1, uuid, rnd).
+"""
+from __future__ import annotations
+
+import os
+
+from ._hashab_py import calc_hashab
+
+SHA1_LEN = 20
+UUID_LEN = 8
+RND_LEN = 23
+OUTPUT_LEN = 57  # signature, starts with 03 00
+
+
+class HashABError(RuntimeError):
+    pass
+
+
+class HashAB:
+    """Pure-Python hashAB. lib_path is ignored (kept for compatibility)."""
+
+    def __init__(self, lib_path: str | os.PathLike | None = None):
+        pass
+
+    def sign(self, sha1: bytes, uuid: bytes, rnd_bytes: bytes | None = None) -> bytes:
+        """Return the 57-byte hashAB signature.
+
+        sha1  — 20 bytes (SHA1 of the hash-protected region).
+        uuid  — 8 bytes, the device's FirewireGuid.
+        rnd_bytes — 23 random bytes (embedded in the signature); defaults to os.urandom.
+        """
+        if len(sha1) != SHA1_LEN:
+            raise HashABError(f"sha1 must be {SHA1_LEN} bytes, not {len(sha1)}")
+        if len(uuid) != UUID_LEN:
+            raise HashABError(f"uuid must be {UUID_LEN} bytes, not {len(uuid)}")
+        if rnd_bytes is None:
+            rnd_bytes = os.urandom(RND_LEN)
+        if len(rnd_bytes) != RND_LEN:
+            raise HashABError(f"rnd_bytes must be {RND_LEN} bytes, not {len(rnd_bytes)}")
+        return calc_hashab(sha1, uuid, rnd_bytes)

ipodsync/importer.py

@@ -0,0 +1,137 @@
+"""Upload an audio file TO the iPod: copy into Fxx/ + metadata + add_track.
+
+MP3 is supported for now (the format codes are known from the reference). AAC/ALAC
+(m4a) is the next step (needs audio_format/extension codes; FLAC — via ffmpeg to ALAC).
+
+Metadata is read via mutagen (required for this operation).
+"""
+from __future__ import annotations
+
+import random
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .library import ItlpLibrary, TrackMeta
+
+MAC_EPOCH = 978307200
+MP3_EXT_4CC = 1297101600      # 0x4d503320 ('MP3 ')
+MP3_AUDIO_FORMAT = 301
+NUM_MUSIC_FOLDERS = 50        # F00..F49
+
+
+def _mac_now() -> int:
+    return int(datetime.now(timezone.utc).timestamp()) - MAC_EPOCH
+
+
+def _pick_target(music_dir: Path, ext: str) -> tuple[str, Path]:
+    """Pick an existing Fxx folder and a free name. Returns (location, abs_path)."""
+    for _ in range(200):
+        fx = f"F{random.randint(0, NUM_MUSIC_FOLDERS - 1):02d}"
+        d = Path(music_dir) / fx
+        if d.is_dir():
+            name = f"idmix{random.randint(100000, 9999999)}{ext}"
+            if not (d / name).exists():
+                return f"{fx}/{name}", d / name
+    raise RuntimeError("could not find a free Fxx folder on the device")
+
+
+def read_mp3_meta(path: Path) -> dict:
+    """Extract duration/bitrate/sample rate and tags from an MP3 via mutagen."""
+    from mutagen.mp3 import MP3
+    from mutagen.easyid3 import EasyID3
+
+    mp3 = MP3(path)
+    info = mp3.info
+    tags = {}
+    try:
+        tags = EasyID3(path)
+    except Exception:
+        pass
+
+    def g(k):
+        v = tags.get(k)
+        return v[0] if v else ""
+
+    tn = g("tracknumber")
+    try:
+        tn = int(str(tn).split("/")[0]) if tn else 0
+    except ValueError:
+        tn = 0
+    yr = g("date")
+    try:
+        yr = int(str(yr)[:4]) if yr else 0
+    except ValueError:
+        yr = 0
+    return {
+        "title": g("title"), "artist": g("artist"), "album": g("album"),
+        "genre": g("genre"), "track_number": tn, "year": yr,
+        "total_time_ms": int(info.length * 1000),
+        "bit_rate": int(getattr(info, "bitrate", 0) // 1000),
+        "sample_rate": int(getattr(info, "sample_rate", 44100)),
+    }
+
+
+def copy_audio_to_ipod(ipod, src: str | Path, ext: str = ".mp3") -> tuple[str, Path]:
+    """Copy an audio file into Fxx/ on the device. Returns (location, abs_path)."""
+    location, abs_path = _pick_target(ipod.music_dir, ext)
+    shutil.copy2(Path(src), abs_path)
+    return location, abs_path
+
+
+def add_mp3_to_library(itlp_dir: str | Path, location: str, meta_src: str | Path,
+                       file_size: int, guid: bytes, *, overrides: dict | None = None,
+                       artwork_dir: str | Path | None = None) -> int:
+    """Add an already-copied MP3 to the .itlp library (itlp_dir) + resign.
+
+    itlp_dir — directory with the .itdb files (a working copy is fine). meta_src —
+    the source file to read tags from. If artwork_dir is given (iPod_Control/Artwork
+    on the device) and the file has embedded cover art, it is automatically linked to
+    the track (frames appended to .ithmb, mhii to ArtworkDB, fields in item). Returns the pid.
+    """
+    meta = read_mp3_meta(Path(meta_src))
+    if overrides:
+        meta.update({k: v for k, v in overrides.items() if v is not None})
+    if not meta.get("title"):
+        meta["title"] = Path(meta_src).stem
+
+    tm = TrackMeta(
+        location=location, title=meta["title"], artist=meta.get("artist", ""),
+        album=meta.get("album", ""), genre=meta.get("genre", ""),
+        total_time_ms=meta["total_time_ms"], track_number=meta.get("track_number", 0),
+        year=meta.get("year", 0), bit_rate=meta.get("bit_rate", 0),
+        sample_rate=meta.get("sample_rate", 44100), audio_format=MP3_AUDIO_FORMAT,
+        file_size=file_size, extension=MP3_EXT_4CC, kind="MPEG audio file",
+    )
+    lib = ItlpLibrary(itlp_dir)
+    try:
+        pid = lib.add_track(tm, date=_mac_now())
+        if artwork_dir is not None:
+            attach_cover_for_track(lib, pid, meta_src, artwork_dir)
+        lib.resign(guid)
+    finally:
+        lib.close()
+    return pid
+
+
+def attach_cover_for_track(lib: ItlpLibrary, pid: int, audio_src: str | Path,
+                           artwork_dir: str | Path) -> int | None:
+    """Extract the embedded cover art from audio_src and link it to track pid.
+
+    Appends thumbnails to .ithmb + an mhii to ArtworkDB (incrementally) and
+    sets item.artwork_status/artwork_cache_id in lib. Returns image_id
+    (for item.artwork_cache_id) or None if there's no cover / it's already linked.
+    """
+    from .artwork_writer import U64, attach_cover, extract_embedded_cover
+
+    cover = extract_embedded_cover(audio_src)
+    if not cover:
+        return None
+    image_id = attach_cover(artwork_dir, pid % U64, cover)
+    if image_id is not None:
+        lib.set_track_artwork(pid, image_id)
+        # album cover art (the "Albums" view/lists) — points to this track, like iTunes
+        album_pid = lib.album_pid_of(pid)
+        if album_pid:
+            lib.set_album_artwork(album_pid, pid)
+    return image_id

ipodsync/library.py

@@ -0,0 +1,360 @@
+"""Editing the nano 7G SQLite library (iTunes Library.itlp) via native sqlite3.
+
+The device's real database (not iTunesCDB). Adding a track = INSERT rows into
+all the needed tables (we clone an existing track as a template so we don't have
+to list dozens of columns) + regeneration of Locations.itdb.cbk.
+
+Only Locations.itdb is hash-protected (via .cbk) — the other .itdb are plain SQLite.
+
+STATUS: first version. Sort fields (*_order) are set approximately
+(appended at the end); the device usually recomputes them. Test on the
+device iteratively (with an .itlp backup).
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+from .cbk import build_cbk
+from .hashab import HashAB
+
+# Template rows for adding to an EMPTY library (fallback, when a table is
+# empty — a freshly wiped database). See scripts/gen_lib_templates.py.
+try:
+    from . import _lib_templates as _tpl
+    _EMPTY_TEMPLATES = {
+        "item": _tpl.ITEM_TEMPLATE, "artist": _tpl.ARTIST_TEMPLATE,
+        "album": _tpl.ALBUM_TEMPLATE, "track_artist": _tpl.TRACK_ARTIST_TEMPLATE,
+        "location": _tpl.LOCATION_TEMPLATE,
+    }
+except ImportError:                      # generated by scripts/gen_lib_templates.py
+    _EMPTY_TEMPLATES = {}
+
+
+def _rand_pid() -> int:
+    """Random signed 64-bit pid (as in the database)."""
+    v = int.from_bytes(os.urandom(8), "little", signed=True)
+    return v
+
+
+def _row_or_template(db, sql: str, table: str, args=()) -> dict | None:
+    """A row from the DB, or if the table is empty — a fresh COPY of the built-in template."""
+    got = _row(db, sql, args)
+    if got is not None:
+        return got
+    tmpl = _EMPTY_TEMPLATES.get(table)
+    return dict(tmpl) if tmpl is not None else None
+
+
+def _row(db, sql: str, args=()) -> dict | None:
+    """db — a Connection or Cursor (both have .execute returning a cursor)."""
+    cur = db.execute(sql, args)
+    r = cur.fetchone()
+    return dict(r) if r is not None else None
+
+
+def _insert(db, table: str, row: dict) -> None:
+    cols = ",".join(f'"{k}"' for k in row)
+    ph = ",".join("?" for _ in row)
+    db.execute(f'INSERT INTO "{table}" ({cols}) VALUES ({ph})', list(row.values()))
+
+
+def _max_order(db, table: str, col: str) -> int:
+    cur = db.execute(f'SELECT COALESCE(MAX("{col}"),0) FROM "{table}"')
+    return cur.fetchone()[0] or 0
+
+
+@dataclass
+class TrackMeta:
+    location: str            # "Fxx/NAME.ext" relative to iPod_Control/Music
+    title: str
+    artist: str
+    album: str
+    genre: str = ""
+    total_time_ms: int = 0
+    track_number: int = 0
+    year: int = 0
+    bit_rate: int = 0
+    sample_rate: int = 44100
+    audio_format: int = 301          # 301 = MP3 (from avformat_info)
+    file_size: int = 0
+    extension: int = 1297101600      # 0x4d503320 (4CC 'MP3 ')
+    kind: str = "MPEG audio file"
+
+
+class ItlpLibrary:
+    """Opens the set of .itdb files in the iTunes Library.itlp directory."""
+
+    DBS = ("Library.itdb", "Locations.itdb", "Dynamic.itdb", "Extras.itdb")
+
+    def __init__(self, itlp_dir: str | os.PathLike):
+        self.dir = Path(itlp_dir)
+        self.cx: dict[str, sqlite3.Connection] = {}
+        for name in self.DBS:
+            c = sqlite3.connect(self.dir / name)
+            c.row_factory = sqlite3.Row
+            self.cx[name] = c
+
+    def close(self):
+        for c in self.cx.values():
+            c.close()
+
+    def _get_or_create_lookup(self, cur, table, name, name_order) -> int:
+        """Find a row by name, or clone a template one with a new pid/name."""
+        got = _row(cur, f'SELECT * FROM "{table}" WHERE name=?', (name,))
+        if got:
+            return got["pid"]
+        tmpl = _row_or_template(cur, f'SELECT * FROM "{table}" LIMIT 1', table)
+        pid = _rand_pid()
+        tmpl.update(pid=pid, name=name, sort_name=name, name_order=name_order)
+        _insert(cur, table, tmpl)
+        return pid
+
+    def add_track(self, m: TrackMeta, *, date: int) -> int:
+        """Add a track to all tables. Returns the pid of the new item."""
+        lib = self.cx["Library.itdb"].cursor()
+        loc = self.cx["Locations.itdb"].cursor()
+        dyn = self.cx["Dynamic.itdb"].cursor()
+        ext = self.cx["Extras.itdb"].cursor()
+
+        tmpl_item = _row_or_template(lib, "SELECT * FROM item LIMIT 1", "item")
+        if tmpl_item is None:
+            raise ValueError(
+                "no template track in item and no built-in template "
+                "(run scripts/gen_lib_templates.py)")
+        item_pid = _rand_pid()
+
+        # genre/artist/album/track_artist lookups
+        genre_id = None
+        if m.genre:
+            g = _row(lib, "SELECT id FROM genre_map WHERE genre=?", (m.genre,))
+            if g:
+                genre_id = g["id"]
+            else:
+                genre_id = _max_order(lib, "genre_map", "id") + 1
+                _insert(lib, "genre_map", {"id": genre_id, "genre": m.genre, "has_music": 1,
+                                           "artist_count_calc": 1, "album_count_calc": 1,
+                                           "album_artist_count_calc": 1})
+        nord = _max_order(lib, "artist", "name_order") + 100
+        artist_pid = self._get_or_create_lookup(lib, "artist", m.artist, nord)
+        aord = _max_order(lib, "album", "name_order") + 100
+        album_pid = self._get_or_create_lookup(lib, "album", m.album, aord)
+        # track_artist (small sequential pids)
+        ta = _row(lib, "SELECT pid FROM track_artist WHERE name=?", (m.artist,))
+        track_artist_pid = ta["pid"] if ta else (_max_order(lib, "track_artist", "pid") + 1)
+        if not ta:
+            tmpl_ta = _row_or_template(lib, "SELECT * FROM track_artist LIMIT 1", "track_artist")
+            tmpl_ta.update(pid=track_artist_pid, name=m.artist, sort_name=m.artist, name_order=nord)
+            _insert(lib, "track_artist", tmpl_ta)
+
+        # item (clone template + patch)
+        end = _max_order(lib, "item", "title_order") + 100
+        tmpl_item.update(
+            pid=item_pid, title=m.title, artist=m.artist, album=m.album,
+            sort_title=m.title, sort_artist=m.artist, sort_album=m.album,
+            year=m.year, total_time_ms=m.total_time_ms, track_number=m.track_number,
+            genre_id=genre_id, album_pid=album_pid, artist_pid=artist_pid,
+            track_artist_pid=track_artist_pid, date_modified=date,
+            title_order=end, album_order=end, artist_order=nord,
+            album_artist_order=nord, album_by_artist_order=nord,
+        )
+        _insert(lib, "item", tmpl_item)
+
+        # avformat_info
+        _insert(lib, "avformat_info", {"item_pid": item_pid, "audio_format": m.audio_format,
+                                       "bit_rate": m.bit_rate, "sample_rate": m.sample_rate})
+        # into the master playlist
+        master = _row(lib, "SELECT primary_container_pid AS p FROM db_info")["p"]
+        phys = _max_order(lib, "item_to_container", "physical_order") + 1
+        _insert(lib, "item_to_container",
+                {"item_pid": item_pid, "container_pid": master, "physical_order": phys})
+        # track_size_calc.audio += file_size
+        lib.execute("UPDATE track_size_calc SET size=COALESCE(size,0)+? WHERE kind='audio'",
+                    (m.file_size,))
+
+        # location
+        tmpl_loc = _row_or_template(loc, "SELECT * FROM location LIMIT 1", "location")
+        tmpl_loc.update(item_pid=item_pid, location=m.location, file_size=m.file_size,
+                        extension=m.extension, date_created=date)
+        _insert(loc, "location", tmpl_loc)
+
+        # item_stats (Dynamic), chapter (Extras) — clone the template onto the new item_pid
+        for cur, table in ((dyn, "item_stats"), (ext, "chapter")):
+            t = _row(cur, f"SELECT * FROM {table} LIMIT 1")
+            if t:
+                t["item_pid"] = item_pid
+                _insert(cur, table, t)
+
+        for c in self.cx.values():
+            c.commit()
+        return item_pid
+
+    # --- READ -----------------------------------------------------------------
+    def list_tracks(self) -> list[dict]:
+        """All library tracks with path and metadata (for listing/export)."""
+        lib = self.cx["Library.itdb"]
+        loc = {r["item_pid"]: r for r in
+               self.cx["Locations.itdb"].execute(
+                   "SELECT item_pid,location,file_size,extension FROM location")}
+        genres = {r["id"]: r["genre"] for r in lib.execute("SELECT id,genre FROM genre_map")}
+        out = []
+        for it in lib.execute(
+                "SELECT pid,title,artist,album,genre_id,year,track_number,total_time_ms "
+                "FROM item ORDER BY artist,album,track_number"):
+            lr = loc.get(it["pid"])
+            out.append({
+                "pid": it["pid"], "title": it["title"], "artist": it["artist"],
+                "album": it["album"], "genre": genres.get(it["genre_id"], ""),
+                "year": it["year"], "track_number": it["track_number"],
+                "duration_ms": int(it["total_time_ms"] or 0),
+                "location": lr["location"] if lr else None,
+                "file_size": lr["file_size"] if lr else 0,
+                "extension": lr["extension"] if lr else 0,
+            })
+        return out
+
+    # --- UPDATE ---------------------------------------------------------------
+    def update_track(self, pid: int, **fields) -> None:
+        """Update a track's tags. Allowed keys: title/artist/album/year/track_number."""
+        allowed = {"title", "artist", "album", "year", "track_number"}
+        upd = {k: v for k, v in fields.items() if k in allowed}
+        if not upd:
+            return
+        sets = ",".join(f'"{k}"=?' for k in upd)
+        self.cx["Library.itdb"].execute(
+            f"UPDATE item SET {sets} WHERE pid=?", [*upd.values(), pid])
+        self.cx["Library.itdb"].commit()
+
+    # --- DELETE ---------------------------------------------------------------
+    def remove_track(self, pid: int, *, music_dir: Path | None = None) -> str | None:
+        """Remove a track from all tables. If music_dir is given — also delete the file.
+
+        Returns the location of the deleted file (or None). After removal, don't
+        forget resign(). We leave orphaned album/artist/genre (iTunes is fine with it).
+        """
+        lib = self.cx["Library.itdb"]
+        r = self.cx["Locations.itdb"].execute(
+            "SELECT location,file_size FROM location WHERE item_pid=?", (pid,)).fetchone()
+        location = r["location"] if r else None
+        fsize = (r["file_size"] if r else 0) or 0
+
+        lib.execute("DELETE FROM item WHERE pid=?", (pid,))
+        lib.execute("DELETE FROM avformat_info WHERE item_pid=?", (pid,))
+        lib.execute("DELETE FROM item_to_container WHERE item_pid=?", (pid,))
+        lib.execute("UPDATE track_size_calc SET size=MAX(0,COALESCE(size,0)-?) WHERE kind='audio'",
+                    (fsize,))
+        self.cx["Locations.itdb"].execute("DELETE FROM location WHERE item_pid=?", (pid,))
+        self.cx["Dynamic.itdb"].execute("DELETE FROM item_stats WHERE item_pid=?", (pid,))
+        self.cx["Extras.itdb"].execute("DELETE FROM chapter WHERE item_pid=?", (pid,))
+        for c in self.cx.values():
+            c.commit()
+
+        if music_dir is not None and location:
+            f = Path(music_dir) / location
+            if f.exists():
+                f.unlink()
+        return location
+
+    # --- PLAYLISTS -------------------------------------------------------------
+    # container (Library.itdb) = playlist; item_to_container = membership;
+    # container_ui (Dynamic.itdb) = UI settings. Locations.itdb is NOT touched,
+    # so resign() is NOT needed for playlist operations.
+
+    def master_pid(self) -> int:
+        return self.cx["Library.itdb"].execute(
+            "SELECT primary_container_pid AS p FROM db_info").fetchone()["p"]
+
+    def list_playlists(self) -> list[dict]:
+        lib = self.cx["Library.itdb"]
+        master = self.master_pid()
+        out = []
+        for c in lib.execute("SELECT pid,name,is_hidden FROM container ORDER BY name_order"):
+            cnt = lib.execute("SELECT COUNT(*) FROM item_to_container WHERE container_pid=?",
+                              (c["pid"],)).fetchone()[0]
+            out.append({"pid": c["pid"], "name": c["name"], "count": cnt,
+                        "is_master": c["pid"] == master, "hidden": bool(c["is_hidden"])})
+        return out
+
+    def create_playlist(self, name: str, *, date: int) -> int:
+        """Create a user playlist. Returns the pid."""
+        lib = self.cx["Library.itdb"]
+        dyn = self.cx["Dynamic.itdb"]
+        master = self.master_pid()
+        tmpl = (_row(lib, "SELECT * FROM container WHERE pid<>? LIMIT 1", (master,))
+                or _row(lib, "SELECT * FROM container LIMIT 1"))
+        pid = _rand_pid()
+        tmpl.update(pid=pid, name=name, name_order=_max_order(lib, "container", "name_order") + 1,
+                    distinguished_kind=0, parent_pid=0, is_hidden=0,
+                    date_created=date, date_modified=date)
+        _insert(lib, "container", tmpl)
+        tui = _row(dyn, "SELECT * FROM container_ui LIMIT 1")
+        if tui:
+            tui["container_pid"] = pid
+            _insert(dyn, "container_ui", tui)
+        for c in self.cx.values():
+            c.commit()
+        return pid
+
+    def add_to_playlist(self, container_pid: int, item_pid: int) -> None:
+        lib = self.cx["Library.itdb"]
+        nxt = lib.execute(
+            "SELECT COALESCE(MAX(physical_order),-1)+1 FROM item_to_container WHERE container_pid=?",
+            (container_pid,)).fetchone()[0]
+        _insert(lib, "item_to_container",
+                {"item_pid": item_pid, "container_pid": container_pid, "physical_order": nxt})
+        lib.commit()
+
+    def remove_from_playlist(self, container_pid: int, item_pid: int) -> None:
+        self.cx["Library.itdb"].execute(
+            "DELETE FROM item_to_container WHERE container_pid=? AND item_pid=?",
+            (container_pid, item_pid))
+        self.cx["Library.itdb"].commit()
+
+    def delete_playlist(self, pid: int) -> None:
+        if pid == self.master_pid():
+            raise ValueError("cannot delete the master playlist")
+        self.cx["Library.itdb"].execute("DELETE FROM container WHERE pid=?", (pid,))
+        self.cx["Library.itdb"].execute("DELETE FROM item_to_container WHERE container_pid=?", (pid,))
+        self.cx["Dynamic.itdb"].execute("DELETE FROM container_ui WHERE container_pid=?", (pid,))
+        for c in self.cx.values():
+            c.commit()
+
+    # --- COVERS (artwork fields; the ArtworkDB/.ithmb files are rendered by libgpod) ---
+    def clear_artwork(self) -> None:
+        """Reset artwork statuses (before a full cover rebuild)."""
+        self.cx["Library.itdb"].execute("UPDATE item SET artwork_status=0, artwork_cache_id=0")
+        self.cx["Library.itdb"].execute("UPDATE album SET artwork_status=0, artwork_item_pid=NULL")
+        self.cx["Library.itdb"].commit()
+
+    def set_track_artwork(self, pid: int, cache_id: int, status: int = 1) -> None:
+        self.cx["Library.itdb"].execute(
+            "UPDATE item SET artwork_status=?, artwork_cache_id=? WHERE pid=?",
+            (status, cache_id, pid))
+        self.cx["Library.itdb"].commit()
+
+    def set_album_artwork(self, album_pid: int, item_pid: int, status: int = 0) -> None:
+        """Attach the album cover to a representative track (as iTunes does).
+
+        iTunes keeps album.artwork_status=0 but fills in artwork_item_pid — via
+        it, the Albums view/lists pull the cover through item.artwork_cache_id.
+        """
+        self.cx["Library.itdb"].execute(
+            "UPDATE album SET artwork_status=?, artwork_item_pid=? WHERE pid=?",
+            (status, item_pid, album_pid))
+        self.cx["Library.itdb"].commit()
+
+    def album_pid_of(self, item_pid: int) -> int | None:
+        r = self.cx["Library.itdb"].execute(
+            "SELECT album_pid FROM item WHERE pid=?", (item_pid,)).fetchone()
+        return r["album_pid"] if r else None
+
+    # --- signing --------------------------------------------------------------
+    def resign(self, firewire_guid: bytes, hasher: HashAB | None = None) -> None:
+        """Regenerate Locations.itdb.cbk after edits."""
+        self.cx["Locations.itdb"].commit()
+        loc_bytes = (self.dir / "Locations.itdb").read_bytes()
+        cbk = build_cbk(loc_bytes, firewire_guid, hasher=hasher)
+        (self.dir / "Locations.itdb.cbk").write_bytes(cbk)

ipodsync/models.py

@@ -0,0 +1,31 @@
+"""Data models for uploading."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Track:
+    """A single track to upload.
+
+    path      — source audio file (mp3/aac/alac/flac; flac will be transcoded).
+    After copying to the device, the uploader fills in ipod_path/dbid.
+    """
+    path: Path
+    title: str = ""
+    artist: str = ""
+    album: str = ""
+    genre: str = ""
+    track_number: int = 0
+    total_tracks: int = 0
+    duration_ms: int = 0
+    filesize: int = 0
+    # filled in during upload:
+    ipod_path: str = ""   # path like ":iPod_Control:Music:F00:XXXX.m4a"
+    dbid: int = 0         # 64-bit unique track id in the database
+
+    def __post_init__(self):
+        self.path = Path(self.path)
+        if not self.title:
+            self.title = self.path.stem