HEOS CLI Protocol Specification 1. Overview 1.1 Supported music services 2. Connection 2.1 Controller Design Guidelines 2.1.1 Driver Initialization 2.1.2 Caveats 2.1.2.1 Compatibility 2.1.2.2 Issues & Solutions 2.1.3 Miscellaneous 3. Command and Response Overview 3.1 Commands 3.2 Responses 4. Command and Response Details 4.1 System Commands 4.1.1 Register for Change Events 4.1.2 HEOS Account Check 4.1.3 HEOS Account Sign In 4.1.4 HEOS Account Sign Out 4.1.5 HEOS System Heart Beat 4.1.
Limitations for the system when used multi devices. 4.4.10 Play URL 4.4.11 Add Container to Queue with Options 4.4.12 Add Track to Queue with Options 4.4.13 Get HEOS Playlists 4.4.14 Rename HEOS Playlist 4.4.15 Delete HEOS Playlist 4.4.16 Get HEOS History 4.4.17 Retrieve Album Metadata 4.4.18 Get Service Options for now playing screen - OBSOLETE 4.4.19 Set service option 5. Change Events (Unsolicited Responses) 5.1 Sources Changed 5.2 Players Changed 5.3 Group Changed 5.4 Player State Changed 5.
1.7 1.373.100 Add Source id for each Music service and source Remove unused change events: source_data_changed, group_changed, player_mute_changed, group_mute_changed 09/21/2016 Prakash Mortha 1.8 1.397.190 Add support for Juke music service 04/12/2017 Prakash Mortha Add support for adding station to HEOS Favorites from browse menu Expand Thumbs Up/Down option to more music services [LS AVR only] Add new commands set_quickselect, play_quickselect, and get_quickselects. 1.9 1.406.
17 Future service N/A N//A 18 QQMusic No No Following table list out other supported music sources through CLI. Source ID (sid) Source name Browse supported Search supported 1024 Local USB Media/ Local DLNA servers Yes Yes 1025 HEOS Playlists Yes No 1026 HEOS History Yes No 1027 HEOS aux inputs Yes No 1028 HEOS Favorites Yes No 2. Connection The HEOS products can be discovered using the UPnP SSDP protocol.
2.1.2.2 Issues & Solutions Changes made to HEOS user account, through HEOS app will not reflect through CLI until the controller is restarted. Ex: Adding or removing music services to HEOS user account, through HEOS app will not reflect in get_music_sources command response until the controller is restarted. Solution: Controller needs to re sign-in to HEOS account to reflect changes made through HEOS app, with out restarting the controller.
Local Music Favorites Playlists History AUX Input station NA NA song Play, Pause, Stop, PlayNext, PlayPrevious Play, Pause, PlayNext, PlayPrevious station *Depending on playing service *Depending on playing service song NA NA station NA NA song Play, Pause, Stop, PlayNext, PlayPrevious Play, Pause, PlayNext, PlayPrevious station *Depending on playing service *Depending on playing service song Play, Pause, Stop, PlayNext, PlayPrevious Play, Pause, PlayNext, PlayPrevious station
"result": "'success'", "message": "command under process'" } } JSON command response delimiter is "\r\n". Note: Special characters '&', '=', and '%' in the JSON response fields are encoded to '%26(&)', '%3D(=)', and '%25(%)'. 4. Command and Response Details 4.1 System Commands 4.1.1 Register for Change Events By default HEOS speaker does not send Change events. Controller needs to send this command with enable=on when it is ready to receive unsolicit responses from CLI.
"command": "system/sign_in ", "result": "success", "message": "signed_in&un=" } } Example: heos://system/sign_in?un=user@gmail.com&pw=12345 4.1.4 HEOS Account Sign Out Command: heos://system/sign_out Response: { "heos": { "command": "system/sign_out ", "result": "success", "message": "signed_out" } } Example: heos://system/sign_out 4.1.
"result": "success", "message": "enable='on_or_off'" } } Example: heos://system/prettify_json_response?enable=on 4.2 Player Commands 4.2.1 Get Players Command: heos://player/get_players Attribute Description Enumeration pid Player id N/A gid pid of the Group leader N/A network Network connection type lineout LineOut level type 1 - variable 2 - Fixed control Only valid when lintout level type is Fixed (2).
. { "name": "'player name N'", "pid": "player id N'", "gid": "group id'", "model": "'player model N'", "version": "'player verison N'" "network": "wifi" "lineout": "level type" "control": "control option" "serial": "serial number" } ] } Example: heos://player/get_players 4.2.
Command: heos://player/get_play_state?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A Response: { "heos": { "command": " player/get_play_state ", "result": "success", "message": "pid='player_id'&state='play_state'" } } Example: heos://player/get_play_state?pid=1 4.2.
"heos": { "command": "player/get_now_playing_media", "result": "success", "message": "pid='player_id'" }, "payload": { "type" : "'song'", "song": "'song name'", "album": "'album name'", "artist": "'artist name'", "image_url": "'image url'", "mid": "'media id'", "qid": "'queue id'", "sid": source_id "album_id": "Album Id'" } } The following response provides example when the speaker is playing a station.
Example: heos://player/get_volume?pid=1 4.2.7 Set Volume Command: heos://player/set_volume?pid=player_id&level=vol_level Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A level Player volume level 0 to 100 Response: { "heos": { "command": " player/ set_volume ", "result": "success", "message": "pid='player_id'&level='vol_level'" } } Example: heos://player/set_volume?pid=2&level=30 4.2.
Example: heos://player/volume_down?pid=2&step=5 4.2.10 Get Mute Command: heos://player/get_mute?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A Response: { "heos": { "command": " player/ get_mute ", "result": "success", "message": "pid='player_id'&state='on_or_off'" } } Example: heos://player/get_mute?pid=1 4.2.
4.2.13 Get Play Mode Command: heos://player/get_play_mode?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A Response: { "heos": { "command": " player/get_play_mode", "result": "success", "message": "pid='player_id'&&repeat= on_all_or_on_one_or_off&shuffle=on_or_off" } } Example: hoes://player/get_play_mode?pid=1 4.2.
}, "payload": [ { "song": "'song name 1'", "album": "'album name 1'", "artist": "'artist name 1'", "image_url": "'image_url 1'", "qid": "'queue id 1'", "mid": "'media id 1'" "album_id": "AlbumId 1'" }, { "song": "'song name 2'", "album": "'album name 2'", "artist": "'artist name 2'", " image_url": "''image_url 2'", "qid": "'queue id 2'", "mid": "'media id 2'" "album_id": "AlbumId 2'" }, . . .
pid Player id returned by 'get_players' or 'get_groups' command N/A qid List of comma separated queue_id's where each queue id for song is returned by 'get_queue' command N/A Response: { "heos": { "command": "player/remove_from_queue ", "result": "success", "message": "pid='player_id'&qid=queue_id_1, queue_id_2,…,queue_id_n'" } } Example: heos://player/remove_from_queue? pid=1&qid=4,5,6 4.2.
pid Player id returned by 'get_players' or 'get_groups' command N/A sqid List of comma separated queue_id's where each queue id for song is returned by 'get_queue' command list item range:1 to size of queue dqid User select this value as the destination of contents which is indicated in sqid. 1 to size of queue. Response: { "heos": { "command": "player/move_queue_item ", "result": "success", "message": "pid='player_id'&sqid=' source_queue_id_1','source_queue_id_2',...
Response: { "heos": { "command": " player/set_quickselect", "result": "success", "message": "pid=player_id&id=" } } Example: heos://player/set_quickselect?pid=1&id=2 Currently supported HEOS products: LEGO AVR, HEOS BAR 4.2.
} ] } Example: heos://player/get_quickselects?pid=1 Currently supported HEOS products: LEGO AVR, HEOS BAR 4.2.
"role": "player role N (leader or member)'" } ] }, { "name": "'group name 2'", "gid": "group id 2'", "players": [ { "name": "player name 1", "pid": "'player id 1'", "role": "player role 1 (leader or member)'" }, { "name": "player name 2", "pid": "'player id 2'", "role": "player role 2 (leader or member)'" }, . . . { "name": "player name N", "pid": "'player id N'", "role": "player role N (leader or member)'" } ] }, . . .
{ "heos": { "command": "player/get_groups", "result": "success", "message": "gid=group_id" }, "payload": { "name": "'group name 1'", "gid": "group id 1'", "players": [ { "name": "player name 1", "pid": "'player id 1'", "role": "player role 1 (leader or member)'" }, { "name": "player name 2", "pid": "'player id 2'", "role": "player role 2 (leader or member)'" }, . . .
} } The following response provides example when all the speakers in the group are un-grouped. { "heos": { "command": "player/set_group ", "result": "success", "message": "pid='player_id' } } Example: heos://group/set_group?pid=3,1,4 4.3.
Response: { "heos": { "command": " group/ volume_up ", "result": "success", "message": "gid='group_id'&step='step_level'" } } Example: heos://group/volume_up?gid=1&step=5 4.2.
Response: { "heos": { "command": "group/ set_mute ", "result": "success", "message": "gid=group_id'&state='on_or_off'" } } Example: heos://group/set_mute?gid=1&state=off 4.3.10 Toggle Group Mute Command: heos://group/toggle_mute?gid=group_id Attribute Description Enumeration gid Group id returned by 'get_groups' command N/A Response: { "heos": { "command": "group/ toggle_mute ", "result": "success", "message": "gid=group_id" } } Example: heos://group/toggle_mute?gid=1 4.4 Browse Commands 4.4.
"image_url": "source logo url 2", "type": "source type 2", "sid": source_id_2, "available": "true/false", "service_username": "user name of the service account" }, { "name": "source name N", "image_url": "source logo url N", "type": "source type N", "sid": source_id_N, "available": "true/false", "service_username": "user name of the service account" } ] } Example: heos://browse/get_music_sources The following are valid source types: music_service heos_service heos_server dlna_server 4.4.
music_service heos_service heos_server dlna_server 4.4.
"type": "'source type 1'" }, { "name": "'source name 2'", "'image_url": "'source logo url 2'", "sid": "source id 2'", "type": "'source type 2'" }, { "name": "'source name N'", "'image_url": "'source logo url N'", "sid": "source id N'", "type": "'source type N'" } ], "options": [ { "browse": [ { "id": 13, "scid": "criteria Id", "name": "criteria string" } ] } ] } Example: heos://browse/browse?sid=1 Response when browsing top music view in an actual music server/music services.
"type": "container", "name": "'container name'", "image_url": "'container image url'", "cid": "'container id'", "mid": "'media id'" }, { "container": "no", "playable": "yes", "type": "station", "name": "'station name'", "image_url": "'station url'", "mid": "'media id'" } ], "options": [ { "browse": [ { "id": 20, "name": "Remove from HEOS Favorites" } ] } ] } Example: heos://browse/browse?sid=1346442495 Supported Sources: Local Media Servers, Playlists, History, Aux-In, Favorites, TuneIn, Pandora, Rhapsody,
id (options) Options available for current browse level Various options are presented as part of 'Browse Source container' command response. Supported options under each browse menu depends on service type and container type.
"artist": "'artist name'", "album": "'album name'", "mid": "'media id'" }, { "container": "yes", "playable": "no", "type": "container", "name": "'container name'", "image_url": "'container image url'", "cid": "'container id'", "mid": "'media id'" }, { "container": "no", "playable": "yes", "type": "station", "name": "'station name'", "image_url": "'station url'", "mid": "'media id'" } ], "options": [ { "browse": [ { "id": 4, "name": "Add Playlist to Library" } ] } ] } Example: heos://browse/browse?sid=2&cid=
"name": "Artist", "scid": "'search_criteria_id'", "wildcard": "yes_or_no", }, { "name": "Album", "scid": "'search_criteria_id'", "wildcard": "yes_or_no", }, { "name": "Track", "scid": "'search_criteria_id'", "wildcard": "yes_or_no", "playable": "yes_or_no", "cid": "Prefix to search string", }, { "name": "Station", "scid": "'search_criteria_id'", "wildcard": "yes_or_no", } ] } Example: heos://browse/get_search_criteria?sid=3 Supported Sources: Local Media Servers, TuneIn, Rhapsody, Deezer, SiriusXM, Napster,
"image_url": "'artist image url'", "cid": "container id'", "mid": "media id" }, { "container": "yes", "playable": "yes", "type": "album", "name": "'album name'", "image_url": "'album image url'", "artist": "'artist name'", "cid": "'container id'", "mid": "'media id'" }, { "container": "no", "playable": "yes", "type": "song", "name": "'song name'", "image_url": "'album image url'", "artist": "'artist name'", "album": "'album name'", "mid": "'media id'" }, { "container": "yes", "playable": "no", "type": "cont
pid Player id returned by 'get_players' or 'get_groups' command N/A name Station name returned by 'browse' command. N/A Note: The mid for this command must be a 'station' media type. Response: Note: this command will cause a Now Playing Change Event to occur if a new stream is played.
spid player id of the HEOS device which is acting as the source N/A Player id returned by 'get_players' or 'get_groups' command input input source name "inputs/aux_in_1" Note: Validity of Inputs depends on the type of source HEOS device "inputs/aux_in_2" "inputs/aux_in_3" "inputs/aux_in_4" "inputs/aux1" "inputs/aux2" "inputs/aux3" "inputs/aux4" "inputs/aux5" "inputs/aux6" "inputs/aux7" "inputs/line_in_1" "inputs/line_in_2" "inputs/line_in_3" "inputs/line_in_4" "inputs/coax_in_1" "inputs/coax_in_2" "i
pid Player id returned by 'get_players' or 'get_groups' command N/A url Absolute path to a playable stream N/A Response: Note: The attribute value pair ?"url=url_path" should be the last attribute value pair in the play_stream command. This is required to handle url_path with special characters and command delimiters. This command will cause a Now Playing Change Event to occur if url is played.
aid Add criteria id as defined by enumerations -> 1 – play now 2 – play next 3 – add to end 4 – replace and play pid Player id returned by 'get_players' or 'get_groups' command N/A Note: The mid for this command must be a 'track' media type. Response: Note: this command will cause a Now Playing Change Event to occur if a new song is played.
"message": "sid='source_id'&cid='contaiiner_id' } } Example: heos://browse/delete_playlist?sid=11&cid=234 4.4.16 Get HEOS History Refer to Browse Sources and Browse Source Containers 4.4.17 Retrieve Album Metadata Rhapsody and Napster services doesn't provide album art url while browsing for tracks. Controllers can use this command to retrieve album art url while browsing for tracks. Retrieve image url associated with a given album id.
Attribute Description Enumeration sid Source id returned by 'get_music_sources' command N/A id (options) Options available on now playing screen Following options are currently supported for 'Get Service options for now playing screen': 11 - Thumbs Up 12 - Thumbs Down Note: This command returns service options that are only available on 'now playing' screen. Please refer to 'Browse Source' and 'Browse Source Containers' for service options available on various browse levels.
3 - Add Station to Library heos://browse/set_service_option?sid=2&option=3&mid=sas.6513639 mid - station id obtained through 'browse source containers' command heos://browse/set_service_option?sid=2&option=4&cid=LIBPLAYLIST-pp.17557314 9&name=Lupe Fiasco cid - playlist id obtained through 'browse source containers' command name - name of the playlist obtained through 'browse source container' command heos://browse/set_service_option?sid=2&option=5&mid=Tra.
12 - Thumbs Down heos://browse/set_service_option?sid=1&option=12&pid=-409995282 pid - player id obtained through 'get_players' command heos://browse/set_service_option?sid=1&option=13&name=Love&scid=1 name search string for creating new station Note: This command returns station ids. Controllers need to use 'play station' command to play a station.
19 - Add station to HEOS Favorites Following command is used on now-playing-screen to add currently playing station to HEOS Favorites heos://browse/set_service_option?option=19&pid=-409995282 Following command is used on browse screen to add a station to HEOS Favorites heos://browse/set_service_option?sid=3&option=19&mid=sas.
{ "heos": { "command": "event/groups_changed", } } 5.4 Player State Changed Response: { "heos": { "command": "event/player_state_changed", "message": "pid='player_id'&state='play_state'" } } 5.5 Player Now Playing Changed Response: { "heos": { "command": " event/player_now_playing_changed", "message": "pid='player_id'" } } 5.6 Player Now Playing Progress Response: { "heos": { "command": " event/player_now_playing_progress", "message": "pid=player_id&cur_pos=position_ms&duration=duration_ms" } } 5.
5.9 Player Volume Changed Response: { "heos": { "command": "event/player_volume_changed ", "message": "pid='player_id'&level='vol_level'&mute='on_or_off'" } } 5.10 Player Repeat Mode Changed Response: { "heos": { "command": "event/repeat_mode_changed", "message": "pid=’player_id’&repeat='on_all_or_on_one_or_off'” } } 5.11 Player Shuffle Mode Changed Response: { "heos": { "command": "event/shuffle_mode_changed", "message": "pid=’player_id’&shuffle='on_or_off'” } } 5.
"command": "'command_group'/'command'", "result": "'fail'", "message": "eid="error_id&text=error text& command_arguments'" } } 6.2 Error Code description Description Code Text Example Unrecognized Command 1 Command not recognized. Invalid ID 2 ID not valid Wroing Number of Command Arguments 3 Command arguments not correct. Requested data not available 4 Requested data not available. Resource currently not available 5 Resource currently not available.