Struct mpris::ProgressTracker

source ·

pub struct ProgressTracker<'a> { /* private fields */ }

Expand description

Controller for calculating Progress and maintaining a TrackList (if supported) for a given Player.

Call the tick method to get the most current Progress data.

Implementations§

source §

impl<'a> ProgressTracker<'a>

source

pub fn new(player: &'a Player, interval_ms: u32) -> Result<Self, DBusError>

Construct a new ProgressTracker for the provided Player.

The interval_ms value is the desired time between ticks when calling the tick method. See tick for more information about that.

You probably want to use Player::track_progress instead of this method.

Errors

Returns an error in case Player metadata or state retrieval over DBus fails.

source

pub fn tick(&mut self) -> ProgressTick<'_>

Returns a ProgressTick at each interval, or as close to each interval as possible.

The returned struct contains borrows of the current data along with booleans telling you if the underlying data changed or not. See ProgressTick for more information about that.

If there is time left until the next interval window, then the tracker will process DBus events to determine if something changed (and potentially perform a full refresh of the data). If there is no time left, then the previous data will be reused.

If refreshing failed for some reason the old data will be reused.

It is recommended to call this inside a loop to maintain your progress display.

On reusing data

Progress can be reused until something about the player changes, like track or playback status. As long as nothing changes, Progress can accurately determine playback position from timing data.

In addition, TrackList will maintain a cache of track metadata so as long as the list remains static if should be cheap to read from it.

You can use the bools in the ProgressTick to perform optimizations as they tell you if any data has changed. If all of them are false you don’t have to treat any of the data as dirty.

The calculated Progress::position might still change depending on the player state, so if you want to show the track position you might still want to refresh that part.

Examples

Simple progress bar of track position:

use mpris::ProgressTick;
// Re-render progress bar every 100ms
let mut progress_tracker = player.track_progress(100).unwrap();
loop {
    let ProgressTick {progress, ..} = progress_tracker.tick();
    update_progress_bar(progress.position());
}

Using the progress_changed bool:

use mpris::ProgressTick;
// Refresh every 100ms
let mut progress_tracker = player.track_progress(100).unwrap();
loop {
    let ProgressTick {progress, progress_changed, ..} = progress_tracker.tick();
    if progress_changed {
        update_track_title(progress.metadata().title());
        reset_progress_bar(progress.position(), progress.length());
    } else {
        update_progress_bar(progress.position());
    }
}

Showing only the track list until the player quits:

use mpris::ProgressTick;
// Refresh every 10 seconds
let mut progress_tracker = player.track_progress(10_000).unwrap();
loop {
    let ProgressTick {track_list, track_list_changed, player_quit, ..} = progress_tracker.tick();
    if player_quit {
        break;
    } else if track_list_changed {
        if let Some(list) = track_list {
            render_track_list(list);
        } else {
            render_track_list_unavailable();
        }
    }
}