Yamaha MusicCast

This driver was written using the Yamaha YXC Protocol. It controls all MusicCast enabled devices, including standalone speakers, soundbars and receivers. The driver only works via ethernet.

As of version 1.21 of this driver, 'Selected' variables will only be available when enabled in the configuration. If you are using selected variables and update the driver, you MUST enable them in the driver configuration.

Release History

1.0: The initial release of the driver

1.1: Adds tuner support (read the Tuner section below as the current API has incomplete/incorrect support for handling preset status). It also adds support for the 'Pure Direct' On and Off commands and adds a list of NetUSB only inputs to the regular input list so you can create a scrolling list of streaming inputs.

1.11: Adds a command for setting volume by percentage. Adds using the internal names of the inputs rather than a generic name. Changing input name in the MusicCast app will change the name in the source variables and the source lists,

1.12: Fixes DAB tuner variable reporting (and Tuner Stereo reporting)

1.13: Adds Link Audio Delay commands (see below) and variables, adds 'Actual Volume' variables to show the same value as the device front panel

1.14: Fixes a problem where selecting a streaming source always changes the main zone.

1.15: Changes the way names are created and displayed as the devices are added so that auto-programming works correctly. Fixes a problem displaying certain non-standard and non-English characters (the Bublé Bug)

1.16: Fixes a problem with the discrete HDMI command for Soundbars -- HDMI vs HDMI1

1.17: Defaults to 'Recall' mode when Presets are triggered by macros.

1.18: Fixes a problem where the boolean Link Client variables weren't working.

1.19: Adds the Audio 5 input available in newer models. Fixes an issue using Coax 2.

1.20: Adds commands for Sound Programs, Commands and a variable for Surround Modes, and support for Surround: AI.

1.21: Disables 'selected' variables by default to reduce the variable load on the system file. Adds extra error checking in the connection management to recover from disconnects.

1.22: Adds Amazon Music as a source, adds variables and events to handle the 'Conflicted Error" discussed below. Adds a language setting to the configuration that allows the streaming service menus to be displayed in the chosen language, if supported by the service.

1.23: Adds cursor and menu commands to control the on-screen GUI of the device. Correctly recognizes presets from DAB tuners and allows them to be accessed. Fixes a problem choosing NetUSB specific inputs

1.24: adds Scenes (with names for v2 network boards), adds party mode

2.0: Restructured driver to include Selected Zones, fixes to linking, and allow for easier programming of zone 2,3, or 4 of recievers. Added Audio Select commands, and some additional Sound Program selections.

2.01: Fixes issue that was causing the driver to lockup when connected to specific receivers.

2.1: Adds support for image lists.

2.2: Fixed issue with player linking

2.21: Fixes issue with group volume commands

2.22: Fixes issues with play/stop driver events. Adds new pause event.

Device Types

Because the driver supports multi-zone receivers it contains three types of sources. First is Zones, which contain all the audio functionality of the system: power, volume, sound fields, source selection, etc. Secondly, Network/USB is the media player portion of the devices with transport control, browsing, presets, etc. Thirdly is the Tuner, which has its own set of functions and variables and its own pages. All zones in a multi-zone device use the same player and tuner. The USB source uses the Music Player device type in your template but will default to a device type called MusicCast if your template contains one.

Note: When setting up your devices in the project you have to use the Network/USB and Tuner sources with numbers that corrispond to the 'main' configured device. If you try to set up "Zone 4" to use "Tuner 3" it will not work. You must always use the Parent zone's Tuner or Network/USB sources.

Configuration

MusicCast sources and MusicCast Zones are added separately to your project. Because you can add a different number of zones than you can players, but you can't have a player without a zone, the total number of devices in the system are determined by the number of zones, and the device configuration information is entered into the Zone sources. Users of Integration Designer version earlier than 10.0 will always have to add the Device Count.

Entering the device name in the configuration will allow that name to show up when selecting variables and commands for that device. There is a variable that allows you to use that name on your panel (Config Name) but most likely you will use the variable for the actual device name (Player Name) that the driver gets from the device itself.

You then select whether this is a 'main' zone or a 2nd, 3rd, or 44th zone, MOST devices are considered 'main' zones. When you select a 2nd,3rd, or 4th zone from the drop down another field opens up to pick which Zone source is the parent, this parent MUST be a 'main' zone source. When adding 2nd,3rd or 4th zones to the project you must use Zone sources with numbers larger then the parent, if the parent is defined after the secondary zones the driver will fail at initialization.

