Summary

MusicCast device controlled via Yamaha Extended Control API (YXC) over Ethernet/WiFi. HTTP transport with JSON payloads. Supports multi-zone power, volume, input routing, sound program selection, tuner, Net/USB playback, and CD. Authentication requirements are UNRESOLVED. Events are delivered via UDP unicast; the source gives 41100 as an example MusicCast Controller event port, not as a default.

Transport

protocols:
  - http
addressing:
  base_url: http://{host}/YamahaExtendedControl  # {host} = device IP address
auth:
  type: UNRESOLVED

Traits

- powerable
- routable
- queryable
- levelable

Actions

- id: setPower
  label: Set Power
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone (main / zone2 / zone3 / zone4)
    - name: power
      type: string
      description: Power state (on / standby / toggle)

- id: setVolume
  label: Set Volume
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone (main / zone2 / zone3 / zone4)
    - name: volume
      type: integer
      description: Volume value (range from getFeatures); on API version 1.17 and later, "up" or "down" is also supported
    - name: step
      type: integer
      required: false
      description: Step value if volume is "up" or "down"; on API version 1.17 and later

- id: setMute
  label: Set Mute
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone
    - name: enable
      type: boolean
      description: Mute state

- id: setInput
  label: Select Input
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone
    - name: input
      type: string
      description: Input ID from getFeatures
    - name: mode
      type: string
      required: false
      description: Select mode (autoplay_disabled; available on API version 1.12 and later)

- id: setSoundProgram
  label: Set Sound Program
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone
    - name: program
      type: string
      description: Sound program ID from getFeatures

- id: setSleep
  label: Set Sleep Timer
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone
    - name: sleep
      type: integer
      description: Sleep time in minutes (0 / 30 / 60 / 90 / 120)

- id: prepareInputChange
  label: Prepare Input Change
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone
    - name: input
      type: string
      description: Input ID from getFeatures

- id: setAutoPowerStandby
  label: Set Auto Power Standby
  kind: action
  params:
    - name: enable
      type: boolean
      description: Enable/disable auto power standby

- id: sendIrCode
  label: Send IR Code
  kind: action
  params:
    - name: code
      type: string
      description: IR code in 8-digit hex

- id: setFreq
  label: Set Tuner Frequency
  kind: action
  params:
    - name: band
      type: string
      description: Band (am / fm)
    - name: tuning
      type: string
      description: Tuning method (up / down / cancel / auto_up / auto_down / tp_up / tp_down / direct); tp_up and tp_down are for RDS band
    - name: num
      type: integer
      required: false
      description: Frequency in kHz (valid only when tuning=direct)

- id: recallPreset
  label: Recall Tuner Preset
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone
    - name: band
      type: string
      description: Preset type from getFeatures (common for band-common presets / separate for per-band presets). The source example uses band=fm; its compatibility with the documented values is UNRESOLVED.
    - name: num
      type: integer
      description: Preset number from getFeatures

- id: storePreset
  label: Store Tuner Preset
  kind: action
  params:
    - name: num
      type: integer
      description: Preset number from getFeatures

- id: switchPreset
  label: Switch Tuner Preset
  kind: action
  params:
    - name: dir
      type: string
      description: Direction (next / previous); available on API version 1.17 and later

- id: setDabService
  label: Set DAB Service
  kind: action
  params:
    - name: dir
      type: string
      description: Direction (next / previous)

- id: netusb_setPlayback
  label: Set Net/USB Playback
  kind: action
  params:
    - name: playback
      type: string
      description: Playback command (play / stop / pause / play_pause / previous / next / fast_reverse_start / fast_reverse_end / fast_forward_start / fast_forward_end)

- id: netusb_toggleRepeat
  label: Toggle Net/USB Repeat
  kind: action

- id: netusb_toggleShuffle
  label: Toggle Net/USB Shuffle
  kind: action

- id: netusb_recallPreset
  label: Recall Net/USB Preset
  kind: action
  params:
    - name: zone
      type: string
      description: Target zone
    - name: num
      type: integer
      description: Preset number from getFeatures

