ipodsync 0.1.4__tar.gz → 0.1.6__tar.gz

{ipodsync-0.1.4 → ipodsync-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipodsync
-Version: 0.1.4
+Version: 0.1.6
 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
@@ -94,51 +94,53 @@ Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 ipodsync status                     # ready / no access / not connected
 ipodsync list
 ipodsync add "Song.mp3"             # + cover auto
+ipodsync add a.mp3 b.mp3 c.mp3      # several at once (one library write)
+ipodsync add -f ~/Music/album       # a whole folder (recursively)
 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`.
 
 ## Linux: mounting the iPod
 
-On macOS, Finder mounts the iPod automatically. A headless Linux box usually
-doesn't — the device shows up as a disk but stays unmounted, so `ipodsync` reports
-"iPod not found". Mount it yourself, then point `IPODSYNC_MOUNT` at it.
+On macOS, Finder mounts the iPod automatically — you never need `--mount`, just run
+`ipodsync add song.mp3`. A headless Linux box usually doesn't mount it: the device
+shows up as a disk but stays unmounted, so `ipodsync` reports "iPod not found".
 
-Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
+The easy way is **mount once, work, unmount once**:
 
 ```bash
-lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT      # e.g.  sda2  14.7G  hfsplus
+ipodsync --mount              # detect + mount the iPod (asks for sudo); stays mounted
+ipodsync add song-1.mp3       # add as many tracks as you like…
+ipodsync add song-2.mp3
+ipodsync add -f ~/Music/album # …or a whole folder at once
+ipodsync list
+ipodsync --unmount            # unmount when done — safe to unplug
 ```
 
-For read commands (`list` / `export`), the quickest way is `--mount`, which mounts
-the iPod for you via `udisksctl` (no root) and runs the command:
-
-```bash
-ipodsync --mount list
-```
+`--mount` leaves the iPod at `/mnt/ipodsync`, which the following commands find on
+their own. Pass `-b` to any write command to snapshot the library first
+(`ipodsync -b add song.mp3`).
 
-Or mount it yourself:
+Or manage the mount yourself and point `IPODSYNC_MOUNT` at it:
 
 ```bash
-sudo modprobe hfsplus
-sudo mkdir -p /mnt/ipod
-sudo mount -t hfsplus -o ro /dev/sda2 /mnt/ipod
-IPODSYNC_MOUNT=/mnt/ipod ipodsync list
+sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
+IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
 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:
-
-```bash
-sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
-```
+Find the iPod's partition with `lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT` (an `hfsplus`
+one, roughly the iPod's size — e.g. `sda2 14.7G hfsplus`).
 
 Two catches:
 

{ipodsync-0.1.4 → ipodsync-0.1.6}/README.md

@@ -62,51 +62,53 @@ Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 ipodsync status                     # ready / no access / not connected
 ipodsync list
 ipodsync add "Song.mp3"             # + cover auto
+ipodsync add a.mp3 b.mp3 c.mp3      # several at once (one library write)
+ipodsync add -f ~/Music/album       # a whole folder (recursively)
 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`.
 
 ## Linux: mounting the iPod
 
-On macOS, Finder mounts the iPod automatically. A headless Linux box usually
-doesn't — the device shows up as a disk but stays unmounted, so `ipodsync` reports
-"iPod not found". Mount it yourself, then point `IPODSYNC_MOUNT` at it.
+On macOS, Finder mounts the iPod automatically — you never need `--mount`, just run
+`ipodsync add song.mp3`. A headless Linux box usually doesn't mount it: the device
+shows up as a disk but stays unmounted, so `ipodsync` reports "iPod not found".
 
-Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
+The easy way is **mount once, work, unmount once**:
 
 ```bash
-lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT      # e.g.  sda2  14.7G  hfsplus
+ipodsync --mount              # detect + mount the iPod (asks for sudo); stays mounted
+ipodsync add song-1.mp3       # add as many tracks as you like…
+ipodsync add song-2.mp3
+ipodsync add -f ~/Music/album # …or a whole folder at once
+ipodsync list
+ipodsync --unmount            # unmount when done — safe to unplug
 ```
 
-For read commands (`list` / `export`), the quickest way is `--mount`, which mounts
-the iPod for you via `udisksctl` (no root) and runs the command:
-
-```bash
-ipodsync --mount list
-```
+`--mount` leaves the iPod at `/mnt/ipodsync`, which the following commands find on
+their own. Pass `-b` to any write command to snapshot the library first
+(`ipodsync -b add song.mp3`).
 
-Or mount it yourself:
+Or manage the mount yourself and point `IPODSYNC_MOUNT` at it:
 
 ```bash
-sudo modprobe hfsplus
-sudo mkdir -p /mnt/ipod
-sudo mount -t hfsplus -o ro /dev/sda2 /mnt/ipod
-IPODSYNC_MOUNT=/mnt/ipod ipodsync list
+sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
+IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
 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:
-
-```bash
-sudo mount -t hfsplus -o rw,uid=$(id -u),gid=$(id -g) /dev/sda2 /mnt/ipod
-```
+Find the iPod's partition with `lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT` (an `hfsplus`
+one, roughly the iPod's size — e.g. `sda2 14.7G hfsplus`).
 
 Two catches:
 

{ipodsync-0.1.4 → ipodsync-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipodsync"
-version = "0.1.4"
+version = "0.1.6"
 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.4 → ipodsync-0.1.6}/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.4"
+__version__ = "0.1.6"
 
 __all__ = [
     "find_ipod",

{ipodsync-0.1.4 → ipodsync-0.1.6}/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")
 
 
@@ -173,34 +169,77 @@ def cmd_wait(args):
     print(f"✅ iPod ready: {ipod.root}")
 
 
+AUDIO_EXTS = {".mp3", ".m4a", ".aac", ".alac", ".mp4"}
+
+
+def _collect_add_files(args) -> list[Path]:
+    """Resolve the files to add from positional paths and/or --folder."""
+    files: list[Path] = [Path(f) for f in (args.file or [])]
+    if args.folder:
+        root = Path(args.folder)
+        if not root.is_dir():
+            raise SystemExit(f"⚠️  --folder: {root} is not a directory")
+        files += sorted(p for p in root.rglob("*")
+                        if p.is_file() and p.suffix.lower() in AUDIO_EXTS)
+    # de-dup, keep order
+    seen, out = set(), []
+    for p in files:
+        rp = p.resolve()
+        if rp not in seen:
+            seen.add(rp)
+            out.append(p)
+    return out
+
+
 def cmd_add(ipod, args):
-    """Upload an MP3 to the iPod: audio -> Fxx/ (onto the device), .itlp -> edit a copy -> back."""
+    """Upload track(s) to the iPod: audio -> Fxx/ (onto the device), .itlp -> edit a copy -> back."""
+    files = _collect_add_files(args)
+    if not files:
+        raise SystemExit("⚠️  add: give a file path, or -f/--folder DIR")
+    if len(files) > 1 and (args.title or args.artist or args.album):
+        raise SystemExit("⚠️  --title/--artist/--album only apply to a single file")
+
     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
+    art_dir = None if args.no_cover else ipod.control / "Artwork"
+    if art_dir is not None and args.backup:
+        _backup_artwork(ipod, stamp)
 
     guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo, mount=ipod.root)
-    location, abs_path = copy_audio_to_ipod(ipod, args.file)
-    print(f"File copied: {location}")
+    overrides = {"title": args.title, "artist": args.artist, "album": args.album}
 
+    # Edit one working copy of the library, add every file, then write it back once.
     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)
