Essentia Genres for MusicBrainz Picard 3

This repository is the directly installable Picard v3 plugin for the Essentia Genres project. It sends explicitly selected audio to a separately distributed Docker worker and places predicted genres into Picard's unsaved metadata for review.

Picard loads the root __init__.py lifecycle adapter. Runtime implementation is kept separately under essentia_genres/; Docker command construction, worker transport, model initialization, and environment checks have focused modules.

Compatibility target: MusicBrainz Picard 3.0, plugin API 3.0.

Install

In Picard, open Options → Plugins → Install Plugin, choose installation from a Git repository, and enter this repository's clone URL. For a local checkout, choose this directory, which contains MANIFEST.toml and __init__.py. Enable Essentia Genres, choose the music-library folder and CPU or NVIDIA GPU, then use Prepare / Verify Models….

Normal configuration is split into a primary page for setup and genre output, plus nested Genre Mapping and Advanced pages. Genre Mapping translates the pinned model's raw Discogs labels to Rate Your Music names or another preferred vocabulary, supports aliases and omissions, and imports or exports a versioned UTF-8 JSON map. The map is copied into Picard configuration, so an imported file does not need to remain available. Unmapped labels keep their selected built-in formatting by default or can be omitted.

The plugin calculates docker, the version-matched CPU/GPU worker image, GPU device all, and an application-local model directory. Advanced exposes effective values and optional overrides for custom Docker executables, model directories, worker images, GPU selectors, duration, fallback, and confidence diagnostics. Recognized settings from the earlier flat page migrate automatically; custom paths and images remain overrides.

The worker image is not included here. Project architecture, worker build and configuration instructions, protocol documentation, integration tests, issue tracking, and development planning live in the umbrella repository:

Essentia Genres umbrella repository

GPU analysis mounts the versioned Docker volume picard-essentia-genres-cuda-cache-v2 at /var/cache/essentia-cuda. CPU analysis and model initialization do not mount or use that volume. The earlier picard-essentia-genres-cuda-cache volume is retained for rollback and may be removed manually after the upgraded GPU worker is accepted.

Validate a checkout

python scripts/validate_distribution.py

The dependency-free validator checks the required Picard root files, compiles tracked Python sources, loads the lazy entry point, and rejects loose root implementation modules or umbrella-only project content.

The repository is validated locally. Run this command before coordinating the plugin revision with the umbrella repository.

Licensing

See COPYING, LICENSE.md, and NOTICE.md. The plugin, worker, Essentia library, and pretrained models have separate license boundaries.