Download your YouTube Music playlists into a properly tagged local library, then sync it to an iPod. Runs on Linux, Windows and macOS (Python + Qt).
YouTube Music ──ytmusicapi──▶ metadata (album, track #, year, art)
└──yt-dlp─────▶ AAC .m4a ──mutagen──▶ ~/Music/Clickwheel/Artist/Album/01 Title.m4a
Playlists/*.m3u8
──pyPodLib──▶ iPod (iTunesDB/CDB + artwork, signed per model)
──iTunesSD──▶ iPod Shuffle
──file copy─▶ Rockbox
uv sync
uv run clickwheel # GUI
uv run clickwheel --help # CLI: login / download / devices / sync
uv run pytest # tests (uses virtual iPods, no hardware needed)ffmpeg must be on PATH (on Windows/macOS it is fetched automatically if missing).
yt-dlp's JavaScript runtime comes from the bundled deno wheel, so nothing else to install.
Download the latest build from Releases:
Clickwheel-windows-x64-setup.exe (Windows), the .dmg for your Mac (Apple Silicon or Intel), or
Clickwheel-linux-x86_64.AppImage (Linux).
The Mac and Windows apps include everything they need, ffmpeg and ffprobe among them; the Linux
builds use the distribution's ffmpeg. The bundled ffmpeg is GPL software (license in the app's
licenses folder): the Mac builds are compiled by packaging/build-ffmpeg-macos.sh from the
FFmpeg, LAME and x264 sources it names, and the Windows builds use
Gyan Doshi's release, whose source is
linked from its README.
GitHub Actions builds the installers, plus the .zip/.tar.gz/.dmg packages the updater uses. Starting the Build workflow from the Actions tab produces test builds (artifacts on the
run page). Tests alone run on every push.
Pushing a version tag publishes a release here with the installers and SHA256SUMS.txt.
Clickwheel checks for a newer release once a day (and via Help ▸ Check for updates),
downloads the build for your platform, verifies its checksum, swaps itself out and restarts.
To publish a version:
# CI stamps the version from the tag; no file to bump
git tag -a v0.2.0 -m "What's new in this version (shown in the update dialog)"
git push origin v0.2.0To build locally for the current OS: uv run pyinstaller packaging/clickwheel.spec → dist/.
The builds aren't code-signed, so the OS warns the first time you open them:
- macOS: open the app once, then System Settings ▸ Privacy & Security ▸ Open Anyway
(or run
xattr -dr com.apple.quarantine /Applications/Clickwheel.app). - Windows: SmartScreen ▸ More info ▸ Run anyway.
YouTube Music has no OAuth flow a desktop app can ship, so Clickwheel reuses your browser session. Sign in at music.youtube.com in a browser, then in Clickwheel choose Sign in… and either:
- From browser: reads the cookies directly. Firefox works everywhere. Recent Chrome on Windows encrypts cookies so other apps can't read them; use Firefox or one of the other two options there.
- Paste headers: copy the request headers of a
browserequest from DevTools ▸ Network. - Cookies file: a
cookies.txtexported by a browser extension.
Credentials are stored with user-only permissions in the platform config dir
(~/.config/Clickwheel on Linux). Public playlist/album/song links work without signing in;
signing in adds your library playlists, private playlists and (with Premium) 256 kbps audio.
- Audio is YouTube's native AAC stream (128 kbps, 256 kbps with Premium), so it isn't re-encoded and every iPod plays it.
- Tags come from YouTube Music's album pages: title, artists, album artist, album, track n/N, year, explicit flag, "The …" sort names, and 1000 px square cover art. Each file also stores its YouTube ID.
- Music videos in a playlist are swapped for the matching album track when there is one. Matching uses the same artist, the same title and a length within 30 s, so covers and karaoke versions are never substituted. Turn this off in Settings.
- File and folder names are safe on FAT32 and Windows.
- Re-running a playlist ("Update from YouTube Music") downloads only new songs.
| Device | Method | Notes |
|---|---|---|
| iPod 1G–5.5G, Mini, Photo, Nano 1G–2G | iTunesDB | no signature needed |
| Classic 6G/6.5G/7G, Nano 3G–4G | iTunesDB + hash58 | key derived from the device's FireWire ID automatically |
| Nano 5G | iTunesCDB + hash72 | needs one iTunes/Finder sync first so the device has a HashInfo file |
| Nano 6G/7G | SQLite + hashAB | supported by pyPodLib; least tested on real hardware |
| Shuffle 1G–4G | iTunesDB + iTunesSD | Clickwheel writes iTunesSD itself (pyPodLib doesn't) |
| Any iPod with Rockbox | file mirror | /Music/... + /Playlists/*.m3u8; only files Clickwheel copied are ever deleted |
| iPod touch | — | not possible: iOS only accepts music from Finder/iTunes |
Sync is one-way: library ➜ iPod. Songs you delete from the library are removed from the iPod on the next sync. Songs that were already on the iPod from iTunes are left alone.
Filesystem: a Windows-formatted (FAT32) iPod works on every OS. A Mac-formatted (HFS+) iPod works on macOS and, if journaling is off, on Linux; Windows can't write to it.
devices/apple.pypatches two pyPodLib 0.1.0 issues at import time: the missingpodcastssubpackage (it would break every sync), and playlist names derived from file names (we read#PLAYLIST:instead). pyPodLib is pinned to==0.1.0for this reason. Re-check both patches before upgrading.devices/itunessd.pyimplements both iTunesSD formats (v1 big-endian 558-byte entries for 1G/2G, v2bdhschunks for 3G/4G).
Downloading from YouTube is against YouTube's Terms of Service. This is meant for personal listening of music you have access to.