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-player-23description: 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---6<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->78# fill-music-player910Curates a DJ-balanced selection of tracks from a source music library and copies them to a portable player, respecting device capacity and supported formats.1112## Quick Reference1314```bash15# Dry run first (always recommend this)16fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC --dry-run1718# Copy for real19fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC2021# Or run the script directly with uv22uv run fill_music_player.py --source ~/Music --dest /Volumes/USB --dry-run23```2425Run `fill-music-player --help` for all options.2627## Key Parameters2829| Flag | Default | Purpose |30|------|---------|---------|31| `--source` / `-s` | required | Source music root (NAS mount, ~/Music, etc.) |32| `--dest` / `-d` | required | Player destination directory |33| `--target-gb` | 95% of free space | How many GB to fill |34| `--formats` | mp3,m4a,wma,aac | Allowed extensions |35| `--max-per-artist` | 4 | Artist diversity cap |36| `--max-per-album` | 3 | Album diversity cap |37| `--skip-dirs` | (none) | Top-level dirs to skip |38| `--dry-run` | false | Preview without copying |3940## Workflow41421. Always do `--dry-run` first432. Review the per-genre breakdown443. Adjust `--skip-dirs`, `--max-file-mb`, or `--max-per-artist` if needed454. Run without `--dry-run` to copy4647## Device Formats4849| Device | Recommended `--formats` |50|--------|------------------------|51| Sony Walkman NWZ series | `mp3,m4a,wma` |52| iPod (classic/nano) | `mp3,m4a,aac` |53| Generic USB player | `mp3` |54| Any modern player | `mp3,m4a,wma,aac,ogg,flac` |5556## Edge Cases and Troubleshooting5758| Situation | What happens | Fix |59|-----------|-------------|-----|60| 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()`) |61| Source has only FLAC/lossless | 0 files selected (FLAC not in default formats) | Use `--formats flac` or `--formats mp3,flac` |62| FAT32 filename too long or illegal chars | Filenames are sanitized: `<>:"/\|?*` replaced with `_`, truncated to 80 chars | Automatic, no action needed |63| Mixed/broken ID3 tags | Falls back to folder name parsing (`Genre/Artist - Album/track.mp3`) | Works transparently; folder structure is the reliable fallback |64| Very large files (DJ mixes, radio shows) | Skipped by default (>20 MB) | Adjust with `--max-file-mb 50` to include mixes |65| Tiny files (jingles, corrupt) | Skipped by default (<300 KB) | Adjust with `--min-file-kb 100` to be more permissive |66| One artist dominates the library | Capped at 4 tracks per artist, 3 per album | Lower with `--max-per-artist 2` for more variety |67| Empty genre directories | Silently skipped, no error | Normal behavior |68| Destination already has files | Existing files are not overwritten or deleted; new tracks added alongside | Clear destination first if you want a fresh set |69| 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 |7071## Real-World Example7273Filling 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:7475```bash76# Step 1: Preview77fill-music-player \78 --source /Volumes/music \79 --dest /Volumes/WALKMAN/MUSIC \80 --skip-dirs "jingles,!recordings,!restored,dubrecords" \81 --formats mp3,m4a,wma \82 --dry-run8384# Output:85# Found 8914 candidate tracks across 14 genres86# Funk → 86 tracks (440.8 MB)87# blues → 38 tracks (316.7 MB)88# hiphop → 33 tracks (234.7 MB)89# ...90# Selected 348 tracks (2473.0 MB)9192# Step 2: Copy93fill-music-player \94 --source /Volumes/music \95 --dest /Volumes/WALKMAN/MUSIC \96 --skip-dirs "jingles,!recordings,!restored,dubrecords" \97 --formats mp3,m4a,wma98```99100Result: 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