wss://queue.ibroadcast.comThe Play Queue Server is a Web Socket server that persists your now playing and play queue information, as well as communicates that information with the rest of the system. While optional, by using the play queue server you can communicate quickly and efficiently with the server and other clients on a user's account. For example, if the user updates their library, the server will notify clients connected to the Play Queue Server so that they can update their copies right away. Additionally, you can connect to other clients' queues and send commands to them, allowing you to remote control clients.
wss://queue.ibroadcast.com?token=play_queue_token
The Play Queue Server will disconnect idle Web Sockets after 10 minutes. In the case that the socket is disconnected, whether it is due to an error or an idle timeout, you should make sure to reconnect to the socket. To prevent performance degredation, wait 5 seconds in between reconnect attempts. Any time you need to reconnect, you should follow the full process as outlined in Connecting.
If the Web Socket connection encounters an error, you should wait 5 seconds and then attempt reconnect. If the server ever responds with a result of false, you should wait 5 seconds and attempt a reconnect. By doing this, you avoid spamming the play queue server with reconnect attempts.
All commands are JSON and should follow this format:
{
"session_uuid": String,
"client": String,
"version": String,
"device_name": String,
"command": String,
"value": Dictionary // Required for only some commands
}
The server will respond to the following commands:
After receiving this command, the server will send a set_state command back down to the client.
Send this command to update the server state with new data.
This command expects a value with the following format:
{
"current_song": Int, // Current track ID
"data": {
"play_from": String, // "tracks" or "play_next"
"play_index": Int, // Current index of now playing item in "tracks"
"repeat_mode": String, // "none", "queue", or "track"
"crossfade": Bool
},
"name": String, // Display name of currently playing track
"pause": Bool,
"tracks": [Int], // Tracks in normal queue
"play_next": [Int], // Tracks in "Up Next" queue
"shuffle": Bool,
"start_position": Float, // Current time of now playing song when the timestamp was equal to start_time
"start_time": Float, // A reference timestamp for the start_position parameter (Unix UTC timestamp with millisecond precision)
"volume": Float // 0.0 - 1.0
}
In response to certain events, commands, etc, the server may send one of the following commands to the client:
Any time a play queue's state is updated by a client, the server will send a set_state command to all OTHER clients. Additionally, if a client calls get_state, the server will send back this set_state command. This command contains the full play queue state. Unlike when sending the state in which the state is provided in the value, this command contains the state at the top level.
{
"command": "set_state",
"role": "player",
"current_song": Int,
"data": {
"play_from": String,
"play_index": Int,
"repeat_mode": String,
"crossfade": Bool
},
"name": String,
"pause": Bool,
"tracks": [Int],
"play_next": [Int],
"shuffle": Bool,
"start_position": Float,
"start_time": Float,
"volume": Float
}
If the user's library is updated, the server will send this command to all connected clients. When this occurs, you should compare the lastmodified parameter to that of the last downloaded version of the library to see if it needs to update. If it does, re-download the user's library.
{
"command":"update_library",
"lastmodified":"2025-09-19 16:51:26",
"message":"ok",
"result":true
}
Any time a user logs in or out of an app, the server will update the sessions list and send this command
{
"command":"sessions",
"message":"ok",
"result":true,
"value": [
{ // session object },
{ // session object },
{ // session object }
]
}
If you receive this command, the that means that the user has been logged out. The current access token is no-longer valid. You should return the user to the login view.
{
"command":"end_session",
"message":"ok",
"result":true,
"value":true
}
These parameters are used to keep track of which track in the queues is currently playing.
iBroadcast has two types of play queues:
tracks
The tracks queue is the normal playback queue. It has no special behaviors and behaves like a normal FIFO queue. The play_from parameter with a value of "tracks" will indicate that the player should be playing from the tracks queue.
Do Not remove tracks from this queue after playing them. If you do, there will be no way to go back to the previous track or repeat the entire queue.
play_next
The second type of queue is the "Up Next" queue. If there are tracks in the play_next queue, the player should always play through these track before continuing on to the tracks queue. To indicate that the player is playing from play_next, set the play_from parameter to "play_next".
If the player is currently playing from tracks and the user adds tracks to play_next, the player should wait until the currently playing track finishes and then start playing from the play_next queue.
The play_next queue always plays the first track in it. Because of this, you should always remove a track from it after that track plays. Similarly, if the user skips ahead to the 5th track in play_next, you should remove tracks 0-4 so that track 5 becomes the first track.
play_index should be used to keep track of the position of the now playing track in the tracks queue. When the play_next queue is exhausted, playback will resume the tracks queue at the index specified by play_index
Example:
1. User plays an album from the beginning:
tracks: [t1, t2, t3, t4]
play_next: []
play_index: 0
play_from: "tracks"2. User adds 1 tracks to play_next:
tracks: [t1, t2, t3, t4]
play_next: [t5]
play_index: 0
play_from: "tracks"3. Next track plays, player is now playing from play_next:
tracks: [t1, t2, t3, t4]
play_next: [t5]
play_index: 1
play_from: "play_next"4. Again, next track plays, player is now playing from tracks:
tracks: [t1, t2, t3, t4]
play_next: []
play_index: 1
play_from: "tracks"
These parameters are used to track the current playhead position of the now playing track.
start_position is the playhead position that the track was at when the current unix timestamp was what is contained inside start_time.
Example:
1. Current unix timestamp is: 1613755101.0
2. User plays a song from the beginning:
start_position: 0
start_time: 1613755101.03. 10 seconds later, user seeks to a position 30 seconds into the track:
start_position: 30.0
start_time: 1613755111.0To calculate the current track's position from the start_position and start_time, you should use the following equation:
player_current_position = now() - (start_time - start_position)Important:
When handling the state received from the server, if pause is true, ignore the start_time value provided and instead use only the start_position. If you do not do this, the player will seek to a new position incorrectly each time a new state is received.
player_current_position = start_position
There are two types of roles that a client might have: player and controller. These roles are provided in the role parameter that is part of the state returned by the server.
{
"role": String
// ... other parameters
}player
This role represents the client that is currently playing music. This client should not have any special behavior.
controller
When multiple clients are connected to the same play queue, all but one will be controllers. A controller can control various aspects of the play queue, but does not play any audio. There are several special considerations when a client is a controller:
Important:
Be sure to gracefully handle role transitions as it's possible for the server to change your role at runtime.