Struct mpris::Player

pub struct Player { /* private fields */ }

A MPRIS-compatible player.

You can query this player about the currently playing media, or control it.

See: MPRIS2 MediaPlayer2.Player Specification.

Implementations

impl Player

pub fn new( connection: Connection, bus_name: String, timeout_ms: i32 ) -> Result<Player, DBusError>

Create a new Player using a D-Bus connection and address information.

If no player is running on this bus name an Err will be returned.

pub fn dbus_timeout_ms(&self) -> i32

Returns the current D-Bus communication timeout (in milliseconds).

When querying D-Bus the call should not block longer than this, and will instead fail the query if no response has been received in this time.

You can change this using set_dbus_timeout_ms.

pub fn set_dbus_timeout_ms(&mut self, timeout_ms: i32)

Change the D-Bus communication timeout.

pub fn bus_name(&self) -> &str

Returns the player’s D-Bus bus name.

pub fn bus_name_player_name_part(&self) -> &str

Returns the player name part of the player’s D-Bus bus name. This is the part after “org.mpris.MediaPlayer2.”, not including the instance part.

See: MPRIS2 specification about bus names.

pub fn unique_name(&self) -> &str

Returns the player’s unique D-Bus bus name (usually something like :1.1337).

pub fn identity(&self) -> &str

Returns the player’s MPRIS Identity.

This is usually the application’s name, like Spotify.

pub fn supports_track_lists(&self) -> bool

Checks if the Player implements the org.mpris.MediaPlayer2.TrackList interface.

pub fn get_desktop_entry(&self) -> Result<Option<String>, DBusError>

Returns the player’s DesktopEntry property, if supported.

See: MPRIS2 specification about DesktopEntry.

pub fn get_supported_mime_types(&self) -> Result<Vec<String>, DBusError>

Returns the player’s SupportedMimeTypes property.

See: MPRIS2 specification about SupportedMimeTypes.

pub fn get_supported_uri_schemes(&self) -> Result<Vec<String>, DBusError>

Returns the player’s SupportedUriSchemes property.

See: MPRIS2 specification about SupportedUriSchemes.

pub fn get_has_track_list(&self) -> Result<bool, DBusError>

Returns the player’s HasTrackList property.

See: MPRIS2 specification about HasTrackList.

pub fn get_position(&self) -> Result<Duration, DBusError>

Returns the player’s MPRIS position as a Duration since the start of the media.

pub fn checked_get_position(&self) -> Result<Option<Duration>, DBusError>

Gets the “Position” setting, if the player indicates that it supports it.

Return Some containing the current value of the position. If the setting is not supported, return None

pub fn get_position_in_microseconds(&self) -> Result<u64, DBusError>

Returns the player’s MPRIS position as a count of microseconds since the start of the media.

pub fn set_position( &self, track_id: TrackID, position: &Duration ) -> Result<(), DBusError>

Sets the position of the current track to the given position (as a Duration).

Current TrackID must be provided to avoid race conditions with the player, in case it changes tracks while the signal is being sent.

Note: There is currently no good way to retrieve the current TrackID through the mpris library. You will have to manually retrieve it through D-Bus until implemented.

See: MPRIS2 specification about SetPosition.

pub fn checked_set_position( &self, track_id: TrackID, position: &Duration ) -> Result<bool, DBusError>

Set the “Position” setting of the player, if the player indicates that it supports the “Position” setting and can be controlled.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Position.

pub fn set_position_in_microseconds( &self, track_id: TrackID, position_in_us: u64 ) -> Result<(), DBusError>

Sets the position of the current track to the given position (in microseconds).

Current TrackID must be provided to avoid race conditions with the player, in case it changes tracks while the signal is being sent.

Note: There is currently no good way to retrieve the current TrackID through the mpris library. You will have to manually retrieve it through D-Bus until implemented.

See: MPRIS2 specification about SetPosition.

pub fn get_playback_rate(&self) -> Result<f64, DBusError>

Returns the player’s MPRIS (playback) rate as a factor.

