ipodsync 0.1.3__tar.gz → 0.1.5__tar.gz

{ipodsync-0.1.3 → ipodsync-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipodsync
-Version: 0.1.3
+Version: 0.1.5
 Summary: Upload music to an iPod nano 6G/7G without iTunes: SQLite library, hashAB signing, cover art (pure-Python).
 Project-URL: Homepage, https://github.com/buldiei/ipodsync
 Project-URL: Repository, https://github.com/buldiei/ipodsync
@@ -98,8 +98,12 @@ ipodsync add "Song.mp3" --no-cover
 ipodsync export ~/Music/ipod --by-album
 ipodsync cover 123456789 --image cover.jpg
 ipodsync rm 123456789 --delete-file
+ipodsync -b add "Song.mp3"          # -b: back up the library first (off by default)
 ```
 
+Writes don't back up the library by default — pass `-b` / `--backup` to snapshot
+`iTunes Library.itlp` to `~/ipod-backups` before editing.
+
 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`.
@@ -116,8 +120,8 @@ Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
 lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT      # e.g.  sda2  14.7G  hfsplus
 ```
 
-For read commands (`list` / `export`), the quickest way is `--mount`, which mounts
-the iPod for you via `udisksctl` (no root) and runs the command:
+For read commands (`list` / `export`), the quickest way is `--mount`: it detects the
+device, mounts it read-only (asks for `sudo`), runs the command, then unmounts:
 
 ```bash
 ipodsync --mount list
@@ -133,11 +137,20 @@ IPODSYNC_MOUNT=/mnt/ipod ipodsync list
 sudo umount /mnt/ipod                     # before unplugging
 ```
 
-**Writing (`add` / `rm` / `cover`) on Linux** needs a read-write mount owned by
-your user (so it can write files), and the GUID (below). Mount it like this:
+**Writing (`add` / `rm` / `cover`) on Linux.** `--mount` handles it in one command —
+it detects the device, mounts HFS+ read-write owned by your user (asks for `sudo`),
+runs the command, then unmounts:
+
+```bash
+ipodsync --mount add song.mp3
+ipodsync --mount -b add song.mp3    # -b: snapshot the library to ~/ipod-backups first
+```
+
+Or mount it yourself and point `IPODSYNC_MOUNT` at it:
 
 ```bash
 sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
+IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
 ```
 
 Two catches:

{ipodsync-0.1.3 → ipodsync-0.1.5}/README.md

@@ -66,8 +66,12 @@ ipodsync add "Song.mp3" --no-cover
 ipodsync export ~/Music/ipod --by-album
 ipodsync cover 123456789 --image cover.jpg
 ipodsync rm 123456789 --delete-file
+ipodsync -b add "Song.mp3"          # -b: back up the library first (off by default)
 ```
 
+Writes don't back up the library by default — pass `-b` / `--backup` to snapshot
+`iTunes Library.itlp` to `~/ipod-backups` before editing.
+
 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`.
@@ -84,8 +88,8 @@ Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
 lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT      # e.g.  sda2  14.7G  hfsplus
 ```
 
-For read commands (`list` / `export`), the quickest way is `--mount`, which mounts
-the iPod for you via `udisksctl` (no root) and runs the command:
+For read commands (`list` / `export`), the quickest way is `--mount`: it detects the
+device, mounts it read-only (asks for `sudo`), runs the command, then unmounts:
 
 ```bash
 ipodsync --mount list
@@ -101,11 +105,20 @@ IPODSYNC_MOUNT=/mnt/ipod ipodsync list
 sudo umount /mnt/ipod                     # before unplugging
 ```
 
-**Writing (`add` / `rm` / `cover`) on Linux** needs a read-write mount owned by
-your user (so it can write files), and the GUID (below). Mount it like this:
+**Writing (`add` / `rm` / `cover`) on Linux.** `--mount` handles it in one command —
+it detects the device, mounts HFS+ read-write owned by your user (asks for `sudo`),
+runs the command, then unmounts:
+
+```bash
+ipodsync --mount add song.mp3
+ipodsync --mount -b add song.mp3    # -b: snapshot the library to ~/ipod-backups first
+```
+
+Or mount it yourself and point `IPODSYNC_MOUNT` at it:
 
 ```bash
 sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
+IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
 ```
 
 Two catches:

{ipodsync-0.1.3 → ipodsync-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipodsync"
-version = "0.1.3"
+version = "0.1.5"
 description = "Upload music to an iPod nano 6G/7G without iTunes: SQLite library, hashAB signing, cover art (pure-Python)."
 readme = "README.md"
 requires-python = ">=3.9"

{ipodsync-0.1.3 → ipodsync-0.1.5}/src/ipodsync/__init__.py

@@ -13,7 +13,7 @@ from .library import ItlpLibrary
 from .models import Track
 from .transport import IPod, IPodNotFound, find_ipod
 
-__version__ = "0.1.3"
+__version__ = "0.1.5"
 
 __all__ = [
     "find_ipod",

{ipodsync-0.1.3 → ipodsync-0.1.5}/src/ipodsync/artwork_writer.py

@@ -58,20 +58,30 @@ 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."""
+    """Resize the cover to width×height, pack into RGB565-LE.
+
+    Each row is padded to the device's row stride (`slot // height`), matching
+    iTunes: e.g. F1016 is 57×57 pixels but stored with a 116-byte (58 px) stride —
+    2 zero bytes at the end of every row. Getting this wrong shears the thumbnail.
+    """
     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:
+    stride = slot // height          # bytes per row the device reads
+    out = bytearray()
+    for y in range(height):
+        row = bytearray(stride)      # zero-padded to the stride
+        base, j = y * width * 3, 0
+        for _ in range(width):
+            v = ((rgb[base] >> 3) << 11) | ((rgb[base + 1] >> 2) << 5) | (rgb[base + 2] >> 3)
+            row[j] = v & 0xFF
+            row[j + 1] = v >> 8
+            base += 3
+            j += 2
+        out += row
+    if len(out) < slot:              # safety (slot == height*stride already)
         out.extend(b"\x00" * (slot - len(out)))
     return bytes(out)
 

{ipodsync-0.1.3 → ipodsync-0.1.5}/src/ipodsync/cli.py

@@ -7,9 +7,9 @@
     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).
-Browsing the iPod in Finder/Music is fine; just don't let Apple's software auto-sync it,
-or a sync will drop manually-added tracks.
+Export is read-only. add/rm/cover write to the database; pass -b to back the library
+up to ~/ipod-backups first. Browsing the iPod in Finder/Music is fine; just don't let
+Apple's software auto-sync it, or a sync will drop manually-added tracks.
 """
 from __future__ import annotations
 
@@ -73,10 +73,7 @@ def cmd_export(ipod, args):
 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}")
+    backup = _backup_library(itlp, stamp) if args.backup else None
 
     guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo, mount=ipod.root)
     lib = ItlpLibrary(itlp)
@@ -84,21 +81,20 @@ def cmd_rm(ipod, args):
     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}'")
