crates

Music library metadata and organization tools.

Features

• Album organization with MusicBrainz/Discogs metadata lookup
• Folder naming: {Artist} - {Album}
• File naming: {Track}. {Artist} - {Album} - {Title}.[mp3/m4a]
• Multi-disc album support, artwork fetching, checkpoint progress
• Interactive repair for unmatched albums

Installation

uv sync

Setup

Discogs API Token (optional)

To enable Discogs metadata lookup, get a personal access token:

1. Create an account at discogs.com
2. Go to Settings → Developers → Generate new token
3. Set the environment variable:

export CRATES_DISCOGS_TOKEN=your_token_here

MusicBrainz works without authentication.

Usage

# Organize albums with metadata lookup (preview mode)
crates albums /path/to/music

# Execute changes (rename files/folders)
crates albums /path/to/music --execute

# Move unmatched albums to _NotFound/_Incomplete folders
crates albums /path/to/music --execute --isolate

# Interactive repair for _NotFound and _Incomplete folders
crates repair /path/to/music

# Update filenames from ID3 tags
crates meta_to_filename /path/to/music --execute

# Update ID3 tags from filenames
crates filename_to_meta /path/to/music --execute

# Convert M4A to MP3
crates to_mp3 /path/to/file.m4a

# Download from URL (YouTube, etc.)
crates rip "https://youtube.com/watch?v=..."

Commands

Command	Description
albums	Clean and tag albums using MusicBrainz/Discogs
repair	Interactive repair for NotFound and Incomplete albums
meta_to_filename	Rename files based on ID3 tags
filename_to_meta	Update ID3 tags from filenames
to_mp3	Convert M4A files to MP3
rip	Download and convert audio/video from URLs (requires yt-dlp, ffmpeg)

TODO at some point

Soulseek Integration

• Auto-patching incomplete albums
• Missing track detection and automated downloading
• Using aioslsk

Library Management

• SQLite database instead of checkpoint files
• Duplicate detection across library
• Playlist export (M3U, etc.)
• Spotify/Apple Music/Tidal playlist sync
• Bandcamp purchases integration

DJ Features

• BPM/key detection (librosa, Essentia)
• Cue point management, beatgrid editing
• Playlist/crate organization
• Serato/Rekordbox library sync

Desktop App

• React/Solid frontend for match review
• Python/FastAPI backend service
• Audio analysis via librosa/madmom or Rust