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
# Dry run first (always recommend this)
fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC --dry-run
# Copy for real
fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC
# Or run the script directly with uv
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:
# Step 1: Preview
fill-music-player \
--source /Volumes/music \
--dest /Volumes/WALKMAN/MUSIC \
--skip-dirs "jingles,!recordings,!restored,dubrecords" \
--formats mp3,m4a,wma \
--dry-run
# Output:
# Found 8914 candidate tracks across 14 genres
# Funk → 86 tracks (440.8 MB)
# blues → 38 tracks (316.7 MB)
# hiphop → 33 tracks (234.7 MB)
# ...
# Selected 348 tracks (2473.0 MB)
# Step 2: Copy
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.
1---2name: fill-music-player3description: 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.4license: MIT5---67# fill-music-player89Curates a DJ-balanced selection of tracks from a source music library and copies them to a portable player, respecting device capacity and supported formats.1011## Quick Reference1213```bash14# Dry run first (always recommend this)15fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC --dry-run1617# Copy for real18fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC1920# Or run the script directly with uv21uv run fill_music_player.py --source ~/Music --dest /Volumes/USB --dry-run22```2324Run `fill-music-player --help` for all options.2526## Key Parameters2728| Flag | Default | Purpose |29|------|---------|---------|30| `--source` / `-s` | required | Source music root (NAS mount, ~/Music, etc.) |31| `--dest` / `-d` | required | Player destination directory |32| `--target-gb` | 95% of free space | How many GB to fill |33| `--formats` | mp3,m4a,wma,aac | Allowed extensions |34| `--max-per-artist` | 4 | Artist diversity cap |35| `--max-per-album` | 3 | Album diversity cap |36| `--skip-dirs` | (none) | Top-level dirs to skip |37| `--dry-run` | false | Preview without copying |3839## Workflow40411. Always do `--dry-run` first422. Review the per-genre breakdown433. Adjust `--skip-dirs`, `--max-file-mb`, or `--max-per-artist` if needed444. Run without `--dry-run` to copy4546## Device Formats4748| Device | Recommended `--formats` |49|--------|------------------------|50| Sony Walkman NWZ series | `mp3,m4a,wma` |51| iPod (classic/nano) | `mp3,m4a,aac` |52| Generic USB player | `mp3` |53| Any modern player | `mp3,m4a,wma,aac,ogg,flac` |5455## Edge Cases and Troubleshooting5657| Situation | What happens | Fix |58|-----------|-------------|-----|59| 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()`) |60| Source has only FLAC/lossless | 0 files selected (FLAC not in default formats) | Use `--formats flac` or `--formats mp3,flac` |61| FAT32 filename too long or illegal chars | Filenames are sanitized: `<>:"/\|?*` replaced with `_`, truncated to 80 chars | Automatic, no action needed |62| Mixed/broken ID3 tags | Falls back to folder name parsing (`Genre/Artist - Album/track.mp3`) | Works transparently; folder structure is the reliable fallback |63| Very large files (DJ mixes, radio shows) | Skipped by default (>20 MB) | Adjust with `--max-file-mb 50` to include mixes |64| Tiny files (jingles, corrupt) | Skipped by default (<300 KB) | Adjust with `--min-file-kb 100` to be more permissive |65| One artist dominates the library | Capped at 4 tracks per artist, 3 per album | Lower with `--max-per-artist 2` for more variety |66| Empty genre directories | Silently skipped, no error | Normal behavior |67| Destination already has files | Existing files are not overwritten or deleted; new tracks added alongside | Clear destination first if you want a fresh set |68| 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 |6970## Real-World Example7172Filling 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:7374```bash75# Step 1: Preview76fill-music-player \77 --source /Volumes/music \78 --dest /Volumes/WALKMAN/MUSIC \79 --skip-dirs "jingles,!recordings,!restored,dubrecords" \80 --formats mp3,m4a,wma \81 --dry-run8283# Output:84# Found 8914 candidate tracks across 14 genres85# Funk → 86 tracks (440.8 MB)86# blues → 38 tracks (316.7 MB)87# hiphop → 33 tracks (234.7 MB)88# ...89# Selected 348 tracks (2473.0 MB)9091# Step 2: Copy92fill-music-player \93 --source /Volumes/music \94 --dest /Volumes/WALKMAN/MUSIC \95 --skip-dirs "jingles,!recordings,!restored,dubrecords" \96 --formats mp3,m4a,wma97```9899Result: 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.
oleg-koval