mirror of
https://github.com/advplyr/audiobookshelf.git
synced 2026-05-30 23:40:40 +02:00
[Enhancement]: MusicBrainz Metadata #2664
Assignees
adam (Adam Melkus)
Clear assignees
adam (Adam Melkus)
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: starred/audiobookshelf#2664
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @Cwavs on GitHub (Mar 16, 2025).
Type of Enhancement
Server Backend
Describe the Feature/Enhancement
Allow matching books to and pulling data down from MusicBrainz.
Why would this be helpful?
I understand this request may sound odd, but there is some logic behind me wanting this. I listen to Big Finish's audio drama's, and I recently set up audio bookshelf because Jellyfin's support for audio books is lacking. It works really well, however, sadly most of the metadata providers are pretty lacking in regards to Big Finish's catalogue. They all seem to have some of the early monthly adventures, however that's a pretty small amount of the whole Big Finish catalogue. MusicBrainz however, does include audio books, and has a pretty complete collection of the Big Finish library.
It would be quite helpful for me at the least if I could use MusicBrainz to get metadata for these dramas. I do appreciate this may be a niche feature though! It is worth mentioning MusicBrainz does have quite a few listing of other Audio Books too, not just Big Finish! See https://musicbrainz.org/release/3b9bdfdc-a3da-4868-a07a-440a24db457d
Future Implementation (Screenshot)
I can make a rough mock up if needed, but I'm not sure it is, I think it's implementation would be similar to other providers like Google Books.
Audiobookshelf Server Version
v2.19.5
Current Implementation (Screenshot)
The matching page:
@Vito0912 commented on GitHub (Mar 16, 2025):
For Big Finish, there is a custom metadata provider. See https://www.audiobookshelf.org/guides/custom-metadata-providers/#community-providers.
You can host it yourself or add
https://provider.vito0912.de/bigfinishas a custom metadata provider. Note that the provided provider might be down sometimes. I don't use these myself and just host them on a remote server that I don't check very often.For other contributors, MusicBrainz has an API: https://musicbrainz.org/doc/MusicBrainz_API
@Cwavs commented on GitHub (Mar 16, 2025):
Oh Wow I don't know how I missed that page! Thanks. I'll still leave this issue open for the time being, as I do think Music Brainz support could be beneficial for someone.
@nichwall commented on GitHub (Mar 16, 2025):
There is an initial version for the provider here, but not sure if it's still accurate for the API.
https://github.com/advplyr/audiobookshelf/blob/master/server%2Fproviders%2FMusicBrainz.js
@tfranken90 commented on GitHub (Mar 18, 2025):
@Cwavs I also rely on Musicbrainz for audio drama metadata. I would suggest using Musicbrainz Picard to tag your files before they are imported into audiobookshelf. Make sure to turn on "use release relationships" and "use track relationships" in the Picard options, then enable this script
Make sure to prefer tag metadata in your audiobookshelf library, and voila! that will give you writer, narrator, series, and label metadata correctly tagged for use in audiobookshelf. If you find any missing information, you can always add it directly to Musicbrainz for other people to use as well.
@jwillikers commented on GitHub (Apr 18, 2025):
@nichwall How would one go about using this? I don't see anything in the UI to enable it.
@nichwall commented on GitHub (Apr 18, 2025):
It is not available in the UI or through the ABS API. I am not sure if it works as is or if any other changes would need to be made for it to work. You can try enabling it manually by modifying the source code.
@ElDubsNZ commented on GitHub (Apr 30, 2025):
Only issue with this is it's based on the release level, so multiple stories in the same release will all get the same metadata.
@Vito0912 commented on GitHub (Apr 30, 2025):
I created the BigFinish metadata provider (though I don’t actually use BigFinish or have any books, so I don't really know the structure), so, if I recall correctly, it pulls data directly from BigFinish. Everything they have should be accessible.
If these “stories” are independent items and you can’t fetch them, I can try to fix it if you provide an example.
If they are not single items on BigFinish then indeed it is not possible currently.
I had a conversation with a person who wanted to implement MusicBrainz one or two weeks ago. Idk what's the current progress and my try on it was just bad. Like the search had to be near exact and results were incomplete 99% without an image, so I did not pursue it any further
@Cwavs commented on GitHub (Apr 30, 2025):
I think the problem is that Big Finish's current boxset release model means they'll release several stories (sometimes loosely connected, sometimes standalone) as one item. This isn't so much a problem with your implementation as it is with pulling from them. If you want all those stories listed, and then maybe use collections or series to group them you're kind of stuck unless you manually do it.
@jwillikers commented on GitHub (Apr 30, 2025):
I'm currently working on this. I've just been figuring everything out in my own project before I start in on the audiobookshelf provider.
@ElDubsNZ commented on GitHub (Apr 30, 2025):
Yeah that's exactly it, a significant amount aren't single items.
Ninth Doctor Adventures - Hidden Depths, this one's a good example, all releases in this series are actually 3 different radio plays all in one release, each with their own description, author, and cover art, but it's all on one release. They even annoyingly merged the cast from all three episodes into one list.
Don't get me wrong though, fantastic tool that gets you so much closer to having complete data than without it.
@jwillikers commented on GitHub (May 1, 2025):
Welcome to the club of those who just want audiobook / audio drama metadata! I hit a lot of frustrations with bad metadata from Audible, and then finally resigned myself to adding my collection to MusicBrainz to have correct metadata. It's a ton of work. I've made 62,959 edits on MB so far, which are practically all for audiobooks. As I'm writing stuff to use the MusicBrainz API for this kind of thing, I'm just starting to get a tantalizing taste of the results. It's all starting to come together really well.
@tfranken90 commented on GitHub (May 2, 2025):
@ElDubsNZ If you use Musicbrainz Picard for managing your files, you can pull the metadata from MB but store the files as standalone (separate) recordings.
At the moment, there are only track and album artists for this release, but it would be relatively easy to add full narrator and writing credits if you want that level of detail.
https://musicbrainz.org/release/3b946f43-f166-4f8e-ba94-95bb57aacafe
@ElDubsNZ commented on GitHub (May 2, 2025):
@tfranken90 Yeah I'm working on adding more metadata to the Ninth Doctor Adventures and will eventually get to the rest.
Doctor Who: The Ninth Doctor Adventures: Respond to All Calls
Here's another that I've completed on MusicBrainz to as much detail as I can fathom.
@jwillikers commented on GitHub (Oct 12, 2025):
FYI, I've just started writing the MusicBrainz provider, and have it listing items nicely in the match dialogue already, displaying cover art and even the match score from MusicBrainz. Right now, I think the ability to fetch chapters from a MusicBrainz release in the chapter editor and support for using AcoustID's should be done in separate follow-up PR's from the one to add the provider. The chapter lookup will require some reworking to allow multiple providers. I should still be able to get chapters for a release when using the Match dialogue, though.
Below I go into some of the gory details, for those that might be interested or want to give feedback. I figured out how to do all of this by adding metadata for a ton of audiobooks to MusicBrainz and by creating this script to use MusicBrainz to tag my audiobooks for Audiobookshelf.
My primary concern with the MusicBrainz provider is the number of API calls necessary to get all of the metadata, some of which return a lot of data. Ideally, I'd only make the minimum API calls necessary to display the available matches and then make additional calls for the complete metadata when the user selects a match. I'm not sure it's currently possible to do that given how the providers currently work. While most of the necessary metadata to display matches can be taken directly from the initial search API call to MusicBrainz, it unfortunately doesn't include the duration, which is a very important characteristic, so an additional API call must be made for each release candidate just for this. While I can cleverly parse the author and narrator from the artist credit in most cases, this isn't ideal since technically, the narrator should be taken from the
spoken vocalsrelationship on the associated recordings and the author should be taken from thewriterrelationship on associated works. Using the artist credit, I'm able to order authors and narrators correctly, and use the names as they appear in the artist credit, which is helpful when dealing with translated names or artists with various pseudonyms. For those not listed in the artist-credit, it may be necessary to check how they are credited in the relationship or fallback to an alias in the same language as the release. These relationships can be included in the data returned from the MusicBrainz release endpoint, but it does make the size of the returned data substantially larger.Series relationships can exist for many different entities in MusicBrainz. Typically for audiobooks, there will be distinct series for the Release Group and the associated Works, and possibly at the release and recording levels, too. There can be any number of series at these levels and there's no distinction between their importance. I could probably infer the most likely primary series evaluating series as a sort of graph problem looking at all of the series-series relationships, but that's not really necessary for audiobookshelf. I typically use the same names for the Release Group series and the Work series for audiobooks, and these can collapse down into the same series as far as audiobookshelf is concerned. Typically, a single work exists for a single audiobook and all tracks are associated with this one work. It's possible works could exist at a finer granularity than a single work per book. In which case, the works could exist in a series with a larger number of indices than the release groups in the release group series. For this reason, release group series are prioritized over work series. Only series related directly to the entities are used, and series-series relationships are completely ignored for simplicity.
Most of the remaining API calls are for getting genres and tags from works and series, and for finding a matching release to use for chapters. Genres are a subset of tags in MusicBrainz. Users can easily and arbitrarily add tags to different MusicBrainz entities. Tags with specific names are categorized as genres. There's a very limited set of official genres in MusicBrainz, and I don't think any are useful for categorizing audiobooks. So, I ended up using an ad-hoc method for extracting genres and special-purpose tags from MusicBrainz tags. I have a few special-purpose tags for adding additional information to MusicBrainz, such as
unabridgedandabridgedfor whether or not the audiobook isabridgedandaccompanying-documentsto mark whether a release contains a document of some kind, like a PDF handout, as well as a few others. Any tags that aren't one of these special purpose ones, I assume are genres. I typically add genre tags for works and series of works, while special purpose tags are added to specific types of entities dependending on their purpose, likeunabridgedI use for release-group and release group series.Chapters are parsed from a release's track list, using the track lengths to determine where each chapter begins. Releases with a single track like an AAX or M4B are separate from releases containing multiple tracks, and it's not possible to link a single track release to another release providing chapters in MusicBrainz. For a single track release, this would result in a single chapter, which is basically useless, so I use some special filtering to find a matching release to use for chapters when the selected release contains only a single track. The filtering is based on total duration, matching distributors, and the presence of the
chapterstag. In case there are multiple releases to use for chapters after applying filtering, none will be used and there will only be a single chapter. Hopefully additional functionality can be added to the chapter editor to allow specifying a MusicBrainz Release ID from which to pull chapters, probably in a subsequent PR. Unless importing tracks from a CD, MusicBrainz only supports entering track lengths down to the second, not millisecond, so I created this tool to round each track's length to prevent rounding errors from accumulating across tracks, otherwise chapter markers could drift and become noticeably off from where the chapter actually starts.Also, it should be noted that while MusicBrainz supports searching via ASIN, this is actually the Amazon ASIN and not the Audible ASIN. The Audible ASIN may still be present in the URL relationships on a release, but there's no way to search using the Audible ASIN.
Initially, I'm just using the disambiguation comment as the description field, since there isn't a relevant description of the audiobook itself on MusicBrainz. The disambiguation comment can be very helpful when distinguishing between releases that otherwise appear the same. The annotation field might be useful to this end, though that will still be about the particular release and not a synopsis of the book.
@tfranken90 commented on GitHub (Oct 13, 2025):
@jwillikers That's awesome! thanks for making some progress on bringing these projects together. I would say the simplest sources for the required data would taking writer and spoken vocals from the release and series from the release group.
As to the chapter information, as I mentioned here we could consider putting the chapter information in the annotation for the recording.
This would make more sense than pulling chapters from track listings because 1. MB doesn't support milliseconds in track listings, 2. releases with track listings do not always exist and it's easier to add an annotation that a release, and 3. podcasts do not have "chapters" which can be split into tracks but it may be desirable to mark segments in a given episode.
Perhaps we could figure out a simple syntax for points of interests on a given recording which could then be easily parsed, for example..
**Chapter 1 [00:00:00]
**Chapter 2 [03:23:23]
@jwillikers commented on GitHub (Oct 14, 2025):
@tfranken90 For the chapters, it appears that those aren't actually incorporated through the Match dialogue, so chapters will require using the lookup from the chapters editor. I won't be doing that in the initial PR, but I'll be providing the necessary function in the MusicBrainz provider to look them up via Release ID. For now, the function just uses track lists, but I don't see why we couldn't support parsing it from the annotation format in a single track release as well. Maybe we'll get a proper method for supporting chapters when alternative tracklists are implemented... someday, fingers-crossed.
Fyi, my branch is here. Hoping to have a draft PR up in the next day or two. The only real impediment now is rate-limiting, but I'll see if it's possible to only hit some of the API's after an entry has been selected. I hit the series and work enpoints to pull tags / genres, and doing that for every possible match is the problem. I think it would also be nice to display the disambiguation comment in the UI.