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}