AcoustID Lookup Provider

AcoustID Lookup works out what a track is by listening to it. It takes a fingerprint of the actual sound and looks that up in the AcoustID database, which tells it which recording this is.

That matters because Music Assistant normally relies on the tags in your files to fetch artwork, descriptions and biographies. Where the tags are thin or missing, nothing can be found. Once AcoustID has identified a track, all of that becomes available, and the same track from different sources is matched up more reliably.

You have to switch this provider on yourself. It comes ready to use, or you can supply a free key of your own from acoustid.org.

Who should enable it

This provider is intended for libraries containing audio files that lack a MusicBrainz Recording Id. For local files, this typically means tracks not yet tagged with MusicBrainz Picard or an equivalent tool. For streaming providers, this typically means catalogues with limited metadata (for example, YouTube Music).

The largest visible improvement is for albums that currently show no cover art in Music Assistant because their tags do not include a MusicBrainz identifier. Once a release-group is identified, art and metadata are fetched automatically by the existing Cover Art Archive, fanart.tv, and TheAudioDB providers.

What is identified

For each analysed track:

• AcoustID — A unique “fingerprint” created by analysing the actual sound waves
• MusicBrainz Recording Id — A unique identifier for the recording
• ISRC(s) — Stands for International Standard Recording Code, a unique 12-character alphanumeric code assigned by labels and distributors to identify specific sound recordings. Having one linked to a track improves matching against streaming providers that expose ISRC in their catalogue
• MusicBrainz Artist Id(s) — A unique identifier for an artist. These are only written to file tags (see the Write tags back setting)

For each analysed album, once enough of its tracks have been identified:

• MusicBrainz Release Group Id — A unique identifier for a group of album releases. This is identified from the analysed tracks on the album and cross-checked against the album name already in the tags. This is what unlocks artwork and album metadata, Release group will only be confirmed when at least half of the tracks in the library from the album have been analysed. This is to try and maximise the chance of identifying the correct release group. For this reason, it is ideal if all of the tracks that are intended to be added to the library are added before tracks are played (and therefore analysed)

When analysis runs

• During the nightly audio-analysis scan, around local midnight. Tracks from Local files sources only, including those on a network share
• During playback of an eligible track. Local files are always eligible; streaming-provider tracks are eligible when Analyse tracks from streaming providers is enabled and the track is in the MA library

Large libraries may take several nights to work through. A well tagged library will see almost nothing happen, because any track that already carries a MusicBrainz Recording Id or an ISRC is skipped. Tracks from streaming services are picked up gradually as you play them rather than all at once.

The “stale” count shown on the Audio analysis page is the number of tracks that AcoustID could not find. Those are tried again every 60 days, in case the database has caught up.

Limitations

• Wrong identifications are difficult to reverse automatically. Once a track’s MusicBrainz Recording Id is set, AcoustID skips that file on future scans. Using Refresh Item may clear the stored Id from the library and allow a fresh lookup, but two things limit the recovery: the file’s own tags reassert themselves on the next scan if Write tags back was on, and AcoustID’s lookup is cached for 30 days so the same audio returns the same result inside that window. The most reliable correction is to fix the source file’s tags directly (for example, by running MusicBrainz Picard against the album) and then rescan in Music Assistant
• Release-group identification is a best-effort match. The album name in the file tags must agree with one of the candidate release-group titles returned by AcoustID. When the album is untagged, abbreviated, or differs significantly from MusicBrainz’s canonical form, no release-group is written and album-level metadata remains unenriched
• Country and edition variants may not match exactly. Multiple pressings of the same album (UK, US, Japan, anniversary editions, remasters) often share the same recordings and are acoustically indistinguishable. The artwork variant Music Assistant chooses may differ from the user’s specific pressing, although the album name and tracks will still be correct
• At least half of an album’s tracks must be analysed before the release-group is set. Single-track folders only ever receive track-level identification; their album row stays unenriched unless the album name agrees closely with the AcoustID candidate
• Mis-identified tracks are possible. Very short tracks, generic loops, and low-quality recordings can match the wrong recording. The minimum match score reduces but does not eliminate this risk

Settings

• AcoustID API key. Only visible when the advanced toggle is on. The provider comes with a builtin API key but if rate limits are hit or for any other reason a personal API key is desired then obtain one free of charge from acoustid.org. Be careful to ensure the API key for uploading fingerprints is not used
• Minimum match score. How sure AcoustID has to be before a match is accepted. The default of 0.85 balances identifying as much as possible against getting it wrong. Raising it means fewer mistakes but more tracks left unidentified (Only visible when advanced toggle is on)
• Analyse tracks from streaming providers. When enabled, tracks played from streaming providers (Spotify, Tidal, Qobuz, YouTube Music, …) that are in the library and lack a MusicBrainz Recording Id are also fingerprinted and identified. Particularly useful for streaming providers like YouTube Music whose catalogues have thin metadata. Note that streaming-provider tracks are only analysed during playback, not in the nightly background scan
• Write AcoustID/MusicBrainz tags back to files. When enabled, the Acoustid Id, MusicBrainz Recording Id, ISRC, and (where resolvable) MusicBrainz Artist Id tags are written back into the source audio file once identification succeeds. Useful when other applications on the network read these tags for their own metadata or to save re-scans if the MA library database is wiped. Write access to the file is required; read-only files are skipped. By default this is off, and identifiers are only stored in the Music Assistant library database