art

Documentation

Overview

Package art is responsible for getting cover art for albums or artist images over the internet.

It finds album artwork by first querying the MusicBrainz web service for a releaseID using the artist name and album name. Then using this ID it queries the Cover Art Archive for the corresponding album front art.

Artist images are found using the MusicBrainz database and Discogs.

The following APIs are used to achieve this packages' objective:

• MusicBrainz API: https://musicbrainz.org/doc/Development/XML_Web_Service/Version_2
• Cover Art Archive: https://musicbrainz.org/doc/Cover_Art_Archive/
• Discogs API: https://www.discogs.com/developers/

Index

• Variables
• type Client
  • func NewClient(useragent string, delay time.Duration, discogsToken string) *Client
  • func (c *Client) GetArtistImage(ctx context.Context, artist string) ([]byte, error)
  • func (c *Client) GetFrontImage(ctx context.Context, artist, album string) ([]byte, error)
• type Finder

Variables

var ErrImageNotFound = errors.New("image not found")

ErrImageNotFound is returned by the Get* functions when no suitable cover image was found anywhere.

var ErrImageTooBig = errors.New("image is too big")

ErrImageTooBig is returned when some image has been find but it is deemed to big for the server to handle.

var ErrNoDiscogsAuth = fmt.Errorf("authentication with Discogs is not configured")

ErrNoDiscogsAuth signals that there is no configured Discogs token in the configuration. This directly means that trying to get an artist image is doomed from the get-go.

Types

type Client

type Client struct {
	sync.Mutex

	// MinScore is the minimal accepted score above which a release is considered
	// a match for the search in the Music Brainz API. The API returns a list of
	// matches and every one of them comes with a "score" metric in 0-100 scale
	// which represents how good a match is this result for the query. 100 means
	// absolutely sure. By lowering this score you may receive more images but
	// some of them may be inaccurate.
	MinScore int
	// contains filtered or unexported fields
}

Client is a client for the Cover Arts Archive. It supports getting images from the Cover Arts Archive and automatically throttles itself so that it does not make too many requests at once. It is safe for concurrent use.

It works in two steps:

* Gets a list of mbids (aka release IDs) from the Music Brainz API which are above MinScore.

* Uses the mbids for fetching a cover art from the Cover Art Archive. The first release ID which has a cover art wins.

Why a list of mbids? Because a certain album may have many records in Music Brainz which correspond to different releases for this album. Perhaps for multiple years or countries. Generally all releases have the same cover art. So we accept any of them.

It implements Finder.

func NewClient

func NewClient(useragent string, delay time.Duration, discogsToken string) *Client

NewClient returns fully configured Client.

The kind people at MusicBrainz provide their API at no cost for everyone to use. For that reason they have kindly asked for all applications to throttle their usage as much as possible and do not exceed one request per second. So we are good citizen and throttle ourselves. More info: https://musicbrainz.org/doc/XML_Web_Service/Rate_Limiting For this reason the delayer and delay are defined here.

Throttling is done with the help of the arguments `useragent` and a `delay`. The user agent is used for representing itself when contacting the Music Brainz API. It is required so that they can use it for throttling and filtering out bad applications. The delay is used to throttle requests to the API. No more than one request per `delay` will be made.

func (*Client) GetArtistImage

func (c *Client) GetArtistImage(
	ctx context.Context,
	artist string,
) ([]byte, error)

GetArtistImage finds and returns an image of particular artist. If none is found it returns ErrImageNotFound.

func (*Client) GetFrontImage

func (c *Client) GetFrontImage(
	ctx context.Context,
	artist,
	album string,
) ([]byte, error)

GetFrontImage returns the front image for particular `album` from `artist`.

type Finder

type Finder interface {
	// GetFrontImage returns the front album artwork for particular album
	// by an artist.
	GetFrontImage(ctx context.Context, artist, album string) ([]byte, error)

	// GetArtistImage returns an image which represents a particular artist.
	// Hopefully a good one! ;D
	GetArtistImage(ctx context.Context, artist string) ([]byte, error)
}

Finder defines a type which is capable of finding art for artists or albums.