Yamaha Extended Control API Specification (Advanced)

Yamaha Extended Control

API Specification (Advanced)

Rev. 1.00

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 1 of 21

Yamaha Extended Control API Specification (Advanced)

Contents

1. Preface ................................................................................................................................................ 3
2. Definitions .......................................................................................................................................... 3
3. API Overview ..................................................................................................................................... 4
4. Zone .................................................................................................................................................... 5
4.1. setLinkControl ........................................................................................................................ 5
4.2. setLinkAudioDelay ................................................................................................................. 5
5. Distribution (Link) ............................................................................................................................ 6
5.1. getDistributionInfo ................................................................................................................. 6
5.2. setServerInfo ........................................................................................................................... 7
5.3. setClientInfo............................................................................................................................ 8
5.4. startDistribution ..................................................................................................................... 8
5.5. stopDistribution ...................................................................................................................... 9
5.6. setGroupName ........................................................................................................................ 9
6. Response Code List .......................................................................................................................... 10
7. All ID List......................................................................................................................................... 10
8. MusicCast Network Initial Setup................................................................................................... 12
9. Application Notes ............................................................................................................................ 13
9.1. Link Function........................................................................................................................ 13
9.1.1. Making a Group ................................................................................................................ 13
9.1.2. Removing a client from the Group ................................................................................... 15
9.1.3. Adding a client to the Group ............................................................................................ 16
9.1.4. Making multi Groups........................................................................................................ 17
9.1.5. External causes/interruptions making a break of a Group ........................................... 19
9.1.6. Note to making Group ...................................................................................................... 19

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 2 of 21

Yamaha Extended Control API Specification (Advanced)

1. Preface

This document describes specifications of API of Yamaha Extended Control (YXC, hereafter) for
Yamaha A/V products. YXC is Yamaha’s new communication protocol sent over Ethernet and Wi-Fi
to control MusicCast enabled devices. This document describes only advanced function (Link etc.).
Basic function is described in Yamaha Extended Control API Specification(Basic)..

2. Definitions

 MusicCast
A function to share music easily among audio devices in multiple rooms at homes
 MusicCast Device(s)
All products/devices that are equipped with MusicCast functions
 MusicCast Network
A communication network on which MusicCast Devices join.
 By multiple MusicCast Devices communicating each other on the same network
(=MusicCast Network), all MusicCast devices can be operated using MusicCast App/YXC
 Location
A unit of MusicCast Network being comprised. Location is expressed as Location ID made up
by 32 characters
 Max number of MusicCast Devices within 1 Location is up to 10
 Link
A function to share an audio stream among rooms
 Link Master Room
A master room an audio distribution comes from
 Link Client Room(s)
Client room(s) a music track to be distributed from Link Master Room
 Linked Rooms
All rooms being linked including master and clients, or a Group
 Linked Room
A room of linked client room(s)
 Group
All lined rooms including master and clients, or Linked Rooms
 Device
Equal to MusicCast Device
 Room
A minimum component MusicCast devices can be shown/associated within a MusicCast
network
 Main Zone Sync
A function to input the same source as Main Zone to Zone 2/3.

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 3 of 21

Yamaha Extended Control API Specification (Advanced)

3. API Overview

 Request Parameters
Parameter information to inquire. Parameters stated as "required = yes" have always to be
specified as one of inquiring parameters, while parameters marked as "required = no" can be
omitted or need to be used in special cases
 Response Parameters
Parameter information to be returned in the body of response (in JSON object format). Not all
parameters listed here are always to be returned in a response, depending on each device
specs/functions/setup situations. “response_code” is always returned
 Note: JSON format data expressions in this document get well formatted for readability,
but actual data don’t include spaces, intends and carriage return/line feeds
 Base URL
"<BaseURL>" shown in URI is http://{host}/YamahaExtendedControl
 {host} is an IP address of a Device to get controlled
 API version
Values like “v1” or “v2” specified in URI shows a corresponding API version number. Backward
compatibility of APIs always being assured unless specified, all APIs that have equal to or
smaller API version number(s) that can be read via “getDeviceInfo” are supported on a Device
 Data size of a sting
In case a string is specified with its data size, it is a size before JSON escape process

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 4 of 21

Yamaha Extended Control API Specification (Advanced)

4. Zone

