Marantz NR1609 HEOS CLI ProtocolSpecification Version 1.11 02072018
Marantz NR1609 Manual
View all Marantz NR1609 manuals
Add to My Manuals
Save this manual to your list of manuals |
Marantz NR1609 manual content summary:
- Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 1
HEOS CLI Protocol Specification 1. Overview 1.1 Supported music services 2. Connection 2.1 Controller Design Guidelines 2.1.1 [LS AVR Only] 4.2.25 Get QuickSelects [LS AVR Only] 4.2.26 Check for Firmware Update 4.3 Group Commands 4.3.1 Get Groups 4.3.2 Get Group Info 4.3.3 Set Group 4.3.4 Get Group - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 2
Tidal/SoundCloud/Amazon Music Extend get_search_criteria to indicate if Play-All option is supported on searched tracks. Ability to create new station through Artist/Show/Track name Add service specific transport control option list 1.4 1.331.120 Bug fixes Documentation changes: Add transport - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 3
get_music_sources and get_source_info command reponses Add QQMusic to the supported music service list 1.442.150 Add new field value (unknown HEOS product and the control system. The control system sends commands and receives responses over the network connection. The CLI commands and responses are - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 4
service N/A 18 QQMusic No N//A No Following table list out other supported music sources through CLI. Source ID (sid) Source name Browse supported Search supported HEOS product IP address can also be set statically and manually programmed into the control system. Search target name (ST) in - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 5
using HEOS command arguments for special purpose. Maximum number of simultaneous socket connections supported by HEOS speaker is 32. Service specific transport control options are as follows: Services Amazon Music Deezer iHeart Radio Napster Pandora Rhapsody SoundCloud SiriusXM Tidal Tunein Juke - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 6
PlayPrevious *Depending on playing service NA NA Play, Pause, Stop, PlayNext, PlayPrevious *Depending on playing service Play, Pause, Stop, Most of the time, controllers use the same string that is received in previous command response. For example, while preparing 'play_stream'/'add_to_queue - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 7
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 - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 8
"command": "system/sign_in ", "result": "success", "message": "signed_in&un=" } } Example: heos://system/[email protected]&pw=12345 4.1.4 HEOS Account Sign Out Command: heos://system/sign_out Response: { "heos": { "command": "system/sign_out ", "result": "success", " - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 9
"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 - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 10
. { "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.2 Get Player Info - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 11
) Description Player id returned by 'get_players' or 'get_groups' command Options available for now playing media Enumeration N/A Following options are currently supported for now playing media 11 - Thumbs Up 12 - Thumbs Down 19 - Add station to HEOS Favorites Response: The following response - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 12
"heos": { "command": "player/get_now_playing_media", "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 - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 13
Example: heos://player/get_volume?pid=1 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": - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 14
Example: heos://player/volume_down?pid=2&step=5 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", " - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 15
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= - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 16
}, "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": - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 17
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= - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 18
pid sqid dqid Player id returned by 'get_players' or 'get_groups' command N/A List of comma separated queue_id's where each queue id for song is returned by 'get_queue' list item range:1 to size of command queue User select this value as the destination of contents which is indicated in sqid. - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 19
" 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.24 Play QuickSelect [LS AVR Only] Command: heos://player/play_quickselect?pid=player_id&id - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 20
pid=1 Currently supported HEOS products: LEGO AVR, HEOS BAR 4.2.26 Check for Firmware Update Command: heos://player/check_update?pid=player_id Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A update Indicates if firmware update is available - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 21
"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": - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 22
{ "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": - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 23
} } 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.4 Get Group Volume Command: heos://group/get_volume?gid= - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 24
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.7 Group Volume Down Command: heos://group/volume_down?gid=group_id&step=step_level Attribute Description Enumeration gid - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 25
should not be treated as the music service being supported through CLI or not. The services supported through CLI is listed in 'Supported music services' section. service_username Provides user name of the service account. Only avaialable for online music services when 'avaialble' field is set to - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 26
should not be treated as the music service being supported through CLI or not. The services supported through CLI is listed in 'Supported music services' section. service_username Provides user name of the service account. Only avaialable for online music services when 'avaialble' field is set to - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 27
of either 50 or 100 records per response. The default maximum number of records depend on the service type. Enumeration N/A Following options are currently supported for 'Browse Source' command 13 - Create New Station (Pandora, iHeartRadio) 20 - Remove from HEOS Favorites (Favorites) Possibilities - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 28
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. { "heos": { "command": "browse - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 29
HEOS Favorites" } ] } ] } Example: heos://browse/browse?sid=1346442495 Supported Sources: Local Media Servers, Playlists, History, Aux-In, Favorites, TuneIn, Pandora response. The default maximum number of records depend on the service type. count Total number of items available in the container. - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 30
for current browse level (options) 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. Possible options under browse menu are listed below: 1 - Add Track to Library 2 - Add - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 31
on searched tracks. yes or no cid Prefix to search string used while adding entire search results to play queue Currently supported prefix: Only valid when 'playable' is 'yes'. SEARCHED_TRACKS- Example command to play all tracked, searched with string 'earth': heos://browse/add_to_queue - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 32
128 unicode characters and may contain '*' for wildcard if supported by search criteria id scid Search criteria id returned 100 records per response. The default maximum number of records depend on the service type. returned Number of items returned in current response Enumeration N/A N/A artist - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 33
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.7 Play Station Command: heos://browse/play_stream - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 34
cid='container_id'&mid='media_id'&name='station_name'" } } Example: heos://browse/play_stream?pid=1&sid=2&cid='CID-55'&mid=15376&name=Q95 Supported Sources: History, Favorites, TuneIn, Pandora, Rhapsody, Deezer, SiriusXM, iHeartRadio, Napster, SoundCloud, Amazon Music, Juke 4.4.8 Play Preset Station - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 35
spid input 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 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" " - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 36
"pid='player_id'&sid='source_id'&cid='container_id'&aid='add_criteria'" } } Example: heos://browse/add_to_queue?pid=1&sid=5&cid=Artist/All&aid=2 Supported Sources: Playable containers from Local Media Servers, Playlists, History, Rhapsody, Deezer, iHeartRadio, Napster, Tidal, SoundCloud, Juke. Also - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 37
='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 - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 38
given album id. This command facilitates controllers to retrieve and update their UI with cover art, if image_url in browse/search ' command Comment Currently supported media sources are Rhapsody/Napster Rhapsody/Napster album ids Note: Supported music service is Rhapsody and Napster - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 39
"name": "Thumbs Down" } ] } ] } Example: heos://browse/get_service_options?sid=5 4.4.19 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 - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 40
?sid=2&option=8&cid=LIBPLAYLIST-mp.1860177 22 cid - playlist id obtained through 'browse source containers' command 11 - Thumbs Up Supported Services provide this option in Get Now Playing Media command response heos://browse/set_service_option?sid=1&option=11&pid=-409995282 pid - player id - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 41
provide this option in Get Now Playing Media command response 13 - Create New Station by Artists Supported Services:Pandora, iHeartRadio heos://browse/set_service_option?sid=1&option=12&pid=-409995282 heos://browse/set_service_option?sid=1&option=13&name=Love&scid=1 heos://browse/set_service_option - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 42
&mid=sas.6513639 mid - station id obtained through 'browse source' command on Favorites Note: Option 13 (Create New Station) supports optional range queries. Response: { "heos": { "command": " browse/set_service_option", "result": "success", "message": "sid=source_id&option=option_id&mid=media_id - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 43
{ "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 - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 44
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=' - Marantz NR1609 | HEOS CLI ProtocolSpecification Version 1.11 02072018 - Page 45
Error 12 System error&syserrno=-2 Processing Previous Command 13 Processing previous command Media can't be played 14 cannot play Option no supported 15 Option not supported Too many commands in message queue to process 16 Too many commands in queue Reached skip limit 17 Reached skip limit
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.6 HEOS Speaker Reboot
4.1.7 Prettify JSON response
4.2 Player Commands
4.2.1 Get Players
4.2.2 Get Player Info
4.2.3 Get Play State
4.2.4 Set Play State
4.2.5 Get Now Playing Media
4.2.6 Get Volume
4.2.7 Set Volume
4.2.8 Volume Up
4.2.9 Volume Down
4.2.10 Get Mute
4.2.11 Set Mute
4.2.12 Toggle Mute
4.2.13 Get Play Mode
4.2.14 Set Play Mode
4.2.15 Get Queue
4.2.16 Play Queue Item
4.2.17 Remove Item(s) from Queue
4.2.18 Save Queue as Playlist
4.2.19 Clear Queue
4.2.20 Move Queue
4.2.21 Play Next
4.2.22 Play Previous
4.2.23 Set QuickSelect [LS AVR Only]
4.2.24 Play QuickSelect [LS AVR Only]
4.2.25 Get QuickSelects [LS AVR Only]
4.2.26 Check for Firmware Update
4.3 Group Commands
4.3.1 Get Groups
4.3.2 Get Group Info
4.3.3 Set Group
4.3.4 Get Group Volume
4.3.5 Set Group Volume
4.2.6 Group Volume Up
4.2.7 Group Volume Down
4.3.8 Get Group Mute
4.3.9 Set Group Mute
4.3.10 Toggle Group Mute
4.4 Browse Commands
4.4.1 Get Music Sources
4.4.2 Get Source Info
4.4.3 Browse Source
4.4.4 Browse Source Containers
4.4.5 Get Source Search Criteria
4.4.6 Search
4.4.7 Play Station
4.4.8 Play Preset Station
4.4.9 Play Input source