Trait mpris_server::PlayerInterface

pub trait PlayerInterface:
    RootInterface
    + Send
    + Sync {
    // Required methods
    fn next(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn previous(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn pause(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn play_pause(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn stop(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn play(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn seek(
        &self,
        offset: Time,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn set_position(
        &self,
        track_id: TrackId,
        position: Time,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn open_uri(
        &self,
        uri: String,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn playback_status(
        &self,
    ) -> impl Future<Output = Result<PlaybackStatus>> + Send + Sync;
    fn loop_status(
        &self,
    ) -> impl Future<Output = Result<LoopStatus>> + Send + Sync;
    fn set_loop_status(
        &self,
        loop_status: LoopStatus,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn rate(&self) -> impl Future<Output = Result<PlaybackRate>> + Send + Sync;
    fn set_rate(
        &self,
        rate: PlaybackRate,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn shuffle(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn set_shuffle(
        &self,
        shuffle: bool,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn metadata(&self) -> impl Future<Output = Result<Metadata>> + Send + Sync;
    fn volume(&self) -> impl Future<Output = Result<Volume>> + Send + Sync;
    fn set_volume(
        &self,
        volume: Volume,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn position(&self) -> impl Future<Output = Result<Time>> + Send + Sync;
    fn minimum_rate(
        &self,
    ) -> impl Future<Output = Result<PlaybackRate>> + Send + Sync;
    fn maximum_rate(
        &self,
    ) -> impl Future<Output = Result<PlaybackRate>> + Send + Sync;
    fn can_go_next(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn can_go_previous(
        &self,
    ) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn can_play(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn can_pause(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn can_seek(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn can_control(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
}

Used to implement org.mpris.MediaPlayer2.Player interface, which implements the methods for querying and providing basic control over what is currently playing.

Required Methods

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

Skips to the next track in the tracklist.

If there is no next track (and endless playback and track repeat are both off), stop playback.

If playback is paused or stopped, it remains that way.

If CanGoNext is false, attempting to call this method should have no effect.

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

Skips to the previous track in the tracklist.

If there is no previous track (and endless playback and track repeat are both off), stop playback.

If playback is paused or stopped, it remains that way.

If CanGoPrevious is false, attempting to call this method should have no effect.

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

Pauses playback.

If playback is already paused, this has no effect.

Calling Play after this should cause playback to start again from the same position.

If CanPause is false, attempting to call this method should have no effect.

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

Pauses playback.

If playback is already paused, resumes playback.

If playback is stopped, starts playback.

If CanPause is false, attempting to call this method should have no effect and raise an error.

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

Stops playback.

If playback is already stopped, this has no effect.

Calling Play after this should cause playback to start again from the beginning of the track.

If CanControl is false, attempting to call this method should have no effect and raise an error.

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

Starts or resumes playback.

If already playing, this has no effect.

If paused, playback resumes from the current position.

If there is no track to play, this has no effect.

If CanPlay is false, attempting to call this method should have no effect.

fn seek(&self, offset: Time) -> impl Future<Output = Result<()>> + Send + Sync

Seeks forward in the current track by the specified offset in time.

Parameters

• offset - The offset in time to seek forward.

A negative value seeks back. If this would mean seeking back further than the start of the track, the position is set to 0.

If the value passed in would mean seeking beyond the end of the track, acts like a call to Next.

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

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

Sets the current track position.

Parameters

• track_id - The currently playing track’s identifier. If this does not match the id of the currently-playing track, the call is ignored as “stale”. /org/mpris/MediaPlayer2/TrackList/NoTrack is not a valid value for this argument.
• position - The track position. This must be between 0 and <track_length>.

If the Position argument is less than 0, do nothing.

If the Position argument is greater than the track length, do nothing.

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

Rationale

The reason for having this method, rather than making Position writable, is to include the track_id argument to avoid race conditions where a client tries to seek to a position when the track has already changed.

fn open_uri( &self, uri: String, ) -> impl Future<Output = Result<()>> + Send + Sync

Opens the uri given as an argument

Parameters

• uri - Uri of the track to load. Its uri scheme should be an element of the SupportedUriSchemes property and the mime-type should match one of the elements of the SupportedMimeTypes.

If the playback is stopped, starts playing

If the uri scheme or the mime-type of the uri to open is not supported, this method does nothing and may raise an error. In particular, if the list of available uri schemes is empty, this method may not be implemented.

Clients should not assume that the uri has been opened as soon as this method returns. They should wait until the mpris:trackid field in the Metadata property changes.

If the media player implements the TrackList interface, then the opened track should be made part of the tracklist, the TrackAdded or TrackListReplaced signal should be fired, as well as the org.freedesktop.DBus.Properties.PropertiesChanged signal on the TrackList interface.

fn playback_status( &self, ) -> impl Future<Output = Result<PlaybackStatus>> + Send + Sync

The current playback status.

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

May be Playing, Paused or Stopped.

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

The current loop / repeat status

This property is optional. Clients should handle its absence gracefully.

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

May be:

• None if the playback will stop when there are no more tracks to play
• Track if the current track will start again from the beginning once it has finished playing
• Playlist if the playback loops through a list of tracks

If CanControl is false, attempting to set this property should have no effect and raise an error.

fn set_loop_status( &self, loop_status: LoopStatus, ) -> impl Future<Output = Result<()>> + Send + Sync

Sets the current loop / repeat status

See LoopStatus for more details.

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

The current playback rate.

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

The value must fall in the range described by MinimumRate and MaximumRate, and must not be 0.0. If playback is paused, the PlaybackStatus property should be used to indicate this. A value of 0.0 should not be set by the client. If it is, the media player should act as though Pause was called.

If the media player has no ability to play at speeds other than the normal playback rate, this must still be implemented, and must return 1.0. The MinimumRate and MaximumRate properties must also be set to 1.0.

Not all values may be accepted by the media player. It is left to media player implementations to decide how to deal with values they cannot use; they may either ignore them or pick a “best fit” value. Clients are recommended to only use sensible fractions or multiples of 1 (eg: 0.5, 0.25, 1.5, 2.0, etc).

Rationale

This allows clients to display (reasonably) accurate progress bars without having to regularly query the media player for the current position.

fn set_rate( &self, rate: PlaybackRate, ) -> impl Future<Output = Result<()>> + Send + Sync

Sets the current playback rate.

See Rate for more details.

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

Whether playback is shuffled.

This property is optional. Clients should handle its absence gracefully.

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

A value of false indicates that playback is progressing linearly through a playlist, while true means playback is progressing through a playlist in some other order.

If CanControl is false, attempting to set this property should have no effect and raise an error.

fn set_shuffle( &self, shuffle: bool, ) -> impl Future<Output = Result<()>> + Send + Sync

Sets whether playback is shuffled.

See Shuffle for more details.

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

The metadata of the current element.

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

If there is a current track, this must have a mpris:trackid entry at the very least, which contains a D-Bus path that uniquely identifies this track.

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

The volume level.

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

When setting, if a negative value is passed, the volume should be set to 0.0.

If CanControl is false, attempting to set this property should have no effect and raise an error.

fn set_volume( &self, volume: Volume, ) -> impl Future<Output = Result<()>> + Send + Sync

Sets the volume level.

See Volume for more details.

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

The current track position, between 0 and the mpris:length metadata entry.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must not be emitted.

Note: If the media player allows it, the current playback position can be changed either the SetPosition method or the Seek method on this interface. If this is not the case, the CanSeek property is false, and setting this property has no effect and can raise an error.

If the playback progresses in a way that is inconstistent with the Rate property, the Seeked signal is emitted.

fn minimum_rate( &self, ) -> impl Future<Output = Result<PlaybackRate>> + Send + Sync

The minimum value which the Rate property can take. Clients should not attempt to set the Rate property below this value.

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

Note that even if this value is 0.0 or negative, clients should not attempt to set the Rate property to 0.0.

This value should always be 1.0 or less.

fn maximum_rate( &self, ) -> impl Future<Output = Result<PlaybackRate>> + Send + Sync

The maximum value which the Rate property can take. Clients should not attempt to set the Rate property above this value.

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

This value should always be 1.0 or greater.

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

Whether the client can call the Next method on this interface and expect the current track to change.

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

If it is unknown whether a call to Next will be successful (for example, when streaming tracks), this property should be set to true.

If CanControl is false, this property should also be false.

Rationale

Even when playback can generally be controlled, there may not always be a next track to move to.

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

Whether the client can call the Previous method on this interface and expect the current track to change.

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

If it is unknown whether a call to Previous will be successful (for example, when streaming tracks), this property should be set to true.

If CanControl is false, this property should also be false.

Rationale

Even when playback can generally be controlled, there may not always be a next previous to move to.

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

Whether playback can be started using Play or PlayPause.

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

Note that this is related to whether there is a “current track”: the value should not depend on whether the track is currently paused or playing. In fact, if a track is currently playing (and CanControl is true), this should be true.

If CanControl is false, this property should also be false.

Rationale

Even when playback can generally be controlled, it may not be possible to enter a “playing” state, for example if there is no “current track”.

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

Whether playback can be paused using Pause or PlayPause.

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

Note that this is an intrinsic property of the current track: its value should not depend on whether the track is currently paused or playing. In fact, if playback is currently paused (and CanControl is true), this should be true.

If CanControl is false, this property should also be false.

Rationale

Not all media is pausable: it may not be possible to pause some streamed media, for example.

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

Whether the client can control the playback position using Seek and SetPosition. This may be different for different tracks.

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

If CanControl is false, this property should also be false.

Rationale

Not all media is seekable: it may not be possible to seek when playing some streamed media, for example.

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

Whether the media player may be controlled over this interface.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must not be emitted.

This property is not expected to change, as it describes an intrinsic capability of the implementation.

If this is false, clients should assume that all properties on this interface are read-only (and will raise errors if writing to them is attempted), no methods are implemented and all other properties starting with Can are also false.

Rationale

This allows clients to determine whether to present and enable controls to the user in advance of attempting to call methods and write to properties.

Object Safety

This trait is not object safe.

Implementors