# 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` |
| `--shuffle-all` | Force `shuffle=1` on every track (overrides audiobook-style rules) |
| `--verbose` | Log each file as it is written (`type`, `shuffle`, `bookmark`), like the original KeyJ tool |

Optional rules file: **`rebuild_db.rules`** in the iPod root (see `--help` and original rebuild_db documentation for the rule syntax).

### WAV, M4A, and “not showing up”

**Hardware:** Apple’s specs for the 1st- and 2nd-gen iPod shuffle list **MP3, AAC (M4A/M4P/M4B), Audible, and WAV** (and AIFF on 2nd gen) as supported formats. The shuffle has **no screen**—tracks do not “appear” anywhere except through playback order and, on disk, under `iPod_Control/Music/`.

**Database:** This tool assigns **type 1** (MP3), **type 2** (AAC/M4A), **type 4** (WAV) in `iTunesSD`, matching KeyJ’s rebuild_db. If something still will not play:

1. Run with **`--verbose`** and confirm every file is listed with **`type=4`** and **`shuffle=1`** for WAV. If **`shuffle=0`**, a rule matched (e.g. **`*.book.???`** treats names like `anything.book.wav` as audiobooks). Use **`--shuffle-all`** or adjust **`rebuild_db.rules`**.
2. **PCM format:** The device is picky like many portables. Prefer **44.1 kHz, 16-bit, stereo, PCM WAV**. **Float WAV, 24/32-bit, or very high sample rates** may fail silently. Re-encode if needed, e.g. `ffmpeg -i in.wav -ar 44100 -ac 2 -sample_fmt s16 out.wav`.
3. **M4A** usually works because AAC matches what iTunes typically synced; if only M4A plays, format (2) vs WAV (4) on the wire is a good clue to try re-encoding WAV to AAC/MP3 as a test.

### Converting a folder of audio for the shuffle

Install **ffmpeg**, then (from a checkout or after `pip install ipodutils`):

```bash
shuffle-convert /path/to/music
# writes 44.1 kHz / 16-bit / stereo WAV under /path/to/music/shuffle_ready/
shuffle-convert /path/to/music -o /path/to/out -f mp3
shuffle-convert /path/to/music --dry-run
```

By default, conversion uses **high-quality resampling** (SoXR when your ffmpeg supports it), **MP3 V0**, and **AAC 256 kbps**. If you hear ringing or “digital” grain, avoid `--fast` (that mode uses lighter resampling and lower bitrates). For the cleanest WAV, keep the default; re-encode from **lossless sources** when possible—transcoding MP3 → WAV cannot remove existing compression artifacts.

## 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`