media_remote/high_level/controller.rs
1use crate::{send_command, Command};
2
3macro_rules! send_command {
4 ($self:expr,$command:expr) => {{
5 if $self.is_info_some() {
6 send_command($command)
7 } else {
8 false
9 }
10 }};
11}
12
13pub trait Controller {
14 fn is_info_some(&self) -> bool;
15
16 /// Toggles between play and pause states.
17 ///
18 /// # Returns
19 /// - `true` if the command was successfully sent.
20 /// - `false` if the command failed.
21 ///
22 /// # Example
23 /// ```rust
24 /// use media_remote::prelude::*;
25 ///
26 /// let now_playing = NowPlaying::new();
27 /// now_playing.toggle();
28 /// ```
29 fn toggle(&self) -> bool {
30 send_command!(self, Command::TogglePlayPause)
31 }
32
33 /// Play the currently playing media.
34 ///
35 /// # Returns
36 /// - `true` if the command was successfully sent.
37 /// - `false` if the operation failed.
38 ///
39 /// # Example
40 /// ```rust
41 /// use media_remote::prelude::*;
42 ///
43 /// let now_playing = NowPlaying::new();
44 /// now_playing.play();
45 /// ```
46 fn play(&self) -> bool {
47 send_command!(self, Command::Play)
48 }
49
50 /// Pauses the currently playing media.
51 ///
52 /// # Returns
53 /// - `true` if the command was successfully sent.
54 /// - `false` if the command failed.
55 ///
56 /// # Example
57 /// ```rust
58 /// use media_remote::prelude::*;
59 ///
60 /// let now_playing = NowPlaying::new();
61 /// now_playing.pause();
62 /// ```
63 fn pause(&self) -> bool {
64 send_command!(self, Command::Pause)
65 }
66
67 /// Skips to the next track in the playback queue.
68 ///
69 /// # Returns
70 /// - `true` if the command was successfully sent.
71 /// - `false` if the command failed.
72 ///
73 /// # Example
74 /// ```rust
75 /// use media_remote::prelude::*;
76 ///
77 /// let now_playing = NowPlaying::new();
78 /// now_playing.next();
79 /// ```
80 fn next(&self) -> bool {
81 send_command!(self, Command::NextTrack)
82 }
83
84 /// Returns to the previous track in the playback queue.
85 ///
86 /// # Returns
87 /// - `true` if the command was successfully sent.
88 /// - `false` if the command failed.
89 ///
90 /// # Example
91 /// ```rust
92 /// use media_remote::prelude::*;
93 ///
94 /// let now_playing = NowPlaying::new();
95 /// now_playing.previous();
96 /// ```
97 fn previous(&self) -> bool {
98 send_command!(self, Command::PreviousTrack)
99 }
100
101 /// Toggles the shuffle state of the playback queue.
102 ///
103 /// # Returns
104 /// - `true` if the command was successfully sent.
105 /// - `false` if the command failed.
106 ///
107 /// # Example
108 /// ```rust
109 /// use media_remote::prelude::*;
110 ///
111 /// let now_playing = NowPlaying::new();
112 /// now_playing.toggle_shuffle();
113 /// ```
114 fn toggle_shuffle(&self) -> bool {
115 send_command!(self, Command::ToggleShuffle)
116 }
117
118 /// Toggles the repeat state of the playback queue.
119 ///
120 /// # Returns
121 /// - `true` if the command was successfully sent.
122 /// - `false` if the command failed.
123 ///
124 /// # Example
125 /// ```rust
126 /// use media_remote::prelude::*;
127 ///
128 /// let now_playing = NowPlaying::new();
129 /// now_playing.toggle_repeat();
130 /// ```
131 fn toggle_repeat(&self) -> bool {
132 send_command!(self, Command::ToggleRepeat)
133 }
134
135 /// Starts a forward seek operation.
136 ///
137 /// # Returns
138 /// - `true` if the command was successfully sent.
139 /// - `false` if the command failed.
140 ///
141 /// # Example
142 /// ```rust
143 /// use media_remote::prelude::*;
144 ///
145 /// let now_playing = NowPlaying::new();
146 /// now_playing.start_forward_seek();
147 /// ```
148 fn start_forward_seek(&self) -> bool {
149 send_command!(self, Command::StartForwardSeek)
150 }
151
152 /// Ends a forward seek operation.
153 ///
154 /// # Returns
155 /// - `true` if the command was successfully sent.
156 /// - `false` if the command failed.
157 ///
158 /// # Example
159 /// ```rust
160 /// use media_remote::prelude::*;
161 ///
162 /// let now_playing = NowPlaying::new();
163 /// now_playing.end_forward_seek();
164 /// ```
165 fn end_forward_seek(&self) -> bool {
166 send_command!(self, Command::EndForwardSeek)
167 }
168
169 /// Starts a backward seek operation.
170 ///
171 /// # Returns
172 /// - `true` if the command was successfully sent.
173 /// - `false` if the command failed.
174 ///
175 /// # Example
176 /// ```rust
177 /// use media_remote::prelude::*;
178 ///
179 /// let now_playing = NowPlaying::new();
180 /// now_playing.start_backward_seek();
181 /// ```
182 fn start_backward_seek(&self) -> bool {
183 send_command!(self, Command::StartBackwardSeek)
184 }
185
186 /// Ends a backward seek operation.
187 ///
188 /// # Returns
189 /// - `true` if the command was successfully sent.
190 /// - `false` if the command failed.
191 ///
192 /// # Example
193 /// ```rust
194 /// use media_remote::prelude::*;
195 ///
196 /// let now_playing = NowPlaying::new();
197 /// now_playing.end_backward_seek();
198 /// ```
199 fn end_backward_seek(&self) -> bool {
200 send_command!(self, Command::EndBackwardSeek)
201 }
202
203 /// Seeks backward by fifteen seconds.
204 ///
205 /// # Returns
206 /// - `true` if the command was successfully sent.
207 /// - `false` if the command failed.
208 ///
209 /// # Example
210 /// ```rust
211 /// use media_remote::prelude::*;
212 ///
213 /// let now_playing = NowPlaying::new();
214 /// now_playing.go_back_fifteen_seconds();
215 /// ```
216 fn go_back_fifteen_seconds(&self) -> bool {
217 send_command!(self, Command::GoBackFifteenSeconds)
218 }
219
220 /// Skips forward by fifteen seconds.
221 ///
222 /// # Returns
223 /// - `true` if the command was successfully sent.
224 /// - `false` if the command failed.
225 ///
226 /// # Example
227 /// ```rust
228 /// use media_remote::prelude::*;
229 ///
230 /// let now_playing = NowPlaying::new();
231 /// now_playing.skip_fifteen_seconds();
232 /// ```
233 fn skip_fifteen_seconds(&self) -> bool {
234 send_command!(self, Command::SkipFifteenSeconds)
235 }
236
237 /// Sets the playback speed of the currently active media client.
238 ///
239 /// # Arguments
240 /// - `speed`: The playback speed multiplier.
241 ///
242 /// # Note
243 /// - Playback speed changes typically do not work most of the time.
244 /// Depending on the media client or content, setting the playback speed may not have the desired effect.
245 ///
246 /// # Example
247 /// ```rust
248 /// use media_remote::prelude::*;
249 ///
250 /// let now_playing = NowPlaying::new();
251 /// now_playing.set_playback_speed(2);
252 /// ```
253 fn set_playback_speed(&self, speed: i32) {
254 if self.is_info_some() {
255 crate::set_playback_speed(speed);
256 }
257 }
258
259 /// Sets the elapsed time of the currently playing media.
260 ///
261 /// # Arguments
262 /// - `elapsed_time`: The elapsed time in seconds to set the current position of the media.
263 ///
264 /// # Note
265 /// - **Limitations**: Setting the elapsed time can often cause the media to pause. Be cautious
266 /// when using this function, as the playback might be interrupted and require manual resumption.
267 ///
268 /// # Example
269 /// ```rust
270 /// use media_remote::prelude::*;
271 ///
272 /// let now_playing = NowPlaying::new();
273 /// now_playing.set_elapsed_time(1.0);
274 /// ```
275 fn set_elapsed_time(&self, elapsed_time: f64) {
276 if self.is_info_some() {
277 crate::set_elapsed_time(elapsed_time);
278 }
279 }
280}