1 /* libmpdclient
2    (c) 2003-2019 The Music Player Daemon Project
3    This project's homepage is: http://www.musicpd.org
4 
5    Redistribution and use in source and binary forms, with or without
6    modification, are permitted provided that the following conditions
7    are met:
8 
9    - Redistributions of source code must retain the above copyright
10    notice, this list of conditions and the following disclaimer.
11 
12    - Redistributions in binary form must reproduce the above copyright
13    notice, this list of conditions and the following disclaimer in the
14    documentation and/or other materials provided with the distribution.
15 
16    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
20    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
21    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
23    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
24    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
25    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28 
29 /*! \file
30  * \brief MPD client library
31  *
32  * Controlling playback.
33  *
34  * Do not include this header directly.  Use mpd/client.h instead.
35  */
36 
37 #ifndef MPD_PLAYER_H
38 #define MPD_PLAYER_H
39 
40 #include "compiler.h"
41 #include "status.h"
42 
43 #include <stdbool.h>
44 
45 struct mpd_connection;
46 struct mpd_song;
47 
48 #ifdef __cplusplus
49 extern "C" {
50 #endif
51 
52 /**
53  * There are two ways to address songs within the queue: by their position and
54  * by their id.
55  * The position is a 0-based index. It is unstable by design: if you move,
56  * delete or insert songs, all following indices will change, and a client can
57  * never be sure what song is behind a given index/position.
58  *
59  * Song ids on the other hand are stable: an id is assigned to a song when it
60  * is added, and will stay the same, no matter how much it is moved around.
61  * Adding the same song twice will assign different ids to them, and a
62  * deleted-and-readded song will have a new id. This way, a client can always
63  * be sure the correct song is being used.
64  *
65  * Many commands come in two flavors, one for each address type. Whenever
66  * possible, ids should be used.
67  */
68 
69 /**
70  * Fetches the currently selected song (the song referenced by
71  * mpd_status_get_song_id()).
72  * Call mpd_recv_song() to receive the response.
73  *
74  * @param connection the connection to MPD
75  * @return true on success, false on error
76  */
77 bool
78 mpd_send_current_song(struct mpd_connection *connection);
79 
80 /**
81  * Shortcut for mpd_send_current_song() and mpd_recv_song().
82  *
83  * @param connection the connection to MPD
84  * @return the current song, or NULL on error or if there is no
85  * current song
86  */
87 mpd_malloc
88 struct mpd_song *
89 mpd_run_current_song(struct mpd_connection *connection);
90 
91 /**
92  * Starts playing the current song from the beginning.
93  *
94  * @param connection the connection to MPD
95  * @return true on success, false on error
96  */
97 bool
98 mpd_send_play(struct mpd_connection *connection);
99 
100 /**
101  * Shortcut for mpd_send_play() and mpd_response_finish().
102  *
103  * @param connection the connection to MPD
104  * @return true on success, false on error
105  */
106 bool
107 mpd_run_play(struct mpd_connection *connection);
108 
109 /**
110  * Starts playing the specified song from the beginning.
111  *
112  * @param connection the connection to MPD
113  * @param song_pos the position of the song in the queue
114  * @return true on success, false on error
115  */
116 bool
117 mpd_send_play_pos(struct mpd_connection *connection, unsigned song_pos);
118 
119 /**
120  * Shortcut for mpd_send_play() and mpd_response_finish().
121  *
122  * @param connection the connection to MPD
123  * @param song_pos the position of the song in the queue
124  * @return true on success, false on error
125  */
126 bool
127 mpd_run_play_pos(struct mpd_connection *connection, unsigned song_pos);
128 
129 /**
130  * Starts playing the specified song from the beginning.
131  *
132  * @param connection the connection to MPD
133  * @param song_id the id of the song
134  * @return true on success, false on error
135  */
136 bool
137 mpd_send_play_id(struct mpd_connection *connection, unsigned song_id);
138 
139 /**
140  * Shortcut for mpd_send_play_id() and mpd_response_finish().
141  *
142  * @param connection the connection to MPD
143  * @param song_id the id of the song
144  * @return true on success, false on error
145  */
146 bool
147 mpd_run_play_id(struct mpd_connection *connection, unsigned song_id);
148 
149 /**
150  * Stops playing the current song.
151  *
152  * @param connection the connection to MPD
153  * @return true on success, false on error
154  */
155 bool
156 mpd_send_stop(struct mpd_connection *connection);
157 
158 /**
159  * Shortcut for mpd_send_stop() and mpd_response_finish().
160  *
161  * @param connection the connection to MPD
162  * @return true on success, false on error
163  */
164 bool
165 mpd_run_stop(struct mpd_connection *connection);
166 
167 /**
168  * This function uses a deprecated feature of MPD, you should avoid it.
169  *
170  * Toggles the pause mode by sending "pause" without arguments.
171  *
172  * @param connection the connection to MPD
173  * @return true on success, false on error
174  */
175 bool
176 mpd_send_toggle_pause(struct mpd_connection *connection);
177 
178 /**
179  * This function uses a deprecated feature of MPD, you should avoid it.
180  * Shortcut for mpd_send_toggle_pause() and mpd_response_finish().
181  *
182  * @param connection the connection to MPD
183  * @return true on success, false on error
184  */
185 bool
186 mpd_run_toggle_pause(struct mpd_connection *connection);
187 
188 /**
189  * Pauses/Resumes playing the current song.
190  * If mode is true, MPD pauses the song; otherwise, MPD resumes the song.
191  *
192  * @param connection the connection to MPD
193  * @param mode if true: pause, if false: resume
194  * @return true on success, false on error
195  */
196 bool
197 mpd_send_pause(struct mpd_connection *connection, bool mode);
198 
199 /**
200  * Shortcut for mpd_send_pause() and mpd_response_finish().
201  *
202  * @param connection the connection to MPD
203  * @param mode if true: pause, if false: resume
204  * @return true on success, false on error
205  */
206 bool
207 mpd_run_pause(struct mpd_connection *connection, bool mode);
208 
209 /**
210  * Play the next song in the playlist.
211  *
212  * @param connection the connection to MPD
213  * @return true on success, false on error
214  */
215 bool
216 mpd_send_next(struct mpd_connection *connection);
217 
218 /**
219  * Shortcut for mpd_send_next() and mpd_response_finish().
220  *
221  * @param connection the connection to MPD
222  * @return true on success, false on error
223  */
224 bool
225 mpd_run_next(struct mpd_connection *connection);
226 
227 /**
228  * Play the previous song in the playlist.
229  *
230  * @param connection the connection to MPD
231  * @return true on success, false on error
232  */
233 bool
234 mpd_send_previous(struct mpd_connection *connection);
235 
236 /**
237  * Shortcut for mpd_send_previous() and mpd_response_finish().
238  *
239  * @param connection the connection to MPD
240  * @return true on success, false on error
241  */
242 bool
243 mpd_run_previous(struct mpd_connection *connection);
244 
245 /**
246  * Seeks to the position t (in seconds) of position song_pos in the playlist.
247  *
248  * @param connection the connection to MPD
249  * @param song_pos the position of the song in the queue
250  * @param t the position within the song, in seconds
251  * @return true on success, false on error
252  */
253 bool
254 mpd_send_seek_pos(struct mpd_connection *connection,
255 		  unsigned song_pos, unsigned t);
256 
257 /**
258  * Shortcut for mpd_send_seek_pos() and mpd_response_finish().
259  *
260  * @param connection the connection to MPD
261  * @param song_pos the position of the song in the queue
262  * @param t the position within the song, in seconds
263  * @return true on success, false on error
264  */
265 bool
266 mpd_run_seek_pos(struct mpd_connection *connection,
267 		 unsigned song_pos, unsigned t);
268 
269 /**
270  * Seeks to the position t (in seconds) of song id song_id.
271  *
272  * @param connection the connection to MPD
273  * @param song_id the id of the song
274  * @param t the position within the song, in seconds
275  * @return true on success, false on error
276  */
277 bool
278 mpd_send_seek_id(struct mpd_connection *connection,
279 		 unsigned song_id, unsigned t);
280 
281 /**
282  * Shortcut for mpd_send_seek_id() and mpd_response_finish().
283  *
284  * @param connection the connection to MPD
285  * @param song_id the id of the song
286  * @param t the position within the song, in seconds
287  * @return true on success, false on error
288  */
289 bool
290 mpd_run_seek_id(struct mpd_connection *connection,
291 		unsigned song_id, unsigned t);
292 
293 /**
294  * Seeks to the position t (in seconds; fractions allowed) of song id song_id.
295  *
296  * @param connection the connection to MPD
297  * @param song_id the id of the song
298  * @param t the position within the song, in seconds (fractions allowed)
299  * @return true on success, false on error
300  */
301 bool
302 mpd_send_seek_id_float(struct mpd_connection *connection,
303 		       unsigned song_id, float t);
304 
305 /**
306  * Shortcut for mpd_send_seek_id_float() and mpd_response_finish().
307  *
308  * @param connection the connection to MPD
309  * @param song_id the id of the song
310  * @param t the position within the song, in seconds (fractions allowed)
311  * @return true on success, false on error
312  */
313 bool
314 mpd_run_seek_id_float(struct mpd_connection *connection,
315 		      unsigned song_id, float t);
316 
317 /**
318  * Seeks the current song.
319  *
320  * @param connection the connection to MPD
321  * @param t the position within the song, in seconds
322  * @param relative true makes #t a relative to the current position
323  * @return true on success, false on error
324  *
325  * @since MPD 0.17, libmpdclient 2.15
326  */
327 bool
328 mpd_send_seek_current(struct mpd_connection *connection,
329 		      float t, bool relative);
330 
331 /**
332  * Shortcut for mpd_send_seek_current() and mpd_response_finish().
333  *
334  * @param connection the connection to MPD
335  * @param t the new position (in seconds)
336  * @param relative true to seek relative to the current position and
337  * false to seek to an absolute time stamp within the song
338  * @return true on success, false on error
339  *
340  * @since MPD 0.17, libmpdclient 2.15
341  */
342 bool
343 mpd_run_seek_current(struct mpd_connection *connection,
344 		     float t, bool relative);
345 
346 /**
347  * Sets repeat on/off for the current song.
348  * If mode is true, MPD repeats the song; otherwise, MPD does not repeat the
349  * song.
350  *
351  * @param connection the connection to MPD
352  * @param mode if true: repeat, if false: do not repeat
353  * @return true on success, false on error
354  */
355 bool
356 mpd_send_repeat(struct mpd_connection *connection, bool mode);
357 
358 /**
359  * Shortcut for mpd_send_repeat() and mpd_response_finish().
360  *
361  * @param connection the connection to MPD
362  * @param mode if true: pause, if false: resume
363  * @return true on success, false on error
364  */
365 bool
366 mpd_run_repeat(struct mpd_connection *connection, bool mode);
367 
368 /**
369  * Sets random mode on/off for the queue.
370  * If mode is true, MPD enables random mode; otherwise, MPD disables random
371  * mode.
372  *
373  * @param connection the connection to MPD
374  * @param mode if true: enable random mode, if false: disable random mode
375  * @return true on success, false on error
376  */
377 bool
378 mpd_send_random(struct mpd_connection *connection, bool mode);
379 
380 /**
381  * Shortcut for mpd_send_random() and mpd_response_finish().
382  *
383  * @param connection the connection to MPD
384  * @param mode if true: enable random mode, if false: disable random mode
385  * @return true on success, false on error
386  */
387 bool
388 mpd_run_random(struct mpd_connection *connection, bool mode);
389 
390 /**
391  * Sets single state for the playlist.
392  * If state is #MPD_SINGLE_ON, MPD enables single mode: playback is stopped
393  * after current song, or song is repeated if the repeat mode is enabled.
394  *
395  * If state is #MPD_SINGLE_OFF, MPD disables single mode: if random mode is
396  * enabled, the playlist order is shuffled after it is played completely.
397  *
398  * If state is #MPD_SINGLE_ONESHOT, MPD enables single mode temporarily: single
399  * mode is disabled (#MPD_SINGLE_OFF) after a song has been played and there is
400  * another song in the current playlist.
401  *
402  * @param connection the connection to MPD
403  * @param state the desired single mode state
404  * @return true on success, false on error or state is #MPD_SINGLE_UNKNOWN
405  *
406  * @since MPD 0.21, libmpdclient 2.18.
407  */
408 bool
409 mpd_send_single_state(struct mpd_connection *connection,
410 		      enum mpd_single_state state);
411 
412 /**
413  * Shortcut for mpd_send_single_state() and mpd_response_finish().
414  *
415  * @param connection the connection to MPD
416  * @param state the desired single mode state
417  * @return true on success, false on error or state is #MPD_SINGLE_UNKNOWN
418  *
419  * @since MPD 0.21, libmpdclient 2.18.
420  */
421 bool
422 mpd_run_single_state(struct mpd_connection *connection,
423 		      enum mpd_single_state state);
424 
425 /**
426  * Sets single mode on/off for the playlist.
427  * This function does not support the 'oneshot' state for single mode: use
428  * mpd_send_single_state() instead.
429  *
430  * If mode is true, MPD enables single mode: playback is stopped after current
431  * song, or song is repeated if the repeat mode is enabled.
432  *
433  * If mode is false, MPD disables single mode: if random mode is enabled, the
434  * playlist order is shuffled after it is played completely.
435  *
436  * @param connection the connection to MPD
437  * @param mode if true: enable single mode, if false: disable single mode
438  * @return true on success, false on error
439  *
440  * @since MPD 0.15
441  */
442 bool
443 mpd_send_single(struct mpd_connection *connection, bool mode);
444 
445 /**
446  * Shortcut for mpd_send_single() and mpd_response_finish().
447  *
448  * @param connection the connection to MPD
449  * @param mode if true: enable single mode, if false: disable single mode
450  * @return true on success, false on error
451  *
452  * @since MPD 0.15
453  */
454 bool
455 mpd_run_single(struct mpd_connection *connection, bool mode);
456 
457 /**
458  * Sets consume mode on/off for the playlist.
459  * If mode is true, MPD enables consume mode: each song played is removed from
460  * the playlist.
461  *
462  * If mode is false, MPD disables consume mode.
463  *
464  * @param connection the connection to MPD
465  * @param mode if true: enable consume mode, if false: disable consume mode
466  * @return true on success, false on error
467  *
468  * @since MPD 0.15
469  */
470 bool
471 mpd_send_consume(struct mpd_connection *connection, bool mode);
472 
473 /**
474  * Shortcut for mpd_send_consume() and mpd_response_finish().
475  *
476  * @param connection the connection to MPD
477  * @param mode if true: enable consume mode, if false: disable consume mode
478  * @return true on success, false on error
479  *
480  * @since MPD 0.15
481  */
482 bool
483 mpd_run_consume(struct mpd_connection *connection, bool mode);
484 
485 /**
486  * Sets crossfading of seconds between songs on for the playlist.
487  * Crossfading only happens when the songs audio format are the same.
488  *
489  * @param connection the connection to MPD
490  * @param seconds seconds of crossfading between songs
491  * @return true on success, false on error
492  */
493 bool
494 mpd_send_crossfade(struct mpd_connection *connection, unsigned seconds);
495 
496 /**
497  * Shortcut for mpd_send_crossfade() and mpd_response_finish().
498  *
499  * @param connection the connection to MPD
500  * @param seconds seconds of crossfading between songs
501  * @return true on success, false on error
502  */
503 bool
504 mpd_run_crossfade(struct mpd_connection *connection, unsigned seconds);
505 
506 /**
507  * Sets the threshold at which songs will be overlapped. Like crossfading but
508  * doesn't fade the track volume, just overlaps.
509  *
510  * The songs need to have MixRamp tags added by an external tool. 0dB is the
511  * normalized maximum volume; so use negative values (I prefer -17dB). In the
512  * absence of MixRamp tags, crossfading will be used.
513  *
514  * @param connection the connection to MPD
515  * @param db decibels of volume for overlapping songs
516  * @return true on success, false on error
517  *
518  * @since libmpdclient 2.2
519  */
520 bool
521 mpd_send_mixrampdb(struct mpd_connection *connection, float db);
522 
523 /**
524  * Shortcut for mpd_send_mixrampdb() and mpd_response_finish().
525  *
526  * @param connection the connection to MPD
527  * @param db decibels of volume for overlapping songs
528  * @return true on success, false on error
529  *
530  * @since libmpdclient 2.2
531  */
532 bool
533 mpd_run_mixrampdb(struct mpd_connection *connection, float db);
534 
535 /**
536  * Sets additional time subtracted from the overlap calculated by mixrampdb.
537  * A value of NaN disables MixRamp overlapping and falls back to crossfading.
538  *
539  * @param connection the connection to MPD
540  * @param seconds seconds subtracted from the overlap calculated by mixrampdb
541  * @return true on success, false on error
542  *
543  * @since libmpdclient 2.2
544  */
545 bool
546 mpd_send_mixrampdelay(struct mpd_connection *connection, float seconds);
547 
548 /**
549  * Shortcut for mpd_send_mixrampdelay() and mpd_response_finish().
550  *
551  * @param connection the connection to MPD
552  * @param seconds seconds subtracted from the overlap calculated by mixrampdb
553  * @return true on success, false on error
554  *
555  * @since libmpdclient 2.2
556  */
557 bool
558 mpd_run_mixrampdelay(struct mpd_connection *connection, float seconds);
559 
560 /**
561  * Clears the current error message in MPD's status (this is also accomplished
562  * by any command that starts playback).
563  *
564  * @param connection the connection to MPD
565  * @return true on success, false on error
566  *
567  * @since libmpdclient 2.4
568  */
569 bool
570 mpd_send_clearerror(struct mpd_connection *connection);
571 
572 /**
573  * Shortcut for mpd_send_clearerror() and mpd_response_finish().
574  *
575  * @param connection the connection to MPD
576  * @return true on success, false on error
577  *
578  * @since libmpdclient 2.4
579  */
580 bool
581 mpd_run_clearerror(struct mpd_connection *connection);
582 
583 #ifdef __cplusplus
584 }
585 #endif
586 
587 #endif
588