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,
	"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.
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.

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/(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.

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/(custom_name)/(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/2022/(user_name)¶: Create the shareable svg image using YIM 2022 stats

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 = 2¶: Minimum dimension

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

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