| name | fill-music-player |
| description | Use when a user wants to fill a portable music player (Walkman, iPod, USB drive) with a curated random selection from a music library on a NAS or local directory. Handles format filtering, artist/album diversity balancing, and size targeting. |
fill-music-player
Curates a DJ-balanced selection of tracks from a source music library and copies them to a portable player, respecting device capacity and supported formats.
Quick Reference
fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC --dry-run
fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC
uv run fill_music_player.py --source ~/Music --dest /Volumes/USB --dry-run
Run fill-music-player --help for all options.
Key Parameters
| Flag | Default | Purpose |
|---|
--source / -s | required | Source music root (NAS mount, ~/Music, etc.) |
--dest / -d | required | Player destination directory |
--target-gb | 95% of free space | How many GB to fill |
--formats | mp3,m4a,wma,aac | Allowed extensions |
--max-per-artist | 4 | Artist diversity cap |
--max-per-album | 3 | Album diversity cap |
--skip-dirs | (none) | Top-level dirs to skip |
--dry-run | false | Preview without copying |
Workflow
- Always do
--dry-run first
- Review the per-genre breakdown
- Adjust
--skip-dirs, --max-file-mb, or --max-per-artist if needed
- Run without
--dry-run to copy
Device Formats
| Device | Recommended --formats |
|---|
| Sony Walkman NWZ series | mp3,m4a,wma |
| iPod (classic/nano) | mp3,m4a,aac |
| Generic USB player | mp3 |
| Any modern player | mp3,m4a,wma,aac,ogg,flac |
Edge Cases and Troubleshooting
| Situation | What happens | Fix |
|---|
| NAS disconnects mid-copy | Copy fails for that file, logged as error, continues with next track | Re-run; already-copied files are skipped (if not dst.exists()) |
| Source has only FLAC/lossless | 0 files selected (FLAC not in default formats) | Use --formats flac or --formats mp3,flac |
| FAT32 filename too long or illegal chars | Filenames are sanitized: <>:"/|?* replaced with _, truncated to 80 chars | Automatic — no action needed |
| Mixed/broken ID3 tags | Falls back to folder name parsing (Genre/Artist - Album/track.mp3) | Works transparently; folder structure is the reliable fallback |
| Very large files (DJ mixes, radio shows) | Skipped by default (>20 MB) | Adjust with --max-file-mb 50 to include mixes |
| Tiny files (jingles, corrupt) | Skipped by default (<300 KB) | Adjust with --min-file-kb 100 to be more permissive |
| One artist dominates the library | Capped at 4 tracks per artist, 3 per album | Lower with --max-per-artist 2 for more variety |
| Empty genre directories | Silently skipped, no error | Normal behavior |
| Destination already has files | Existing files are not overwritten or deleted; new tracks added alongside | Clear destination first if you want a fresh set |
| SMB/NFS mount is slow | Scanning with mutagen tag reading can take 5-10 min for large libraries | Expected; the dry-run output appears once scanning completes |
Real-World Example
Filling a Sony Walkman NWZ-B183F (4 GB) from a Synology DS918+ NAS with ~9,000 tracks across blues, funk, hip-hop, soul, IDM, dubstep, dub, indie, and post-rock:
fill-music-player \
--source /Volumes/music \
--dest /Volumes/WALKMAN/MUSIC \
--skip-dirs "jingles,!recordings,!restored,dubrecords" \
--formats mp3,m4a,wma \
--dry-run
fill-music-player \
--source /Volumes/music \
--dest /Volumes/WALKMAN/MUSIC \
--skip-dirs "jingles,!recordings,!restored,dubrecords" \
--formats mp3,m4a,wma
Result: 348 tracks, 2.4 GB, balanced across 14 genres with max 4 tracks per artist. Artists included Fela Kuti, ZZ Top, Mobb Deep, Gregory Porter, Tinariwen, Chick Corea, Hudson Mohawke, and Funkadelic. Total copy time over SMB: ~12 minutes.