+    n = len(files)
+    added = 0
+    for i, src in enumerate(files, 1):
+        prefix = f"[{i}/{n}] " if n > 1 else ""
+        print(f"→ {prefix}copying \"{src.name}\" onto the iPod…")
+        location, abs_path = copy_audio_to_ipod(ipod, str(src))
+        pid = add_mp3_to_library(work, location, str(src), abs_path.stat().st_size,
+                                 guid, overrides=overrides if n == 1 else {},
+                                 artwork_dir=art_dir)
+        cover = "" if args.no_cover else " (+ cover art)"
+        print(f"  ✓ {prefix}added \"{src.name}\"{cover}  ·  pid {pid}")
+        added += 1
+
     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}'")
+    print(f"✓ Added {added} track{'s' if added != 1 else ''}. 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 +247,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 +258,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 +291,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:
@@ -263,11 +301,17 @@ def main() -> int:
                     "The iPod mounts as a plain volume; ipodsync edits its SQLite library, "
                     "signs it (hashAB) and writes cover art.",
         epilog="Set IPODSYNC_MOUNT=/path to point at the iPod explicitly. "
-               "add/rm/cover back up the library before editing. Run "
-               "`ipodsync <command> -h` for per-command help.")
+               "On Linux, `ipodsync --mount` mounts the iPod once (sudo) and leaves it "
+               "mounted, so `add`/`list`/... just work; `ipodsync --unmount` when done. "
+               "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)")
-    sub = ap.add_subparsers(dest="cmd", required=True, metavar="<command>")
+                    help="Linux: mount the iPod (sudo) and leave it mounted, then exit")
+    ap.add_argument("--unmount", "--umount", action="store_true", dest="unmount",
+                    help="Linux: unmount the iPod mounted by --mount, then exit")
+    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=False, metavar="<command>")
 
     sub.add_parser("list", help="show tracks on the iPod")
 
