Sony AV Receiver (Audio Control API)

Current Sony AV receivers — the STR-AZ1000ES / AZ3000ES / AZ5000ES / AZ7000ES ES line, the STR-ZA series and the STR-DN1080 — expose Sony's Audio Control API: JSON-RPC over plain HTTP on port 10000, with a websocket on the same port that pushes state changes. GEM talks to the receiver's own IP on the LAN; there is no gateway, no serial adapter and no login. One receiver is one GEM device, and the driver creates no zones of its own.

Once the IP is entered, GEM can power the main zone and Zone 2 / Zone 3 on and off, switch each zone's input, set and step volume, mute discretely, and pick the sound field. State comes back by push notification the moment someone touches the remote, with polling as the fallback, so touch panels and triggers stay live. Bind a room's AV zone to the receiver as its Volume Device and the zone slider drives the matching receiver zone — see Feeding an AV zone.

Which Sony receiver driver?

• Sony AV Receiver (Audio Control API) — this driver. Any receiver that answers at http://<ip>:10000/sony/system. That is every networked Sony receiver from the STR-DN1080 (2017) onward, including the whole STR-AZ ES line.
• Sony AV Receiver (Legacy HTTP) — the older STR-DA generation with the /request.cgi control page. See Sony AV Receiver (Legacy HTTP).

What's controlled

