Essentia Genres for MusicBrainz Picard 3

Essentia Genres combines a MusicBrainz Picard 3 plugin with an isolated Docker worker that predicts genres using Essentia and the MAEST-519 model. Predictions are added to Picard's unsaved genre metadata for review; Picard remains responsible for writing tags to audio files.

The plugin can translate the model's raw Discogs labels to Rate Your Music names or another user-owned vocabulary before applying metadata. The active map is stored in Picard and can be imported or exported as versioned UTF-8 JSON.

This is the umbrella development repository. The directly installable plugin is maintained as the plugin/ Git submodule. Do not install the umbrella repository in Picard.

Compatibility target: MusicBrainz Picard 3.0, plugin API 3.0.

Architecture

Picard plugin -- docker run + JSON lines --> Essentia worker container
      |                                           |
      +-- updates unsaved genre metadata          +-- reads /music and /models

Essentia and TensorFlow never load into the Picard process. Normal analysis runs without network access, with a read-only root filesystem and read-only music and model mounts. A separate, user-confirmed initialization container downloads and verifies model files.

The worker loads one pinned discogs-maest-30s-pw-519l graph. It decodes mono audio at 16 kHz, analyzes completed non-overlapping 30-second windows, and averages their probabilities before selecting track-level genres.

Quick start

1. Install the prerequisites described in the usage guide.

2. Build the cataloged CPU worker image from the umbrella repository:

   .\scripts\build_cpu_worker.ps1
   

3. In Picard, open Options → Plugins → Install Plugin and install the dedicated plugin repository.

4. Enable Essentia Genres, choose the music-library folder, and click Prepare / Verify Models….

5. Select files or tracks, choose Analyze Essentia Genres…, review the predicted genres, and use Picard's normal Save operation when satisfied.

CPU is the default. NVIDIA GPU execution requires a separately built GPU image and Docker GPU support; see the GPU qualification guide.

Documentation

• Documentation index: entry point for all project docs.
• Usage guide: setup, configuration, and analysis.
• Troubleshooting: runtime and GPU failures.
• Development guide: checkout, builds, and validation.
• Worker protocol: canonical NDJSON contract.
• Release checklist: coordinated release procedure.

OpenSpec requirements and archived design decisions live under openspec/.

Development

Clone the umbrella repository recursively:

git clone --recurse-submodules https://git.n00levoy.space/picard-plugins/essentia-genres-picard.git
cd essentia-genres-picard
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt

Run the local validation sequence before coordinating a plugin revision with the umbrella repository:

.\.venv\Scripts\python.exe scripts\validate_submodule.py
.\.venv\Scripts\python.exe plugin\scripts\validate_distribution.py
.\.venv\Scripts\python.exe scripts\versioning.py check
.\.venv\Scripts\ruff.exe check .
.\.venv\Scripts\ruff.exe format --check .
.\.venv\Scripts\python.exe -m pytest -q
openspec validate --all --strict --no-interactive
git diff --check

The project uses local validation rather than hosted CI. Environment-gated Picard, Docker, Essentia, and GPU checks are documented in the development guide.

Releases

versions.json is the authoritative catalog for the coordinated semantic version, worker image variants, protocol version, CUDA cache schema, dependency pins, and reproducible build inputs. Use scripts/versioning.py instead of editing managed version strings directly.

A release pairs an exact plugin commit with the umbrella commit that pins it and immutable CPU/GPU worker image digests. Follow the coordinated release checklist.

Licensing

See LICENSE.md and NOTICE.md. The plugin, worker, Essentia library, NVIDIA CUDA/cuDNN runtime, and pretrained models have separate license boundaries. Confirm that your intended use complies with the applicable licenses before downloading or distributing components.