Skip to content

Getting Started

Prerequisites

CrateDigger requires Python 3.11 or newer, plus several media tools.

Required tools

Tool Purpose
MediaInfo Extract media metadata (duration, codec, resolution)
FFmpeg (includes ffprobe) Probe media files, extract thumbnails
MKVToolNix (mkvpropedit, mkvextract, mkvmerge) Read and write MKV tags, chapters

Install dependencies

sudo apt install mediainfo ffmpeg mkvtoolnix

brew install media-info ffmpeg mkvtoolnix

scoop install mediainfo ffmpeg mkvtoolnix

Download and install each tool, then add their directories to your system PATH:

If the tools are not on your PATH, you can set explicit paths in the configuration.

Install CrateDigger

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

For poster generation with advanced image processing (optional):

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

Verify the installation:

cratedigger --help

First run

1. Copy the example config

mkdir -p ~/.cratedigger
cp config.example.json ~/.cratedigger/config.json

Edit ~/.cratedigger/config.json to add your credentials and preferences. At minimum, you may want to:

  • Set your 1001Tracklists email and password (for the identify command)
  • Set your fanart.tv personal API key (for artist artwork lookups)
  • Choose a default layout

See Configuration for all available options.

2. Copy the example festivals file

cp festivals.example.json ~/.cratedigger/festivals.json

This provides a starting set of festival definitions with aliases, editions, and colors. See Festivals for details.

Step 1: Identify

Match your recordings against 1001Tracklists to embed chapter markers and metadata:

cratedigger identify ~/Downloads/sets/

This searches 1001Tracklists for each MKV/WEBM file, lets you pick the correct tracklist, and embeds chapter markers directly into the file. Use --auto for batch processing without prompts.

Step 2: Organize

Move files into a structured library:

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

This classifies each file as a festival set or concert recording, then copies it into the library using your configured folder layout and filename template.

Step 3: Enrich

Add artwork, posters, NFO files, and tags:

cratedigger enrich ~/Music/Library/

This generates cover art, looks up artist fanart, creates poster images, writes NFO metadata files, and embeds MKV tags.

One-step organize + enrich

You can combine organizing and enriching in a single pass:

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