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.8 Play Preset Station 4.4.9 Play Input source 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.
1.5 1.349.101 Add preset command to play stations from HEOS Favorites. Add players network connection type in get_players and get_player_info command responses. Fix issue with range queries on Amazon Music. Add issues and solutions section. Refer Issues & Solutions. Remove support for Rdio as it is gone. 04/13/2016 Prakash Mortha 1.6 1.364.110 Add limitations while using inputs. Add AVR inputs list. 07/25/2016 Prakash Mortha 1.7 1.373.100 Add Source id for each Music service and source.
1.13 1.481.130 Remove support for Juke Music service. Juke support is currently removed from HEOS. Add option '21 - Playable Container' to support playable containers on Windows Media share. Add popular list of system errors. 10/31/2018 Prakash Mortha 1.14 1.505.140 Remove "inputs/analog" from input source name for Play input source command. Add "inputs /analog_in_1", "inputs /analog_in_2" and "inputs /recorder_in_1" to input source name for Play input source command.
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.
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.
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 Play, Pause, Stop, PlayNext, PlayPrevious Play, Pause, PlayNext, PlayPrevious station Play, Stop Play, Stop song NA NA 3. Command and Response Overview 3.
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. Please refer to "Driver Initialization" section regarding when to register for change events.
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.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.
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 wired wifi unknown (not applicable for external controllers) 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.
Example: heos://player/get_player_info?pid=1 4.2.3 Get Play State 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.
Response: The following response provides example when the speaker is playing a song. Note: For local music and DLNA servers sid will point to Local Music Source id.
Response: { "heos": { "command": " player/ get_volume ", "result": "success", "message": "pid='player_id'&level='vol_level'" } } Example: heos://player/get_volume?pid=1 4.2.
level Player volume step level 1 to 10(default 5) Response: { "heos": { "command": " player/ volume_down ", "result": "success", "message": "pid='player_id'&step='step_level'" } } Example: heos://player/volume_down?pid=2&step=5 4.2.
pid Player id returned by 'get_players' or 'get_groups' command N/A Response: { "heos": { "command": " player/ toggle_mute ", "result": "success", "message": "pid=player_id" } } Example: heos://player/toggle_mute?pid=3 4.2.
Range is start and end record index to return. Range parameter is optional. Omitting range parameter returns all records but a maximum of 100 records are returned per response. Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A range Range is start and end record index to return. Range parameter is optional. Omitting range parameter returns all records up to a maximum of 100 records per response.
pid Player id returned by 'get_players' or 'get_groups' command N/A qid Queue id for song returned by 'get_queue' command N/A Response: { "heos": { "command": " player/play_queue", "result": "success", "message": "pid='player_id'&qid='queue_id'" } } Example: heos://player/play_queue?pid=2&qid=9 4.2.
Command: heos://player/clear_queue?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A Response: { "heos": { "command": "player/clear_queue ", "result": "success", "message": "pid='player_id'" } } Example: heos://player/clear_queue 4.2.20 Move Queue Command: heos://player/move_queue_item?pid=player_id&sqid=source_queue_id_1,source_queue_id_2,...
4.2.22 Play Previous Command: heos://player/play_previous?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A Response: { "heos": { "command": " player/play_previous", "result": "success", "message": "pid=player_id" } } Example: heos://player/play_previous?pid=1 4.2.
Command: heos://player/get_quickselects?pid=player_id Command: heos://player/get_quickselects?pid=player_id&id= Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A id Optional Id for which information is required.
4.3 Group Commands 4.3.1 Get Groups Command: heos://group/get_groups Response: { "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": "'group name N'", "gid": "group id N'", "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.
Example: heos://group/get_group_info&?gid=1 4.3.3 Set Group This command is used to perform the following actions: Create new group: Creates new group. First player id in the list is group leader. Ex: heos://group/set_group?pid=3,1,4 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.
{ "heos": { "command": "group/get_volume ", "result": "success", "message": "gid='group_id'&level='vol_level'" } } Example: heos://group/get_volume?gid=1 4.3.
Response: { "heos": { "command": " group/ volume_down ", "result": "success", "message": "gid='group_id'&step='step_level'" } } Example: heos://group/volume_down?gid=1&step=5 4.3.8 Get Group Mute Command: heos://group/get_mute?gid=group_id 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": "group/ toggle_mute ", "result": "success", "message": "gid=group_id" } } Example: heos://group/toggle_mute?gid=1 4.4 Browse Commands 4.4.1 Get Music Sources Attribute Description Enumeration available Only valid for online music services. If true 'service_username' will provide user name of the service account. This should not be treated as the music service being supported through CLI or not.
} ] } Example: heos://browse/get_music_sources The following are valid source types: music_service heos_service heos_server dlna_server 4.4.2 Get Source Info Command: heos://browse/get_source_info?sid=source_id Attribute Description Enumeration sid Source id returned by 'get_music_sources' command (Or) Source id returned by 'browse' command when browsing source types 'heos_server' and 'heos_service' N/A available Only valid for online music services.
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
"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": 20, "name": "Remove from HEOS Favorites" } ] } ] } Example: heos://browse/browse?sid=1346442495 Supported Sources:
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.
"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": "container", "name": "'container name'", "image_url": "'container image url'", "cid": "'container id'", "mid": "'media id'" }, { "container": "
Example command to play all tracked, searched with string 'earth': heos://browse/add_to_queue? pid=&sid=2&cid=SEARCHED_T RACKS-earth&aid=1 Note: the following response provides examples of the various search criteria types. The actual response will depend on the source and the search types supported by that source.
range Range is start and end record index to return. Range parameter is optional. Omitting range parameter returns all records up to a maximum of 50/100 records per response. The default maximum number of records depend on the service type. range starts from 0 returned Number of items returned in current response N/A Response: Note: the following response provides examples of the various media types. The actual response will depend on the source searched and the results returned for the search string.
{ "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 4.4.7 Play Station Command: heos://browse/play_stream?pid=player_id&sid=source_id&cid=container_id&mid=media_id&name=station_name Attribute Description Enumeration sid Source id returned by 'get_music_sources' command N/A cid Container id that is used to browse current container.
"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.
"inputs/game" "inputs/mediaplayer" "inputs/cd" "inputs/tuner" "inputs/hdradio" "inputs/tvaudio" "inputs/phono" "inputs/usbdac" "inputs/analog_in_1" "inputs/analog_in_2" "inputs/recorder_in_1" Response for command "heos://browse/play_input?pid=player_id&input=input_name" : Note: this command will cause a Now Playing Change Event to occur if an aux in stream is played.
sid Source id returned by 'get_music_sources' command N/A cid Container id returned by 'browse' or 'search' command N/A 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 cid for this command must be a 'playable' container type. Response: Note: this command will cause a Now Playing Change Event to occur if a new song is played.
Supported Sources: Local Media Servers, Playlists, History, Rhapsody Tracks, Deezer Tracks, iHeartRadio Tracks, Napster, Tidal, SoundCloud, Amazon Music. Please note Amazon Music tracks are played without adding to HEOS queue. 4.4.13 Get HEOS Playlists Refer to Browse Sources and Browse Source Containers 4.4.
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.
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. The actual response will depend on the service options available for a given source type.
6 - Remove Album from Library Supported Services: Napster 7 - Remove Station from Library heos://browse/set_service_option? sid=2&option=6&cid=LIBALBUM-Alb. 174684186 cid - album id obtained through 'browse source containers' command heos://browse/set_service_option? sid=2&option=7&mid=sas.6513639 mid - station id obtained through 'browse source containers' command heos://browse/set_service_option? sid=2&option=8&cid=LIBPLAYLIST-mp.
Response: { "heos": { "command": " browse/set_service_option", "result": "success", "message": "sid=source_id&option=option_id&mid=media_id" } } Example: heos://browse/set_service_option?sid=2&option=1&mid=Tra.174684187 5. Change Events (Unsolicited Responses) 5.1 Sources Changed Response: { "heos": { "command": "event/sources_changed", } } 5.2 Players Changed Response: { "heos": { "command": "event/players_changed", } } 5.3 Group Changed Response: { "heos": { "command": "event/groups_changed", } } 5.
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.7 Player Playback Error Response: { "heos": { "command": " event/player_playback_error", "message": "pid=player_id&error=Could Not Download" } } Note: error string represents error type. Controller can directly display the error string to the user. 5.
"message": "pid=’player_id’&shuffle='on_or_off'” } } 5.12 Group Volume Changed Response: { "heos": { "command": "event/group_volume_changed ", "message": "gid='group_id'&level='vol_level'&mute='on_or_off'" } } 5.13 User Changed Response: { "heos": { "command": "event/user_changed", "message": "signed_out" or "signed_in&un=" } } 6.0 Error Codes 6.
Popular system errors are: -9: Indicates that the action was sent to the remote service, but the remote service returned an error response -1061: The user has not registered this service -1063: The user is not logged in -1056: User not found -1201: General content services authentication error -1232: Content services user authorization error -1239: User account related parameters are invalid Processing Previous Command 13 Processing previous command Media can't be played 14 cannot play Option no suppo