• Power — main zone (wakes the receiver from network standby, or puts it in standby) and Zone 2 / Zone 3 (activates or deactivates that zone's output).
• Input — per zone, by friendly alias, by the title the receiver shows, or by the raw uri.
• Volume — per zone, absolute on a 0–100 scale that GEM maps onto the range the receiver reports, plus single-step up and down.
• Mute — discrete mute_on / mute_off per zone, and a toggle. Mute state is read back, so a UI can show it.
• Sound field — select and read the main-zone sound field (Dolby Surround, Neural:X, stereo, direct and the rest of the receiver's list).
• Live state — power, volume, mute, input and sound field are written to device attributes as they change, and mirrored onto bound AV zones.

Prerequisites

• Receiver on the same network as GEM at a fixed IP (DHCP reservation).
• Network Standby (some models call it Quick Start) enabled on the receiver. Without it the API sleeps with the unit and power_on cannot wake it.
• Port 10000 open between GEM and the receiver. The Audio Control API is always on; there is no receiver setting to enable it.

Setup

1. Open Devices, add a device, and choose Sony AV Receiver (Audio Control API).
2. Choose the AV subsystem and an AV receiver device type.
3. Fill in the connection fields:
   • Receiver IP Address (required).
   • API Port — leave at 10000.
   • Pre-Shared Key — leave blank unless you set one on the receiver's IP-control page.
   • Status Poll Interval (ms) — default 10000. Push notifications update state sooner; this is the fallback cadence.
   • Use Push Notifications — default on. Turn off to poll only.
4. Save and enable. Run get_info on the Commands tab — the model name confirms the API is answering. Run get_inputs to see the receiver's real input and output names.
5. Confirm control end-to-end with get_power, power_on, a volume and an input before wiring the receiver into macros, a UI or an AV zone.

Zone addressing

Every command takes an optional address naming the receiver zone:

Address	Receiver zone
blank, 1 or main	Main zone
2	Zone 2
3	Zone 3
extOutput:zone?zone=2	A full output uri

Main-zone power is the receiver's system power, so power_off with no address puts the whole unit in standby. Zone 2 / Zone 3 power only activates or deactivates that output.

Addresses are checked against the receiver, and a bad one is refused

An address that does not name a zone the receiver reports is refused, not guessed at. The command returns address <x> is not an output this receiver reports and nothing goes on the wire.

This is deliberate, and it matters more than it sounds. An output uri the receiver cannot resolve does not come back as an error — it takes the unit down. The request never answers, the whole network stack drops, and the receiver cold-boots, which takes about 155 seconds. Measured reproducibly on an STR-AZ5000ES running firmware 001.484: extOutput:zone?zone=4, extOutput:zone?zone=9 and a uri of plain bogus each did it, while a bad value (volume sent as a number instead of a string) errored cleanly and left the unit alone.

So the driver sends only output uris the receiver itself listed through get_inputs, and it never retries a request that went unanswered. An AV zone whose address names a zone the receiver does not have is skipped by the status poll with one log line, instead of taking the receiver down on every poll interval.

Run get_inputs to see the real output list for your unit. Until it has answered once, the driver allows zones 1 to 3 — the range every receiver in this family has — and refuses anything beyond.

Inputs

input resolves the input argument in this order:

1. A value containing a colon is used verbatim as a uri: extInput:hdmi?port=3, radio:fm.
2. A friendly alias: hdmi1 … hdmi7, bd-dvd (bd, dvd), sat-catv (sat, catv), game, video, tv, sacd-cd (cd), aux (line), media-box, source, bluetooth, fm, usb, network, airplay, spotify.
3. A title or label from the receiver's own input list, matched case-insensitively — run get_inputs to see them. Inputs you renamed on the receiver resolve by that name.

Inputs are whitelisted the same way outputs are, for the same reason: once the receiver has reported its input list, an extInput: uri that is not on it is refused rather than sent. Content uris in other schemes (radio:fm, storage:usb1, dlna:music) are not terminals, are never enumerated, and always pass through.

The terminal schemes are matched regardless of case, so a respelled uri cannot slip past the check as content: extinput:GAME goes out as the receiver's own extInput:game when it reports that input and is refused when it does not. An extOutput: uri given as an input is held to the same check as a zone address, since an output uri the receiver cannot resolve is what reboots it.

The uri stems differ by model, so get_inputs is the list that counts. The current ES line answers extInput:game, extInput:tv, extInput:sacd-cd; the STR-DN1080 era answers extInput:hdmi?port=N. An alias like hdmi1 that resolves to a uri your receiver does not have is refused with <name> is not an input this receiver reports. Note also that the stem does not always match the front-panel label — on the ES line extInput:line is AUX and extInput:sacd-cd is SA-CD/CD. Use pass_through for a uri the terminal list does not carry.

How volume works

The receiver reports its own volume range and step with every volume read. GEM learns those bounds on the first read and maps the 0–100 slider onto them in both directions, rounding to the receiver's step. Until the first read succeeds the driver assumes 0–100. volume_up and volume_down send a relative step; the new level arrives by notification, or is read back when notifications are off.

Feeding an AV zone

1. Open AV Zones and edit the room's AV zone.
2. Set its Volume Device to this receiver.
3. Set the AV zone address to the receiver zone the room plays through — blank or 1 for the main zone, 2 or 3 for the powered zones.
4. Reload the receiver device after changing which AV zones point at it.

From then on the zone's volume slider drives that receiver zone, and every push or poll writes volume, mute_state, input and power_state back onto the bound zone.

Live state

The receiver opens three notification sockets (system, audio, avContent) and subscribes to power, volume, playing-content and terminal-status notifications. If a socket fails the driver logs once, retries in the background (15 s, then 60 s after repeated failures) and relies on polling in the meantime. Polling reads power first, and only while the receiver is on reads volume and input, then the sound field.

Volume and input are read for every zone in a single call, using an empty output, which is the one output value that never needs checking. That keeps the poll loop from building a zone uri at all, so no AV zone address can make the recurring poll crash the receiver. A receiver that rejects the all-outputs form falls back to reading each validated zone on its own.

If the receiver stops answering entirely, the driver pauses requests for three minutes rather than retrying — long enough for a cold boot to finish. A unit that was never reachable is treated as simply off and probed again after 30 seconds.

Attributes

Device — required

Attribute	Type	Description
ip	string	The receiver's LAN IP address.

Device — optional

Attribute	Type	Default	Description
port	int	10000	Audio Control API port.
preshared_key	string		Only if a PSK is set on the receiver's IP-control page. Stored encrypted.
status_interval	int	10000	Polling cadence in ms (minimum 2000).
use_notifications	bool	true	Open the notification websockets for instant state.

Device — written by the driver

Attribute	Description
power_state	Main-zone power, on / off.
main_volume, main_mute, main_input	Main-zone volume (0–100), mute (on / off), input uri.
zone2_power, zone2_volume, zone2_mute, zone2_input	Same for Zone 2 (and zone3_* for Zone 3). Written once that zone has been read or bound.
sound_field	Current sound field value.
model_name	Model reported by the receiver.

Zone

Bound AV zones receive volume (0–100), mute_state, input and power_state for the receiver zone their address names.

Commands

Command	Args	Action
power_on / power_off	address	Main zone: wake / standby the receiver. Zone 2/3: activate / deactivate that output.
get_power	address	Read a zone's power state.
input	address, input	Select an input — see Inputs.
get_input	address	Read what a zone is playing.
get_inputs		List the receiver's inputs and outputs with uris, titles and connection state.
volume	address, level	Absolute volume 0–100.
volume_up / volume_down	address	One receiver step.
get_volume	address	Read volume and mute.
mute_on / mute_off / mute_toggle	address	Discrete mute; the toggle is native, and when the zone's mute has never been read the new state is read back rather than guessed.
sound_field	mode	Set the sound field (dolbySurround, neuralX, stereo, direct, …).
get_sound_field		Current sound field and the receiver's candidate list.
get_info		Model, firmware and network identity.
pass_through	service, method, params, version	Raw API call for anything not wrapped — service is system, audio or avContent; params is a JSON object. method is required; a blank params or version (whitespace included) is treated as none.

Known limitations and quirks

• Sound field is main zone only. The API exposes it on the main output.
• Standby reads fail by design. While the receiver is in standby, volume and content reads return an error; the driver treats that as off and polls only power until it wakes.
• Bounds learned at runtime. The 0–100 mapping uses the range the receiver reports; before the first successful read, an absolute volume assumes 0–100.
• Hidden inputs are not selectable. An input you removed from the receiver's own input menu is rejected by the receiver.
• An unresolvable output uri reboots the receiver. See Zone addressing. The driver guards against this, which is why an address it cannot match is refused rather than sent.
• Method versions differ across the range. The API rejects a wrong version outright and never falls back on its own, so the driver tries the versions it knows for getSystemInformation (1.6 on the current ES line, 1.4 on the DN1080 era) and remembers which one answered. The terminal list is asked for at 1.2, which returns the full list, falling back to 1.0 — at 1.0 an STR-AZ5000ES answers with only 2 of its 13 terminals.
• Success does not always mean applied. While the receiver is held by its own on-screen menu, input and zone power return success and change nothing, while volume and mute keep working. Read the state back when a routing or power change matters.
• Verified on an STR-AZ5000ES (firmware 001.484) on 2026-09-14. The rest of the range follows Sony's Audio Control API reference and the openHAB / Homebridge implementations for the STR-DN1080 and STR-ZA line. Use pass_through to probe anything that behaves differently.

Troubleshooting

Symptom	Check
Never connects	Run get_power. If it errors, confirm the IP and that port 10000 is reachable from GEM.
power_on does nothing from standby	Enable Network Standby / Quick Start on the receiver.
input rejected	Run get_inputs and use a returned uri or title. The driver only sends inputs the receiver reports.
is not an output this receiver reports	The address names a zone the receiver does not have. Run get_inputs for the real output list and fix the AV zone or macro address.
Receiver reboots on its own, repeatedly	Before this guard shipped, an AV zone addressed to a zone the receiver does not have made the status poll send an unresolvable output uri every interval, rebooting the unit each time. Check the address on every AV zone bound to this receiver.
requests paused while it recovers	The receiver stopped answering and the driver is waiting out a suspected reboot. It resumes on its own.
State lags several seconds	Notifications are down; check the log for a websocket warning. Polling still updates state on status_interval.
Zone slider drives the wrong zone	The AV zone address is blank (main) or names the wrong zone number.

See also

• Sony AV Receiver (Legacy HTTP) — older /request.cgi receivers.
• AV Zones — Volume Device binding.
• Devices · Commands · Triggers