Festival set & concert library manager. Organize, enrich, and curate your collection with professional artwork, metadata, and chapter markers.

CrateDigger is a Python CLI tool for managing festival set and concert recording libraries. It follows a three-command workflow: identify matches recordings against 1001Tracklists and embeds chapter markers, organize moves files into your library with smart folder layouts, and enrich generates posters, artwork, NFO files, and embeds tags. CrateDigger integrates with Kodi for a polished media center experience, complete with artwork, metadata, and library sync.

Pair it with TrackSplit: a sibling CLI that extracts chapter-based audio from your video library into gapless, tagged FLAC albums for Jellyfin, Lyrion, and other music servers. TrackSplit reads CrateDigger's place and artist config, so canonical naming and MusicBrainz IDs stay consistent across your video and music libraries. Landing page · Documentation · GitHub

Set Posters

Album Posters

Match recordings against 1001Tracklists to retrieve full tracklist metadata. Chapter markers are embedded directly into MKV files, giving you track-by-track navigation. DJ artwork and event details are pulled in automatically.

Sort your library using four folder layouts: artist_flat, place_flat, artist_nested, and place_nested. Sonarr-style collapsing tokens let you group events under a single folder (for example, grouping all Ultra stages together). Files can be copied, moved, or renamed in place. The older names festival_flat and festival_nested continue to work as deprecated aliases.

Extract cover art from video files, fetch HD ClearLOGOs and artist fanart from fanart.tv, and generate posters in two distinct styles (set posters and album posters). Kodi-compatible NFO files are written alongside each recording. MKV tags are embedded with full metadata including artist, event, date, and tracklist info.

Trigger library refreshes over JSON-RPC so Kodi picks up new content automatically. Automatic path mapping translates between local and Kodi filesystem paths. NFO files follow Kodi conventions for seamless scraper compatibility.

Interactive runs check GitHub for newer stable releases and print a one-line upgrade hint. See Update Check for the full reference.

• Python 3.11+
• MediaInfo
• FFmpeg
• MKVToolNix

pipx (recommended for end users): pipx installs CrateDigger into an isolated environment and puts the cratedigger command on your PATH automatically.

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

Upgrade later with:

pipx upgrade cratedigger

pip (user site or venv): If you prefer pip or are working inside a virtual environment:

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

Upgrade later with:

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

Optional: install with frame sampling support for higher-quality poster backgrounds (uses OpenCV to score video frames):

pipx

pipx install "cratedigger[vision] @ git+https://github.com/Rouzax/CrateDigger.git"

pip

pip install "cratedigger[vision] @ git+https://github.com/Rouzax/CrateDigger.git"

# Step 1: Match recordings against 1001Tracklists and embed chapters
cratedigger identify /path/to/downloads

# Step 2: Organize files into your library
cratedigger organize /path/to/downloads --output /path/to/library

# Step 3: Generate artwork, posters, NFO files, and embed tags
cratedigger enrich /path/to/library

CrateDigger reads settings from config.toml and supports library-level overrides. Copy config.example.toml from the repository as a starting point.

Curated data files (places.json, artists.json, artist_mbids.json) live in the same folder as config.toml. The older filename festivals.json continues to work as a fallback when places.json is not present. Caches and logs go to platform-standard locations (~/.cache/CrateDigger/ on Linux, $env:LOCALAPPDATA\CrateDigger\ on Windows) and are managed automatically.

A per-library override at {library}/.cratedigger/config.toml takes precedence over the user-level file. See the docs folder for a full configuration reference.

When you run CrateDigger interactively and a newer stable release is available on GitHub, it prints a one-line notice showing the new version and the upgrade command for your install method:

! CrateDigger 0.14.1 is available. Run: pipx upgrade cratedigger

The check uses a 2-second HTTP timeout, never delays your run, and is silent on any network failure. Results are cached locally for 24 hours on success and 1 hour on failure, so repeat runs do not hit the network.

Automatic suppression. The notice is suppressed whenever stdout is not a terminal, including pipes, redirects, cron jobs, and CI environments.

Disable explicitly. Set CRATEDIGGER_NO_UPDATE_CHECK=1 before running. The values true and yes are also accepted, case-insensitively.

No telemetry: the check is a read-only request to the GitHub Releases API. See the FAQ for cache locations by platform and the full list of upgrade-command variants.

Artwork displayed in this project is sourced from fanart.tv and 1001Tracklists. All artwork, logos, and trademarks belong to their respective owners. CrateDigger is not affiliated with any festival, artist, or platform shown.

This project is licensed under the GPL-3.0 License. See LICENSE for details.