79 lines
2.2 KiB
Markdown
79 lines
2.2 KiB
Markdown
# ipodutils
|
||
|
||
Rebuild the on-disk database for **1st- and 2nd-generation Apple iPod shuffle** players (`iTunesSD`, shuffle order, playback state, and related files) so you can manage music by copying files—without iTunes—for each sync.
|
||
|
||
Python 3 port of **KeyJ’s rebuild_db** ([Martin J. Fiedler](mailto:martin.fiedler@gmx.net)).
|
||
|
||
## Supported hardware
|
||
|
||
| Supported | Not supported |
|
||
|-----------|----------------|
|
||
| iPod shuffle (1st gen), iPod shuffle (2nd gen) | 3rd-gen shuffle and later (VoiceOver, different DB format) |
|
||
|
||
The volume must already contain `iPod_Control/` (typically after one-time setup with iTunes or an equivalent).
|
||
|
||
## Requirements
|
||
|
||
- **Python** ≥ 3.14
|
||
- Write access to the iPod’s mounted volume
|
||
|
||
## Install
|
||
|
||
From a checkout:
|
||
|
||
```bash
|
||
uv sync
|
||
```
|
||
|
||
From [PyPI](https://pypi.org/) (after you publish):
|
||
|
||
```bash
|
||
pip install ipodutils
|
||
```
|
||
|
||
The console entry point is **`rebuild-db`** (implements `main:cli`).
|
||
|
||
## Usage
|
||
|
||
Run with the working directory set to the **iPod root**, or pass **`--ipod-path`**:
|
||
|
||
```bash
|
||
# From repo / env that has the package installed
|
||
uv run rebuild-db --ipod-path /run/media/$USER/IPOD
|
||
|
||
# Or: cd to the mount, then
|
||
rebuild-db
|
||
```
|
||
|
||
Full options:
|
||
|
||
```bash
|
||
rebuild-db --help
|
||
```
|
||
|
||
### Common options
|
||
|
||
| Option | Meaning |
|
||
|--------|---------|
|
||
| `--ipod-path DIR` | Use `DIR` as the iPod root (mount point) |
|
||
| `-s` / `--nosmart` | Plain random shuffle instead of “smart shuffle” |
|
||
| `-i` / `--interactive` | Confirm each directory while scanning |
|
||
| `-v N` | Playback volume (0–38) |
|
||
| `-f` / `--force` | Rebuild DB entries from scratch (do not reuse old entries; useful for `.aa` only if you understand the trade-offs) |
|
||
| `-r` / `--rename` | Rename unsafe paths outside `iPod_Control` |
|
||
| `-l` / `--nolog` | Do not write `rebuild_db.log.txt` |
|
||
|
||
Optional rules file: **`rebuild_db.rules`** in the iPod root (see `--help` and original rebuild_db documentation for the rule syntax).
|
||
|
||
## Logging
|
||
|
||
By default, output is also written to **`rebuild_db.log.txt`** on the iPod root. Use **`--nolog`** to disable.
|
||
|
||
## License
|
||
|
||
GPL v2 — see [`License.txt`](License.txt).
|
||
|
||
## See also
|
||
|
||
- Original project lineage: *KeyJ’s iPod shuffle Database Builder* / `rebuild_db`
|