- id: netusb_storePreset
  label: Store Net/USB Preset
  kind: action
  params:
    - name: num
      type: integer
      description: Preset number from getFeatures

- id: setListControl
  label: Set List Control
  kind: action
  params:
    - name: list_id
      type: string
      required: false
      description: List ID (main / auto_complete / search_artist / search_track); defaults to main if omitted
    - name: type
      type: string
      description: Control type (select / play / return)
    - name: index
      type: integer
      required: false
      description: Element position in list; required when type is select or play
    - name: zone
      type: string
      required: false
      description: Target zone for playback; defaults to main if omitted

- id: setSearchString
  label: Set Search String
  kind: action
  params:
    - name: list_id
      type: string
      required: false
      description: List ID (main / auto_complete / search_artist / search_track); defaults to main if omitted
    - name: string
      type: string
      description: Search text
    - name: index
      type: integer
      required: false
      description: Element index; valid only with list_id=main

- id: cd_setPlayback
  label: Set CD Playback
  kind: action
  params:
    - name: playback
      type: string
      description: Playback command (play / stop / pause / previous / next / fast_reverse_start / fast_reverse_end / fast_forward_start / fast_forward_end / track_select)
    - name: num
      type: integer
      required: false
      description: Track number (valid only when playback=track_select)

- id: cd_toggleTray
  label: Toggle CD Tray
  kind: action

- id: cd_toggleRepeat
  label: Toggle CD Repeat
  kind: action

- id: cd_toggleShuffle
  label: Toggle CD Shuffle
  kind: action

- id: switchAccount
  label: Switch Account
  kind: action
  params:
    - name: input
      type: string
      description: Target Input ID (pandora)
    - name: index
      type: integer
      description: Switch account index (0 ~ 7)
    - name: timeout
      type: integer
      description: Timeout duration in ms (0`～`60000); 0 treats as maximum value

Feedbacks

- id: getDeviceInfo
  query_command: /v1/system/getDeviceInfo
  type: object
  description: Retrieve basic device info (model name, API version, network module version, etc.)

- id: getFeatures
  query_command: /v1/system/getFeatures
  type: object
  description: Retrieve feature info (func_list, zone info, input list, range_step values, sound programs, tuner/netusb capabilities)

- id: getNetworkStatus
  query_command: /v1/system/getNetworkStatus
  type: object
  description: Retrieve network setup/information (connection type, DHCP, IP address, MAC address, MusicCast network status)

- id: getFuncStatus
  query_command: /v1/system/getFuncStatus
  type: object
  description: Retrieve overall system function status (auto power standby, IR sensor, speakers, headphone, dimmer)

- id: getLocationInfo
  query_command: /v1/system/getLocationInfo
  type: object
  description: Retrieve Location info (ID, name, zone list, stereo pair status)

- id: zone_getStatus
  query_command: /v1/<zone>/getStatus
  type: object
  description: Retrieve zone status (power, sleep, volume, mute, input, sound_program, tone_control, equalizer, balance, subwoofer_volume, etc.)
  params:
    - name: zone
      type: string
      description: Target zone (main / zone2 / zone3 / zone4)

- id: getSoundProgramList
  query_command: /v1/<zone>/getSoundProgramList
  type: array
  description: Retrieve list of available sound programs for a zone

- id: tuner_getPresetInfo
  query_command: /v1/tuner/getPresetInfo?band=<band>
  type: object
  description: Retrieve tuner preset info
  params:
    - name: band
      type: string
      description: Band (common / separate; source example also uses fm, compatibility unresolved)

- id: tuner_getPlayInfo
  query_command: /v1/tuner/getPlayInfo
  type: object
  description: Retrieve tuner playback info (band, frequency, RDS, DAB info)

- id: netusb_getPresetInfo
  query_command: /v1/netusb/getPresetInfo
  type: object
  description: Retrieve Net/USB preset info

- id: netusb_getPlayInfo
  query_command: /v1/netusb/getPlayInfo
  type: object
  description: Retrieve Net/USB playback info (input, playback state, repeat, shuffle, play_time, artist, album, track, albumart_url)

