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.
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. Through discovery, the IP address of the HEOS products can be retrieved.
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.
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.
"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.
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.
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.
"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.
id (options) Options available for current browse level Following options are currently supported for 'Browse Source' command 13 - Create New Station (Pandora, iHeartRadio) 20 - Remove from HEOS Favorites (Favorites) scid criteria for creating new station Possibilities: 1 - Artist (default) (Criteria String: Create New Station by Artists) 5 - Show (Criteria String: Create New Station by Shows) 3 - Track (Criteria String: Create New Station by Tracks) range Range is start and end record index to retur
{ "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. Note: the following response provides examples of the various media types. The actual response will depend on the source browsed and the hierarchy supported by that source.
{ "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, Deezer, SiriusXM, iHeartRadio, Napster, Tidal, SoundCloud, Amazon Music, Juke 4.4.
Note: Following response provides examples of the various media types. The actual response will depend on the source browsed and the hierarchy supported by that source.
Example: heos://browse/browse?sid=2&cid=TopAlbums&range=0,100 Supported Sources: Local Media Servers, Playlists, History, Aux-In, TuneIn, Pandora, Rhapsody, Deezer, SiriusXM, iHeartRadio, Napster, Tidal, SoundCloud, Amazon Music, Juke 4.4.5 Get Source Search Criteria Command: heos://browse/get_search_criteria?sid=source_id Attribute Description Enumeration sid Source id returned by 'get_music_sources' command N/A playable Indicates if Play-All option is supported on searched tracks.
Attribute Description Enumeration sid Source id returned by 'get_music_sources' command N/A search String for search limited to 128 unicode characters and may contain '*' for wildcard if supported by search criteria id N/A scid Search criteria id returned by 'get_search_criteria' command artist, album, song, station count Total number of items available in the container. NOTE: count value of '0' indicates unknown container size.
"container": "no", "playable": "yes", "type": "station", "name": "'station name'", "image_url": "'station url'", "mid": "'media id'" } ], "options": [ { "browse": [ { "id": 2, "name": "Add Album to Library" } ] } ] } Example: heos://browse/search?sid=2&search="U2"&scid=1 Supported Sources: Local Media Servers, TuneIn, Rhapsody, Deezer, Napster, Tidal, SoundCloud, Juke 4.4.
Note: this command will cause a Now Playing Change Event to occur if a new stream is played. { "heos": { "command": " browse/play_preset", "result": "success", "message": "pid='player_id'&preset='preset_number'" } } Example: heos://browse/play_preset?pid=1&preset=2 Supported Sources: HEOS Favorites 4.4.
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" "inputs/optical_in_1" "inputs/optical_in_2" "inputs/hdmi_in_1" "inputs/hdmi_arc_1" "inputs/cable_sat" "inputs/dvd" "inputs/bluray" "i
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. { "heos": { "command": " browse/play_stream ", "result": "success", "message": "pid='palyer_id'&url='path to stream" } } Example: heos://browse/play_stream?pid=1&url=http://10.110.25.159:49152/web/138.mp3 4.4.
Response: Note: this command will cause a Now Playing Change Event to occur if a new song is played. { "heos": { "command": " browse/add_to_queue", "result": "success", "message": "pid='player_id'&sid='source_id'&cid='container_id'&mid='media_id'&aid='add_criteria'" } } Example: heos://browse/add_to_queue?pid=1&sid=8&cid=Artists/All&mid=9&aid=1 Supported Sources: Local Media Servers, Playlists, History, Rhapsody Tracks, Deezer Tracks, iHeartRadio Tracks, Napster, Tidal, SoundCloud, Amazon Music, Juke 4.4.
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. This command facilitates controllers to retrieve and update their UI with cover art, if image_url in browse/search/get_queue/get_now_playing_media command response is blank.
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. Note: the following response provides examples of the various service options.
4 - Add Playlist to Library 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.174684187 mid - track id obtained through 'browse source containers' command heos://browse/set_service_option?sid=2&option=6&cid=LIBALBUM-Alb.
13 - Create New Station by Artists heos://browse/set_service_option?sid=1&option=13&name=Love&scid=1 heos://browse/set_service_option?sid=1&option=13&name=Love&range=0, 10 Supported Services:Pandora, iHeartRadio 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.