Skip to the rows

agentsclimarketplace

Fill music player

Skill oleg-koval/agent-skills/packages/music/fill-music-player/adapters/cursor/skills/fill-music-player

Opinionated agent skill catalog for Codex, Claude, Cursor, Copilot, and launch workflows.

Install

npx -y skills add oleg-koval/agent-skills --skill fill-music-player

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.7 KB, as published. Nobody here has run it

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.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.