4.1. setLinkControl

For setting Link Control in each Zone.

Request Parameters
name type required description
zone string yes Specifies target zone. Available for zones with this function
Values: "main" / "zone2" / "zone3" / "zone4"
control string yes Specifies Link Control setting
Values: Values gotten via /system/getFeatures

URI <BaseURL>/v1/<zone>/setLinkControl?control=<control>
Method GET
Example Request http://{host}/YamahaExtendedControl/v1/main/setLinkControl?control=normal

Response Parameters
name type description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details

Example Response {
"response_code":0
}

4.2. setLinkAudioDelay

For setting Link Audio Delay in each Zone. This setting is invalid when Link Control setting is "
Stability Boost ".

Request Parameters
name type required description
zone string yes Specifies target zone. Available for zones with this function
Values: "main" / "zone2" / "zone3" / "zone4"
delay string yes Specifies Link Audio Delay setting
Values: Values gotten via /system/getFeatures

URI <BaseURL>/v1/<zone>/setLinkAudioDelay?delay=<delay>
Method GET
Example Request http://{host}/YamahaExtendedControl/v1/main/setLinkAudioDelay?delay=lip_sync

Response Parameters
name type description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 5 of 21

Yamaha Extended Control API Specification (Advanced)

Example Response {
"response_code":0
}

5. Distribution (Link)

APIs in regard to Link distribution related setting and getting information

5.1. getDistributionInfo

For retrieving a Device information related to Link distribution

Request Parameters
URI <BaseURL>/v1/dist/getDistributionInfo
Method GET
Example Request http://{host}/YamahaExtendedControl/v1/dist/getDistributionInfo

Response Parameters
name type Description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details
group_id string Returns Group ID in 32-digit hex
group_name string Returns Group Name
role string Returns a role of Link distribution
Values: "server" / "client" / "none"
server_zone string Returns target Zone ID that can work as a client of distributing server. If
there’s no parameter of this, “main” is implicitly chosen.
Values: "main" / "zone2" / "zone3" / "zone4"
client_list array Returns registered client IP address list
Valid only when the role is "server"
|- ip_address string Returns clients’ IP Address
|- data_type string Returns a type of distributed data
Values: "base" / "ext"

Example Response {
"response_code":0,
"group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"group_name":"[Link] Living Room",
"role":"server",
"server_zone":"main",
"client_list":[
{
"ip_address":"192.168.0.5",
"data_type":"base"
},
{
"ip_address":"192.168.0.11",

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 6 of 21

Yamaha Extended Control API Specification (Advanced)

"data_type":"base"
},
{
"ip_address":"192.168.0.22,
"data_type":"ext"
}
]
}

5.2. setServerInfo

For setting a Link distribution server (Link master)

Request Parameters
Name type required description
group_id string yes Specify Group ID in 32-digit hex.
Specify "" (empty text) here to cancel a Device being the Link
distribution server. Group ID will be initialized ("000...")
after the cancel operation
Zone string no Specifies which target Zone ID to be the Link distribution
server. If nothing is specified, current setting is kept. Zone
ID to be the Link distribution server is confirmable using
system/getFeatures server_zone_list.
Values: "main" / "zone2" / "zone3" / "zone4"
Type string no Specifies a type of adding or removing clients. Not necessary
to specify when canceling the Link master status,
Values: "add" / "remove"
client_list string array no Specifies IP addresses of adding/removing clients. Specifiable
up to 9 clients

URI <BaseURL>/v1/dist/setServerInfo
Method POST
Example Request http://{host}/YamahaExtendedControl/v1/dist/setServerInfo
(URI)
Example Request {
(json) "group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":"main",
"type":"add",
"client_list":[
"192.168.0.5",
"192.168.0.11"
]
}

Response Parameters
name type description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 7 of 21

Yamaha Extended Control API Specification (Advanced)

Example Response {
"response_code":0
}

5.3. setClientInfo

For setting Link distributed clients. If a Device is already setup as Link distribution server, this
client setup is denied by that Device: use this API after canceling a Device’s Link distribution
server setup using setServerInfo, then confirming that the target Device’s role is changed to other
values than “server” using getDistributionInfo.

