Trait mpris_server::TrackListInterface

source · 
pub trait TrackListInterface:
    PlayerInterface
    + Send
    + Sync {
    // Required methods
    fn get_tracks_metadata(
        &self,
        track_ids: Vec<TrackId>,
    ) -> impl Future<Output = Result<Vec<Metadata>>> + Send + Sync;
    fn add_track(
        &self,
        uri: Uri,
        after_track: TrackId,
        set_as_current: bool,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn remove_track(
        &self,
        track_id: TrackId,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn go_to(
        &self,
        track_id: TrackId,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn tracks(&self) -> impl Future<Output = Result<Vec<TrackId>>> + Send + Sync;
    fn can_edit_tracks(
        &self,
    ) -> impl Future<Output = Result<bool>> + Send + Sync;
}
Expand description

Used to implement org.mpris.MediaPlayer2.TrackList interface, which provides access to a short list of tracks which were recently played or will be played shortly. This is intended to provide context to the currently-playing track, rather than giving complete access to the media player’s playlist.

Example use cases are the list of tracks from the same album as the currently playing song or the Rhythmbox play queue.

Each track in the tracklist has a unique identifier. The intention is that this uniquely identifies the track within the scope of the tracklist. In particular, if a media item (a particular music file, say) occurs twice in the track list, each occurrence should have a different identifier. If a track is removed from the middle of the playlist, it should not affect the track ids of any other tracks in the tracklist.

As a result, the traditional track identifiers of URLs and position in the playlist cannot be used. Any scheme which satisfies the uniqueness requirements is valid, as clients should not make any assumptions about the value of the track id beyond the fact that it is a unique identifier.

Note that the (memory and processing) burden of implementing this interface and maintaining unique track ids for the playlist can be mitigated by only exposing a subset of the playlist when it is very long (the 20 or so tracks around the currently playing track, for example). This is a recommended practice as the tracklist interface is not designed to enable browsing through a large list of tracks, but rather to provide clients with context about the currently playing track.

Required Methods§

source

fn get_tracks_metadata( &self, track_ids: Vec<TrackId>, ) -> impl Future<Output = Result<Vec<Metadata>>> + Send + Sync

Gets all the metadata available for a set of tracks.

§Parameters
  • track_ids - The list of track ids for which metadata is requested.
§Returns
  • metadata - Metadata of the set of tracks given as input.

Each set of metadata must have a mpris:trackid entry at the very least, which contains a string that uniquely identifies this track within the scope of the tracklist.

source

fn add_track( &self, uri: Uri, after_track: TrackId, set_as_current: bool, ) -> impl Future<Output = Result<()>> + Send + Sync

Adds a URI in the tracklist.

§Parameters
  • uri - The uri of the item to add. Its uri scheme should be an element of the SupportedUriSchemes property and the mime-type should match one of the elements of the SupportedMimeTypes property.
  • after_track - The identifier of the track after which the new item should be inserted. The path /org/mpris/MediaPlayer2/TrackList/NoTrack indicates that the track should be inserted at the start of the track list.
  • set_as_current - Whether the newly inserted track should be considered as the current track. Setting this to true has the same effect as calling GoTo afterwards.

If the CanEditTracks property is false, this has no effect.

Note: Clients should not assume that the track has been added at the time when this method returns. They should wait for a TrackAdded (or TrackListReplaced) signal.

source

fn remove_track( &self, track_id: TrackId, ) -> impl Future<Output = Result<()>> + Send + Sync

Removes an item from the tracklist.

§Parameters

If the track is not part of this tracklist, this has no effect.

If the CanEditTracks property is false, this has no effect.

Note: Clients should not assume that the track has been removed at the time when this method returns. They should wait for a TrackRemoved (or TrackListReplaced) signal.

source

fn go_to( &self, track_id: TrackId, ) -> impl Future<Output = Result<()>> + Send + Sync

Skip to the specified TrackId.

§Parameters
  • track_id - Identifier of the track to skip to. [/org/mpris/MediaPlayer2/TrackList/NoTrack] is not a valid value for this argument.

If the track is not part of this tracklist, this has no effect.

If this object is not /org/mpris/MediaPlayer2, the current tracklist’s tracks should be replaced with the contents of this tracklist, and the TrackListReplaced signal should be fired from /org/mpris/MediaPlayer2.

source

fn tracks(&self) -> impl Future<Output = Result<Vec<TrackId>>> + Send + Sync

An array which contains the identifier of each track in the tracklist, in order.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via track_list_properties_changed must be emitted without the new value.

The org.freedesktop.DBus.Properties.PropertiesChanged signal is emitted every time this property changes, but the signal message does not contain the new value. Client implementations should rather rely on the TrackAdded, TrackRemoved and TrackListReplaced signals to keep their representation of the tracklist up to date.

source

fn can_edit_tracks(&self) -> impl Future<Output = Result<bool>> + Send + Sync

Whether tracks can be added to and removed from the tracklist.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via track_list_properties_changed must be emitted with the new value.

If false, calling AddTrack or RemoveTrack will have no effect, and may raise a NotSupported error.

Object Safety§

This trait is not object safe.

Implementors§