Skip to content

CrateDigger

Festival set and concert library manager. CrateDigger organizes, enriches, and tags your DJ set and concert recordings into a clean, media-player-ready library.

What you get

After running CrateDigger on a folder of recordings:

  • Consistent folder structure and filenames, organized by artist, festival, year, or any combination
  • Cover art and generated poster images for every recording and every folder
  • NFO files that Kodi, Jellyfin, and Plex read to display title, artist, genre, and artwork
  • Structured MKV metadata tags for any tag-aware tool
  • Chapter markers (one per track) for navigation inside DJ sets, sourced from 1001Tracklists
  • MusicBrainz artist IDs, aligned with track-level performer tags

Three-command workflow

# Match recordings against 1001Tracklists, embed chapter markers
cratedigger identify ~/Downloads/sets/

# Organize into a library with consistent folder and file names
cratedigger organize ~/Downloads/sets/ --output ~/Music/Library/

# Add artwork, posters, NFO files, and metadata tags
cratedigger enrich ~/Music/Library/

Or organize and enrich in one pass:

cratedigger organize ~/Downloads/sets/ --output ~/Music/Library/ --enrich

1001Tracklists account (optional)

identify needs a free 1001Tracklists account. Without one, skip straight to organize and enrich. You still get an organized library, artwork, posters, and NFO files built from filename parsing and embedded metadata. See what you get with vs. without an account.

Install

pipx (recommended): installs CrateDigger into an isolated environment and puts cratedigger on your PATH.

pipx install git+https://github.com/Rouzax/CrateDigger.git

pip also works, for example inside a virtual environment:

pip install git+https://github.com/Rouzax/CrateDigger.git

See Getting Started for required tools, upgrade commands, config setup, and the recommended yt-dlp download settings.

TrackSplit is a sibling CLI that extracts chapter-based audio from your CrateDigger library into gapless, tagged FLAC albums for music servers like Jellyfin and Lyrion. TrackSplit reads CrateDigger's festival and artist config so canonical naming and MusicBrainz IDs stay consistent across your video and music libraries. See the TrackSplit documentation or source on GitHub.

Chapter Notify is a Kodi service addon that displays a styled overlay notification at the start of each chapter during playback, showing the artist, track title, and label. It reads the chapter markers and MKV tags that CrateDigger embeds, so no extra setup is needed beyond installing the addon. See the Chapter Notify repository for installation instructions and trigger mode options.

Documentation
Getting Started Installation, required tools, first run
identify Match tracklists, embed chapters
organize Library layouts, move vs. copy, templates
enrich Artwork, posters, NFO, MBIDs
audit-logos Check festival logo coverage
Configuration All config options
Festivals Festival names, aliases, editions
1001Tracklists Account setup, caching, what you get
Library layout Every file CrateDigger writes and why
Tag reference Every MKV tag CrateDigger writes
Kodi Integration JSON-RPC sync, path mapping
FAQ Common problems and troubleshooting