Protocol Specs

ManualsBrandsDenon ManualsAV receivers9.2-channel home theater receiver with Wi-Fi® and Dolby Atmos®

Table Of Contents

HEOS CLI Protocol Specification

HEOS CLI Protocol Specification
Overview
1 Supported music services
Connection
1 Controller Design Guidelines
1.1 Driver Initialization
1.2 Caveats
1.2.1 Compatibility
1.2.2 Issues & Solutions
1.3 Miscellaneous
Command and Response Overview
1 Commands
2 Responses
Command and Response Details
1 System Commands
1.1 Register for Change Events
1.2 HEOS Account Check
1.3 HEOS Account Sign In
1.4 HEOS Account Sign Out
1.5 HEOS System Heart Beat
1.6 HEOS Speaker Reboot
1.7 Prettify JSON response
2 Player Commands
2.1 Get Players
2.2 Get Player Info
2.3 Get Play State
2.4 Set Play State
2.5 Get Now Playing Media
2.6 Get Volume
2.7 Set Volume
2.8 Volume Up
2.9 Volume Down
2.10 Get Mute
2.11 Set Mute
2.12 Toggle Mute
2.13 Get Play Mode
2.14 Set Play Mode
2.15 Get Queue
2.16 Play Queue Item
2.17 Remove Item(s) from Queue
2.18 Save Queue as Playlist
2.19 Clear Queue
2.20 Play Next
2.21 Play Previous
3 Group Commands
3.1 Get Groups
3.2 Get Group Info
3.3 Set Group
3.4 Get Group Volume
3.5 Set Group Volume
2.6 Group Volume Up
2.7 Group Volume Down
3.8 Get Group Mute
3.9 Set Group Mute
3.10 Toggle Group Mute
4 Browse Commands
4.1 Get Music Sources
4.2 Get Source Info
4.3 Browse Source
4.4 Browse Source Containers
4.5 Get Source Search Criteria
4.6 Search
4.7 Play Station
4.8 Play Preset Station
4.9 Play Input source
Limitations for the system when used multi devices.
4.10 Add Container to Queue with Options
4.11 Add Track to Queue with Options
4.12 Get HEOS Playlists
4.13 Rename HEOS Playlist

Summary of content (41 pages)