1.0 would mean normal rate, while 2.0 would mean twice the playback speed.

pub fn checked_get_playback_rate(&self) -> Result<Option<f64>, DBusError>

Gets the “Rate” setting, if the player indicates that it supports it.

Returns Some containing the current value of the rate setting. If the setting is not supported, returns None

pub fn set_playback_rate(&self, rate: f64) -> Result<(), DBusError>

Sets the player’s MPRIS (playback) rate as a factor.

1.0 would mean normal rate, while 2.0 would mean twice the playback speed.

It is not allowed to try to set playback rate to a value outside of the supported range. get_valid_playback_rate_range returns a Range<f64> that encodes the maximum and minimum values.

You must not set rate to 0.0; instead call pause.

See: MPRIS2 specification about Rate.

pub fn checked_set_playback_rate(&self, rate: f64) -> Result<bool, DBusError>

Set the playback rate of the player, if the player indicates that supports it and that it can be controlled.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Rate.

pub fn get_minimum_playback_rate(&self) -> Result<f64, DBusError>

Gets the minimum allowed value for playback rate.

See: MPRIS2 specification about MinimumRate.

pub fn get_maximum_playback_rate(&self) -> Result<f64, DBusError>

Gets the maximum allowed value for playback rate.

See: MPRIS2 specification about MaximumRate.

pub fn get_valid_playback_rate_range(&self) -> Result<Range<f64>, DBusError>

Gets the minimum-maximum allowed value range for playback rate.

See: get_minimum_playback_rate and get_maximum_playback_rate.

pub fn get_metadata(&self) -> Result<Metadata, DBusError>

Query the player for current metadata.

See Metadata for more information about what is included here.

pub fn get_track_list(&self) -> Result<TrackList, DBusError>

Query the player for the current tracklist.

Note: It’s more expensive to rebuild this each time rather than trying to keep the same TrackList updated. See TrackList::reload.

See checked_get_track_list to automatically detect players not supporting track lists.

pub fn checked_get_track_list(&self) -> Result<Option<TrackList>, DBusError>

Query the player for the current tracklist.

Note: It’s more expensive to rebuild this each time rather than trying to keep the same TrackList updated. See TrackList::reload.

See get_track_list, supports_track_lists and get_has_track_list if you want to manually handle compatibility checks.

pub fn can_edit_tracks(&self) -> Result<bool, DBusError>

Query the player to see if it allows changes to its TrackList.

Will return Err if Player isn’t supporting the TrackList interface.

See checked_can_edit_tracks to automatically detect players not supporting track lists.

See: MPRIS2 specification about CanEditTracks.

pub fn checked_can_edit_tracks(&self) -> bool

Query the player to see if it allows changes to its TrackList.

Will return false if Player isn’t supporting the TrackList interface.

See can_edit_tracks and supports_track_lists if you want to manually handle compatibility checks.

See: MPRIS2 specification about CanEditTracks.

pub fn get_tracks_metadata( &self, track_ids: &[TrackID] ) -> Result<Vec<Metadata>, DBusError>

Query the player for metadata for the given TrackIDs.

This is used by the TrackList type to iterator metadata for the tracks in the track list.

See: MediaPlayer2.TrackList.GetTracksMetadata.

pub fn get_track_metadata( &self, track_id: &TrackID ) -> Result<Metadata, DBusError>

Query the player for metadata for a single TrackID.

Note that get_tracks_metadata with a list is more effective if you have more than a single TrackID to load.

See: MediaPlayer2.TrackList.GetTracksMetadata.

pub fn track_progress( &self, interval_ms: u32 ) -> Result<ProgressTracker<'_>, DBusError>

Returns a new ProgressTracker for the player.

Use this if you want to monitor a player in order to show close-to-realtime information about it.

It is built like a blocking “frame limiter” where it returns at an approximately fixed interval with the most up-to-date information. It’s mostly appropriate when trying to render something like a progress bar, or information about the current track.

See: events for an alternative approach.

pub fn events(&self) -> Result<PlayerEvents<'_>, DBusError>

