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