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.
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.5 Player Now Playing Changed 5.6 Player Now Playing Progress 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 05/23/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.
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. Through discovery, the IP address of the HEOS products can be retrieved. Once the IP address is retrieved, a telnet connection to port 1255 can be opened to access the HEOS CLI and control the HEOS system. The HEOS product IP address can also be set statically and manually programmed into the control system.
2.1.3 Miscellaneous Controllers can add custom argument SEQUENCE= in browse commands to associate command and response. This is possible because the 'message' field in the response packet includes all the arguments sent in the command. Please let us know if you need additional custom argument other than 'SEQUENCE'. This is to avoid accidentally using HEOS command arguments for special purpose. Maximum number of simultaneous socket connections supported by HEOS speaker is 32.
History AUX Input station *Depending on playing service *Depending on playing service song Play, Pause, Stop, PlayNext, PlayPrevious Play, Pause, PlayNext, PlayPrevious 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.
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. Please refer to "Driver Initialization" section regarding when to register for change events. Command: heos://system/register_for_change_events?enable='on_or_off' Attribute Description Enumeration enable Register or unregister for change events.
Command: heos://system/sign_out Response: { "heos": { "command": "system/sign_out ", "result": "success", "message": "signed_out" } } Example: heos://system/sign_out 4.1.5 HEOS System Heart Beat Command: heos://system/heart_beat Response: { "heos": { "command": "system/heart_beat ", "result": "success" "message": "" } } Example: heos://system/heart_beat 4.1.6 HEOS Speaker Reboot Using this command controllers can reboot HEOS device.
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). 1 - None 2 - IR 3 - Trigger 4 - Network wired wifi Note: The group id field (gid) is optional. The 'gid' field will only be appeared if the player(s) is part of a group.
4.2.2 Get Player Info Command: heos://player/get_player_info?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command 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). 1 - None 2 - IR 3 - Trigger 4 - Network wired wifi Note: The group id field (gid) is optional.
Command: heos://player/set_play_state?pid=player_id&state=play_state Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A state Player play state play, pause, stop Response: { "heos": { "command": " player/set_play_state ", "result": "success", "message": "pid='player_id'&state='play_state'" } } Example: heos://player/set_play_state?pid=1&state=play Note: Play state of a group can be controlled by sending set_play_state command to any of the player i
"heos": { "command": "player/get_now_playing_media", "result": "success", "message": "pid='player_id'" }, "payload": { "type" : "'station'", "song": "'song name'", "station": "'station name'", "album": "'album name'", "artist": "'artist name'", "image_url": "'image url'", "mid": "'media id'", "qid": "'queue id'", "sid": source_id } "options": [ { "play": [ { "id": 19, "name": "Add to HEOS Favorites" } ] } ] } Example: heos://player/get_now_playing_media?pid=1 4.2.
} } Example: heos://player/set_volume?pid=2&level=30 4.2.8 Volume Up Command: heos://player/volume_up?pid=player_id&step=step_level Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A step Player volume step level 1 to 10(default 5) Response: { "heos": { "command": " player/ volume_up ", "result": "success", "message": "pid='player_id'&step='step_level'" } } Example: heos://player/volume_up?pid=2&step=5 4.2.
"message": "pid='player_id'&state='on_or_off'" } } Example: heos://player/get_mute?pid=1 4.2.11 Set Mute Command: heos://player/set_mute?pid=player_id&state=on_or_off Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A state Player mute state on, off Response: { "heos": { "command": " player/ set_mute ", "result": "success", "message": "pid='player_id'&state='on_or_off'" } } Example: heos://player/set_mute?pid=3&state=off 4.2.
} } Example: hoes://player/get_play_mode?pid=1 4.2.
" image_url": "''image_url 2'", "qid": "'queue id 2'", "mid": "'media id 2'" "album_id": "AlbumId 2'" }, . . . { "song": "'song name N'", "album": "'album name N'", "artist": "'artist name N'", " image_url": "''image_url N'", "qid": "'queue id N'", "mid": "'media id N'" "album_id": "AlbumId N'" } ] } Example: heos://player/get_queue?pid=1&range=0,10 4.2.
4.2.18 Save Queue as Playlist Command: heos://player/save_queue?pid=player_id&name=playlist_name Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A name String for new playlist name limited to 128 unicode characters N/A Response: { "heos": { "command": "player/save_queue ", "result": "success", "message": "pid='player_id'&name='playlist_name'" } } Example: heos://player/save_queue?pid=1&name=great playlist 4.2.
Example: heos://player/move_queue_item?pid=2,4&sqid=2&dqid=6 4.2.21 Play Next Command: heos://player/play_next?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A Response: { "heos": { "command": " player/play_next", "result": "success", "message": "pid=player_id" } } Example: heos://player/play_next?pid=1 4.2.
Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A id Quick select Id whose source needs to be played 1-6 Response: { "heos": { "command": "player/play_quickselect", "result": "success", "message": "pid=player_id&id=" } } Example: heos://player/play_quickselect?pid=1&id=2 Currently supported HEOS products: LEGO AVR, HEOS BAR 4.2.
{ "heos": { "command": "player/get_groups", "result": "success", "message": "" }, "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)'" }, . . .
. . . { "name": "player name N", "pid": "'player id N'", "role": "player role N (leader or member)'" } ] } ] } Example: heos://group/get_groups 4.3.
Modify existing group members: Adds or delete players from the group. First player id should be the group leader id. Ex: heos://group/set_group?pid=3,1,5 Ungroup all players in the group Ungroup players. Player id (pid) should be the group leader id.
gid Group id returned by 'get_groups' command N/A level Group volume level 0 to 100 Response: { "heos": { "command": "group/set_volume ", "result": "success", "message": "gid='group_id'&level='vol_level'" } } Example: heos://group/set_volume?gid=1&level=30 4.2.
Attribute Description Enumeration gid Group id returned by 'get_groups' command N/A Response: { "heos": { "command": "group/ get_mute ", "result": "success", "message": "gid='group_id'&state='on_or_off'" } } Example: heos://group/get_mute?gid=1 4.3.
Response: { "heos": { "command": "browse/get_music_sources", "result": "success", "message": "" }, "payload": [ { "name": "source name 1", "image_url": "source logo url 1", "type": "source type 1", "sid": source_id_1 }, { "name": "source name 2", "image_url": "source logo url 2", "type": "source type 2", "sid": source_id_2 }, { "name": "source name N", "image_url": "source logo url N", "type": "source type N", "sid": source_id_N } ] } Example: heos://browse/get_music_sources The following are valid source t
} Example: heos://browse/get_source_info The following are valid source types: music_service heos_service heos_server dlna_server 4.4.
"payload": [ { "name": "'source name 1'", "'image_url": "'source logo url 1'", "sid": "source id 1'", "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
"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": 20, "name": "Remove from HEOS Favorites" } ] } ] } Example: heos://browse/browse?sid=1346442495 Supported Sources: Local Media Servers, Pla
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.