Returns a PlayerEvents iterator, or an DBusError if there was a problem with the D-Bus connection to the player.

This iterator will block until an event for the current player is emitted. This is a lot more bare-bones than track_progress, but it’s also something that makes it easier for you to translate events into your own application’s domain events and only deal with actual changes.

You could implement your own progress tracker on top of this, but it’s probably not appropriate to render a live progress bar using this iterator as the progress bar will remain frozen until the next event is emitted and the iterator returns.

See: track_progress for an alternative approach.

pub fn is_running(&self) -> bool

Returns true if the bus of this player is still occupied in the connection, or put in another way: If there’s a process still listening on messages on this bus.

If the player that you are controlling / querying has shut down, then this would return false. You can use this to do graceful restarts, begin looking for another player, etc.

pub fn play_pause(&self) -> Result<(), DBusError>

Send a PlayPause signal to the player.

See: MPRIS2 specification about PlayPause

pub fn play(&self) -> Result<(), DBusError>

Send a Play signal to the player.

See: MPRIS2 specification about Play.

pub fn pause(&self) -> Result<(), DBusError>

Send a Pause signal to the player.

See: MPRIS2 specification about Pause.

pub fn stop(&self) -> Result<(), DBusError>

Send a Stop signal to the player.

See: MPRIS2 specification about Stop.

pub fn next(&self) -> Result<(), DBusError>

Send a Next signal to the player.

See: MPRIS2 specification about Next.

pub fn previous(&self) -> Result<(), DBusError>

Send a Previous signal to the player.

See: MPRIS2 specification about Previous.

pub fn seek(&self, offset_in_microseconds: i64) -> Result<(), DBusError>

Send a Seek signal to the player.

See: MPRIS2 specification about Seek.

pub fn seek_forwards(&self, offset: &Duration) -> Result<(), DBusError>

Tell the player to seek forwards.

See: seek method.

pub fn raise(&self) -> Result<(), DBusError>

Send a Raise signal to the player.

Brings the media player’s user interface to the front using any appropriate mechanism available.

The media player may be unable to control how its user interface is displayed, or it may not have a graphical user interface at all. In this case, the CanRaise property is false and this method does nothing.

See: MPRIS2 specification about Raise and the can_raise method.

pub fn checked_raise(&self) -> Result<bool, DBusError>

Send a Raise signal to the player, if it supports it.

See: can_raise and raise methods.

pub fn quit(&self) -> Result<(), DBusError>

Send a Quit signal to the player.

Causes the media player to stop running.

The media player may refuse to allow clients to shut it down. In this case, the CanQuit property is false and this method does nothing.

Note: Media players which can be D-Bus activated, or for which there is no sensibly easy way to terminate a running instance (via the main interface or a notification area icon for example) should allow clients to use this method. Otherwise, it should not be needed.

If the media player does not have a UI, this should be implemented.

See: MPRIS2 specification about Quit and the can_quit method.

pub fn checked_quit(&self) -> Result<bool, DBusError>

Send a Quit signal to the player, if it supports it.

See: can_quit and quit methods.

pub fn seek_backwards(&self, offset: &Duration) -> Result<(), DBusError>

Tell the player to seek backwards.

See: seek method.

pub fn go_to(&self, track_id: &TrackID) -> Result<(), DBusError>

Go to a specific track on the Player’s TrackList.

If the given TrackID is not part of the player’s TrackList, it will have no effect.

Requires the player to implement the TrackList interface.

See: MPRIS2 specification about GoTo

pub fn add_track( &self, uri: &str, after: &TrackID, set_as_current: bool ) -> Result<(), DBusError>

Add a URI to the TrackList and optionally set it as current.

It is placed after the specified TrackID, if supported by the player.

Requires the player to implement the TrackList interface.

See: MPRIS2 specification about AddTrack.

pub fn add_track_at_start( &self, uri: &str, set_as_current: bool ) -> Result<(), DBusError>

Add a URI to the start of the TrackList and optionally set it as current.

Requires the player to implement the TrackList interface.

See: MPRIS2 specification about AddTrack.

