[WS] Cover Art Archive

rboss · March 3, 2025, 3:40am

Greetings to the Mp3Tag community.

Cover Art Archive is the database of cover art images used (and maintained) by the MusicBrainz project.

On physical releases, besides front and back covers, many times there are other forms of interesting visual media present, like booklets, medium graphics, and the like.

Here is my attempt at a Web Source Script (WSS) to source these media provided by Cover Art Archive (CAA), directly from Mp3Tag.

This project is -and always will be- released in beta stage, due to the particular challenges that rose from creating an interface between the CAA API and Mp3Tag, which I'll summarize further below.

Installation

Download the script to your Mp3Tag \sources folder; on Mp3Tag go to 'Tag Sources' > 'Cover Art Archive WS' and select the version of the script you want to use.

There is no .settings file requirement for this script.

Instructions

Search:

The CAA API only accepts* a single search parameter: a valid album MusicBrainz Identifier (MBID). Therefore, this script will require the same information; if you already use a MusicBrainz WSS to tag your files, there is a good chance that the [MUSICBRAINZ_ALBUMID] tag is already present, and its value will be preloaded into the query field.

You can also find the album id on the URL of an MusicBrainz album page, as well as in the 'Details' section of said page, under MBID. As an example, for this link the album MBID will be f268b8bc-2768-426b-901b-c7966e76de29, so this is the value to be used in the search.

*although this is not entirely true; the API also accepts MusicBrainz' release group IDs, which identifies all related entries to a release (i.e. all MBIDs - for releases in different countries, media, etc.- related to a release). Since the release id is the most relevant for a web source, that's the one I went with

Search results:

The search results' list shows the following columns:

[Preview thumbnail]: a 250x250px preview of each media provided by the API. Hovering with the cursor will show an enlarged version of the image
# (media index): a counter for each media set returned (generated during script execution, and provided for sorting purposes)
Sorting by 'Size' followed by '#' will restore the original sort order of the results, if necessary.
Description: the media type description, as shown in the 'Cover art' section of an album's MusicBrainz page. This description may be complemented by additional info in parentheses, if provided by the source
Size: the available pixel sizes for each media image entry, as provided by the API.
These values should match those shown in the album page, but this may not always be the case

Tag information:

Besides the selected cover art image, the search will return the following text-based tags:

#_COVERID
- the API's id code for each image set

#_COVERTYPE
- same as the 'Description' column data in the search results

#_COVERURL
- a direct link to the source image file

#_WWW
- a link to the 'Cover art' section of the MusicBrainz album page. This is provided as a replacement for the Preview link modified by the script

MUSICBRAINZ_ALBUMID
- the same id used in the initial query

All text-based tags are optional; additionally all those starting with #_ are custom to this script, and provided only as additional information. If unnecessary, their respective boxes should be unchecked before applying the cover to your files (and will be memorized between searches).

As mentioned before, the CAA API only accepts one search value; this meant that, in order to get cover sets and sizes available as search results/options, I had to use some creative coding, which required modifying the field intended for the preview option in the 'Search results' and 'Tag info' windows, and using the preview link as a "clipboard", by appending the additional size (and cover id) data to the URL string. Because this breaks the original intention of the feature, it could be considered as an exploit by the developer.

At the time of this post, even with the additional data in the URL, the preview link still connects to the correct page, so the preview options are still functional, but this may change in the future.

Because of this, I'm releasing this script as a beta, and ~~until the time when the developer notices my work and signs off his approval,~~ it will always be considered as such.

Here is the link to the script; and a change log text file.

Enjoy.

Cover Art Archive WSS
# Version - beta_0.0.2
# Mp3Tag_Windows - Yes | v3.28 and above
# Mp3Tag_Mac - No

Cover Art Archive WS#CAA_002_beta.src (4.0 KB)
WS_CAA_changelog.txt (334 Bytes)

Florian · March 4, 2025, 9:24am

Many thanks for the new Tag Source!

I had a look at the creative coding you've mentioned: it's yet another new way of using Mp3tag in a way I never imagined

Unfortunately, the macOS version doesn't have the preview feature you're creatively using to pass the data along and, thus, it's not working for macOS.

rboss · March 4, 2025, 5:38pm

And Thank You for (once again) noticing my work.

As I had teased back then, this is one of the projects I had in development. My main concern was if the use of [CurrentPreview] in a manner outside of its scope could have unforeseen negative impacts elsewhere in Mp3Tag's internal workings, and was hesitant to release the script due to this (and lack of quality development time).

That is unfortunate. I had tested using [CurrentUrl] in an earlier draft, but since that data is essential to proper script operation, modifying it could cause the CAA API to reject the request (it had on other projects / APIs); so I tentatively went with [CurrentPreview], and its possible negative impacts.

Thank you for the input; I'll update the first post with this info.

But... here's some food for thought:
The addition of a %_CurrentClipboard% variable in [ParserIndex] could serve the same purpose, and would enable the script to run in macOS. I had sent you (at the time of the quoted post) some notes on this via PM, but just as it took me until now to properly debug and tidy up this script, I'm aware that you are also very busy with development to properly analyze and reply to every idea and suggestion that arrives to your inbox, and know better than to expect a reply straight away.

Oh, and one more thing.
You may have noticed that, in the initial query results, the cover preview thumbnail \ popup has its aspect ratio changed into squared dimensions. For square-ish physical cover art this isn't much of an issue, but for booklets, obi, and other 'less squared' images, there is a visual impact on the preview (see example). The end result (with "Correct aspect ratio" enabled) is fine, so I'll leave to your consideration if this is worth addressing.

Thank you once again.

rboss · May 11, 2025, 4:20pm

Greetings to all;

Here is a small update; which removes macOS specific fields, and has some minor overall script improvements.
You can find more details about what's new in the changelog.

Download links in the first post.

And enjoy.

Cover Art Archive WSS
# Version - beta_0.0.2
# Mp3Tag_Windows - Yes | v3.28+
# Mp3Tag_Mac - No