ipodsync 0.1.0__py3-none-any.whl

ipodsync/sysinfo.py

@@ -0,0 +1,50 @@
+"""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 "")
+    )

ipodsync/transport.py

@@ -0,0 +1,165 @@
+"""Transport: the iPod nano mounts as an ordinary mass-storage volume.
+
+Uploading = writing files under ``iPod_Control/``. No WebUSB/MTP involved.
+This module locates the device, hands out paths and tracks availability.
+
+Discovery is cross-platform:
+  - macOS: ``/Volumes/*``
+  - Linux: ``/media/$USER/*``, ``/media/*``, ``/run/media/$USER/*``, ``/mnt/*``
+  - override: set ``IPODSYNC_MOUNT=/path/to/mount`` or pass ``mount=`` explicitly.
+A candidate is an iPod if it contains ``iPod_Control/``.
+
+Access note: on macOS the OS may return ``Operation not permitted`` (EPERM) for a
+removable volume when the terminal lacks Full Disk Access (TCC). We tell that state
+(NO_ACCESS) apart from "no iPod connected" (NOT_FOUND).
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class IPodNotFound(RuntimeError):
+    pass
+
+
+class Access(Enum):
+    READY = "ready"          # volume mounted and iPod_Control/iTunes is readable
+    NO_ACCESS = "no_access"  # EPERM — missing TCC permission (macOS Full Disk Access)
+    NOT_FOUND = "not_found"  # no iPod connected
+
+
+NO_ACCESS_HINT = (
+    "iPod is mounted ({vols}) but not accessible (macOS TCC).\n"
+    "  Quick fix: eject -> unplug -> plug back in.\n"
+    "  Permanent: System Settings -> Privacy & Security -> Full Disk Access -> "
+    "add your terminal (Terminal/iTerm) and enable it."
+)
+
+
+@dataclass(frozen=True)
+class IPod:
+    """A mounted iPod. All paths are absolute."""
+    root: Path
+
+    @property
+    def control(self) -> Path:
+        return self.root / "iPod_Control"
+
+    @property
+    def itunes_dir(self) -> Path:
+        return self.control / "iTunes"
+
+    @property
+    def itunes_cdb(self) -> Path:
+        """Legacy mhbd named iTunesCDB (device regenerates it from SQLite)."""
+        return self.itunes_dir / "iTunesCDB"
+
+    @property
+    def music_dir(self) -> Path:
+        return self.control / "Music"
+
+    @property
+    def device_dir(self) -> Path:
+        return self.control / "Device"
+
+    @property
+    def sysinfo_extended(self) -> Path:
+        return self.device_dir / "SysInfoExtended"
+
+    @property
+    def sysinfo(self) -> Path:
+        return self.device_dir / "SysInfo"
+
+
+def _candidate_roots() -> list[Path]:
+    """Possible mount points to probe, in priority order."""
+    env = os.environ.get("IPODSYNC_MOUNT")
+    if env:
+        return [Path(env)]
+    roots: list[Path] = []
+    if sys.platform == "darwin":
+        base_dirs = ["/Volumes"]
+    else:  # linux and other posix
+        user = os.environ.get("USER") or os.environ.get("LOGNAME") or ""
+        base_dirs = [f"/media/{user}", "/media", f"/run/media/{user}", "/mnt"]
+    for base in base_dirs:
+        try:
+            roots += sorted(Path(base).iterdir())
+        except OSError:
+            continue
+    return roots
+
+
+def _probe(vol: Path) -> str:
+    """'ready' — iPod_Control/iTunes readable; 'blocked' — EPERM; 'no' — not an iPod."""
+    marker = vol / "iPod_Control" / "iTunes"
+    try:
+        os.stat(marker)
+        return "ready"
+    except PermissionError:
+        return "blocked"
+    except OSError:
+        # no iPod_Control here — but the whole volume may be EPERM-locked
+        try:
+            os.stat(vol)
+            return "no"
+        except PermissionError:
+            return "blocked"
+        except OSError:
+            return "no"
+
+
+def probe_ipods(name_hint: str = "iPod") -> tuple[Access, IPod | None, list[Path]]:
+    """Return (state, IPod|None, list of blocked volumes)."""
+    ready, blocked = [], []
+    for v in _candidate_roots():
+        s = _probe(v)
+        if s == "ready":
+            ready.append(v)
+        elif s == "blocked":
+            blocked.append(v)
+    if ready:
+        pick = (next((v for v in ready if v.name == name_hint), None)
+                or next((v for v in ready if name_hint.lower() in v.name.lower()), None)
+                or ready[0])
+        return Access.READY, IPod(pick), blocked
+    if blocked:
+        return Access.NO_ACCESS, None, blocked
+    return Access.NOT_FOUND, None, []
+
+
+def find_ipod(name_hint: str = "iPod") -> IPod:
+    """Find a ready iPod. Raises with a helpful message on NO_ACCESS / NOT_FOUND."""
+    status, ipod, blocked = probe_ipods(name_hint)
+    if status is Access.READY:
+        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."
+    )
+
+
+def wait_for_ipod(timeout: float = 120, interval: float = 2,
+                  name_hint: str = "iPod", on_wait=None) -> IPod:
+    """Wait until an iPod becomes READY. timeout=0 waits forever.
+
+    on_wait(status, blocked) is called on each waiting iteration (for logging).
+    """
+    start = time.monotonic()
+    while True:
+        status, ipod, blocked = probe_ipods(name_hint)
+        if status is Access.READY:
+            return ipod
+        if on_wait:
+            on_wait(status, blocked)
+        if timeout and (time.monotonic() - start) > timeout:
+            raise IPodNotFound(f"iPod did not become available within {timeout}s "
+                               f"(last state: {status.value})")
+        time.sleep(interval)

ipodsync-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: ipodsync
+Version: 0.1.0
+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
+Project-URL: Issues, https://github.com/buldiei/ipodsync/issues
+Project-URL: LinkedIn, https://www.linkedin.com/in/alex-buldiei-b10a9a150/
+Author-email: Alex Buldiei <abuldiei@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: artwork,ipod,itunes,music,nano,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.9
+Requires-Dist: mutagen>=1.47
+Requires-Dist: pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+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/)
+[![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
+the terminal, on macOS and Linux. The iPod mounts as a plain volume; `ipodsync`
+edits its SQLite library, signs it (hashAB) and **generates cover art itself**.
+
+> ⚠️ Alpha. Works on real hardware, but it writes to the player's binary database.
+> **Keep backups** (the tool makes one before every edit) and don't open this iPod
+> in iTunes.
+
+## Features
+
+- `list` / `export` — inspect and download tracks from the device (with tags).
+- `add` — upload an MP3, metadata from tags, **cover art attached automatically**
+  (from an embedded APIC/covr): shown both in Now Playing and in list/Albums views.
+- `rm` — remove a track (+file), re-sign.
+- playlists — `playlists` / `pl-create` / `pl-add` / `pl-rm` / `pl-del`.
+- `cover` — attach a cover to an already-uploaded track.
+- works on an **empty (wiped) library** too — no iTunes needed to initialize it.
+
+## Install
+
+```bash
+pipx install ipodsync      # recommended (isolated), or: pip install ipodsync
+```
+
+Requires Python ≥ 3.9. Pure-Python — no compiler or native library needed.
+
+> Note: uploading currently supports **MP3 only**. FLAC/AAC → ALAC transcoding
+> (which will need `ffmpeg`) is on the roadmap and not implemented yet.
+
+## Usage
+
+```bash
+ipodsync status                     # ready / no access / not connected
+ipodsync list
+ipodsync add "Song.mp3"             # + cover auto
+ipodsync add "Song.mp3" --no-cover
+ipodsync export ~/Music/ipod --by-album
+ipodsync cover 123456789 --image cover.jpg
+ipodsync rm 123456789 --delete-file
+```
+
+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`.
+
+## How it works
+
+- **Transport** — mass storage: files are written under `iPod_Control/`.
+- **Database** — SQLite `iTunes Library.itlp/*.itdb` (not `iTunesCDB`, which the
+  device regenerates on its own). Only `Locations.itdb` is hash-protected (`.cbk`).
+- **hashAB** — anti-tamper `.cbk` signature (white-box AES). **Pure-Python** port of
+  [dstaley/hashab](https://github.com/dstaley/hashab) (public domain), 100/100 test
+  vectors. No compiler or native lib — the package installs everywhere.
+- **Cover art** — pure-Python writer for `ArtworkDB` + `F<fmt>_1.ithmb` (RGB565 LE,
+  formats 1010/1013/1015/1016), appended incrementally.
+
+## Status / roadmap
+
+| | Status |
+|---|---|
+| Upload / remove / export / playlists (MP3) | ✅ confirmed on nano 7G |
+| Cover art (pure-Python) | ✅ confirmed on nano 7G |
+| Empty-library bootstrap | ✅ |
+| **Pure-Python hashAB** (no native lib, installs everywhere) | ✅ 100/100 vectors |
+| Cross-platform device discovery (macOS + Linux) | ✅ |
+| FLAC/AAC → ALAC | ⬜ |
+
+## Development
+
+```bash
+git clone … && cd ipodsync
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT (see [LICENSE](LICENSE)). The vendored hashAB algorithm is public domain.
+Not affiliated with Apple; iPod and iTunes are trademarks of Apple.

ipodsync-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+ipodsync/__init__.py,sha256=REzF6I-MS8uPGE59UpRYrGQh79D388XzD2SY0PfZahE,728
+ipodsync/__main__.py,sha256=Pf37VnDwFZ-NTChYi2r9XHtP1jxVecowifdRUeZ4CG4,114
+ipodsync/_art_templates.py,sha256=R53aZ3UkypEaEawD7a1CO1rwc4fKn_L9duq5WsREcg0,4816
+ipodsync/_hashab_gen.py,sha256=giyPzQlobsNUo4uf7mCfq1K2VM7pdZ3xzgPnKWsQw4E,162837
+ipodsync/_hashab_gen2.py,sha256=9UcfJoJ9UbUO0eM_g9NvIaQzQUcoM8Q9yqzH22_cAtg,85793
+ipodsync/_hashab_gen_rt.py,sha256=zvHYc1wNruCyMWoi7CX10HjL4RasXkoD76M8c-3FkNI,4829
+ipodsync/_hashab_py.py,sha256=i6whCvzsHKGh3lo_WqmHmdyuGov5XM1xtc67CHMhzK4,11756
+ipodsync/_hashab_tables.bin,sha256=PfbLKaUk-54FZjOq96VyZXrfX0j_8vIodKSbdPkJiUQ,443788
+ipodsync/_hashab_tables.py,sha256=b5lVY59cGGsfZ70LDFdOyaAeX8SDcg3jjoNKifib9pk,1023
+ipodsync/_lib_templates.py,sha256=tYy0e6VYr_acZ8e8qNDjVABhSGzjCrV2C2AR7CZGFuc,3167
+ipodsync/artwork_writer.py,sha256=jfSON_D5L9G8jT_eGKCV7smn4kJTJFQehUouJ1M-cck,9986
+ipodsync/cbk.py,sha256=GDqTKBagNvjdWzb0K24qPd1KcIPvS7JXbENuV7VCOho,1737
+ipodsync/cli.py,sha256=DG8pG3go4hdfN7OKUpLeAveUmEhE72QdG6jdxhES0rM,11595
+ipodsync/export.py,sha256=uhbPf4zZT_f1UeX-vD3SF149LNDis4wNvIB6CzynIZ8,3044
+ipodsync/hashab.py,sha256=VDCopl-smX4dskISJoCW49MRbsxBOHCxI3XAJgZ8cSc,1555
+ipodsync/importer.py,sha256=upYW2wG-x-9efgWUsI4c2_bX0_612yC6Nq7YUaK64vE,5122
+ipodsync/library.py,sha256=Oat1MoKKzZ3HXMNYHd2hhRXTlORE5bNVpvec9i9WAVQ,16511
+ipodsync/models.py,sha256=M6KlH_sKFLB0IOT6_emhO_N2qFl0F63stgt0MfnvJQw,855
+ipodsync/sysinfo.py,sha256=eVqQouHUeQN1Ui3Pcxpjs2s_XC47eMI4TSTb29-9y_M,1486
+ipodsync/transport.py,sha256=vNbomxeUUdruCfiaVA2XqWZNaWai7vEiLhSA8tli2kY,5361
+ipodsync-0.1.0.dist-info/METADATA,sha256=KZJ1-pThmLNeixe3-_3CzCGv04HiBky12yFzSF7ArvI,4641
+ipodsync-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ipodsync-0.1.0.dist-info/entry_points.txt,sha256=vVHLPxHbzX23-SnQop2t_EYyOV4cQwAOeE2ecpiDfU8,47
+ipodsync-0.1.0.dist-info/licenses/LICENSE,sha256=Fmqk7PBD9o10kvqvy5N1ojgf--SNLWkCovih-jM9HB4,1069
+ipodsync-0.1.0.dist-info/RECORD,,

ipodsync-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ipodsync-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ipodsync = ipodsync.cli:main

ipodsync-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Buldiei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.