Provides the base for obtaining and storing covers, also known as album art.

Cover Manager

xl.covers.MANAGER = <xl.covers.CoverManager object>

The singleton CoverManager instance

class xl.covers.CoverManager(location)[source]

Handles finding covers from various sources.

find_covers(track, limit=-1, local_only=False)[source]

Find all covers for a track

  • track – The track to find covers for
  • limit – maximum number of covers to return. -1=unlimited.
  • local_only – If True, will only return results from local sources.
get_cover(track, save_cover=True, set_only=False, use_default=False)[source]

get the cover for a given track. if the track has no set cover, backends are searched until a cover is found or we run out of backends.

  • track – the Track to get the cover for.
  • save_cover – if True, a set_cover call will be made to store the cover for later use.
  • set_only – Only retrieve covers that have been set in the db.
  • use_default – If True, returns the default cover instead of None when no covers are found.
get_cover_data(db_string, use_default=False)[source]

Get the raw image data for a cover.

  • db_string – The db_string identifying the cover to get.
  • use_default – If True, returns the default cover instead of None when no covers are found.
get_cover_for_tracks(tracks, db_strings_to_ignore)[source]

For tracks, try to find a cover Basically returns the first cover found :param tracks: list of tracks [xl.trax.Track] :param db_strings_to_ignore: list [str] :return: GdkPixbuf.Pixbuf or None if no cover found

get_db_string(track: xl.trax.track.Track) → Optional[str][source]

Returns the internal string used to map the cover to a track

Parameters:track (xl.trax.Track) – the track to retrieve the string for
Returns:the internal identifier string

Get the raw image data for the cover to show if there is no cover to display.


Load the saved db


Called when a new provider is added

Parameters:provider (object) – the new provider

Called when a provider is removed

Parameters:provider (object) – the removed provider

Remove the saved cover entry for a track, if it exists.


Save the db

set_cover(track, db_string, data=None)[source]

Sets the cover for a track. This will overwrite any existing entry.

  • track – The track to set the cover for
  • db_string – the string identifying the source of the cover, in “method:key” format.
  • data – The raw cover data to store for the track. Will only be stored if the method has use_cache=True

Sets the preferred search order

Parameters:order – a list containing the order you’d like to search first

Cover Search Methods

class xl.covers.CoverSearchMethod[source]

Base class for creating cover search methods.

Search methods do not have to inherit from this class, it’s intended more as a template to demonstrate the needed interface.

find_covers(track, limit=-1)[source]

Find the covers for a given track.

  • track – The track to find covers for.
  • limit – Maximal number of covers to return.

A list of strings that can be passed to get_cover_data.


Get the image data for a cover

Parameters:db_string – A method-dependent string that identifies the cover to get.
name = 'base'

A name uniquely identifying the search method.

use_cache = True

If true, cover results will be cached for faster lookup

class xl.covers.TagCoverFetcher[source]

Cover source that looks for images embedded in tags.

class xl.covers.LocalFileCoverFetcher[source]

Cover source that looks for images in the same directory as the Track.