================================ Song Queue programming interface ================================ A description of the available programming interfaces used to interact with the Song Queue component. .. _SongQueue-Summary: Summary ~~~~~~~ ========================================== ========================================= ================ Chapter URL JSON HTTP Method ========================================== ========================================= ================ :ref:`SongQueue/Content/List` /SongQueue/Content/List.json GET :ref:`SongQueue/Content/Add` /SongQueue/Content/Add.json POST :ref:`SongQueue/Content/Remove` /SongQueue/Content/Remove.json POST :ref:`SongQueue/Content/Clear` /SongQueue/Content/Clear.json DELETE :ref:`SongQueue/Content/MaxSongsNumber` /SongQueue/Content/MaxSongsNumber.json GET :ref:`SongQueue/Control/Position` /SongQueue/Control/Position.json POST/PUT and GET :ref:`SongQueue/Control/Play` /SongQueue/Control/Play.json POST/PUT :ref:`SongQueue/Control/Pause` /SongQueue/Control/Pause.json POST/PUT :ref:`SongQueue/Control/PlayPause` /SongQueue/Control/PlayPause.json POST/PUT :ref:`SongQueue/Control/Stop` /SongQueue/Control/Stop.json POST/PUT :ref:`SongQueue/Control/Next` /SongQueue/Control/Next.json POST/PUT :ref:`SongQueue/Control/Previous` /SongQueue/Control/Previous.json POST/PUT :ref:`SongQueue/Control/RepeatMode` /SongQueue/Control/RepeatMode.json POST/PUT and GET :ref:`SongQueue/Control/ToggleRepeatMode` /SongQueue/Control/ToggleRepeatMode.json POST/PUT :ref:`SongQueue/Control/ShuffleMode` /SongQueue/Control/ShuffleMode.json POST/PUT and GET :ref:`SongQueue/Control/ToggleShuffleMode` /SongQueue/Control/ToggleShuffleMode.json POST/PUT :ref:`SongQueue/Control/ActiveState` /SongQueue/Control/ActiveState.json GET :ref:`Service/Notification/SongQueue` /Service/Notification/SongQueue.json COMET ========================================== ========================================= ================ ---------- .. _SongQueue/Content/List: 1. Get the songs list ~~~~~~~~~~~~~~~~~~~~~ =============== ============================ Key Value JSON =============== ============================ Resource URL /SongQueue/Content/List.json HTTP Method GET Response format ``application/json`` =============== ============================ Description ^^^^^^^^^^^ This route sends back informations about: - The songs list - The repeat mode - The shuffle mode - The song selected position - The active state Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ================================= ============== HTTP Code Status Type Description ========= ========== ================================= ============== 200 ``Passed`` ``SongQueueContentListContainer`` The songs list ========= ========== ================================= ============== .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "song_queue": [ { "uri": "http://localhost:54321/csp/Deezer/editorial/113/toptracks/87371673", "info": { "ti": "Dangerous" } } ], "repeat_mode": "repeat_none", "shuffle_mode": false, "song_selected_position": -1, "active_state": false, "id": "/SongQueue/Content/List.json", "status": "passed", "response_code": 200 } ---------- .. _SongQueue/Content/Add: 2. Add songs to the song queue ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== =========================== Key Value JSON =============== =========================== Resource URL /SongQueue/Content/Add.json HTTP Method POST Response format ``application/json`` =============== =========================== Description ^^^^^^^^^^^ Add one or more ``Song`` object at a specific position in the song queue. If the song queue is full, the HTTP error 507 is returned. Parameters ^^^^^^^^^^ = ========= ========= ============================================= # Name Type Description = ========= ========= ============================================= 1 position Integer The position from which we must add the songs 2 songs Array The list of ``Song`` objects = ========= ========= ============================================= Request Body Example ^^^^^^^^^^^^^^^^^^^^ .. hidden-code-block:: json :linenos: :label: JSON Request Body Example (Open/Close) { "position": 0, "songs": [ { "uri": "http://localhost:54321/csp/Deezer/editorial/113/toptracks/87371673", "info": { "ti": "Dangerous" } }, { "uri": "http://localhost:54321/csp/Deezer/editorial/113/toptracks/79223833", "info": { "ti": "Prayer In C" } } ] } | Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Content/Add.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Content/Remove: 3. Remove songs from the song queue ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ============================== Key Value JSON =============== ============================== Resource URL /SongQueue/Content/Remove.json HTTP Method POST Response format ``application/json`` =============== ============================== Description ^^^^^^^^^^^ Remove one or more ``Song`` objects in the song queue. There is two ways to use this method: - The first one is used to remove N songs from a specific position. - The second one is used to remove N songs at specific positions. Method#1 Parameters ^^^^^^^^^^^^^^^^^^^ = ============ ========= ================================================ # Name Type Description = ============ ========= ================================================ 1 position Integer The position from which we must remove the songs 2 songs_number Integer The number of ``Song`` objects to remove = ============ ========= ================================================ Method#1 Request Body Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. hidden-code-block:: json :linenos: :label: JSON Request Body Example (Open/Close) { "position": 1, "songs_number": 5 } | Method#2 Parameters ^^^^^^^^^^^^^^^^^^^ = =============== ========= ========================================= # Name Type Description = =============== ========= ========================================= 1 songs_positions Array A list of positions number to remove. The positions must be in descending order = =============== ========= ========================================= Method#2 Request Body Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. hidden-code-block:: json :linenos: :label: JSON Request Body Example (Open/Close) { "songs_positions": [ 10,3,0 ] } | Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Content/Remove.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Content/Clear: 4. Clear the song queue ~~~~~~~~~~~~~~~~~~~~~~~ =============== ============================= Key Value JSON =============== ============================= Resource URL /SongQueue/Content/Clear.json HTTP Method DELETE Response format ``application/json`` =============== ============================= Description ^^^^^^^^^^^ Remove all the songs from the song queue, stop the playback and reset the song selected position. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Content/Clear.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Content/MaxSongsNumber: 5. Get the max songs number ~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ====================================== Key Value JSON =============== ====================================== Resource URL /SongQueue/Content/MaxSongsNumber.json HTTP Method GET Response format ``application/json`` =============== ====================================== Description ^^^^^^^^^^^ This route sends back the max songs number authorized in the song queue. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ====================== =========== ==================== HTTP Code Status Name Type Description ========= ========== ====================== =========== ==================== 200 ``Passed`` max_songs_number Integer The max songs number ========= ========== ====================== =========== ==================== .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "max_songs_number": 200, "id": "/SongQueue/Content/MaxSongsNumber.json", "status": "passed", "response_code": 200 } ---------- .. _SongQueue/Control/Position: 6. Set/Get the song position ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ================================ Key Value JSON =============== ================================ Resource URL /SongQueue/Control/Position.json HTTP Method POST/PUT Response format ``application/json`` =============== ================================ Description ^^^^^^^^^^^ Set the position, in the song queue, of the song to play. Parameters ^^^^^^^^^^ = ========= ========= =================== # Name Type Description = ========= ========= =================== 1 position Integer The position to set = ========= ========= =================== Request Body Example ^^^^^^^^^^^^^^^^^^^^ .. hidden-code-block:: json :linenos: :label: JSON Request Body Example (Open/Close) { "position": 12 } | Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/Position.json", "status": "passed", "return_code": 200 } ---------- =============== ================================ Key Value JSON =============== ================================ Resource URL /SongQueue/Control/Position.json HTTP Method GET Response format ``application/json`` =============== ================================ Description ^^^^^^^^^^^ This route sends back the song selected position. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ====================== =========== ========================== HTTP Code Status Name Type Description ========= ========== ====================== =========== ========================== 200 ``Passed`` song_selected_position Integer The song selected position ========= ========== ====================== =========== ========================== .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "song_selected_position": 0 "id": "/SongQueue/Control/Position.json", "status": "passed", "response_code": 200 } ---------- .. _SongQueue/Control/Play: 7. Play the song at the selected position ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ============================ Key Value JSON =============== ============================ Resource URL /SongQueue/Control/Play.json HTTP Method POST/PUT Response format ``application/json`` =============== ============================ Description ^^^^^^^^^^^ Play the song at the selected position. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/Play.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Control/Pause: 8. Pause the playback of the selected song ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ============================= Key Value JSON =============== ============================= Resource URL /SongQueue/Control/Pause.json HTTP Method POST/PUT Response format ``application/json`` =============== ============================= Description ^^^^^^^^^^^ Pause the playback of the selected song. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/Pause.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Control/PlayPause: 9. Play/Pause the playback of the selected song ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ================================= Key Value JSON =============== ================================= Resource URL /SongQueue/Control/PlayPause.json HTTP Method POST/PUT Response format ``application/json`` =============== ================================= Description ^^^^^^^^^^^ Toggle Play/Pause the playback of the selected song. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/PlayPause.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Control/Stop: 10. Stop the playback of the selected song ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ============================ Key Value JSON =============== ============================ Resource URL /SongQueue/Control/Stop.json HTTP Method POST/PUT Response format ``application/json`` =============== ============================ Description ^^^^^^^^^^^ Stop the playback of the selected song. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/Stop.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Control/Next: 11. Set the Next position of the song to play ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ============================ Key Value JSON =============== ============================ Resource URL /SongQueue/Control/Next.json HTTP Method POST/PUT Response format ``application/json`` =============== ============================ Description ^^^^^^^^^^^ Set the Next position of the song to play. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/Next.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Control/Previous: 12. Set the Previous position of the song to play ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ================================ Key Value JSON =============== ================================ Resource URL /SongQueue/Control/Previous.json HTTP Method POST/PUT Response format ``application/json`` =============== ================================ Description ^^^^^^^^^^^ Set the Previous position of the song to play. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/Previous.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Control/RepeatMode: 13. Set/Get the Repeat Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ================================== Key Value JSON =============== ================================== Resource URL /SongQueue/Control/RepeatMode.json HTTP Method POST/PUT Response format ``application/json`` =============== ================================== Description ^^^^^^^^^^^ Set the repeat mode of the song queue. Parameters ^^^^^^^^^^ = =========== ========= ================================================================== # Name Type Description = =========== ========= ================================================================== 1 repeat_mode String The value can be ''repeat_none'', ''repeat_one'' or ''repeat_all'' = =========== ========= ================================================================== Request Body Example ^^^^^^^^^^^^^^^^^^^^ .. hidden-code-block:: json :linenos: :label: JSON Request Body Example (Open/Close) { "repeat_mode": "repeat_none" } | Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/RepeatMode.json", "status": "passed", "return_code": 200 } ---------- =============== ================================== Key Value JSON =============== ================================== Resource URL /SongQueue/Control/RepeatMode.json HTTP Method GET Response format ``application/json`` =============== ================================== Description ^^^^^^^^^^^ This route sends back the repeat mode. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== =========== =========== =============== HTTP Code Status Name Type Description ========= ========== =========== =========== =============== 200 ``Passed`` repeat_mode String The repeat mode ========= ========== =========== =========== =============== .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "repeat_mode": "repeat_none", "id": "/SongQueue/Control/RepeatMode.json", "status": "passed", "response_code": 200 } ---------- .. _SongQueue/Control/ToggleRepeatMode: 14. Toggle the Repeat Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ======================================== Key Value JSON =============== ======================================== Resource URL /SongQueue/Control/ToggleRepeatMode.json HTTP Method POST/PUT Response format ``application/json`` =============== ======================================== Description ^^^^^^^^^^^ Toggle the repeat mode of the song queue. "repeat_none" --> "repeat_all" --> "repeat_one" --> ... Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/ToggleRepeatMode.json", "status": "passed", "return_code": 200 } ---------- .. _SongQueue/Control/ShuffleMode: 15. Set/Get the Shuffle Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== =================================== Key Value JSON =============== =================================== Resource URL /SongQueue/Control/ShuffleMode.json HTTP Method POST/PUT Response format ``application/json`` =============== =================================== Description ^^^^^^^^^^^ Set the shuffle mode of the song queue. Parameters ^^^^^^^^^^ = ============ ========= ====================================== # Name Type Description = ============ ========= ====================================== 1 shuffle_mode Boolean The value can be ''true'' or ''false'' = ============ ========= ====================================== Request Body Example ^^^^^^^^^^^^^^^^^^^^ .. hidden-code-block:: json :linenos: :label: JSON Request Body Example (Open/Close) { "shuffle_mode": true } | Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/ShuffleMode.json", "status": "passed", "return_code": 200 } ---------- =============== =================================== Key Value JSON =============== =================================== Resource URL /SongQueue/Control/ShuffleMode.json HTTP Method GET Response format ``application/json`` =============== =================================== Description ^^^^^^^^^^^ This route sends back the shuffle mode. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============ ============ ====================== HTTP Code Status Name Type Description ========= ========== ============ ============ ====================== 200 ``Passed`` shuffle_mode Boolean The shuffle mode state ========= ========== ============ ============ ====================== .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "shuffle_mode": true, "id": "/SongQueue/Control/ShuffleMode.json", "status": "passed", "response_code": 200 } ---------- .. _SongQueue/Control/ToggleShuffleMode: 16. Toggle the Shuffle Mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ========================================= Key Value JSON =============== ========================================= Resource URL /SongQueue/Control/ToggleShuffleMode.json HTTP Method POST/PUT Response format ``application/json`` =============== ========================================= Description ^^^^^^^^^^^ Toggle the shuffle mode of the song queue: ''true'' --> ''false'' --> ... Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============================= ========================= HTTP Code Status Type Description ========= ========== ============================= ========================= 200 ``Passed`` ``RequestSucceededContainer`` The command is successful ========= ========== ============================= ========================= .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "id": "/SongQueue/Control/ToggleShuffleMode.json", "status": "passed", "return_code": 200 } | ---------- .. _SongQueue/Control/ActiveState: 17. Get the Active State ~~~~~~~~~~~~~~~~~~~~~~~~ =============== =================================== Key Value JSON =============== =================================== Resource URL /SongQueue/Control/ActiveState.json HTTP Method GET Response format ``application/json`` =============== =================================== Description ^^^^^^^^^^^ This route sends back the song queue active state. Parameters ^^^^^^^^^^ None. Expected response ^^^^^^^^^^^^^^^^^ ========= ========== ============ ============ =========================== HTTP Code Status Name Type Description ========= ========== ============ ============ =========================== 200 ``Passed`` active_state Boolean The song queue active state ========= ========== ============ ============ =========================== .. hidden-code-block:: json :linenos: :label: JSON Response Example (Open/Close) { "active_state": true, "id": "/SongQueue/Control/ActiveState.json", "status": "passed", "response_code": 200 } | ---------- .. _Service/Notification/SongQueue: 18. Song Queue HTTP long polling ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =============== ==================================== Key Value JSON =============== ==================================== Resource URL /Service/Notification/SongQueue.json HTTP Method COMET Response format ``application/json`` =============== ==================================== Description ^^^^^^^^^^^ This route sends back the song queue notifications. Parameters ^^^^^^^^^^ None. Expected notifications ^^^^^^^^^^^^^^^^^^^^^^ .. hidden-code-block:: json :linenos: :label: JSON Expected Notifications (Open/Close) { "notification_type":"song_queue" } { "notification_type":"song_selected_position" } { "notification_type":"repeat_mode", } { "notification_type":"shuffle_mode" } { "notification_type":"active_state" } |