You must enter an IP address for the device into the configuration if the device is a 'main' zone. This will require you to use either a static IP address or to have your router reserve a specific DHCP address for the device.

Differing MusicCast models have different resolution in their volume control. The driver can get that information from the device, but you need to know that information so that you can have ID set any gauges or sliders to the correct ranges (although they can always be edited later). There are commands that allow you to treat the volume as a range from 0 to 100 and that works fine with sliders but doing that with volume up/down buttons while showing volume as an integer can cause scaling problems as not every volume change command causes a change in the displayed value, even though it does change the actual system volume. In addition, although the device can find the range of the volume control, it can’t find the actual numbers used, or whether it uses half dB steps. Because of this the range for most receivers is 0 to 161 instead of the -80 to 16 they show on the front panel. If you need to find the range of the volume control or other controls such as subwoofer, tone control etc. you can access the device from your browser at: Error! Hyperlink reference not valid. to get this information. Look down towards the end for information marked as “range-step”

New with version 1.13:

Yamaha has added an 'Actual Volume' notification to the protocol. This allows you to create a variable (tagged: Volume Text) that shows a string matching the volume value as it appears on the front of the device. This requires the mid-May 2018 firmware

Transport (including visibility)

Transport controls are part of the NetUSB device and include revered state and visibility variables. You can program visibility so that only the transport commands available in the current service are displayed. A classic example is that skipping backwards is not available in Pandora, so the system can be programmed to hide the button when on that service. Integration Designer does not autoprogram visibility, so it will have to be added manually. This is especially important for stop and pause buttons as most broadcast type services such as SiriusXM don’t support a pause command so it’s a good idea to only leave the stop button showing.

Source Selection

Zones are also responsible for the source selection, even if it’s a streaming source. There are discrete commands for every possible input for every zone even though some of the combinations are obviously not possible. Once again, the device can find the available sources for a room and, in fact, the list variables that allows you to select sources for a room do adjust to only show available sources but if you use discrete commands you’ll be responsible for knowing which inputs/sources can be used is a specific zone of a device.

NOTE: Soundbars and other devices that have a single HDMI input use the HDMI parameter for the source selection command, not HDMI1

Volume Control

As mentioned earlier the volume range can be different on each device. You have the option of showing volume using the native resolution/values of the device or as a 0-100 value. There is (as of driver version 1.13) a variable called 'Volume Text' that will show the volume, with decimal point, just as it appears on the front of the device.

If you use the Group Volume command the driver will send the command to every other player in the group as well. It is recommended that the Group volume commands be used even if there is no group. It will just change the one device if it's not linked, but when there is a group it will adjust all of them. You can create a separate page if you want to adjust the balance in a group using the regular volume commands.

EQ/Tone/Subwoofer

Tone controls also can have a range that varies from device to device, and in fact, they can be unavailable in some devices. The URL mentioned under volume in the Configuration section can also show the range for tone control/eq and other controls. Any gauges tend to get programmed with -12 to 12 as their range, you may have to change this manually.

Browsing

Every MusicCast device keeps its own set of browsing lists. When you enter your account information it must be entered into each device. The devices themselves can have multiple accounts for some services and switch between them but this is not available in the API yet. The MusicCast API describes each entry in the list as something it can enter, like a folder, or something it can play. The Browse Mode can be changed on a panel by panel basis so that if you select a folder in ‘Select’ mode it will enter that folder and list its content. Selecting it in Play mode should play the folder. These commands are in the API but do not work yet. I’ve left them in as they are supposed to work and subsequent firmware updates may enable it but as of now there is no need for these commands as they don’t alter how the menu works.

The overall source menu does not drill down to the top menu of the service, they are separate lists. You can use the source list and then switch to the browse list and it will reflect the source most recently picked, or you can use separate discrete commands to select the source while jumping to a browse page with the browse list on it.

NetUSB Presets

Each player has 40 presets which store predefined sources. A set of modes for presets is defined as well. The action taken by the driver when selecting from the preset list depends on the current mode of the panel. Recall, or Play, starts playback of the selected preset. Store replaces the current preset with the currently playing item. Clear removes the preset at the current location.

The Presets list will always have 40 items in it, even if they are empty, so you have access to any empty preset you want to fill.

There are also commands to directly access presets to allow you to make a page with direct buttons, as well as variables that can be used to label those buttons with the titles and services for that preset

