110 lines
4.5 KiB
Markdown
110 lines
4.5 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 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`
|