# 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 this package index (HTTPS):

**Download URL (simple index):** `https://barrys.cloud/pypi/simple/`

```bash
pip install --index-url https://barrys.cloud/pypi/simple/ ipodutils
```

```bash
uv pip install --index-url https://barrys.cloud/pypi/simple/ 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`