+    print(f"✓ Removed track pid {args.pid}"
+          f"{' (+ deleted the file)' if args.delete_file else ''}. Eject the iPod.")
+    if backup:
+        print(f"  Undo: 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.
+def _edit_library(ipod, fn, *, label: str, backup: bool = False):
+    """Edit a /tmp 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)
+    bak = _backup_library(itlp, stamp) if backup else None
     work = Path("/tmp") / f"itlp_{label}_{stamp}"
     shutil.copytree(itlp, work)
 
@@ -109,7 +105,7 @@ def _edit_library(ipod, fn, *, label: str):
         lib.close()
     for name in ("Library.itdb", "Dynamic.itdb"):
         shutil.copy2(work / name, itlp / name)
-    print(f".itlp backup: {backup}. Eject iPod.")
+    print("✓ Done — eject the iPod." + (f"  (backup: {bak.name})" if bak else ""))
     return result
 
 
@@ -123,24 +119,24 @@ def cmd_playlists(ipod, args):
 
 def cmd_pl_create(ipod, args):
     pid = _edit_library(ipod, lambda lib: lib.create_playlist(args.name, date=_mac_now()),
-                        label="plcreate")
+                        label="plcreate", backup=args.backup)
     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")
+                  label="pladd", backup=args.backup)
     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")
+                  label="plrm", backup=args.backup)
     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")
+    _edit_library(ipod, lambda lib: lib.delete_playlist(args.playlist), label="pldel", backup=args.backup)
     print(f"Playlist {args.playlist} deleted")
 
 
@@ -177,30 +173,37 @@ 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}")
+    backup = _backup_library(itlp, stamp) if args.backup else None
 
     guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo, mount=ipod.root)
+    print("→ copying the track onto the iPod…")
     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:
+    if art_dir is not None and args.backup:
         _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}'")
+    cover = "" if args.no_cover else " (+ cover art)"
+    print(f"✓ Added \"{Path(args.file).name}\"{cover}  ·  pid {pid}")
+    print("  Eject the iPod, then check Songs.")
+    if backup:
+        print(f"  Undo: rm -rf '{itlp}' && cp -r '{backup}' '{itlp}'")
+
+
+def _backup_library(itlp: Path, stamp: str) -> Path:
+    """Copy the whole .itlp to ~/ipod-backups (only when -b/--backup is given)."""
+    dst = Path.home() / "ipod-backups" / f"itlp-{stamp}"
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(itlp, dst)
+    print(f"→ backed up the library ({dst.name})")
+    return dst
 
 
 def _backup_artwork(ipod, stamp: str) -> None:
@@ -208,8 +211,7 @@ def _backup_artwork(ipod, stamp: str) -> None:
     art = ipod.control / "Artwork"
     if art.exists():
         dst = Path.home() / "ipod-backups" / f"Artwork-{stamp}"
-        shutil.copytree(art, dst)
-        print(f"Artwork backup: {dst}")
+        shutil.copytree(art, dst)  # backed up alongside the library
 
 
 def cmd_cover(ipod, args):
@@ -220,7 +222,8 @@ def cmd_cover(ipod, args):
 
     itlp = ipod.itunes_dir / "iTunes Library.itlp"
     stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
-    _backup_artwork(ipod, stamp)
+    if args.backup:
+        _backup_artwork(ipod, stamp)
 
     if args.image:
         cover = Path(args.image).read_bytes()
@@ -252,8 +255,7 @@ def cmd_cover(ipod, args):
     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.")
+    print(f"✓ Cover attached to pid {args.pid}. Eject the iPod and check the album art.")
 
 
 def main() -> int:
@@ -266,7 +268,10 @@ def main() -> int:
                "add/rm/cover back up the library before editing. Run "
                "`ipodsync <command> -h` for per-command help.")
     ap.add_argument("--mount", action="store_true",
-                    help="Linux: mount the iPod first via udisksctl (read-only)")
+                    help="Linux: auto-mount the iPod (sudo) before the command, unmount after")
+    ap.add_argument("-b", "--backup", action="store_true",
+                    help="back up the library to ~/ipod-backups before editing "
+                         "(off by default)")
     sub = ap.add_subparsers(dest="cmd", required=True, metavar="<command>")
 
     sub.add_parser("list", help="show tracks on the iPod")
@@ -312,22 +317,33 @@ def main() -> int:
 
     args = ap.parse_args()
 
+    WRITE_CMDS = {"add", "rm", "cover", "pl-create", "pl-add", "pl-rm", "pl-del"}
+    mounted = None
     if args.mount:
         from ipodsync.transport import mount_ipod
         try:
-            mp = mount_ipod()
+            mp, mounted_by_us = mount_ipod(rw=args.cmd in WRITE_CMDS)
         except IPodNotFound as e:
             print(f"⚠️  {e}")
             return 2
         os.environ["IPODSYNC_MOUNT"] = mp
-        print(f"Mounted iPod at {mp}")
+        print(f"✓ iPod mounted at {mp}")
+        mounted = mp if mounted_by_us else None
+
+    try:
+        return _dispatch(args)
+    finally:
+        if mounted:
+            from ipodsync.transport import umount_ipod
+            umount_ipod(mounted)
+            print(f"✓ iPod unmounted — safe to unplug")
 
-    # commands that don't require a ready iPod
+
+def _dispatch(args) -> int:
     if args.cmd == "status":
         return cmd_status(args)
     if args.cmd == "wait":
         return cmd_wait(args)
-
     try:
         ipod = find_ipod()
     except IPodNotFound as e:

{ipodsync-0.1.3 → ipodsync-0.1.5}/src/ipodsync/transport.py

@@ -208,11 +208,15 @@ def _not_found_message() -> str:
             "or set IPODSYNC_MOUNT=/path/to/mount.")
 
 
-def mount_ipod() -> str:
-    """Mount the iPod via udisksctl (Linux, no root). Returns the mountpoint.
+MOUNTPOINT = "/mnt/ipodsync"
 
-    This is read-only for a journaled HFS+ volume — enough for list/export; for
-    add/rm mount read-write with uid= yourself (see the README).
+
+def mount_ipod(rw: bool = False) -> tuple[str, bool]:
+    """Mount the iPod on Linux via `sudo mount` (asks for a password if needed).
+
+    Auto-detects the current device node (which changes across re-plugs), mounts
+    HFS+ read-only (or force,rw,uid= for writes) at MOUNTPOINT. Returns
+    (mountpoint, mounted_by_us) — if it was already mounted, mounted_by_us is False.
     """
     if sys.platform == "darwin":
         raise IPodNotFound("On macOS the iPod is mounted automatically by Finder.")
@@ -220,12 +224,18 @@ def mount_ipod() -> str:
     if not dev or not dev.get("path"):
         raise IPodNotFound("No iPod block device found — is it connected?")
     if dev.get("mountpoint"):
-        return dev["mountpoint"]
-    out, err = _run(["udisksctl", "mount", "-b", dev["path"]])
-    m = re.search(r"\bat\s+(\S+)", out)
-    if m:
-        return m.group(1).rstrip(".")
-    raise IPodNotFound(
-        f"Could not mount {dev['path']} via udisksctl"
-        + (f": {err.strip()}" if err.strip() else "")
-        + ". Mount it manually — see the README.")
+        return dev["mountpoint"], False
+    opts = f"force,rw,uid={os.getuid()},gid={os.getgid()},umask=022" if rw else "ro"
+    print(f"Mounting {dev['path']} at {MOUNTPOINT} ({opts})…")
+    subprocess.run(["sudo", "mkdir", "-p", MOUNTPOINT])          # inherit stdio (prompt)
+    r = subprocess.run(["sudo", "mount", "-t", "hfsplus", "-o", opts,
+                        dev["path"], MOUNTPOINT])
+    if r.returncode != 0:
+        raise IPodNotFound(
+            f"Failed to mount {dev['path']} (see the error above). "
+            "See the README \"Linux: mounting the iPod\".")
+    return MOUNTPOINT, True
+
+
+def umount_ipod(mountpoint: str) -> None:
+    subprocess.run(["sudo", "umount", mountpoint])

{ipodsync-0.1.3 → ipodsync-0.1.5}/tests/test_artwork_writer.py

@@ -137,3 +137,17 @@ def test_row_or_template_fallback_on_empty():
     got["title"] = "x"
     assert library._EMPTY_TEMPLATES["item"].get("title") != "x"
     c.close()
+
+
+def test_f1016_row_stride_padding():
+    """F1016 is 57×57 pixels but stored with a 116-byte (58 px) row stride — two
+    zero bytes at the end of every row, like iTunes. Wrong stride shears the thumb."""
+    from PIL import Image
+    import io
+    buf = io.BytesIO()
+    Image.new("RGB", (80, 80), (200, 30, 30)).save(buf, format="PNG")
+    data = aw.to_rgb565(buf.getvalue(), 57, 57, 6612)
+    assert len(data) == 6612
+    stride = 6612 // 57  # 116
+    for y in range(57):
+        assert data[y * stride + 114:y * stride + 116] == b"\x00\x00", f"row {y}"