ipodsync 0.1.1__tar.gz → 0.1.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipodsync
-Version: 0.1.1
+Version: 0.1.3
 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
@@ -17,6 +17,11 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio
 Requires-Python: >=3.9
 Requires-Dist: mutagen>=1.47
@@ -28,8 +33,8 @@ Description-Content-Type: text/markdown
 # ipodsync
 
 [![CI](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml/badge.svg)](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg)](https://pypi.org/project/ipodsync/)
-[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg)](https://pypi.org/project/ipodsync/)
+[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
+[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 Upload music to an **iPod nano 6G/7G** without iTunes/Apple Music — straight from
@@ -54,9 +59,29 @@ edits its SQLite library, signs it (hashAB) and **generates cover art itself**.
 
 ## Install
 
+`ipodsync` is a command-line tool, so install it with **pipx** — it lands in an
+isolated environment while the `ipodsync` command stays available everywhere:
+
+```bash
+pipx install ipodsync
+```
+
+No pipx yet? `brew install pipx` (macOS) or `sudo apt install pipx` (Debian/Ubuntu),
+then `pipx ensurepath`.
+
+<details>
+<summary><code>pip install ipodsync</code> fails with <code>externally-managed-environment</code>?</summary>
+
+On modern Debian/Ubuntu (PEP 668) the system Python is locked, so a plain
+`pip install` into it is refused — that's an OS guard, not an ipodsync issue.
+Use `pipx` (above), or a virtualenv:
+
 ```bash
-pipx install ipodsync      # recommended (isolated), or: pip install ipodsync
+python3 -m venv ~/.venvs/ipodsync
+~/.venvs/ipodsync/bin/pip install ipodsync
+~/.venvs/ipodsync/bin/ipodsync --help
 ```
+</details>
 
 Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 
@@ -79,6 +104,57 @@ The iPod is discovered under `/Volumes` (macOS) and `/media`, `/run/media`, `/mn
 (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.
+
+Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
+
+```bash
+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:
+
+```bash
+ipodsync --mount list
+```
+
+Or mount it yourself:
+
+```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 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
+```
+
+Two catches:
+
+- **The GUID.** Signing needs the device's FireWireGUID, which lives in a
+  `Device/SysInfo*` file — but those are HFS+-compressed and unreadable by the Linux
+  driver. ipodsync works around it by reading the GUID from the device's **USB serial**
+  automatically. If that fails, pass it yourself:
+  ```bash
+  udevadm info -q property -n /dev/sda | grep ID_SERIAL
+  #   ID_SERIAL=Apple_iPod_0123456789ABCDEF-0:0
+  IPODSYNC_FIREWIRE_GUID=0123456789ABCDEF IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
+  ```
+- **Journaling.** If the mount comes up read-only, the volume is *journaled* HFS+;
+  disable the journal once, on a Mac: `diskutil disableJournal /Volumes/iPod`. Forcing
+  it with `-o force,rw` on a still-journaled volume can corrupt the filesystem — don't.
+
 ## How it works
 
 - **Transport** — mass storage: files are written under `iPod_Control/`.

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

@@ -1,8 +1,8 @@
 # ipodsync
 
 [![CI](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml/badge.svg)](https://github.com/buldiei/ipodsync/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg)](https://pypi.org/project/ipodsync/)
-[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg)](https://pypi.org/project/ipodsync/)
+[![PyPI](https://img.shields.io/pypi/v/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
+[![Python](https://img.shields.io/pypi/pyversions/ipodsync.svg?v=2)](https://pypi.org/project/ipodsync/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 Upload music to an **iPod nano 6G/7G** without iTunes/Apple Music — straight from
@@ -27,9 +27,29 @@ edits its SQLite library, signs it (hashAB) and **generates cover art itself**.
 
 ## Install
 
+`ipodsync` is a command-line tool, so install it with **pipx** — it lands in an
+isolated environment while the `ipodsync` command stays available everywhere:
+
+```bash
+pipx install ipodsync
+```
+
+No pipx yet? `brew install pipx` (macOS) or `sudo apt install pipx` (Debian/Ubuntu),
+then `pipx ensurepath`.
+
+<details>
+<summary><code>pip install ipodsync</code> fails with <code>externally-managed-environment</code>?</summary>
+
+On modern Debian/Ubuntu (PEP 668) the system Python is locked, so a plain
+`pip install` into it is refused — that's an OS guard, not an ipodsync issue.
+Use `pipx` (above), or a virtualenv:
+
 ```bash
-pipx install ipodsync      # recommended (isolated), or: pip install ipodsync
+python3 -m venv ~/.venvs/ipodsync
+~/.venvs/ipodsync/bin/pip install ipodsync
+~/.venvs/ipodsync/bin/ipodsync --help
 ```
+</details>
 
 Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
 
@@ -52,6 +72,57 @@ The iPod is discovered under `/Volumes` (macOS) and `/media`, `/run/media`, `/mn
 (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.
+
+Find the iPod's partition (an `hfsplus` one, roughly the iPod's size):
+
+```bash
+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:
+
+```bash
+ipodsync --mount list
+```
+
+Or mount it yourself:
+
+```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 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
+```
+
+Two catches:
+
+- **The GUID.** Signing needs the device's FireWireGUID, which lives in a
+  `Device/SysInfo*` file — but those are HFS+-compressed and unreadable by the Linux
+  driver. ipodsync works around it by reading the GUID from the device's **USB serial**
+  automatically. If that fails, pass it yourself:
+  ```bash
+  udevadm info -q property -n /dev/sda | grep ID_SERIAL
+  #   ID_SERIAL=Apple_iPod_0123456789ABCDEF-0:0
+  IPODSYNC_FIREWIRE_GUID=0123456789ABCDEF IPODSYNC_MOUNT=/mnt/ipod ipodsync add song.mp3
+  ```
+- **Journaling.** If the mount comes up read-only, the volume is *journaled* HFS+;
+  disable the journal once, on a Mac: `diskutil disableJournal /Volumes/iPod`. Forcing
+  it with `-o force,rw` on a still-journaled volume can corrupt the filesystem — don't.
+
 ## How it works
 
 - **Transport** — mass storage: files are written under `iPod_Control/`.

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipodsync"
-version = "0.1.1"
+version = "0.1.3"
 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"
@@ -19,6 +19,11 @@ classifiers = [
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Multimedia :: Sound/Audio",
 ]
 dependencies = [

{ipodsync-0.1.1 → ipodsync-0.1.3}/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.1"
+__version__ = "0.1.3"
 
 __all__ = [
     "find_ipod",

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

@@ -14,6 +14,7 @@ or a sync will drop manually-added tracks.
 from __future__ import annotations
 
 import argparse
+import os
 import shutil
 from datetime import datetime, timezone
 from pathlib import Path
@@ -77,7 +78,7 @@ def cmd_rm(ipod, args):
     shutil.copytree(itlp, backup)
     print(f".itlp backup: {backup}")
 
-    guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo)
+    guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo, mount=ipod.root)
     lib = ItlpLibrary(itlp)
     music = ipod.music_dir if args.delete_file else None
     loc = lib.remove_track(args.pid, music_dir=music)
@@ -181,7 +182,7 @@ def cmd_add(ipod, args):
     shutil.copytree(itlp, backup)
     print(f".itlp backup: {backup}")
 
-    guid = read_firewire_guid(ipod.sysinfo_extended, ipod.sysinfo)
+    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}")
 
@@ -256,41 +257,71 @@ def cmd_cover(ipod, args):
 
 
 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)
+    ap = argparse.ArgumentParser(
+        prog="ipodsync",
+        description="Upload music to an iPod nano 6G/7G without iTunes (macOS + Linux). "
+                    "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.")
+    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>")
+
+    sub.add_parser("list", help="show tracks on the iPod")
+
+    pe = sub.add_parser("export", help="download tracks from the iPod (read-only)")
+    pe.add_argument("dest", help="destination directory")
+    pe.add_argument("--pid", type=int, help="export only this track (by pid)")
+    pe.add_argument("--by-album", action="store_true", help="lay out as Artist/Album/")
+    pe.add_argument("--no-tag", action="store_true", help="don't write ID3/MP4 tags")
+
+    pr = sub.add_parser("rm", help="remove a track from the iPod")
+    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.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")
+
+    pw = sub.add_parser("wait", help="block until an iPod is ready")
+    pw.add_argument("--timeout", type=float, default=120, help="seconds to wait (0 = forever)")
+    pw.add_argument("--interval", type=float, default=2, help="poll interval, seconds")
+
+    sub.add_parser("playlists", help="list playlists")
+    pc = sub.add_parser("pl-create", help="create a playlist")
+    pc.add_argument("name", help="playlist name")
+    ppa = sub.add_parser("pl-add", help="add tracks to a playlist")
+    ppa.add_argument("playlist", type=int, help="playlist pid")
+    ppa.add_argument("track", type=int, nargs="+", help="track pid(s)")
+    ppr = sub.add_parser("pl-rm", help="remove a track from a playlist")
+    ppr.add_argument("playlist", type=int, help="playlist pid")
+    ppr.add_argument("track", type=int, help="track pid")
+    ppd = sub.add_parser("pl-del", help="delete a playlist")
+    ppd.add_argument("playlist", type=int, help="playlist pid")
+
+    pcv = sub.add_parser("cover", help="attach a cover to an existing track")
+    pcv.add_argument("pid", type=int, help="track pid")
     pcv.add_argument("--image", help="cover image file (otherwise the track's APIC is used)")
+
     args = ap.parse_args()
 
+    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
     if args.cmd == "status":
         return cmd_status(args)

ipodsync-0.1.3/src/ipodsync/sysinfo.py

@@ -0,0 +1,118 @@
+"""Read the device's FirewireGuid — needed for the hashAB signature.
+
+FirewireGuid is an 8-byte device identifier. It normally lives in
+`iPod_Control/Device/SysInfoExtended` (XML plist) or `SysInfo` (text), as a hex
+string like `0x000A2700XXXXXXXX` (16 hex chars).
+
+On a Mac-formatted iPod mounted on Linux those files are often unreadable (HFS+
+transparent compression / restrictive perms). As fallbacks we accept the GUID via
+the `IPODSYNC_FIREWIRE_GUID` env var, and derive it from the device's USB serial
+(e.g. udev `ID_SERIAL=Apple_iPod_0123456789ABCDEF-0:0`), which stays readable.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ENV_GUID = "IPODSYNC_FIREWIRE_GUID"
+
+# 0x + 16 hex, or a FireWireGUID key near 16 hex chars
+_GUID_RE = re.compile(
+    r"(?:FireWireGUID|FirewireGuid)\D{0,40}?(?:0x)?([0-9A-Fa-f]{16})",
+    re.IGNORECASE | re.DOTALL,
+)
+_BARE_HEX_RE = re.compile(r"0x([0-9A-Fa-f]{16})")
+_SERIAL_RE = re.compile(r"ID_SERIAL=\S*?([0-9A-Fa-f]{16})")
+
+
+class FirewireGuidNotFound(RuntimeError):
+    pass
+
+
+def _clean_hex(s: str) -> str | None:
+    s = s.strip().lower()
+    if s.startswith("0x"):
+        s = s[2:]
+    return s if re.fullmatch(r"[0-9a-f]{16}", s) else None
+
+
+def _extract(text: str) -> str | None:
+    m = _GUID_RE.search(text) or _BARE_HEX_RE.search(text)
+    return m.group(1) if m else None
+
+
+def _from_env() -> bytes | None:
+    v = os.environ.get(ENV_GUID)
+    if not v:
+        return None
+    h = _clean_hex(v)
+    if not h:
+        raise FirewireGuidNotFound(
+            f"{ENV_GUID}={v!r} is not 16 hex digits (e.g. 0123456789ABCDEF)")
+    return bytes.fromhex(h)
+
+
+def _from_files(*paths: Path | None) -> bytes | None:
+    for p in paths:
+        if p is None:
+            continue
+        try:
+            if not p.exists():
+                continue
+            text = p.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue  # unreadable (e.g. HFS+ compression on Linux)
+        h = _extract(text)
+        if h:
+            return bytes.fromhex(h)
+    return None
+
+
+def _run(cmd: list[str]) -> str:
+    try:
+        return subprocess.run(cmd, capture_output=True, text=True,
+                              timeout=5).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def _from_usb_serial(mount: Path | None) -> bytes | None:
+    """Linux: derive the GUID from the iPod's USB serial (readable when the
+    HFS+ SysInfo* files are not)."""
+    if mount is None or not sys.platform.startswith("linux"):
+        return None
+    src = _run(["findmnt", "-no", "SOURCE", "--target", str(mount)])
+    devices = [src] if src else []
+    if src:
+        pk = _run(["lsblk", "-no", "pkname", src])
+        if pk:
+            devices.append(f"/dev/{pk}")
+    for dev in devices:
+        m = _SERIAL_RE.search(_run(["udevadm", "info", "-q", "property", "-n", dev]))
+        if m:
+            return bytes.fromhex(m.group(1))
+    return None
+
+
+def read_firewire_guid(sysinfo_extended: Path, sysinfo: Path | None = None,
+                       mount: Path | None = None) -> bytes:
+    """Return the FirewireGuid as 8 bytes (big-endian, as in the hex string).
+
+    Resolution order: `IPODSYNC_FIREWIRE_GUID` env → SysInfoExtended/SysInfo files
+    → the device's USB serial (Linux). `mount` is the iPod root (for the USB fallback).
+    """
+    for guid in (_from_env(), _from_files(sysinfo_extended, sysinfo),
+                 _from_usb_serial(mount)):
+        if guid:
+            return guid
+    raise FirewireGuidNotFound(
+        "Could not read the device FireWireGUID.\n"
+        f"  Tried {sysinfo_extended} / {sysinfo}"
+        + ("  (unreadable — Mac-formatted HFS+ files often aren't readable on Linux)\n"
+           if not sys.platform == "darwin" else "\n")
+        + f"  Fix: pass it via {ENV_GUID}=<16 hex digits>. Find it with:\n"
+        + "    udevadm info -q property -n /dev/sdXN | grep ID_SERIAL   (Linux)\n"
+        + "  e.g. ID_SERIAL=Apple_iPod_0123456789ABCDEF-0:0  ->  0123456789ABCDEF")

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

@@ -16,6 +16,8 @@ removable volume when the terminal lacks Full Disk Access (TCC). We tell that st
 from __future__ import annotations
 
 import os
+import re
+import subprocess
 import sys
 import time
 from dataclasses import dataclass
@@ -140,10 +142,7 @@ def find_ipod(name_hint: str = "iPod") -> IPod:
         return ipod
     if status is Access.NO_ACCESS:
         raise IPodNotFound(NO_ACCESS_HINT.format(vols=", ".join(v.name for v in blocked)))
-    raise IPodNotFound(
-        "iPod not found. Connect the device (enable Disk Use), or set "
-        "IPODSYNC_MOUNT=/path/to/mount."
-    )
+    raise IPodNotFound(_not_found_message())
 
 
 def wait_for_ipod(timeout: float = 120, interval: float = 2,
@@ -163,3 +162,70 @@ def wait_for_ipod(timeout: float = 120, interval: float = 2,
             raise IPodNotFound(f"iPod did not become available within {timeout}s "
                                f"(last state: {status.value})")
         time.sleep(interval)
+
+
+# --- Linux: detect / mount an unmounted iPod block device -----------------------
+def _run(cmd: list[str]) -> tuple[str, str]:
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=8)
+        return p.stdout, p.stderr
+    except (OSError, subprocess.SubprocessError):
+        return "", ""
+
+
+def find_ipod_block_device() -> dict | None:
+    """Linux: locate the iPod's HFS+ block device.
+
+    Lists hfsplus partitions and confirms each is an Apple iPod via udev
+    (lsblk vendor/model aren't always populated on the partition).
+    Returns {'path': '/dev/sdXN', 'mountpoint': str|None} or None.
+    """
+    if not sys.platform.startswith("linux"):
+        return None
+    out, _ = _run(["lsblk", "-rno", "PATH,FSTYPE,MOUNTPOINT"])
+    for line in out.splitlines():
+        f = line.split(None, 2)
+        if len(f) < 2 or f[1] != "hfsplus":
+            continue
+        path, mp = f[0], (f[2] if len(f) > 2 else "")
+        info, _ = _run(["udevadm", "info", "-q", "property", "-n", path])
+        low = info.lower()
+        if ("apple_ipod" in low or "id_model=ipod" in low
+                or "id_vendor=apple" in low or "scsi_vendor=apple" in low):
+            return {"path": path, "mountpoint": mp or None}
+    return None
+
+
+def _not_found_message() -> str:
+    dev = find_ipod_block_device()
+    if dev and dev.get("path") and not dev.get("mountpoint"):
+        return (f"iPod detected at {dev['path']} but not mounted.\n"
+                f"  Mount it (read-only, for list/export):  ipodsync --mount <command>\n"
+                f"  or manually:                            udisksctl mount -b {dev['path']}\n"
+                "  For writing (add/rm) mount read-write with uid= — see the README "
+                "\"Linux: mounting the iPod\".")
+    return ("iPod not found. Connect the device (enable Disk Use on the iPod), "
+            "or set IPODSYNC_MOUNT=/path/to/mount.")
+
+
+def mount_ipod() -> str:
+    """Mount the iPod via udisksctl (Linux, no root). Returns the mountpoint.
+
+    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).
+    """
+    if sys.platform == "darwin":
+        raise IPodNotFound("On macOS the iPod is mounted automatically by Finder.")
+    dev = find_ipod_block_device()
+    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.")

ipodsync-0.1.1/src/ipodsync/sysinfo.py

@@ -1,50 +0,0 @@
-"""Read the device's FirewireGuid — needed for the hashAB signature.
-
-FirewireGuid is an 8-byte device identifier. It lives in
-`iPod_Control/Device/SysInfoExtended` (XML plist) or `SysInfo` (text),
-as a hex string like `0x000A2700XXXXXXXX` (16 hex characters).
-"""
-from __future__ import annotations
-
-import re
-from pathlib import Path
-
-# 0x + 16 hex, or a FireWireGUID key near 16 hex chars
-_GUID_RE = re.compile(
-    r"(?:FireWireGUID|FirewireGuid)\D{0,40}?(?:0x)?([0-9A-Fa-f]{16})",
-    re.IGNORECASE | re.DOTALL,
-)
-_BARE_HEX_RE = re.compile(r"0x([0-9A-Fa-f]{16})")
-
-
-class FirewireGuidNotFound(RuntimeError):
-    pass
-
-
-def _extract(text: str) -> str | None:
-    m = _GUID_RE.search(text)
-    if m:
-        return m.group(1)
-    m = _BARE_HEX_RE.search(text)
-    if m:
-        return m.group(1)
-    return None
-
-
-def read_firewire_guid(sysinfo_extended: Path, sysinfo: Path | None = None) -> bytes:
-    """Return FirewireGuid as 8 bytes (big-endian, as in the hex string).
-
-    Tries SysInfoExtended, then SysInfo. errors='ignore' — the files may
-    contain binary tails.
-    """
-    for p in (sysinfo_extended, sysinfo):
-        if p is None or not p.exists():
-            continue
-        text = p.read_text(encoding="utf-8", errors="ignore")
-        hexs = _extract(text)
-        if hexs:
-            return bytes.fromhex(hexs)
-    raise FirewireGuidNotFound(
-        f"Could not find FireWireGUID in {sysinfo_extended}"
-        + (f" / {sysinfo}" if sysinfo else "")
-    )