Art

ListenBrainz has a (cover) art infrastructure that creates new cover art from a user’s statistics or a user’s instructions on how to composite a cover art grid.

As these endpoints return SVGs rather than images, you must embed them in an html <object data="covert_art_url" type="image/svg+xml"> element rather than an <img src="covert_art_url"> element. Otherwise external resources such as cover art images and fonts will not be loaded and the result will be useless.

See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/object for reference.

POST /1/art/grid/

Create a cover art grid SVG file from the POSTed JSON data to this endpoint. The JSON data should look like the following:

{
	"background": "transparent",
	"image_size": 750,
	"dimension": 4,
	"skip-missing": false,
	"show-caa": false,
	"caption": false,
	"tiles": [
		"0,1,4,5",
		"10,11,14,15",
		"2",
		"3",
		"6",
		"7",
		"8",
		"9",
		"12",
		"13"
	],
	"release_mbids": [
		"d101e395-0c04-4237-a3d2-167b1d88056c",
		"4211382c-39e8-4a72-a32d-e4046fd96356",
		"6d895dfa-8688-4867-9730-2b98050dae04",
		"773e54bb-3f43-4813-826c-ca762bfa8318",
		"ec782dbe-9204-4ec3-bf50-576c7cf3dfb3",
		"10dffffc-c2aa-4ddd-81fd-42b5e125f240",
		"be5f714d-02eb-4c89-9a06-5e544f132604",
		"3eee4ed1-b48e-4894-8a05-f535f16a4985"
	]
}

Parameters:

background (str) – The background for the cover art: Must be “transparent”, “white” or “black”.
image_size (int) – The size of the cover art image. See constants at the bottom of this document.
dimension (int) – The dimension to use for this grid. A grid of dimension 3 has 3 images across and 3 images down, for a total of 9 images.
skip-missing (bool) – If cover art is missing for a given release_mbid, skip it and move on to the next one, if true is passed. If false, the show-caa option will decide what happens.
show-caa (bool) –
If cover art is missing and skip-missing is false, then show-caa will determine if a blank square is shown or if the Cover Art Archive missing image is show.

one, if true is passed. If false, the show-caa option will decide what happens.
caption (boolean) – Whether to show the release name and artist overlayed on each cover art image. Default True.
tiles (list) – The tiles paramater is a list of strings that determines the location where cover art images should be placed. Each string is a comma separated list of image cells. A grid of dimension 3 has 9 cells, from 0 in the upper left hand corner, 2 in the upper right hand corner, 6 in the lower left corner and 8 in the lower right corner. Specifying only a single cell will have the image cover that cell exactly. If more than one cell is specified, the image will cover the area defined by the bounding box of all the given cells. These tiles only define bounding box areas – no clipping of images that may fall outside of these tiles will be performed.
release_mbids (list) – An ordered list of release_mbids. The images will be loaded and processed in the order that this list is in. The cover art for the release_mbids will be placed on the tiles defined by the tiles parameter. If release_group_mbids are supplied as well, ONLY cover arts for release_group_mbids will be processed.
release_group_mbids (list) – An ordered list of release_group_mbids. The images will be loaded and processed in the order that this list is in. The cover art for the release_group_mbids will be placed on the tiles defined by the tiles parameter. If release_mbids are supplied as well, ONLY cover arts for release_mbids will be processed.
cover_art_size (int) – Size in pixels of each cover art in the composited image. Can be either 250 or 500

Status Codes:

200 OK – cover art created successfully.
400 Bad Request – Invalid JSON or invalid options in JSON passed. See error message for details.

Response Headers:

Content-Type – image/svg+xml

See the bottom of this document for constants relating to this method.

GET /1/art/grid-stats/(mb_username: user_name)/(time_range)/(int: dimension)/(int: layout)/(int: image_size)

Create a cover art grid SVG file from the stats of a given user.

Parameters:

user_name (str) – The name of the user for whom to create the cover art.
time_range (str) – Must be a statistics time range – see below.
dimension (int) – The dimension to use for this grid. A grid of dimension 3 has 3 images across and 3 images down, for a total of 9 images.
layout (int) – The layout to be used for this grid. Layout 0 is always a simple grid, but other layouts may have image images be of different sizes. See https://art.listenbrainz.org for examples of the available layouts.
image_size (int) – The size of the cover art image. See constants at the bottom of this document.
caption (boolean) – Whether to show the release name and artist overlayed on each cover art image. Default True
skip-missing (boolean) – Whether to skip albums that don’t have cover art, or show a placeholder. Default True

Status Codes:

