Marantz AV8805 HEOS CLI PROTOCOL Specification
Marantz AV8805 Manual
 |
View all Marantz AV8805 manuals
Add to My Manuals
Save this manual to your list of manuals |
Marantz AV8805 manual content summary:
- Marantz AV8805 | HEOS CLI PROTOCOL Specification - 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. - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 2
General Error Response 6.2 Error Code description Version HEOS Version 1.0 1.280.96 Modifications Initial release. 1.1 1.304.61 Add set service option command. 1.2 1.310.170 Remove support for play url. Special characters ('&,'=', and '%') are encoded. 1.3 1.331.70 Add reboot command - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 3
09/21/2016 Prakash Remove unused change events: Mortha source_data_changed, group_changed, player_mute_changed, group_mute_changed 1.8 1.397.190 Add support for Juke music service Add support for adding station to HEOS Favorites from browse menu 04/12/2017 Prakash Mortha Expand Thumbs Up - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 4
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 until the controller is restarted. Ex: Adding or removing music services to HEOS user account, through HEOS app will not reflect in - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 5
, PlayPrevious Play, Pause, Stop, PlayNext, PlayPrevious NA Play, Pause, Stop, PlayNext, PlayPrevious *Depending on playing service NA NA Play, Pause, Stop, PlayNext, PlayPrevious Supported Transport Controls in HEOS App (No significance. Only for Reference) Play, Pause, PlayNext, PlayPrevious Play - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 6
. This usually occurs during browse/search as CLI needs to retrieve data from remote media server or online service. { "heos": { "command": "'command_group'/'command'", "result": "'success'", "message": "command under process'" } } JSON command response delimiter is "\r\n". Note: Special characters - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 7
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 - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 8
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": " - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 9
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 lineout LineOut level type 1 - variable 2 - Fixed control Only valid when lintout level type is Fixed - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 10
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 wired wifi lineout LineOut level type 1 - - Marantz AV8805 | HEOS CLI PROTOCOL Specification - 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 AV8805 | HEOS CLI PROTOCOL Specification - Page 12
"heos": { "command": "player/get_now_playing_media", "result": "success", "message": "pid='player_id'" }, "payload": { "type" : "'station'", "song": "'song name'", "station": "'station name'", "album": "'album name'", "artist": "'artist name'", "image_url": "'image url'", "mid": "'media id'", "qid": - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 13
} } Example: heos://player/set_volume?pid=2&level=30 4.2.8 Volume Up Command: heos://player/volume_up?pid=player_id&step=step_level Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A step Player volume step level 1 to 10(default 5) Response - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 14
"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 - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 15
} } Example: hoes://player/get_play_mode?pid=1 4.2.14 Set Play Mode Command: heos://player/set_play_mode?pid='player_id'&repeat=on_all_or_on_one_or_off&shuffle=on_or_off Attribute Description Enumeration pid Player id returned by 'get_players' or 'get_groups' command N/A repeat Player repeat - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 16
" image_url": "''image_url 2'", "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'" } ] - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 17
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": { - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 18
": " 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 AV8805 | HEOS CLI PROTOCOL Specification - Page 19
": "player/play_quickselect", "result": "success", "message": "pid=player_id&id=" Example: heos://player/play_quickselect?pid=1&id=2 Currently supported HEOS products: LEGO AVR, HEOS BAR 4.2.25 Get QuickSelects [LS AVR Only] Command: heos://player/get_quickselects?pid=player_id - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 20
{ "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 - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 21
. . . { "name": "player name N", "pid": "'player id N'", "role": "player role N (leader or member Example: heos://group/get_groups 4.3.2 Get Group Info Command: heos://group/get_group_info?gid=group_id Attribute Description Enumeration gid Group id returned by 'get_groups' command N/A - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 22
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. Ex: heos://group/set_group?pid=3 Command: heos - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 23
gid level Group id returned by 'get_groups' command N/A Group volume level 0 to 100 Response: { "heos": { "command": "group/set_volume ", "result": "success", "message": "gid='group_id'&level='vol_level'" } } Example: heos://group/set_volume?gid=1&level=30 4.2.6 Group Volume Up Command: heos:// - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 24
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.9 Set Group Mute Command: heos://group/ - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 25
Response: { "heos": { "command": "browse/get_music_sources", "result": "success", "message": "" }, "payload": [ { "name": "source name 1", "image_url": "source logo url 1", "type": "source type 1", "sid": source_id_1 }, { "name": "source name 2", "image_url": "source logo url 2", "type": "source - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 26
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 27
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 28
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 29
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 30
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 31
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 32
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 33
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 34
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 35
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 heos://browse/add_to_queue?pid=1&sid=5&cid=Artist/All&aid=2 Supported Sources: Playable containers from Local Media Servers, Playlists, - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 36
-> 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 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 - Marantz AV8805 | HEOS CLI PROTOCOL Specification - Page 37
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 38
"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 AV8805 | HEOS CLI PROTOCOL Specification - Page 39
?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 AV8805 | HEOS CLI PROTOCOL Specification - Page 40
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 41
&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 AV8805 | HEOS CLI PROTOCOL Specification - Page 42
{ "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 AV8805 | HEOS CLI PROTOCOL Specification - Page 43
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 AV8805 | HEOS CLI PROTOCOL Specification - Page 44
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
-
1 -
2 -
3 -
4 -
5 -
6 -
7 -
8
-
9
-
10
-
11
-
12
-
13
-
14
-
15
-
16
-
17
-
18
-
19
-
20
-
21
-
22
-
23
-
24
-
25
-
26
-
27
-
28
-
29
-
30
-
31
-
32
-
33
-
34
-
35
-
36
-
37
-
38
-
39
-
40
-
41
-
42
-
43
-
44
 |
 |
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.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
Limitations for the system when used multi devices.