Crate mpris_server

Source
Expand description

§MPRIS Server

github crates.io docs CI

Implement MPRIS D-Bus interface in your application.

This library provides the essential functionalities for implementing the MPRIS D-Bus interface on the service side. This enables your application to become discoverable and controllable by other MPRIS-compatible media controllers, including but not limited to GNOME Shell, KDE Plasma, and other libraries such as mpris.

This library supports all the following interfaces as defined in the specification:

To implement these interfaces, this crate offers two flavors: you can either create your own struct and implement RootInterface and PlayerInterface (or with optional TrackListInterface and PlaylistsInterface), or you can use the ready-to-use Player struct.

§Optional Features

FeatureDescriptionDefault
unstableEnables internal APIs and unstable features.No

§Examples

For more detailed examples, see also the examples directory.

There is also a real-world example of this library being used in Mousai, a music recognizer application for Linux.

§Manual Implementation (via Server or LocalServer)

If you want to have more control, it is recommended to manually create your own implementation of the interfaces. You can do this by creating your own struct and implementing the required interfaces, then passing your struct as implementation in Server. You can also use LocalServer and the local version of the interfaces if your struct can’t be sent and shared across threads.

use std::future;

use mpris_server::{
    zbus::{fdo, Result},
    Metadata, PlayerInterface, Property, RootInterface, Server, Signal, Time, Volume,
};

pub struct MyPlayer;

impl RootInterface for MyPlayer {
    async fn identity(&self) -> fdo::Result<String> {
        Ok("MyPlayer".into())
    }

    // Other methods...
}

impl PlayerInterface for MyPlayer {
    async fn set_volume(&self, volume: Volume) -> Result<()> {
        self.volume.set(volume);
        Ok(())
    }

    async fn metadata(&self) -> fdo::Result<Metadata> {
        let metadata = Metadata::builder()
            .title("My Song")
            .artist(["My Artist"])
            .album("My Album")
            .length(Time::from_micros(123))
            .build();
        Ok(metadata)
    }

    // Other methods...
}

#[async_std::main]
async fn main() -> Result<()> {
    let server = Server::new("com.my.Application", MyPlayer).await?;

    // Emit `PropertiesChanged` signal for `CanSeek` and `Metadata` properties
    server
        .properties_changed([
            Property::CanSeek(false),
            Property::Metadata(Metadata::new()),
        ])
        .await?;

    // Emit `Seeked` signal
    server
        .emit(Signal::Seeked {
            position: Time::from_micros(124),
        })
        .await?;

    // Prevent the program from exiting.
    future::pending::<()>().await;

    Ok(())
}

§Ready-to-use Implementation (via Player)

If you want to create a simple player without having to implement the interfaces, you can use the ready-to-use Player struct that implements those interfaces internally. This struct has its own internal state, automatically emits properties changed signals, and allows you to connect to method and property setter calls.

However, Player currently only supports the more commonly used org.mpris.MediaPlayer2 and org.mpris.MediaPlayer2.Player interfaces.

use std::future;

use mpris_server::{zbus::Result, Player, Time};

#[async_std::main]
async fn main() -> Result<()> {
    let player = Player::builder("com.my.Application")
        .can_play(true)
        .can_pause(true)
        .build()
        .await?;

    // Handle `PlayPause` method call
    player.connect_play_pause(|_player| {
        println!("PlayPause");
    });

    // Run event handler task
    async_std::task::spawn_local(player.run());

    // Update `CanPlay` property and emit `PropertiesChanged` signal for it
    player.set_can_play(false).await?;

    // Emit `Seeked` signal
    player.seeked(Time::from_millis(1000)).await?;

    // Prevent the program from exiting.
    future::pending::<()>().await;

    Ok(())
}

§License

Copyright 2024 Dave Patrick Caberto

This software is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at this site.

Re-exports§

pub use zbus;

Modules§

builder
This contains the definitions of builder-pattern structs.

Structs§

LocalServer
Local version of Server that doesn’t require T to be Send and Sync.
LocalServerRunTask
A task that runs LocalServer’s event handler until the server and this task is dropped.
Metadata
A mapping from metadata attribute names to values.
Player
Ready-to-use mutable service-side object that internally implements LocalRootInterface and LocalPlayerInterface.
Playlist
A data structure describing a playlist.
Server
Thin wrapper around [zbus::Connection] that calls to T’s implementation of RootInterface, PlayerInterface, TrackListInterface, and PlaylistsInterface to implement org.mpris.MediaPlayer2 and its sub-interfaces.
Time
A time with microsecond precision which can be negative.
TrackId
Unique track identifier.

Enums§

LoopStatus
A repeat / loop status.
PlaybackStatus
A playback state.
PlaylistOrdering
Specifies the ordering of returned playlists.
PlaylistsProperty
Used for emitting PropertiesChanged signals on Server::playlists_properties_changed and LocalServer::playlists_properties_changed, if T implements PlaylistsInterface or LocalPlaylistsInterface.
PlaylistsSignal
Used for emitting signals on Server::playlists_emit and LocalServer::playlists_emit, if T implements PlaylistsInterface or LocalPlaylistsInterface.
Property
Used for emitting PropertiesChanged signals on Server::properties_changed and LocalServer::properties_changed.
Signal
Used for emitting signals on Server::emit and LocalServer::emit.
TrackListProperty
Used for emitting PropertiesChanged signals on Server::track_list_properties_changed and LocalServer::track_list_properties_changed, if T implements TrackListInterface or LocalTrackListInterface.
TrackListSignal
Used for emitting signals on Server::track_list_emit and LocalServer::track_list_emit, if T implements TrackListInterface or LocalTrackListInterface.

Traits§

LocalPlayerInterface
Local version of PlayerInterface to be used with LocalServer.
LocalPlaylistsInterface
Local version of PlaylistsInterface to be used with LocalServer.
LocalRootInterface
Local version of RootInterface to be used with LocalServer.
LocalTrackListInterface
Local version of TrackListInterface to be used with LocalServer.
PlayerInterface
Used to implement org.mpris.MediaPlayer2.Player interface, which implements the methods for querying and providing basic control over what is currently playing.
PlaylistsInterface
Used to implement org.mpris.MediaPlayer2.Playlists interface, which provides access to the media player’s playlists.
RootInterface
Used to implement org.mpris.MediaPlayer2 interface.
TrackListInterface
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.

Type Aliases§

DateTime
Combined date and time.
PlaybackRate
A playback rate.
PlaylistId
Unique playlist identifier.
Uri
A unique resource identifier.
Volume
Audio volume level.