mpris_server/
signal.rs

1use crate::{Metadata, Playlist, Time, TrackId};
2
3/// Used for emitting signals on [`Server::emit`] and [`LocalServer::emit`].
4///
5/// [`Server::emit`]: crate::Server::emit
6/// [`LocalServer::emit`]: crate::LocalServer::emit
7#[derive(Debug)]
8pub enum Signal {
9    /// Indicates that the track position has changed in a way that is
10    /// inconsistent with the current playing state.
11    ///
12    /// When this signal is not received, clients should assume that:
13    ///
14    /// * When playing, the position progresses according to the rate property.
15    /// * When paused, it remains constant.
16    ///
17    /// This signal does not need to be emitted when playback starts or when the
18    /// track changes, unless the track is starting at an unexpected position.
19    /// An expected position would be the last known one when going from Paused
20    /// to Playing, and 0 when going from Stopped to Playing.
21    Seeked {
22        /// The new position.
23        position: Time,
24    },
25}
26
27/// Used for emitting signals on [`Server::track_list_emit`] and
28/// [`LocalServer::track_list_emit`], if `T` implements [`TrackListInterface`]
29/// or [`LocalTrackListInterface`].
30///
31/// [`Server::track_list_emit`]: crate::Server::track_list_emit
32/// [`LocalServer::track_list_emit`]: crate::LocalServer::track_list_emit
33/// [`TrackListInterface`]: crate::TrackListInterface
34/// [`LocalTrackListInterface`]: crate::LocalTrackListInterface
35#[derive(Debug)]
36pub enum TrackListSignal {
37    /// Indicates that the entire tracklist has been replaced.
38    ///
39    /// It is left up to the implementation to decide when a change to the track
40    /// list is invasive enough that this signal should be emitted instead of a
41    /// series of [`TrackAdded`] and [`TrackRemoved`] signals.
42    ///
43    /// [`TrackAdded`]: TrackListSignal::TrackAdded
44    /// [`TrackRemoved`]: TrackListSignal::TrackRemoved
45    TrackListReplaced {
46        /// The new content of the tracklist.
47        tracks: Vec<TrackId>,
48        /// The identifier of the track to be considered as current.
49        ///
50        /// [`/org/mpris/MediaPlayer2/TrackList/NoTrack`] indicates that there
51        /// is no current track.
52        ///
53        /// This should correspond to the [`mpris:trackid`] field of the
54        /// [`Metadata`] property of the [`Player interface`].
55        ///
56        /// [`/org/mpris/MediaPlayer2/TrackList/NoTrack`]: crate::TrackId::NO_TRACK
57        /// [`mpris:trackid`]: crate::Metadata::trackid
58        /// [`Metadata`]: crate::PlayerInterface::metadata
59        /// [`Player interface`]: crate::PlayerInterface
60        current_track: TrackId,
61    },
62    /// Indicates that a track has been added to the track list.
63    TrackAdded {
64        /// The metadata of the newly added item.
65        ///
66        /// This must include a [`mpris:trackid`] entry.
67        ///
68        /// [`mpris:trackid`]: crate::Metadata::trackid
69        metadata: Metadata,
70        /// The identifier of the track after which the new track was inserted.
71        /// The path [`/org/mpris/MediaPlayer2/TrackList/NoTrack`] indicates
72        /// that the track was inserted at the start of the track list.
73        ///
74        /// [`/org/mpris/MediaPlayer2/TrackList/NoTrack`]: crate::TrackId::NO_TRACK
75        after_track: TrackId,
76    },
77    /// Indicates that a track has been removed from the track list.
78    TrackRemoved {
79        /// The identifier of the track being removed.
80        ///
81        /// [`/org/mpris/MediaPlayer2/TrackList/NoTrack`] is *not* a valid value
82        /// for this argument.
83        ///
84        /// [`/org/mpris/MediaPlayer2/TrackList/NoTrack`]: crate::TrackId::NO_TRACK
85        track_id: TrackId,
86    },
87    /// Indicates that the metadata of a track in the tracklist has changed.
88    ///
89    /// This may indicate that a track has been replaced, in which case the
90    /// [`mpris:trackid`] metadata entry is different from the `track_id`
91    /// argument.
92    ///
93    /// [`mpris:trackid`]: crate::Metadata::trackid
94    TrackMetadataChanged {
95        /// The id of the track which metadata has changed.
96        ///
97        /// If the track id has changed, this will be the old value.
98        ///
99        /// [`/org/mpris/MediaPlayer2/TrackList/NoTrack`] is *not* a valid value
100        /// for this argument.
101        ///
102        /// [`/org/mpris/MediaPlayer2/TrackList/NoTrack`]: crate::TrackId::NO_TRACK
103        track_id: TrackId,
104        /// The new track metadata.
105        ///
106        /// This must include a [`mpris:trackid`] entry. If the track id has
107        /// changed, this will be the new value.
108        ///
109        /// [`mpris:trackid`]: crate::Metadata::trackid
110        metadata: Metadata,
111    },
112}
113
114/// Used for emitting signals on [`Server::playlists_emit`] and
115/// [`LocalServer::playlists_emit`], if `T` implements
116/// [`PlaylistsInterface`] or [`LocalPlaylistsInterface`].
117///
118/// [`Server::playlists_emit`]: crate::Server::playlists_emit
119/// [`LocalServer::playlists_emit`]: crate::LocalServer::playlists_emit
120/// [`PlaylistsInterface`]: crate::PlaylistsInterface
121/// [`LocalPlaylistsInterface`]: crate::LocalPlaylistsInterface
122#[derive(Debug)]
123pub enum PlaylistsSignal {
124    /// Indicates that either the Name or Icon attribute of a playlist has
125    /// changed.
126    ///
127    /// Client implementations should be aware that this signal may not be
128    /// implemented.
129    ///
130    /// <details><summary>Rationale</summary>
131    ///
132    /// Without this signal, media players have no way to notify clients of a
133    /// change in the attributes of a playlist other than the active one.
134    ///
135    /// </details>
136    PlaylistChanged {
137        /// The playlist which details have changed.
138        playlist: Playlist,
139    },
140}