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)

Handles finding covers from various sources.

Parameters:location – The directory to load and store data in.
find_covers(*__args, **__kw)

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)

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)

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.

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)

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

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)

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 identifing the search method.

use_cache = True

If true, cover results will be cached for faster lookup

class xl.covers.TagCoverFetcher

Cover source that looks for images embedded in tags.

class xl.covers.LocalFileCoverFetcher

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