HEOS CLI Protocol Specification - Denon

1 HEOS CLI Protocol Specification1. Supported music services2. Controller Design Driver Issues & Miscellaneous3. Command and Response Responses4. Command and Response System Register for Change HEOS Account HEOS Account Sign HEOS Account Sign HEOS System Heart HEOS Speaker Prettify JSON Player Get Get Player Get Play Set Play Get Now Playing Get Set Volume Volume Get Set Toggle Get Play Set Play Get Play Queue Remove Item(s) from Save Queue as Clear Move Play Play Set QuickSelect [LS AVR Only] Play QuickSelect [LS AVR Only] Get QuickSelects [LS AVR Only] Check for Firmware Group Get Get Group Set Get Group Set Group Group Volume Group Volume Get Group Set Group Toggle Group Browse Get Music Get Source Browse Browse Source Get Source Search Play Play Preset Play Input sourceLimitations for the system when used multi Play Add Container to Queue with Add Track to Queue with Get HEOS Rename HEOS Delete HEOS Get HEOS Retrieve Album Get Service Options for now playing screen - Set service option5.

2 Change Events (Unsolicited Responses) Sources Players Group Player State Player Now Playing Player Now Playing Player Playback Player Queue Player Volume Changed Player Repeat Mode Player Shuffle Mode Group Volume User Error General Error Error Code descriptionVersionHEOS set service option support for play url. Special characters ('&,'=', and '%') are reboot Tidal/SoundCloud/Amazon get_search_criteria to indicate if Play-All option is supported on searched to create new station through Artist/Show/Track service specific transport control option Prakash changes: Add transport control options for Amazon Issues: Range queries doesn't work on Amazon preset command to play stations from HEOS players network connection type in get_players and get_player_info command issue with range queries on Amazon issues and solutions section. Refer Issues & support for Rdio as it is limitations while using AVR inputs Source id for each Music service and unused change events:source_data_changed, group_changed, player_mute_changed, support for Juke music support for adding station to HEOS Favorites from browse Thumbs Up/Down option to more music services.

3 [LS AVR only] Add new commands set_quickselect, play_quickselect, and support to Play Url05/23/2017 Prakash check_update new response field 'serial' to get_players and get_player_info command new response fields 'available' and 'service_username' to get_music_sources and get_source_info command QQMusic to the supported music service new field value (unknown) to network connection on 'available' field in 'Get Music Sources' and 'Get Source Info' command more inputs05/14/2018 Prakash support for Juke Music service. Juke support is currently removed from option '21 - Playable Container' to support playable containers on Windows Media popular list of system "inputs/analog" from input source name for Play input source "inputs/analog_in_1", "inputs/analog_in_2" and "inputs/recorder_in_1" to input source name for Play input source Ishida1. OverviewThe 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.

4 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. The command is a text string and the responses are in JSON format. The commands and responses for browsing music servers and services use a RESTFUL like approach while other commands and responses are more Supported music servicesFollowing table list out all supported online music services through HEOS. Please note, currently not all services are supported through ID (sid)Service NameBrowse through CLIS earch/New station through CLI1 PandoraYesYes (Create New Station)2 RhapsodyYesYes3 TuneInYesYes4 SpotifyNoNo5 DeezerYesYes6 NapsterYesYes7iHeartRadioYesYes (Create New Station)8 Sirius XMYesNo9 SoundcloudYesYes10 TidalYesYes11 Future serviceN/AN/A12 RdioNot supported in HEOSNot supported in HEOS13 Amazon MusicYesNo14 Future serviceN/AN/A15 MoodmixNoNo16 JukeNot supported in HEOSNot supported in HEOS17 Future serviceN/AN//A18 QQMusicNoNo1.

5 2. 3. 4. Following table list out other supported music sources through ID (sid)Source nameBrowse supportedSearch supported1024 Local USB Media/ Local DLNA serversYesYes1025 HEOS PlaylistsYesNo1026 HEOS HistoryYesNo1027 HEOS aux inputsYesNo1028 HEOS FavoritesYesNo2. ConnectionThe 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. Search target name (ST) in M-SEARCH discovery request is 'urn:schemas- Denon -com:device:ACT- Denon : 1'.The control system should use various Get commands to determine the players and groups currently in the HEOS software can control all HEOS speakers in the network by establishing socket connection with just one HEOS speaker. It is recommended not to establish socket connection to each HEOS speaker.

6 This is to decrease network traffic caused by establishing socket connection to each HEOS speaker. Controller software can open multiple socket connections to the single HEOS speaker. Typically controllers will use one connection to listen for change events and one to handle user Controller Design Driver InitializationIn order to reduce number of UPnP devices running on the network, HEOS Speaker runs CLI module in a dormant mode. HEOS speaker spawns CLI core modules when the controller establishes the first socket connection to the speaker. What it all means for controller? Inability of CLI module to process player commands. This is because, by nature of UPnP, CLI module need some time to discover all players before they can be identified by their unique Id (pid)Spew of events when controller initially connects to the speaker. In order to avoid excessive event handling in a event driven controller system, the following initialization sequence is suggested:Un-register for change events.

7 By default speaker doesn't send unsolicited events but still it is a good idea to send un-register is done through 'register_for_change_events' user credentials are available, sign-in to HEOS user account. This is done through 'sign_in' current HEOS ecosystem status. This is done through commands like 'get_players', 'get_sources', 'get_groups', 'get_queue', 'get_now_playing_media', 'get_volume', 'get_play_state' for change events. This is done through 'register_for_change_events' controller design involves disconnect and reconnect to HEOS speakers through CLI, it is recommended to keep a idle connection to HEOS Speaker thus avoiding CLI module to set back to dormant CompatibilityPlease take a look at the following suggestions to avoid breaking controller code due to future enhancementsThe 'message' field part of HEOS response is a string. The attribute value pair in this message string is delimited by '&'. Further the attribute name and value is separated by '=' sign.

8 Please note that new arguments can be added in the JSON objects may be added to the 'payload' as part of future Issues & SolutionsChanges 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 : Controller needs to re sign-in to HEOS account to reflect changes made through HEOS app, with out restarting the controller. So, in addition to performing HEOS account sign-in as part of driver initialization process, it is highly recommended to provide sign-out and sign-in option through end users UI screen. End user need to re-signIn when he adds/removes music service through HEOS MiscellaneousControllers can add custom argument SEQUENCE=<number> 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.

9 Please let us know if you need additional custom argument other than 'SEQUENCE'. This is to avoid accidentally using HEOS command arguments for special number of simultaneous socket connections supported by HEOS speaker is specific transport control options are as follows:ServicesTypeSupported Transport Controls by CLIS upported Transport Controls in HEOS App (No significance. Only for Reference)Amazon MusicstationPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPrevioussongPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousDeezerstationPlay, Pause, Stop, PlayNextPlay, Pause, PlayNextsongPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousiHeart RadiostationPlay, StopPlay, Stop, ScansongPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousNapsterstationPlay, Pause, Stop, PlayNextPlay, Pause, PlayNextsongPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousPandorastationPlay, Pause, Stop, PlayNextPlay, Pause, PlayNextsongNANAR hapsodystationPlay, Pause, Stop, PlayNextPlay, Pause, PlayNextsongPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousSoundCloudstationNANA songPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousSiriusXMstationPlay, StopPlay, StopsongNANAT idalstationNANA songPlay, Pause, Stop.

10 PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousTuneinstationPlay, StopPlay, StopsongPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousLocal MusicstationNANA songPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousFavoritesstation*Depending on playing service*Depending on playing servicesongNANAP laylistsstationNANA songPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousHistorystation*Depending on playing service*Depending on playing servicesongPlay, Pause, Stop, PlayNext, PlayPreviousPlay, Pause, PlayNext, PlayPreviousAUX InputstationPlay, StopPlay, StopsongNANA3. Command and Response Overview CommandsHEOS CLI commands are in the following general format: heos://command_group/command?attribute1= value1&attribute2=value2&..&attributeN=v alueNCommand string delimiter is "\r\n".Note: Special characters, '&', '=', and '%' in attribute/value needs to be encoded to '%26(&)', '%3D(=)', and '%25(%)'.