- id: netusb_getListInfo
  query_command: /v1/netusb/getListInfo?input=<input>&index=<index>&size=<size>&lang=<lang>
  type: object
  description: Retrieve Net/USB list info (menu_layer, max_line, list_info with text, thumbnail, attribute)
  params:
    - name: input
      type: string
      description: Target input
    - name: index
      type: integer
      description: Reference index (must be multiple of 8)
    - name: size
      type: integer
      description: Max list size (1-8)
    - name: lang
      type: string
      required: false
      description: Language (en / ja / fr / de / es / ru / it / zh); defaults to en if omitted

- id: netusb_getAccountStatus
  query_command: /v1/netusb/getAccountStatus
  type: object
  description: Retrieve streaming service account info (registered status, login status, trial time left)

- id: netusb_getServiceInfo
  query_command: /v1/netusb/getServiceInfo?input=<input>&type=<type>&timeout=<timeout>
  type: object
  description: Retrieve streaming service info (account_list / licensing / activation_code)

- id: cd_getPlayInfo
  query_command: /v1/cd/getPlayInfo
  type: object
  description: Retrieve CD playback info (device_status, playback, repeat, shuffle, play_time, track_number, total_tracks, artist, album, track)

- id: response_code
  type: integer
  values: [0, 1, 2, 3, 4, 5, 6, 99, 100-112]
  description: |
    Standard response codes:
    0 = success, 1 = initializing, 2 = internal error, 3 = invalid request,
    4 = invalid parameter, 5 = guarded, 6 = timeout, 99 = firmware updating,
    100s = streaming service errors (100=access error, 103=wrong password, 104=account expired, etc.)

Variables

# All settable parameters via GET/POST are documented in Actions and Feedbacks.
# Tunable variables (from zone getStatus responses):
- id: volume
  type: integer
  description: Zone volume (range from getFeatures, e.g. 0-194)

- id: tone_control
  type: object
  description: Tone control settings (bass, treble)

- id: equalizer
  type: object
  description: Equalizer settings (mode, low, mid, high)

- id: balance
  type: integer
  description: Speaker L/R balance (negative=left, positive=right)

- id: dialogue_level
  type: integer
  description: Dialogue level setting

- id: dialogue_lift
  type: integer
  description: Dialogue lift setting

- id: subwoofer_volume
  type: integer
  description: Subwoofer volume

- id: bass_extension
  type: boolean
  description: Bass extension status

- id: link_control
  type: string
  description: Link control setting (standard / stability / speed)

- id: link_audio_delay
  type: string
  description: Link audio delay setting (lip_sync / audio_sync / audio_sync_on / audio_sync_off)

- id: dimmer
  type: integer
  description: Dimmer setting (-1=auto, 0+=manual)

- id: sleep
  type: integer
  description: Sleep timer in minutes (0/30/60/90/120)

- id: auto_power_standby
  type: boolean
  description: Auto power standby enabled/disabled

- id: sound_program
  type: string
  description: Selected sound program

- id: repeat
  type: string
  description: Repeat setting (off / one / all / folder / program)

- id: shuffle
  type: string
  description: Shuffle setting (off / on / songs / albums / folder)

Events

# UDP unicast events (X-AppName + X-AppPort headers are required; 41100 is shown as the MusicCast Controller example port, not a documented default)
# Event notifications time out after 10 minutes of inactivity.

- id: system_event
  type: object
  description: System events
  fields:
    - bluetooth_info_updated: boolean
    - func_status_updated: boolean
    - location_info_updated: boolean
    - name_text_updated: boolean

- id: main_zone_event
  type: object
  description: Main zone events
  fields:
    - power: string (on/standby)
    - input: string
    - volume: integer
    - mute: boolean
    - status_updated: boolean

- id: tuner_event
  type: object
  description: Tuner events
  fields:
    - play_info_updated: boolean
    - preset_info_updated: boolean

- id: netusb_event
  type: object
  description: Net/USB events
  fields:
    - play_error: integer
    - play_message: string
    - account_updated: boolean
    - play_time: integer
    - preset_info_updated: boolean
    - play_info_updated: boolean
    - list_info_updated: boolean
    - preset_control: object (type, num, result)