pub fn remove_track(&self, track_id: &TrackID) -> Result<(), DBusError>

Remove an item from the TrackList.

Requires the player to implement the TrackList interface.

See: MPRIS2 specification about RemoveTrack.

pub fn checked_play_pause(&self) -> Result<bool, DBusError>

Sends a PlayPause signal to the player, if the player indicates that it can pause.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about PlayPause

pub fn checked_play(&self) -> Result<bool, DBusError>

Sends a Play signal to the player, if the player indicates that it can play.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Play.

pub fn checked_pause(&self) -> Result<bool, DBusError>

Sends a Pause signal to the player, if the player indicates that it can pause.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Pause.

pub fn checked_stop(&self) -> Result<bool, DBusError>

Sends a Stop signal to the player, if the player indicates that it can stop.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Stop.

pub fn checked_next(&self) -> Result<bool, DBusError>

Sends a Next signal to the player, if the player indicates that it can go to the next media.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Next.

pub fn checked_previous(&self) -> Result<bool, DBusError>

Sends a Previous signal to the player, if the player indicates that it can go to a previous media.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Previous.

pub fn checked_seek( &self, offset_in_microseconds: i64 ) -> Result<bool, DBusError>

Sends a Seek signal to the player, if the player indicates that it can seek.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Seek.

pub fn checked_seek_forwards( &self, offset: &Duration ) -> Result<bool, DBusError>

Seeks the player forwards, if the player indicates that it can seek.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Seek.

pub fn checked_seek_backwards( &self, offset: &Duration ) -> Result<bool, DBusError>

Seeks the player backwards, if the player indicates that it can seek.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Seek.

pub fn can_raise(&self) -> Result<bool, DBusError>

Queries the player to see if it can be raised or not.

See: MPRIS2 specification about CanRaise and the raise method.

pub fn can_quit(&self) -> Result<bool, DBusError>

Queries the player to see if it can be asked to quit.

See: MPRIS2 specification about CanQuit and the quit method.

pub fn can_set_fullscreen(&self) -> Result<bool, DBusError>

Queries the player to see if it can be asked to entrer fullscreen.

This property was added in MPRIS 2.2, and not all players will implement it. This method will try to detect this case and fall back to Ok(false).

It is up to you to decide if you want to ignore errors caused by this method or not.

See: MPRIS2 specification about CanSetFullscreen and the set_fullscreen method.

pub fn can_control(&self) -> Result<bool, DBusError>

Queries the player to see if it can be controlled or not.

See: MPRIS2 specification about CanControl.

pub fn can_go_next(&self) -> Result<bool, DBusError>

Queries the player to see if it can go to next or not.

See: MPRIS2 specification about CanGoNext.

pub fn can_go_previous(&self) -> Result<bool, DBusError>

Queries the player to see if it can go to previous or not.

See: MPRIS2 specification about CanGoPrevious.

pub fn can_pause(&self) -> Result<bool, DBusError>

Queries the player to see if it can pause.

See: MPRIS2 specification about CanPause

pub fn can_play(&self) -> Result<bool, DBusError>

Queries the player to see if it can play.

See: MPRIS2 specification about CanPlay.

pub fn can_seek(&self) -> Result<bool, DBusError>

Queries the player to see if it can seek within the media.

See: MPRIS2 specification about CanSeek.

pub fn can_stop(&self) -> Result<bool, DBusError>

Queries the player to see if it can stop.

MPRIS2 defines the Stop message to only work when the player can be controlled, so that is the property used for this method.

See: MPRIS2 specification about CanControl.

pub fn can_set_playback_rate(&self) -> Result<bool, DBusError>

Queries the player to see if it currently supports/allows changing playback rate.

pub fn can_shuffle(&self) -> Result<bool, DBusError>

Queries the player to see if it supports the “Shuffle” setting

pub fn can_loop(&self) -> Result<bool, DBusError>

Queries the player to see if it supports the “LoopStatus” setting

pub fn has_playback_rate(&self) -> Result<bool, DBusError>

Queries the player to see if it supports the “Rate” setting

