Yamaha MusicCast (YXC)

Local LAN integration with Yamaha AV receivers and MusicCast streaming amplifiers via the Yamaha Extended Control (YXC) HTTP API. The driver enumerates the receiver's available zones and inputs, polls each configured zone for power / volume / mute / input changes, and exposes per-zone power, volume, mute, input-routing, and basic transport commands.

Compatible with most current-generation Yamaha gear:

• RX-V / Aventage AV receivers (RX-V4A, RX-V6A, RX-A2A, RX-A4A, RX-A6A, RX-A8A, …)
• WXA-50 / WXC-50 / WXA-50 streaming amplifiers
• MusicCast 20 / MusicCast 50 / MusicCast 200 wireless speakers (single zone)
• MusicCast Sub 100 / Bar 40 / Bar 400 sound bars

Prerequisites

• Receiver / amp on the same LAN as GEM, with a static IP or DHCP reservation.
• Network Standby enabled in the receiver setup (Setup → Network → Network Standby → On). Without this the receiver disappears from the LAN when powered off and the driver will mark it disconnected.
• (Optional) The MusicCast mobile app paired with the device, if you want to route to authenticated streaming inputs (Spotify, TIDAL, etc.).

Setup steps

1. Create a device in GEM with driver yamaha_musiccast.
2. Set the ip attribute to the receiver IP. Leave port at the default 80.
3. Save. On connect the driver:
   • calls GET /YamahaExtendedControl/v1/system/getDeviceInfo to verify reachability and log the model name
   • calls GET /YamahaExtendedControl/v1/system/getFeatures to cache the supported zones and inputs
   • starts polling each configured GEM zone's getStatus endpoint on status_interval (default 5s)
4. Run the get_features command on the device to print the zone names and input ids supported by this specific model. Volume scale (max_volume) is also returned per zone.
5. For each receiver zone you want to control, create a GEM zone with address set to one of: main, zone2, zone3, zone4 (only the zones your model supports).
6. Use set_input with input ids from get_features (e.g. hdmi1, tuner, spotify, net_radio, bluetooth) to route sources.

Attributes

Device — required

Attribute	Type	Description
ip	string	LAN IP of the Yamaha receiver / MusicCast device.

Device — optional

Attribute	Type	Default	Description
port	int	80	YXC HTTP port. Almost always 80.
status_interval	int (ms)	5000	Polling cadence per zone. Lower values feel snappier but increase LAN chatter.

Zone

• Address required: yes.
• Address format: main, zone2, zone3, or zone4. Run get_features to see which zones this model exposes.

The driver writes the following attributes onto each polled zone as state changes are observed:

Attribute	Type	Source
state	string	on when the receiver zone power is on, off when in standby.
volume	integer	Raw YXC volume value (model-specific scale).
mute	boolean	Mute state.
input	string	Active input id.

Commands

System

Command	Args	Description
get_device_info	–	Model name, firmware version, system id.
get_features	–	Available zones, inputs, sound programs, max volume per zone. Run this first when adding a new receiver.
get_status	address	Full zone status payload.

Zone power & volume

Command	Args	Description
on	address	Power the zone on.
off	address	Put the zone in standby.
toggle	address	Toggle zone power.
set_volume	address, level	Set raw volume. Range is model-specific — check getFeatures.zone[].max_volume.
volume_up	address, step?	Step volume up (default step 1).
volume_down	address, step?	Step volume down (default step 1).
mute	address	Mute zone.
unmute	address	Unmute zone.

Source routing & DSP

Command	Args	Description
set_input	address, input	Switch the zone input. Use ids from get_features (e.g. hdmi1, tuner, spotify, net_radio).
set_sound_program	address, program	Switch DSP / sound program (e.g. straight, stereo, surround_decoder).

Streaming transport (netusb)

Command	Description
play	Resume playback.
pause	Pause playback.
stop	Stop playback.
next_track	Skip to next track.
previous_track	Go to previous track.

Transport commands act on the device's current MusicCast playback session and apply across whichever zone is consuming netusb.

Known limitations

• YXC events — YXC supports server-push event notifications via UDP unicast to a registered listener. This driver currently uses HTTP polling only. Event subscription is a future enhancement (would lower latency and LAN chatter).
• MusicCast room / link grouping — The driver does not yet wrap dist/setServerInfo / dist/setClientInfo for whole-house link audio. You can still trigger groups from the MusicCast app.
• Authenticated streaming inputs — set_input can route to spotify, net_radio, etc., but the driver cannot sign the receiver into those services. Pair the MusicCast app first.
• Tuner presets — Not exposed yet. Use set_input to switch to tuner then control via the front panel or remote.

Troubleshooting

Symptom	Check
Receiver unreachable when off	Enable Network Standby in Setup → Network.
set_volume rejected or clamped silently	Run get_features and read zone[].max_volume. RX-V models commonly cap at 161; streaming amps at 60.
set_input fails	Run get_features and use an input id from system.input_list[]. Names are model-specific (hdmi1 vs av1).
Zone stuck in off after powering on from front panel	Check that GEM zone address matches the receiver zone exactly (main, zone2, …). The driver only polls zones with addresses it recognizes.
Frequent log noise about HTTP errors	Increase status_interval if the receiver / network is slow. Default 5s is comfortable on wired LAN.