ipodsync 0.1.2__tar.gz → 0.1.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipodsync
-Version: 0.1.2
+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
@@ -104,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.2 → ipodsync-0.1.3}/README.md

@@ -72,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.2 → ipodsync-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipodsync"
-version = "0.1.2"
+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"

{ipodsync-0.1.2 → 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.2"
+__version__ = "0.1.3"
 
 __all__ = [
     "find_ipod",

{ipodsync-0.1.2 → 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}")
 
@@ -264,6 +265,8 @@ def main() -> int:
         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")
@@ -309,6 +312,16 @@ def main() -> int:
 
     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.2 → 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.2/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 "")
-    )