200 OK – cover art created successfully.
400 Bad Request – Invalid JSON or invalid options in JSON passed. See error message for details.

Response Headers:

Content-Type – image/svg+xml

See the bottom of this document for constants relating to this method.

GET /1/art/artist-grid/(uuid: artist_mbid)/(int: dimension)/(int: layout)/(int: image_size)

Create a cover art grid SVG file from the release groups of a given artist.

Parameters:

artist_mbid (uuid) – MusicBrainz ID of the artist.
dimension (int) – The dimension to use for this grid. A grid of dimension 3 has 3 images across and 3 images down, for a total of 9 images.
layout (int) – The layout to be used for this grid. Layout 0 is always a simple grid, but other layouts may have image images be of different sizes. See https://art.listenbrainz.org for examples of the available layouts.
image_size (int) – The size of the cover art image. See constants at the bottom of this document.
caption (boolean) – Whether to show the release group name and artist overlayed on each cover art image. Default True.
skip-missing (boolean) – Whether to skip release groups that don’t have cover art, or show a placeholder. Default True.

Status Codes:

200 OK – Cover art grid SVG generated successfully.
400 Bad Request – Invalid parameters or insufficient cover art.
404 Not Found – Artist not found in metadata cache.

Response Headers:

Content-Type – image/svg+xml

GET /1/art/(custom_name)/(mb_username: user_name)/(time_range)/(int: image_size)

Create a custom cover art SVG file from the stats of a given user.

Parameters:

cover_name (str) – The name of cover art to be generated. See https://art.listenbrainz.org for the different types that are available.
user_name (str) – The name of the user for whom to create the cover art.
time_range (str) – Must be a statistics time range – see below.
image_size (int) – The size of the cover art image. See constants at the bottom of this document.

Status Codes:

200 OK – cover art created successfully.
400 Bad Request – Invalid JSON or invalid options in JSON passed. See error message for details.

Response Headers:

Content-Type – image/svg+xml

See the bottom of this document for constants relating to this method.

GET /1/art/year-in-music/(int: year)/(mb_username: user_name)

Create shareable SVG images using Year In Music stats

Parameters:

year (int) – The selected year for which to create the Year In Music cover art.
user_name (str) – The name of the user for whom to create the cover art.
branding (bool) – Show or hide the LsitenBrainz branding on the image. Default True.
show-caption (bool) – For cover art grids, show or hide the album title and artist name. Default True.
anonymous (bool) – Show or hide the user’s name. Default False (shows user name).
bg-color-1 (str) – Background color 1 to use in the image. Default #2f6368.
bg-color-2 (str) – Background color 2 to use in the image. Default #463f62.
accent-color (str) – Accent color to use in the image. Default #F1F2E1.
legacy (bool) – Generate images from archived previous versions of YIM. Deprecated. Default False.

Status Codes:

200 OK – Image created successfully.
204 No Content – Missing enough data to generate an image for the selected year and user.
400 Bad Request – Invalid JSON or invalid options in JSON passed. See error message for details.

Response Headers:

Content-Type – image/svg+xml

POST /1/art/playlist/(uuid: playlist_mbid)/(int: dimension)/(int: layout)

Create a cover art grid SVG file from the playlist.

Parameters:

playlist_mbid (str) – The mbid of the playlist for whom to create the cover art.
dimension (int) – The dimension to use for this grid. A grid of dimension 3 has 3 images across and 3 images down, for a total of 9 images.
layout (int) – The layout to be used for this grid. Layout 0 is always a simple grid, but other layouts may have image images be of different sizes. See https://art.listenbrainz.org for examples of the available layouts.

Status Codes:

200 OK – cover art created successfully.
400 Bad Request – Invalid JSON or invalid options in JSON passed. See error message for details.

Response Headers:

Content-Type – image/svg+xml

See the bottom of this document for constants relating to this method.

Constants

Constants that are relevant to using the API:

listenbrainz.art.cover_art_generator.MIN_IMAGE_SIZE = 128: Minimum image size

listenbrainz.art.cover_art_generator.MAX_IMAGE_SIZE = 1024: Maximum image size

listenbrainz.art.cover_art_generator.MIN_DIMENSION = 1: Minimum dimension

listenbrainz.art.cover_art_generator.MAX_DIMENSION = 5: Maximum dimension

data.model.common_stat.ALLOWED_STATISTICS_RANGE = ['this_week', 'this_month', 'this_year', 'week', 'month', 'quarter', 'year', 'half_yearly', 'all_time']: list of allowed value for range param accepted by various statistics endpoints