---
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.
license: MIT
allowed-tools: Bash
compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires shell access and the fill-music-player CLI or underlying script in the target environment.
metadata:
  targets: [_source-only]
  author: Oleg Koval
  tags:
    - music
    - media
    - curation
    - copy
    - cli
---

# 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

```bash
# 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

1. Always do `--dry-run` first
2. Review the per-genre breakdown
3. Adjust `--skip-dirs`, `--max-file-mb`, or `--max-per-artist` if needed
4. 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:

```bash
# 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.