README

MusicBrainz metadata provider for Phlix — enriches your music library with artist/album/track metadata and album art from the Cover Art Archive.

Overview

Connects a Phlix server to MusicBrainz to enrich music items with comprehensive metadata:

Artist metadata — name, sort name, aliases, type, country, begin/end dates and areas, disambiguation, tags, genres
Album metadata — release date, country, label, catalog number, barcode, media format, ASIN, full artist credit (featured artists and joinphrases)
Track metadata — track number, position, duration (duration_ms, milliseconds — the host's own duration is seconds), ISRC codes, full artist credit
Album artwork — the front cover is fetched from the Cover Art Archive; item metadata persists an album_art presence marker (the image bytes themselves need a dedicated host-side artwork ingestion hook)

It subscribes to phlix.library.item.added and enqueues each item in src/EnrichmentQueue.php, so enrichment runs deferred and throttled instead of inline during a library scan.

Install

From the Phlix admin Plugins section, paste this repo's URL:

https://github.com/detain/phlix-plugin-musicbrainz

…or from the CLI:

php bin/phlix plugin:install https://github.com/detain/phlix-plugin-musicbrainz

Settings

All settings are optional — MusicBrainz is an open service, so no API key is required.

Setting	Type	Default	Description
`enabled`	boolean	`false`	Master on/off for MusicBrainz enrichment. Optional; default off. No API key needed — MusicBrainz is an open service.
`user_agent`	string	`PhlixMusicBrainzPlugin/0.4.0 (…)`	Identifies Phlix to MusicBrainz (their policy REQUIRES a descriptive User-Agent with contact info). Enforced: the plugin only runs enrichment when the value contains a URL (the `://` substring) — an email-only contact like `MyFork/1.0 (me@example.com)` FAILS the gate and the plugin stays a no-op; include a project/contact URL (an email may sit alongside it). Optional — the default is fine; customise if you run a fork. See MusicBrainz API etiquette.
`rate_limit_delay`	integer	`1100`	Minimum delay between MusicBrainz requests (ms). Optional; default 1100 (MusicBrainz asks for no more than ~1 request/second). Values below 1000 are raised to the 1000 ms ToS floor; non-integer or ≤0 values fall back to the 1100 default.
`auto_enrich`	boolean	`true`	Automatically enrich music items as they are scanned. Optional; default on.
`fetch_album_art`	boolean	`true`	Pull cover art via the Cover Art Archive. Optional; default on.
`search_depth`	string	`normal`	How hard to search for matches: fast, normal or deep. Optional; default normal.

Development

composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse -c phpstan.neon   # level 9, zero baseline entries
vendor/bin/phpcs src --standard=PSR12
# audits the whole composer.lock (require AND require-dev); the composer-audit CI job runs this
php scripts/security-audit-check.php

Requirements: PHP >= 8.3 with ext-curl (declared in composer.json) — curl is the documented CLI/test fallback transport only; inside the resident Workerman server process the plugin uses the host's Workerman\Http\Client instead (soft dependency, class_exists-guarded). Host-supplied classes the plugin talks to through the DI container (Phlix\Media\Library\*, Workerman\Http\Client, Workerman\Timer) are deliberately not composer dependencies; PHPStan resolves them through verbatim-shape stubs under tests/Stub/ wired via bootstrapFiles, so the level 9 gate runs clean with no ignoreErrors and no baseline file (M-MUSICBRAINZ-10/21).

The entry class is Phlix\Plugin\MusicBrainz\MusicBrainzPlugin (implements Phlix\Shared\Plugin\LifecycleInterface and Phlix\Shared\Plugin\ConfigurableInterface). It runs inside a Phlix server host, which provides the library services at runtime.

API Rate Limiting

MusicBrainz requires no more than 1 request per second. This plugin enforces a configurable delay (default 1100ms) between all API calls, and src/EnrichmentQueue.php releases at most one queued item per interval (floor of 1s) so the budget holds across a whole scan. Please configure a valid user_agent with contact information so MusicBrainz can reach you if there are issues. The gate is enforced, not advisory: a user_agent without a URL (the :// substring) — e.g. an email-only contact — makes isConfigured() false and the plugin silently declines to enqueue or enrich anything. Put a project or contact URL in the UA; add your e-mail alongside it if you like.

License

MIT — see LICENSE.

detain / phlix-plugin-musicbrainz

Package info

Security

Statistics