PAGE 1
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.
PAGE 2
4.4.14 Delete HEOS Playlist 4.4.15 Get HEOS History 4.4.16 Retrieve Album Metadata 4.4.17 Get Service Options for now playing screen - OBSOLETE 4.4.18 Set service option 5. Change Events (Unsolicited Responses) 5.1 Sources Changed 5.2 Players Changed 5.3 Group Changed 5.4 Source Data Changed 5.5 Player State Changed 5.6 Player Now Playing Changed 5.7 Player Now Playing Progress 5.8 Player Playback Error 5.9 Player Queue Changed 5.10 Player Volume Changed 5.11 Player Mute Changed 5.
PAGE 3
1. Overview The Denon HEOS is a network connected, wireless, multi-room music system. The HEOS Command Line Interface (CLI) allows external control systems to manage, browse, play, and get status from the Denon HEOS products. The HEOS CLI is accessed through a telnet connection between the HEOS product and the control system. The control system sends commands and receives responses over the network connection. The CLI commands and responses are in human readable (ascii) format.
PAGE 4
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.
PAGE 5
Favorites Playlists History AUX Input 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 Play, Stop Play, Stop song NA NA 3. Command and Response Overview 3.
PAGE 6
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. Please refer to "Driver Initialization" section regarding when to register for change events.
PAGE 7
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.
PAGE 8
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). 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.
PAGE 9
] } Example: heos://player/get_players 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.
PAGE 10
Example: heos://player/get_playe_state?pid=1 4.2.4 Set Play State 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 4.2.
PAGE 11
The following response provides example when the speaker is playing a station.
PAGE 12
"command": " player/ set_volume ", "result": "success", "message": "pid='player_id'&level='vol_level'" } } Example: heos://player/set_volume?pid=2&level=30 4.2.
PAGE 13
"result": "success", "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.
PAGE 14
"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.
PAGE 15
"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.
PAGE 16
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.
PAGE 17
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.3 Group Commands 4.3.
PAGE 18
. { "name": "player name N", "pid": "'player id N'", "role": "player role N (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)'" }, . . .
PAGE 19
. . . { "name": "player name N", "pid": "'player id N'", "role": "player role N (leader or member)'" } ] } } 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.
PAGE 20
Attribute Description Enumeration gid Group id returned by 'get_groups' command N/A Response: { "heos": { "command": "group/get_volume ", "result": "success", "message": "gid='group_id'&level='vol_level'" } } Example: heos://group/get_volume?gid=1 4.3.
PAGE 21
Attribute Description Enumeration gid Group id returned by 'get_groups' command N/A level Group volume step level 1 to 10(default 5) 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.
PAGE 22
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.
PAGE 23
4.4.
PAGE 24
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 either 50 or 100 records per response. The default maximum number of records depend on the service type. range starts from 0 NOTE: Range in Browse source command is only supported while browsing Favorites This command is used under two scenarios. Browsing actual media sources of type 'heos_server' and 'heos_service'.
PAGE 25
"command": "browse/browse", "result": "success", "message": "sid=source_id&returned=items_in_current_response&count=total_items_available" }, "payload": [ { "container": "yes", "playable": "no", "type": "artist", "name": "'artist name'", "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'" }, { "
PAGE 26
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 either 50 or 100 records per response. The default maximum number of records depend on the service type. range starts from 0 count Total number of items available in the container. NOTE: count value of '0' indicates unknown container size. Controllers needs to query until the return payload is empty (returned attribute is 0).
PAGE 27
"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": "no", "playable": "yes", "type": "station", "name": "'station name'", "image_url": "'station url'", "mid": "'me
PAGE 28
{ "heos": { "command": "browse/ get_search_criteria ", "result": "success", "message": "sid='source_id " }, "payload": [ { "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: h
PAGE 29
end#'&returned=items_in_current_response&count='total_items_available" }, "payload": [ { "container": "yes", "playable": "no", "type": "artist", "name": "'artist name'", "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
PAGE 30
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.
PAGE 31
input input source name Note: Validity of Inputs depends on the type of source HEOS device "inputs/aux_in_1" "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" "inputs/game" "inputs/mediaplayer" "inputs/cd" "inputs/tun
PAGE 32
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.
PAGE 33
name String for new playlist name limited to 128 unicode characters N/A Response: { "heos": { "command": "browse/rename_playlist ", "result": "success", "message": "sid='source_id'&cid='contaiiner_id'&name='playlist_name'" } } Example: heos://browse/rename_playlist?sid=11&cid=234&name=new name 4.4.
PAGE 34
"payload": [ { "album_id": "album_id", "images": [ { "image_url": "URL to image file", "width": current image width }, . . . { "image_url": " URL to image file", "width": current image width } ] } ] } Example: heos://browse/retrieve_metadata?sid=2&cid=Alb.184664171 4.4.17 Get Service Options for now playing screen - OBSOLETE Obsolete - Now get_now_playing_media command will include supported option for currently playing media.
PAGE 35
Example: heos://browse/get_service_options?sid=5 4.4.18 Set service option Set service option is a generic command used to select any of the supported service options provided through 'Get Service Options for now playing screen', 'Browse Sources' and 'Browse Source Containers' command response. Following service options are currently supported: Option id Example Command Parameter description 1 - Add Track to Library (Rhapsody) heos://browse/set_service_option?sid=2&option=1&mid=Tra.
PAGE 36
7 - Remove Station from Library (Rhapsody) heos://browse/set_service_option?sid=2&option=7&mid=sas.6513639 mid station id obtained through 'browse source containers' command 8 - Remove Playlist from Library (Rhapsody) heos://browse/set_service_option?sid=2&option=8&cid=LIBPLAYLIST-mp.
PAGE 37
13 - Create New Station by Tracks heos://browse/set_service_option?sid=7&option=13&name=Love&scid=3 name search string for creating new station through track Note: This command returns station ids. Controllers need to use 'play station' command to play a station.
PAGE 38
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.4 Source Data Changed Response: { "heos": { "command": "event/source_data_changed", "message": "sid='source_id'" } } 5.5 Player State Changed Response: { "heos": { "command": "event/player_state_changed", "message": "pid='player_id'&state='play_state'" } } 5.
PAGE 39
5.7 Player Now Playing Progress Response: { "heos": { "command": " event/player_now_playing_progress", "message": "pid=player_id&cur_pos=position_ms&duration=duration_ms" } } 5.8 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.
PAGE 40
"command": "event/repeat_mode_changed", "message": "pid=’player_id’&repeat='on_all_or_on_one_or_off'” } } 5.13 Player Shuffle Mode Changed Response: { "heos": { "command": "event/shuffle_mode_changed", "message": "pid=’player_id’&shuffle='on_or_off'” } } 5.14 Group Status Changed Response { "heos": { "command": "event/group_changed", "message": "gid='group_id'" } } 5.
PAGE 41
6.1 General Error Response Respone: { "heos": { "command": "'command_group'/'command'", "result": "'fail'", "message": "eid="error_id&text=error text& command_arguments'" } } 6.2 Error Code and Text Table 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.