Trax

Provides the base for creating and managing Track objects.

Tracks

class xl.trax.Track(uri=None, scan=True, _unpickles=None)[source]

Represents a single track.

exists()[source]

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

get_loc_for_io()[source]

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_rating()[source]

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)[source]

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)[source]

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)[source]

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()[source]

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

list_tags()[source]

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

local_file_name()[source]

If the file is accessible on the local filesystem, returns a standard path to it (e.g. “/home/foo/bar”), otherwise, returns None.

If a path is returned, it is safe to use for IO operations. Existence of a path does not guarantee file existence.

read_tags(force=True, notify_changed=True)[source]

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, notify_changed=True)[source]

Sets the location.

Parameters:loc – the location, as either a uri or a file path.
set_rating(rating)[source]

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)[source]

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

set_tags(notify_changed=True, **kwargs)[source]

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

write_tags()[source]

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)[source]

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

Parameters:location (string) – the location to check
Returns:whether the file is a valid track
Return type:boolean
xl.trax.get_uris_from_tracks(tracks)[source]

Returns all URIs for tracks

Parameters:tracks (list of xl.trax.Track) – the tracks to retrieve the URIs from
Returns:the uris
Return type:list of string
xl.trax.get_tracks_from_uri(uri)[source]

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, iter, trackfunc=None, reverse=False, artist_compilations=False)[source]

Sorts tracks.

Parameters:
  • fields (iterable) – tag names to sort by
  • iter (iterable) – the tracks to sort, alternatively use trackfunc
  • trackfunc (function or None) – function to get a Track from an item in the iterable
  • reverse (boolean) – whether to sort in reversed order
xl.trax.sort_result_tracks(fields, trackiter, reverse=False, artist_compilations=False)[source]

Sorts SearchResultTracks, ie. the output from a search.

Same params as sort_tracks.

xl.trax.get_rating_from_tracks(tracks)[source]

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='', location='', pickle_attrs=[], loadfirst=False)[source]

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)[source]

Adds a track to the database of tracks

Parameters:track – The xl.trax.Track to add
add_tracks(*__args, **__kw)[source]

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

load_from_location(*__args, **__kw)[source]

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

Parameters:location (string) – the location to load the data from
remove(track)[source]

Removes a track from the database

Parameters:track – the xl.trax.Track to remove
remove_tracks(*__args, **__kw)[source]

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

save_to_location(*__args, **__kw)[source]

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

Parameters:location (string) – the location to save the data to

Searching

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

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

xl.trax.search_tracks(trackiter, trackmatchers)[source]

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)[source]

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.