ListenBrainz/MBIDMappingDocumentation

From MusicBrainz Wiki
Revision as of 14:00, 15 February 2023 by Reosarevok (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

The MusicBrainz ID (MBID) Mapping

Since not every listen includes MusicBrainz IDs as part of the send data, we at ListenBrainz we have built the MBID Mapping tool, which automatically attempts to map incoming listens to their right tracks in MusicBrainz. This mapper is a fairly complex system that takes data from MusicBrainz, processes it into a form that is usable by ListenBrainz and then ships it to the ListenBrainz server that runs the MBID Mapping tool itself. When a listen from a user arrives, we will look up that listen in our database and, if we have never matched that data before, we will look it up in the MBID Mapping. This manages to map a large amount of listens which came without the specific metadata, but it cannot automatically map every listen. There are two common reasons why a listen may not be found in the mapping:

  1. The data is missing from MusicBrainz. This happens a lot on Fridays when new music is released -- a track might already be available at a music service, but no one has entered the new release into MusicBrainz yet. In this case, the MBID Mapping obviously has no chance of mapping the track to MusicBrainz.
  2. The data is in MusicBrainz, but the data in the Listen differs significantly from the data in MusicBrainz. For instance, if a music service provides us a recording name of "Running up that hill - 2008 remaster" we need to work out that the "- 2008 remaster" portion is noise (since MusicBrainz does not specify remasters as part of the title) and should be discarded before trying to match the listen. Music labels and services carry out all sort of data atrocities to make their service more palatable to their users and our challenge is to undo these atrocities, so as you can imagine there are some pitfalls in the process.

What to do if my listen wasn't mapped

Given the issues above, when a listen of your does not get mapped and the link remains grey, what can you do?

  1. Check to make sure that the data exists in MusicBrainz. If it's already there, then either it's so new that it's not available to the mapping yet (see 3.) or the mapping failed to find it and you'll need to associate it manually (see 6.).
  2. If the data does not exist in MusicBrainz, add it. Keep in mind even if you have only listened to one or two tracks, it is always best to add whole releases to MusicBrainz (be it albums or singles) rather than trying to add tracks on their own. You can follow MusicBrainz's text or video how-to guides for adding releases.
  3. Once the data has been added to MusicBrainz, you'll need to wait 4-5 hours before that data is available for the ListenBrainz MBID mapping.
  4. After this time, the easiest way to get the listen matched is to listen to the unmatched tracks again. When we receive a listen that we've been unable to map in the past, we'll try to map it again.
  5. We also have a process that wakes up on a periodic basis and goes back over old listens that have not been matched, attempting to match them again. However, as of this writing, this process is broken -- we're working hard to resolve this issue.
  6. If all else fails, you can manually map this track. From your listens page, look for the track that was not matched, click the three stacked dots by it and select "Link with MusicBrainz" (see the image below). Then enter the MBID of the recording that this listen should be mapped to, and you're done! We realize that this is less than ideal, but that's why it is a fallback for when all else fails. Also, please consider letting us know about the track that did not match (see "More options for diving deeper" below).

manual mapping.png

More options for diving deeper

Also, for people who are inclined to delve even deeper into this, we have an "MBID Mapping Explain" API endpoint that gives its (somewhat cryptic) feedback from the matching process of matching a listen. If you enter the artist_name and recording_name that is part of your listen you can see what the mapper attempts to do while trying to match your data.

Finally, if all else fails and you suspect there is a bug or an unhandled case in the mapping (there are probably many!) then you can add your case to our MBID Mapping improvement rollup ticket where we collect all of these data cases that give us headaches.

We hope that this explains our process and helps you turn those pesky grey links blue!