pub fn has_position(&self) -> Result<bool, DBusError>

Queries the player to see if it supports the “Position” setting

pub fn has_volume(&self) -> Result<bool, DBusError>

Queries the player to see if it supports the “Volume” setting

pub fn get_fullscreen(&self) -> Result<Option<bool>, DBusError>

Query the player for current fullscreen state.

This property was added in MPRIS 2.2, and not all players will implement it. This method will try to detect this case and fall back to Ok(None).

It is up to you to decide if you want to ignore errors caused by this method or not.

See: MPRIS2 specification about Fullscreen and the can_set_fullscreen method.

pub fn set_fullscreen(&self, new_state: bool) -> Result<bool, DBusError>

Asks the player to change fullscreen state.

If method call succeeded, Ok(true) will be returned.

This property was added in MPRIS 2.2, and not all players will implement it. This method will try to detect this case and fall back to Ok(false).

Other errors will be returned as Err.

See: MPRIS2 specification about Fullscreen and the can_set_fullscreen method.

pub fn get_playback_status(&self) -> Result<PlaybackStatus, DBusError>

Query the player for current playback status.

pub fn get_shuffle(&self) -> Result<bool, DBusError>

Query player for the state of the “Shuffle” setting.

See: MPRIS2 specification about Shuffle.

pub fn checked_get_shuffle(&self) -> Result<Option<bool>, DBusError>

Gets the “Shuffle” setting, if the player indicates that it supports it.

Return Some containing the current value of the shuffle setting. If the setting is not supported, will return None

pub fn set_shuffle(&self, state: bool) -> Result<(), DBusError>

Set the “Shuffle” setting of the player.

See: MPRIS2 specification about Shuffle.

pub fn checked_set_shuffle(&self, state: bool) -> Result<bool, DBusError>

Set the “Shuffle” setting of the player, if the player indicates that it supports the “Shuffle” setting and can be controlled.

Returns a bool to show if the signal was sent or not.

See: MPRIS2 specification about Shuffle.

pub fn get_loop_status(&self) -> Result<LoopStatus, DBusError>

Query the player for the current loop status.

See: MPRIS2 specification about LoopStatus.

pub fn checked_get_loop_status(&self) -> Result<Option<LoopStatus>, DBusError>

Gets the “LoopStatus” setting, if the player indicates that it supports it.

Returns Some containing the current value of the loop setting. If the setting is not supported, returns None

pub fn set_loop_status(&self, status: LoopStatus) -> Result<(), DBusError>

Set the loop status of the player.

See: MPRIS2 specification about LoopStatus.

pub fn checked_set_loop_status( &self, status: LoopStatus ) -> Result<bool, DBusError>

Set the loop status of the player, if the player indicates that supports it and that it can be controlled.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about LoopStatus.

pub fn get_volume(&self) -> Result<f64, DBusError>

Get the volume of the player.

Volume should be between 0.0 and 1.0. Above 1.0 is possible, but not recommended.

See: MPRIS2 specification about Volume.

pub fn checked_get_volume(&self) -> Result<Option<f64>, DBusError>

Gets the “Volume” setting, if the player indicates that it supports it.

Returns Some containing the current value of the position. If the setting is not supported, returns None

pub fn set_volume(&self, value: f64) -> Result<(), DBusError>

Set the volume of the player.

Volume should be between 0.0 and 1.0. Above 1.0 is possible, but not recommended.

See: MPRIS2 specification about Volume.

pub fn checked_set_volume(&self, volume: f64) -> Result<bool, DBusError>

Set the “Volume” setting of the player, if the player indicates that it supports the “Volume” setting and can be controlled.

Returns a boolean to show if the signal was sent or not.

See: MPRIS2 specification about Volume.

pub fn set_volume_checked(&self, value: f64) -> Result<bool, DBusError>

Set the volume of the player, if the player indicates that it can be controlled.

Volume should be between 0.0 and 1.0. Above 1.0 is possible, but not recommended.

See: MPRIS2 specification about Volume.

Trait Implementations

impl Debug for Player

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.