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.
-
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) → Union[str, List[str]][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.
Returns a list of the names of all tags present in this Track.
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
Returns: True if changed, False otherwise
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
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 fromReturns: 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: Iterable[str], items: Iterable[T], trackfunc: Optional[Callable[[T], xl.trax.track.Track]] = None, reverse: bool = False, artist_compilations: bool = False) → List[T][source]¶ 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
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)[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: xl.trax.track.Track) → None[source]¶ Adds a track to the database of tracks
Parameters: track – The xl.trax.Track
to add
-
add_tracks
(tracks: Iterable[xl.trax.track.Track]) → None[source]¶ Like add(), but takes a list of
xl.trax.Track
-
load_from_location
(location=None)[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: xl.trax.track.Track) → None[source]¶ Removes a track from the database
Parameters: track – the xl.trax.Track
to remove
-
remove_tracks
(tracks: Iterable[xl.trax.track.Track]) → None[source]¶ Like remove(), but takes a list of
xl.trax.Track
- name – The name of this
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: Collection[xl.trax.search.TracksMatcher])[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
andTracksMatcher
.