Request Parameters
name type required description
group_id string yes Specifies Group ID in 32-digit hex.
Specify "" (empty text) here to cancel a Device being a Link
distributed client. Group ID will be initialized ("000...") after
the cancel operation
zone string array no Specifies which target Zone ID to be a Link distributed
client. Not necessary to specify when cancelling a client
status.
Values: "main" / "zone2" / "zone3" / "zone4"
server_ip_address string no Specifies the IP Address of the Link distribution server

URI <BaseURL>/v1/dist/setClientInfo
Method POST
Example Request http://{host}/YamahaExtendedControl/v1/dist/setClientInfo
(URI)
Example Request {
(json) "group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":[
"main",
"zone2"
]
}

Response Parameters
name type description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details

Example Response {
"response_code":0
}

5.4. startDistribution

For initiating Link distribution. This is valid to a Device that is setup as Link distribution server.

Request Parameters
Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 8 of 21
Yamaha Extended Control API Specification (Advanced)

name type required description

num integer yes Specifies Link distribution number on current MusicCast Network

URI <BaseURL>/v1/dist/startDistribution?num=<num>
Method GET
Example Request http://{host}/YamahaExtendedControl/v1/dist/startDistribution?num=2

Response Parameters
name type description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details

Example Response {
"response_code":0
}

5.5. stopDistribution

For quitting Link distribution. This is valid to a Device that is setup as Link distribution server.

Request Parameters
URI <BaseURL>/v1/dist/stopDistribution
Method GET
Example Request http://{host}/YamahaExtendedControl/v1/dist/stopDistribution

Response Parameters
name type description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details

Example Response {
"response_code":0
}

5.6. setGroupName

For setting up Group Name. Note that Group Name is reserved in volatile memory

Request Parameters
name type required description
name string yes Specifies Group Name. Use UTF-8 within 128 bytes. Default name
would be used if it’s not setup or "" (empty text) is specified

URI <BaseURL>/v1/dist/setGroupName
Method POST
Example Request http://{host}/YamahaExtendedControl/v1/dist/setGroupName
(URI)
Example Request {

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 9 of 21

Yamaha Extended Control API Specification (Advanced)

(json) "name":"[Link] Living Room"

}

Response Parameters
name type description
response_code integer 0: Successful request / Others: Error
Refer to “Response Code List” for details

Example Response {
"response_code":0
}

6. Response Code List

In a response contains one of Response Codes listed below. No other data is included to a response if
its response code was other than '0' (Successful request)

code description
0 Successful request
1 Initializing
2 Internal Error
3 Invalid Request (A method did not exist, a method wasn’t appropriate etc.)
4 Invalid Parameter (Out of range, invalid characters etc.)
5 Guarded (Unable to setup in current status etc.)
6 Time Out
99 Firmware Updating
(100s are Streaming Service related errors)
100 Access Error
101 Other Errors
102 Wrong User Name
103 Wrong Password
104 Account Expired
105 Account Disconnected/Gone Off/Shut Down
106 Account Number Reached to the Limit
107 Server Maintenance
108 Invalid Account
109 License Error
110 Read Only Mode
111 Max Stations
112 Access Denied

7. All ID List

Type ID
Zone main / zone2 / zone3 / zone4

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 10 of 21

Yamaha Extended Control API Specification (Advanced)

※Zone A is handles as "main”, Zone B is handles as "zone2"

Input cd / tuner / multi_ch / phono / hdmi1 / hdmi2 / hdmi3 / hdmi4 / hdmi5 / hdmi6 / hdmi7 /
hdmi8 / hdmi / av1 / av2 / av3 / av4 / av5 / av6 / av7 / v_aux / aux1 / aux2 / aux / audio1 /
audio2 / audio3 / audio4 / audio_cd / audio / optical1 / optical2 / optical / coaxial1 / coaxial2 /
coaxial / digital1 / digital2 / digital / line1 / line2 / line3 / line_cd / analog / tv / bd_dvd /
usb_dac / usb / bluetooth / server / net_radio / rhapsody / napster / pandora / siriusxm /
spotify / juke / airplay / radiko / qobuz / mc_link / main_sync / none
Sound Program munich_a / munich_b / munich / frankfurt / stuttgart / vienna / amsterdam / usa_a / usa_b /
tokyo / freiburg / royaumont / chamber / concert / village_gate / village_vanguard /
warehouse_loft / cellar_club / jazz_club / roxy_theatre / bottom_line / arena / sports /
action_game / roleplaying_game / game / music_video / music / recital_opera / pavilion /
disco / standard / spectacle / sci-fi / adventure / drama / talk_show / tv_program /
mono_movie / movie / enhanced / 2ch_stereo / 5ch_stereo / 7ch_stereo / 9ch_stereo /
11ch_stereo / stereo / surr_decoder / my_surround / target / straight / off

