Protocol Specs

Favorites station *Depending on playing service *Depending on playing service
song NA NA
Playlists station NA NA
song Play, Pause, Stop, PlayNext,
PlayPrevious
Play, Pause, PlayNext, PlayPrevious
History station *Depending on playing service *Depending on playing service
song Play, Pause, Stop, PlayNext,
PlayPrevious
Play, Pause, PlayNext, PlayPrevious
AUX Input station Play, Stop Play, Stop
song NA NA
3. Command and Response Overview
3.1 Commands
HEOS CLI commands are in the following general format:
heos://command_group/command?attribute1=value1&attribute2=value2&…&attributeN=valueN
Command string delimiter is "\r\n".
Note: Special characters, i.e '&', '=', and '%' in attribute/value needs to be encoded to '%26(&)', '%3D(=)', and '%25(%)'. Most of the time,
controllers use the same string that is received in previous command response. For example, while preparing 'play_stream'/'add_to_queue'
command, controllers will use the strings obtained in 'browse' command response. Those strings are already encoded. So, controllers are
not required to perform any special action. However, controllers might need to decode the encoded strings before they can be properly
displayed on the controller GUI.
3.2 Responses
The responses to commands are in JSON format and use the following general structure:
{
"heos": {
"command": "'command_group'/'command'",
"result": "'success' or 'fail'",
"message": "other result information'"
},
"payload":{
'Rest of response data'
}
}
Some command responses will not include a payload.
If the "result" of the command is "fail" then the "message" information contains the error codes for the failure. The error codes can be
found in Section TBD.
Some commands will also cause unsolicited responses. For example, sending the 'player/clear_queue' command will also cause the
Player/Group Queue Changed response and could also cause the Player/Group Status Changed response.
When the actual response can't be populated immediately, a special response will be sent back as shown below. This usually occurs
during browse/search as CLI needs to retrieve data from remote media server or online service.
{
"heos": {
"command": "'command_group'/'command'",
"result": "'success'",
"message": "command under process'"
}
}