Trax

Provides the base for creating and managing Track objects.

Tracks

class xl.trax.Track(*args, **kwargs)

Represents a single track.

exists()

Returns whether the file exists This can be very slow, use with caution!

get_loc_for_io() → str

Gets the location as a full uri.

Safe for IO operations via gio, not suitable for display to users as it may be in non-utf-8 encodings.

get_local_path()

If the file is accessible on a local filesystem, retrieves the full path to it, otherwise nothing.

Returns:

the file path or None

Return type:

string or NoneType

get_rating()

Returns the current track rating as an integer, as determined by the rating/maximum setting.

Return type:

int

get_tag_display(tag, join=True, artist_compilations=False, extend_title=True) → str | List[str]

Get a tag value in a form suitable for display.

Parameters:

• tag – The name of the tag to get

• join – If True, joins lists of values into a single value.

• artist_compilations – If True, automatically handle albumartist and other compilations detections when tag==”albumartist”.

• extend_title – If the title tag is unknown, try to add some identifying information to it.

get_tag_raw(tag, join=False)

Get the raw value of a tag. For non-internal tags, the result will always be a list of unicode strings.

Parameters:

• tag – The name of the tag to get

• join – If True, joins lists of values into a single value.

Returns:

None if the tag is not present

get_tag_sort(tag, join=True, artist_compilations=False, extend_title=True)

Get a tag value in a form suitable for sorting.

Parameters:

• tag – The name of the tag to get

• join – If True, joins lists of values into a single value.

• artist_compilations – If True, automatically handle albumartist and other compilations detections when tag==”albumartist”.

• extend_title – If the title tag is unknown, try to add some identifying information to it.

get_type()

Get the URI schema the file uses, e.g. file, http, smb.

list_tags()

Returns a list of the names of all tags present in this Track.

read_tags(force=True, notify_changed=True)

Reads tags from the file for this Track.

Parameters:

force – If not True, then only read the tags if the file has be modified.

Returns False if unsuccessful, and a Format object from xl.metadata otherwise.

set_loc(loc: str, notify_changed: bool = True) → None

Sets the location.

Parameters:

loc – the location, as either a uri or a file path.

set_rating(rating)

Sets the current track rating from an integer, on the scale determined by the rating/maximum setting.

Returns the scaled rating

set_tag_raw(tag, values, notify_changed=True)

Set the raw value of a tag.

Parameters:

• tag – The name of the tag to set.

• values – The value or values to set the tag to.

• notify_changed – whether to send a signal to let other parts of Exaile know there has been an update. Only set this to False if you know that no other parts of Exaile need to be updated.

Note

When setting more than one tag, prefer set_tags instead

Warning

Covers and lyrics tags must be set via set_tag_disk

Returns:

True if changed, False otherwise

set_tags(notify_changed=True, **kwargs)

Set multiple tags on a track.

Parameters:

notify_changed – whether to send a signal to let other parts of Exaile know there has been an update. Only set this to False if you know that no other parts of Exaile need to be updated.

Prefer this method over calling set_tag_raw multiple times, as this method will be more efficient.

Warning

Covers and lyrics tags must be set via set_tag_disk

Returns:

Set of tags that have changed

write_tags()

Writes tags to the file for this Track.

Returns False if unsuccessful, and a Format object from xl.metadata otherwise.

xl.trax.is_valid_track(location: str) → bool

Returns whether the file at the given location is a valid track

Parameters:

location – the location to check

Returns:

whether the file is a valid track

xl.trax.get_uris_from_tracks(tracks: Iterable[Track]) → List[str]

Returns all URIs for tracks

Parameters:

tracks – the tracks to retrieve the URIs from

Returns:

the uris

xl.trax.get_tracks_from_uri(uri: str) → List[Track]

Returns all valid tracks located at uri

Parameters:

uri (string) – the uri to retrieve the tracks from

Returns:

the retrieved tracks

Return type:

list of xl.trax.Track

xl.trax.sort_tracks(fields: Iterable[str], items: Iterable[_T], trackfunc: Callable[[_T], Track] | None = None, reverse: bool = False, artist_compilations: bool = False) → List[_T]

Sorts tracks.

Parameters:

• fields – tag names to sort by

• items – the tracks to sort, alternatively use trackfunc

• trackfunc – function to get a Track from an item in the items iterable

• reverse – whether to sort in reversed order

xl.trax.sort_result_tracks(fields, trackiter, reverse=False, artist_compilations=False)

Sorts SearchResultTracks, ie. the output from a search.

Same params as sort_tracks.

xl.trax.get_rating_from_tracks(tracks)

Returns the common rating for all tracks or simply 0 if not all tracks have the same rating. Same goes if the amount of tracks is 0 or more than the internal limit.

Parameters:

tracks (iterable) – the tracks to retrieve the rating from

Track Database

Track databases are a simple persistence layer to hold collections of Track objects.

class xl.trax.TrackDB(name: str = '', location: str = '', pickle_attrs: List[str] = [], loadfirst: bool = False)

Manages a track database.

Allows you to add, remove, retrieve, search, save and load Track objects.

Parameters:

• name – The name of this TrackDB.

• location – Path to a file where this TrackDB should be stored.

• pickle_attrs – A list of attributes to store in the pickled representation of this object. All attributes listed must be built-in types, with one exception: If the object contains the phrase ‘tracks’ in its name it may be a list or dict of Track objects.

• load_first – Set to True if this collection should be loaded before any tracks are created.

add(track: Track) → None

Adds a track to the database of tracks

Parameters:

track – The xl.trax.Track to add

add_tracks(tracks: Iterable[Track]) → None

Like add(), but takes a list of xl.trax.Track

load_from_location(location: str | None = None)

Restores TrackDB state from the pickled representation stored at the specified location.

Parameters:

location – the location to load the data from

remove(track: Track) → None

Removes a track from the database

Parameters:

track – the xl.trax.Track to remove

remove_tracks(tracks: Iterable[Track]) → None

Like remove(), but takes a list of xl.trax.Track

save_to_location(location: str | None = None)

Saves a pickled representation of this TrackDB to the specified location.

Parameters:

location – the location to save the data to

Searching

class xl.trax.TracksMatcher(search_string, case_sensitive=True, keyword_tags=None)

Holds criteria and determines whether a given track matches those criteria.

xl.trax.search_tracks(trackiter, trackmatchers: Collection[TracksMatcher])

Search a set of tracks for those that match specified conditions.

Parameters:

• trackiter – An iterable object returning Track objects

• trackmatchers – A list of TrackMatcher objects

xl.trax.search_tracks_from_string(trackiter, search_string, case_sensitive=True, keyword_tags=None)

Convenience wrapper around search_tracks that builds matchers automatically from the search string.

Arguments have the same meaning as the corresponding arguments on on search_tracks and TracksMatcher.