Note: Rhapsody service name will be changed to Napster. Accordingly, rhapsody input ID is changed
to napster input ID.

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 11 of 21

Yamaha Extended Control API Specification (Advanced)

8. MusicCast Network Initial Setup

Initial Setup means to let a MusicCast Device join to MusicCast Network. It can be done only
though MusicCast CONTROLLER app. To do so, download and install the free app of MusicCast
CONTROLLER to mobile devices (smart phones, tablets)
 AppStore
(US)
https://itunes.apple.com/us/app/musiccast-controller-us/id1002730190
(Outside US)
https://itunes.apple.com/jp/app/musiccast-controller/id1012248381

GooglePlay
https://play.google.com/store/apps/details?id=com.yamaha.av.musiccastcontroller

1. Launch the app

Choose “Setup” when it’s launched. When you setup 2nd or more MusicCast devices, choose
“Add New Device” in the setup menu of the app.
2. Turn on the power of MusicCast Device being setup.
3. Press and hold “CONNECT” button on a MusicCast Device for more than 5 seconds
4. Choose or type in Location Name
5. Choose or type in Room Name
6. Choose a Room Image

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 12 of 21

Yamaha Extended Control API Specification (Advanced)

9. Application Notes

9.1. Link Function

Here explains how to use MusicCast Link function with YXC commands.
Assume that MusicCast Network initial setup is already done and MusicCast Network is
established as following.

9.1.1. Making a Group

Here shows how to make a Group. This is trying to establish a distribution network with Device
B being a master, and with Device A and Device C being clients.

1. Create a random Group ID (16 byte).

2. Setup all clients with the Group ID and target Zone being used by “setClientInfo”.

Request (URI)
http://{Device A}/ YamahaExtendedControl/v1/dist/setClientInfo

Request (json)
{
"group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":[
"main"
]
}
Response
{
"response_code":0
}

Request (URI)
http://{Device C}/ YamahaExtendedControl/v1/dist/setClientInfo

Request (json)
{
"group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":[
"main"

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 13 of 21

Yamaha Extended Control API Specification (Advanced)

]
}
Response
{
"response_code":0
}

3. Setup the master with GroupID and client list by “setServerInfo (add)”.

Request (URI)
http://{Device B}/ YamahaExtendedControl/v1/dist/setServerInfo

Request (json)
{
"group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":"main",
"type":"add",
"client_list":[
"192.168.0.5", Device A IP address
"192.168.0.6"
] Device C IP address
}
Response
{
"response_code":0
}

4. Start distribution with setting current all system distribution number to the master by
“startDistribution”.

Request (URI)
http://{Device B}/ YamahaExtendedControl/v1/dist/startDistribution?num=0

Response
{
"response_code":0
}

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 14 of 21

Yamaha Extended Control API Specification (Advanced)

9.1.2. Removing a client from the Group

Here shows how to remove DeviceC from the Group

1. Clear GourpID and target Zone of the removing client(s) by “setClientInfo”.

*Set Group ID with empty text ””.
Request (URI)
http://{Device C}/ YamahaExtendedControl/v1/dist/setClientInfo

Request (json)
{
"group_id":"",
"zone":[
"main"
]
}
Response
{
"response_code":0
}

2. Setup the master with GroupID and removing client list by “setServerInfo (remove)”.
*If all clients are to be remove, set empty text ”” to GroupID in setServerInfo
Request (URI)
http://{Device B}/ YamahaExtendedControl/v1/dist/setServerInfo

Request (json)
{
"group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":"main",
"type":"remove",
"client_list":[
"192.168.0.6" Device C IP address
]
}
Response
{
"response_code":0
}

3. Reflect current all system distribution number to the master by “startDistribution”.

Request (URI)
http://{Device B}/ YamahaExtendedControl/v1/dist/startDistribution?num=2

Response
{
"response_code":0
}

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 15 of 21

