Music Manager

Organize messy music files and auto-populate albums using spotdl (YouTube downloads with Spotify metadata). Works great with Nextcloud Music.

Features

Organize files into Artist/Album
Auto-download full albums by folder names
Complete partial albums (optional)
Reads tags or parses "Artist - Title" filenames
Skips existing files, embeds metadata/art

Requirements

Python 3.9+
uv (package/venv)
spotdl

Install (uv)

# In project root
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .
uv pip install spotdl

Optional (improves matching):

export SPOTIFY_CLIENT_ID="your_id"
export SPOTIFY_CLIENT_SECRET="your_secret"

Commands

Organize existing files:

music-organize SOURCE DEST            # organize
music-organize SOURCE DEST --dry-run  # preview

Auto-populate from folders:

# Create folders: Music/Artist/Album (empty or partial)
music-autopop LIBRARY                 # download empty albums
music-autopop LIBRARY --dry-run       # preview
music-autopop LIBRARY --include-partial  # complete partial albums

Tips

Use exact artist/album names for best results
Singles (no album) go to Artist/Singles
Always try --dry-run first

Troubleshooting

spotdl not found: uv pip install spotdl
Recreate venv: rm -rf .venv && uv venv && source .venv/bin/activate && uv pip install -e .
Wrong matches: rename folder to exact album name (add year if needed)

License

MIT