clickwheel is a local, single-tenant tool: it runs on your Mac and works with your library and iPod in place. Here’s what it expects.Documentation Index
Fetch the complete documentation index at: https://docs.clickwheel.fm/llms.txt
Use this file to discover all available pages before exploring further.
System
macOS
macOS only. Mounting and writing the iPod use macOS disk tools.
Python 3.11+
Python 3.11 through 3.14, installed via pipx.
Supported iPods
clickwheel writes the iTunesDB format used by the click-wheel iPod line, with stock firmware, over USB. The iPod Classic is the primary, tested target; other models from the same era that use the same format should work too:- iPod Classic
- iPod 4th and 5th gen, including photo and video
- iPod mini
- iPod nano, 1st through 5th gen
iPod touch and iOS devices aren’t supported, nor the touchscreen nano
6th/7th gen (different on-device database).
/Volumes/IPOD and assumes 64 GB. Override with
ipod_mount and ipod_capacity_gb, see Configuration.
Audio formats
| Format | On the iPod? | Notes |
|---|---|---|
| MP3, AAC/M4A, ALAC | Yes | Played natively by stock firmware. |
| FLAC | Skipped | Stock firmware can’t play it, so it’s excluded from sync. Your FLACs stay in your library. |
Optional integrations
Everything below is optional and off until you set it up. The base install, includingfix metadata repair, needs none of it.
| Integration | Extra | Credentials |
|---|---|---|
| Plex / Plexamp | [plex] | Server URL + token |
| Apple Music | [applemusic] | MusicKit key (paid Apple Developer) |
| Last.fm | none | API key |
| MCP server | [mcp] | none |