Yamaha Extended Control API Specification (Advanced)

9.1.3. Adding a client to the Group

Here shows how to add DeviceC to the Group.
1. Setup GourpID and target Zone of the adding client(s) by “setClientInfo”.
Request (URI)
http://{Device C}/ YamahaExtendedControl/v1/dist/setClientInfo

Request (json)
{
"group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":[
"main"
]
}
Response
{
"response_code":0
}

2. Setup the master with GroupID and adding client list by “setServerInfo (add)”.
Request (URI)
http://{Device B}/ YamahaExtendedControl/v1/dist/setServerInfo

Request (json)
{
"group_id":"9A237BF5AB80ED3C7251DFF49825CA42",
"zone":"main",
"type":"add",
"client_list":[
"192.168.0.6" Device C IP address
]
}
Response
{
"response_code":0
}

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 16 of 21

Yamaha Extended Control API Specification (Advanced)

3. Reflect all system distribution number to the master by “startDistribution”.

Request (URI)
http://{Device B}/ YamahaExtendedControl/v1/dist/startDistribution?num=1

Response
{
"response_code":0
}

9.1.4. Making multi Groups

Here shows how to make multi Groups.
Assume that MusicCast Network initial setup is already done and MusicCast Network is
established as following.

Follow 13.2.1(Making a Group), establish a distribution network with Device B being a master,
and with Device A and Device C being clients.

Group ID: 9A237BF5AB80ED3C7251DFF49825CA42

Next is trying to establish a distribution network with Device D being a master, and with
Device E being clients.

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 17 of 21

Yamaha Extended Control API Specification (Advanced)

1. Create a random Group ID (16 byte).

＊Note not set the same Group ID

2. Setup all clients with the Group ID and target Zone being used by “setClientInfo”.

Request (URI)
http://{Device E}/ YamahaExtendedControl/v1/dist/setClientInfo

Request (json)
{
"group_id":"7B335AE4C12345677251DAA466669B40",
"zone":[
"main"
]
}
Response
{
"response_code":0
}

3. Setup the master with GroupID and client list by “setServerInfo (add)”.

Request (URI)
http://{Device D}/ YamahaExtendedControl/v1/dist/setServerInfo

Request (json)
{
"group_id":"7B335AE4C12345677251DAA466669B40",
"zone":"main",
"type":"add",
"client_list":[
"192.168.0.8" Device E IP address
]
}
Response
{
"response_code":0
}

4. Start distribution with setting current all system distribution number to the master by
“startDistribution”.Already establish a distribution network with Device B being a master,
and with Device A and Device C being clients, need to set num = 2.

Request (URI)
http://{Device B}/ YamahaExtendedControl/v1/dist/startDistribution?num=2

Response
{
"response_code":0

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 18 of 21

Yamaha Extended Control API Specification (Advanced)

9.1.5. External causes/interruptions making a break of a Group

If things shown below happen, it is necessary for a Group to be properly handled as mentioned
below (mostly by removing client(s) from the master. Refer to 13.2.2, procedure #2);

1. In case a Device’s input is selected to others than MusicCast Link

- If a Device is the master, nothing matters
- If a Deice is a client, it needs to be removed from the Group, meaning:
・Remove the client from the master
・Clear the Group ID in the client
2. In case a Device is assigned to the other Group for some reason
- If a Device is the master, all client(s) assigned to it need to be removed from the Group
- If a Device is a client, it needs to be removed from the master

9.1.6. Note to making Group

1. In case of Multi Zone Receiver, each Zone unable to join discrete separate groups.

× ×
Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 19 of 21
Yamaha Extended Control API Specification (Advanced)

2. Zone A or B but not both is not being the Client.

○ × ×

3. Each Zone unable to be set Master and Client in same group.

× × ×
Available to make pseudo-Group that Main Zone is Master and Zone2 or Zone3
equipped Main Zone Sync feature is Client. In this case, no network distribution among
Master and Client.

4. Group can be made between devices have different Location ID. Max number of MusicCast
Devices within 1 Group is up to 10.

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 20 of 21

Yamaha Extended Control API Specification (Advanced)

Revision History

Rev. Date Contents Author

1.00 9/28/2016 First edition Eto

Copyright  2016 Yamaha Corporation, ALL rights reserved. Page 21 of 21