@@ -281,11 +325,12 @@ def main() -> int:
     pr.add_argument("pid", type=int, help="track pid (see `list`)")
     pr.add_argument("--delete-file", action="store_true", help="also delete the audio file")
 
-    pa = sub.add_parser("add", help="upload an MP3 (cover attached automatically)")
-    pa.add_argument("file", help="path to the MP3 to upload")
-    pa.add_argument("--title", help="override the title tag")
-    pa.add_argument("--artist", help="override the artist tag")
-    pa.add_argument("--album", help="override the album tag")
+    pa = sub.add_parser("add", help="upload a track (or a whole folder); cover attached automatically")
+    pa.add_argument("file", nargs="*", help="path(s) to the audio file(s) to upload")
+    pa.add_argument("-f", "--folder", help="add every audio file in this folder (recursively)")
+    pa.add_argument("--title", help="override the title tag (single file only)")
+    pa.add_argument("--artist", help="override the artist tag (single file only)")
+    pa.add_argument("--album", help="override the album tag (single file only)")
     pa.add_argument("--no-cover", action="store_true", help="don't attach the embedded cover")
 
     sub.add_parser("status", help="report ready / no-access / not-connected")
@@ -312,22 +357,50 @@ def main() -> int:
 
     args = ap.parse_args()
 
+    if args.unmount:
+        return _do_unmount()
     if args.mount:
-        from ipodsync.transport import mount_ipod
-        try:
-            mp = mount_ipod()
-        except IPodNotFound as e:
-            print(f"⚠️  {e}")
-            return 2
-        os.environ["IPODSYNC_MOUNT"] = mp
-        print(f"Mounted iPod at {mp}")
-
-    # commands that don't require a ready iPod
+        rc = _do_mount()
+        if rc != 0 or args.cmd is None:
+            return rc                       # standalone: mounted, now exit
+    if args.cmd is None:
+        ap.print_help()
+        return 1
+    return _dispatch(args)
+
+
+def _do_mount() -> int:
+    """Mount the iPod and leave it mounted for subsequent commands."""
+    from ipodsync.transport import mount_ipod
+    try:
+        mp, mounted_by_us = mount_ipod(rw=True)
+    except IPodNotFound as e:
+        print(f"⚠️  {e}")
+        return 2
+    if mounted_by_us:
+        print(f"✓ iPod mounted at {mp}")
+    else:
+        print(f"✓ iPod already mounted at {mp}")
+    print("  Now run e.g. `ipodsync add song.mp3`; `ipodsync --unmount` when done.")
+    return 0
+
+
+def _do_unmount() -> int:
+    from ipodsync.transport import find_ipod, umount_ipod, MOUNTPOINT
+    try:
+        mp = str(find_ipod().root)
+    except IPodNotFound:
+        mp = MOUNTPOINT
+    umount_ipod(mp)
+    print(f"✓ iPod unmounted ({mp}) — safe to unplug.")
+    return 0
+
+
+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.4 → ipodsync-0.1.6}/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])