- id: cd_event
  type: object
  description: CD events
  fields:
    - device_status: string (open/close/ready/not_ready)
    - play_time: integer
    - play_info_updated: boolean

- id: dist_event
  type: object
  description: Link distribution events
  fields:
    - dist_info_updated: boolean

- id: device_id_event
  type: string
  description: Device ID (available on API v1.17+)

Macros

# Multi-step sequences from source (Section 12):

- id: browse_and_play_usb
  label: Browse USB and Play File
  description: |
    1. send prepareInputChange (input=usb)
    2. optionally send setInput (input=usb, mode=autoplay_disabled)
    3. send getListInfo (input=usb, index=0, size=8) to get root list
    4. send setListControl (list_id=main, type=select, index=N) to navigate into folder
    5. repeat getListInfo with index=0/8/16... to get all pages
    6. send setListControl (list_id=main, type=play, index=N) to play target file
  note: getListInfo blocks all other commands for up to 30 seconds while fetching full list

- id: search_and_play_pandora
  label: Search and Play Pandora
  description: |
    1. send setSearchString (list_id=search_artist or search_track, string="query")
    2. send setListControl (list_id=search_artist/search_track, type=select, index=N) to select result
    3. send setListControl (list_id=main, type=play, index=N) to start playback

Safety

confirmation_required_for: []
interlocks:
  - description: Zone B (physical) maps to zone2 in YXC protocol
  - description: Input change to USB requires prepareInputChange before browsing
  - description: getListInfo command blocks all other commands for up to 30 seconds
# UNRESOLVED: no explicit safety warnings or interlock procedures in source

Notes

Base URL pattern: http://{host}/YamahaExtendedControl/v1/

Event transport: UDP unicast. The app must send X-AppName: MusicCast/XXX and X-AppPort: YYY in request headers to receive events. The source's MusicCast Controller example uses event port 41100; no default event port is documented. Events time out after 10 minutes without another request from the registered device.

API versioning: v1 in URI. Backward compatibility is assured for API versions up to the current API version, which can be read via getDeviceInfo. API version 1.17 is required for the device_id field and switchPreset.

Device discovery: via UPnP M-Search, identify manufacturer="Yamaha Corporation", check for yamaha:X_device tag, confirm yamaha:X_yxcControlURL = /YamahaExtendedControl/v1/

Response codes: 0=success, 1=initializing, 2=internal error, 3=invalid request, 4=invalid parameter, 5=guarded, 6=timeout, 99=firmware updating. 100s = streaming errors.

Port number: UNRESOLVED: no explicit HTTP port is stated in the source. URLBase example uses port 80 but does not document it as a default.

Provenance

source_domains:
  - raw.githubusercontent.com
  - github.com
source_urls:
  - https://raw.githubusercontent.com/rsc-dev/pyamaha/master/doc/YXC_API_Spec_Basic.pdf
  - https://github.com/opctim/yamaha-extended-control-openapi
retrieved_at: 2026-05-19T04:51:05.122Z
last_checked_at: 2026-10-07T17:16:13.411Z

Verification Summary

verdict: verified
checked_at: 2026-10-07T17:16:13.411Z
matched_actions: 41
action_count: 41
confidence: medium
summary: "All 41 action units match YXC endpoints in the source, the base URL is supported, auth is honestly UNRESOLVED, and every documented endpoint is represented. (5 unresolved item(s) noted in Known Gaps.)"

Known Gaps

- "TrueX-90A model not explicitly named in source; inferred from Convex entity bootstrap"
- "no explicit safety warnings or interlock procedures in source"
- "no explicit HTTP port is stated in the source. URLBase example uses port 80 but does not document it as a default."
- "firmware compatibility range not stated"
- "HTTP port is not explicitly stated; port 80 appears only in a URLBase example"
- "source applicability inferred: the manufacturer protocol document names no model; commands verified against it but not confirmed for this exact model"

From the AI4AV catalog (https://ai4av.net) · ODbL-1.0