The preset mode, whether it's Recall, Store, Clear, or Move, is a panel-based setting, meaning it only applies to the device on which the mode button was pressed. If you're sending a command from a macro, it will always be in the play mode.

Recent

The Recent list is like the Presets list but is added to with every change in source. A Clear Recents command allows the end user to clear the list and start saving them again.

Scenes

Receivers support a varying number of scenes. These scenes are zone specific so there is a zone parameter when you trigger them. Current devices allow you to name the scenes when you create them so variables are available, early MusicCast devices will not have distinctive names. These names are only loaded on startup, the receiver does not update them.

Events

The players send driver events whenever they leave or enter play mode, or just when the currently playing song title changes. There are also events for zone audio events: Power or Mute on or off and source changes for any zone on the device. Each zone has its own set of these events, so you can distinguish where it happened.

Linking

Linking commands allow you to link any device to any other, with ‘selected’ devices able to be either the target or the master of the link. Variables include boolean variables to show the relationship between any two devices as well as an overall status that tells when a device is the master or client of a group. Unfortunately, unlinking from a group leaves the device using ‘MCLink’ as its source and the device saying it’s still a client. For it to show that it’s not a client a new source has to be selected.

Party Mode
The receivers may have a Party Mode that gets turned on for the whole receiver. You cannot turn on Party Mode in a specific zone, even though the zones have their own Party Variables. This powers up all the zones in the receiver and locks them to the main’s input choices. When in Party Mode there is a separate command for volume control (up and down only) as well as mute. Toggle commands for Party Mute and Party Enable use the status of the main zone as a reference on whether to go on or off.

Link Audio Delay
The Link Audio Delay allows you to adjust the amount of audio buffered by the system. While keeping extra audio in a memory buffer helps the system play smoothly while keeping multiple devices in sync, it allows causes delays when used for audio that is supposed to be in sync with a picture. When using an HDMI input the device can be set to 'Lip Sync' which will reduce the buffer and play the audio in sync with the picture. When just playing audio, the system can be set to 'Audio Sync' for fewer dropouts and better sync between multiple payers. Older versions of the devices used 'Audio Sync On' and Audio Sync Off' instead. All are supported in the driver. The same link used in volume above will tell you which set your player uses.

Tuner
Tuner control consists of commands to both step and scan through the frequency range. In addition, there are 40 presets for the tuner that follow the same 'mode' changing rules mentioned above in the NetUSB presets section. These presets can be accessed from a scrolling list, directly by number, or using commands that rotate through the next or previous presets. If using direct access, there are variables that allow you to label the preset buttons with their current values.

In addition, you can create commands to directly change the frequency or band of the tuner to a desired value.

NOTE: There are some issues in the handling of tuner presets in the current MusicCast. The current firmware does not keep track of changes to the actual frequency of the tuner and use it to update the current preset. On the front panel of the receiver you'll see the preset number when a preset is selected, and it will go away if the frequency changes. The driver can't do this as it continues to get reports from the tuner that it is still on the preset.

Amazon Music

Driver version 1.22 adds support for Amazon Music as a source but it requires some special care. Amazon only allows one stream at a time, so the MusiCast system warns if there is already a stream playing by raising a 'Device Conflicted' error. If you don't allow a way for a user to see, and then clear that error, they can be stuck at what is essentially a modal dialog.

The conflict will generate a Conflict Error event which you can use to change pages, it also changes the Conflicted Source variable, which can be used to make a response option visible. To clear this error you can execute either the 'Cancel Attempt' or the 'Continue Attempt' commands; cancel simply clears the flag, where continue will begin the stream, causing the existing system to eventually stop playing.

The truth is that the system does not lock up waiting for the response. You can simply make a different choice and the system will switch to it. The flag will get cleared any time a new tune begins (The title changes), so you can simply ignore it. You can even not handle the event, but the user will be able to make a selection, which the device won't play, and they won't know why.

Language Support
The language of the menu system can be changed in the driver configuration in ID. The supported languages are:
English
Japanese
French
German
Spanish
Russian
Italy
Chinese

These language choices depend on the streaming services support of the localized menu.

Templates
The driver contains three different 'sources'. The zone doesn't have a template attached to it as there is generally not a specific page for a zone. The two audio sources each use their own templates if available but will default to standard template device types:

Tuner looks for a device type (page set) called 'MusicCast Tuner' but will default to the standard AM/FM template
Network/USB looks for a page set called MusicCast but will default to the standard Music Player pages.