Metadata-Version: 2.5
Name: pypodlib
Version: 0.1.0
Summary: Communicate with iPod Classic/Nano/Mini devices — detect and identify the device, read and write the iTunesDB library, and sync media — without iTunes.
Project-URL: Homepage, https://la22e.github.io/pyPodLib/
Project-URL: Repository, https://github.com/La22e/pyPodLib
Author: La22e
License: MIT
License-File: LICENSE
Keywords: ipod,ipod-classic,ipod-manager,ipod-sync,itunes,itunes-alternative,itunesdb,music-library,music-sync
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.11
Requires-Dist: libusb-package>=1.0.30.0
Requires-Dist: pycryptodome>=3.20.0
Requires-Dist: pyusb>=1.3.1
Requires-Dist: wasmtime>=30.0.0
Provides-Extra: artwork
Requires-Dist: mutagen>=1.47.0; extra == 'artwork'
Requires-Dist: numpy>=2.0.0; extra == 'artwork'
Requires-Dist: pillow>=10.0.0; extra == 'artwork'
Description-Content-Type: text/markdown

# pyPodLib

Read, write, and sync iPod Classic/Nano/Mini libraries from Python — no
iTunes required.

pyPodLib is a pure-Python library extracted from
[iOpenPod](https://github.com/TheRealSavi/iOpenPod) (MIT, © John Gibbons).
It keeps the battle-tested iTunesDB / iTunesCDB parsing and writing engine,
device detection, and sync logic, and exposes it as a headless library.

## Features

- **Device detection** — scan for connected iPods and identify model,
  generation, capacity, colour, serial, and checksum type (`scan_ipods`,
  `identify_ipod_at_path`).
- **Read** — parse the full library: tracks, user playlists, podcast
  playlists, smart playlists (dataset 2/3/5), play counts, artwork refs.
- **Write** — save edits back with the correct per-device signature
  (HASH58 via FireWire GUID, HASH72 via AES, HASHAB via WebAssembly,
  NONE for pre-2007 devices), plus SQLite DBs for Nano 6G/7G and
  iTunesPrefs protection.
- **Sync** — plan and execute media sync, with optional artwork and
  transcode support.
- **Testable without hardware** — create "virtual iPods" (a folder
  identity + seeded database) for round-trip tests
  (`pypodlib.device.create_virtual_ipod`).

## Install

```console
pip install pypodlib                          # core (device + library read/write)
pip install 'pypodlib[artwork]'               # + embedded-art extraction/encoding
```

Runtime dependencies: `pyusb` / `libusb-package` (USB identification),
`pycryptodome` (HASH72 signing), `wasmtime` (HASHAB signing).

## Documentation

Full documentation: [la22e.github.io/pyPodLib](https://la22e.github.io/pyPodLib/)

## Quick start

```python
import pypodlib

ipod = pypodlib.connect("/media/user/IPOD")        # or pypodlib.scan_ipods()[0]
print(ipod.model_number, ipod.generation, ipod.capacity)

lib = ipod.library()
print(len(lib.tracks), "tracks")

track = lib.tracks[0]
track.title = "New Title"
track.rating = 80                                 # 4 stars
ipod.save()                                       # writes iTunesDB + signature
```

### Low-level access

Every layer stays importable:

```python
from pypodlib.device import scan_for_ipods, identify_ipod_at_path
from pypodlib.itunesdb_parser import parse_itunesdb, load_ipod_library
from pypodlib.itunesdb_writer import write_itunesdb, detect_checksum_type
from pypodlib.sync._db_io import read_existing_database, write_database
```

### Virtual iPods (no hardware)

```python
from pypodlib.device import create_virtual_ipod, available_virtual_ipod_models

import tempfile
root = tempfile.mkdtemp()
info = create_virtual_ipod(root, "MC297")   # iPod Classic 7th Gen (HASH58)
ipod = pypodlib.connect(root)
ipod.library()
ipod.save()                                  # round-trips through real writer
```

## Limitations

- Requires a mounted iPod volume (or a virtual iPod root) — USB enumeration
  is used for identification only.
- Photo sync and embedded-art encoding need the `artwork` extra
  (`numpy`, `Pillow`, `mutagen`).
- Video/ffmpeg transcoding requires an `ffmpeg`/`ffprobe` binary.
- Smart playlists are re-evaluated on save (matching iTunes behaviour).

## License

MIT. pyPodLib is derived from iOpenPod (MIT, © John Gibbons).