fill-music-player

Fill a portable music player with a curated, DJ-balanced random selection from your music library.

Point it at a music folder (NAS, ~/Music, external drive) and a destination (Walkman, iPod, USB stick). It scans for audio files, reads ID3/MP4/WMA tags, balances by artist and genre, and copies a shuffled selection that fits your player's capacity.

Install

# Option 1: run directly with uv (no install needed)
uvx fill-music-player --help

# Option 2: install from PyPI
pip install fill-music-player

# Option 3: run the script directly
uv run fill_music_player.py --help

Usage

# Always dry-run first to preview the selection
fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC --dry-run

# Then copy for real
fill-music-player --source /Volumes/music --dest /Volumes/WALKMAN/MUSIC

Common examples

# Fill a Sony Walkman from a Synology NAS
fill-music-player -s /Volumes/music -d /Volumes/WALKMAN/MUSIC

# Target exactly 2 GB, MP3 only
fill-music-player -s ~/Music -d /media/usb/MUSIC --target-gb 2 --formats mp3

# Skip radio recordings and jingles folders
fill-music-player -s /Volumes/music -d /Volumes/PLAYER \
    --skip-dirs "jingles,!recordings,!restored"

# Reproducible selection (same seed = same tracks every time)
fill-music-player -s /Volumes/music -d /Volumes/PLAYER --seed 42

# Tighter artist diversity (max 2 tracks per artist)
fill-music-player -s /Volumes/music -d /Volumes/PLAYER --max-per-artist 2

How it works

1. Scan — walks your music library for supported audio files (MP3, M4A, WMA, AAC by default)
2. Filter — skips files that are too large (radio shows/mixes) or too small (jingles/corrupt)
3. Read tags — extracts artist/album from ID3, MP4, or WMA metadata; falls back to folder name parsing (Genre/Artist - Album/track.mp3)
4. Curate — allocates a proportional byte budget per genre directory, then picks tracks while enforcing artist and album diversity caps
5. Shuffle — globally randomizes the final selection so genres are interleaved
6. Copy — writes files to the destination preserving the genre/artist/album/track structure, with FAT32-safe filenames

Options

Device format cheat sheet

Expected folder structure

The tool expects your source music to be organized as:

/Volumes/music/
  blues/
    Muddy Waters - Electric Mud/
      01 - Tom Cat.mp3
    ZZ Top/
      1983 - Eliminator/
        01 Gimme All Your Lovin.mp3
  funk/
    Fela Kuti/
      ...
  hiphop/
    Dr.Dre - The Chronic/
      ...

Top-level directories are treated as genre categories. Artist/album info comes from metadata tags first, folder names second.

AI agent skill

This tool also works as a Claude Code / pi.dev skill. Copy the SKILL.md to your skills directory and the agent will know when and how to use it.

License

MIT