Fill Music Player

fill-music-player

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.

oleg-koval/agent-skills·0installs3stars

SKILL.md

Full skill instructions

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.

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/oleg-koval/agent-skills --skill fill-music-player

View on GitHub

packages/music/fill-music-player/adapters/cursor/skills/fill-music-player/SKILL.md

semantic-release-beta
Set up or update a Node.js release pipeline that uses semantic-release-npm-github-publish with a stable main channel and a prerelease beta channel on a beta branch, including GitHub Actions validation and npm publishing behavior.
0 installs
git-commit
Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from d...
0 installs
gallery
Create photo galleries with AI-assisted layout curation. Orchestrates atomic scripts and sub-agents. Use when user wants to create a gallery from photos, mentions "/gallery", or asks about photo layout and sequencing.
0 installs
changelog-generator
Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.
0 installs

More skills from oleg-koval

oleg-koval/agent-skills

promptctl

Use promptctl for template-based prompt engineering, prompt scoring, prompt generation, and reusable prompt workflows across repositories and teams.

3 0

View

oleg-koval/agent-skills

product-builder

Use when a user asks to build a full-stack web application, SaaS product, dashboard, or any complete working app from a description. Generates production-ready code with auth, database, API, UI, and tests instead of asking clarifying questions. Activates on "build me X", "create an app that", or ...

3 0

View

oleg-koval/agent-skills

docs-index-keeper

Keep a repository's Markdown docs index in sync by installing and running docs-index-keeper in pre-commit hooks, CI, or one-off maintenance flows.

3 0

View

oleg-koval/agent-skills

gh-cli

GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line.

3 0

View

oleg-koval/agent-skills

viral-launch

Set up a project repository and launch plan for shareable marketing, public launch readiness, and growth loops without pretending virality is guaranteed.

3 0

View