Audio Control API

Develop apps to control Sony's latest home audio devices.

How to perform the device discovery process

The discovery process to find products connected to your network, uses the Universal Plug and Play (UPnP) protocols and the Simple Service Discovery Protocol (SSDP). The audio product must be connected to the network and powered on, for the the discovery process to work. For instructions, see the user manual for your product.

See the illustration below to get a better idea of the discovery process:

How can you find the device?
Devices supporting Audio Control API are discovered via the SSDP M-SEARCH method, using a specific search target (ST) header:

ST: urn:schemas-sony-com:service:ScalarWebAPI:1

All multicast messages are sent to the reserved address and port, 239.255.255.250:1900. The following sample SSDP M-SEARCH method searches for devices that support the Audio Control API.

M-SEARCH * HTTP/1.1
HOST: 239.255.255.250:1900
MAN: "ssdp:discover"
MX: seconds to delay response
ST: urn:schemas-sony-com:service:ScalarWebAPI:1
USER-AGENT: OS/version product/version

How does the API respond to discovery?

Products that implement the service specified in the search target (ST) field will respond with a unicast response.

Example response:

HTTP/1.1 200 OK
LOCATION: http://192.168.0.1:61000/dd.xml 
CACHE-CONTROL: max-age=1800
EXT:
BOOTID.UPNP.ORG: 1
SERVER: OS/version UPnP/1.1 product/version
ST: urn:schemas-sony-com:service:ScalarWebAPI:1

The value of the LOCATION header points to an UPnP Device Description, which is an XML document. The value of the ST header is identical to the one sent in the M-SEARCH request. Note that the value of the LOCATION header may vary depending on model.

How does the API manage device description?

Once you’ve received a discovery response, you can retrieve the device description from the LOCATION using the HTTP GET method and the device description URL. There's an example in the code box below, with that method you can check whether the desired API service is supported by the device.

http://192.168.0.1:61000/dd.xml

An Audio Control API device has an X_ScalarWebAPI_DeviceInfo tag in the device description, and its name space is "urn:schemas-sony-com:av".

For example:

<av:X_ScalarWebAPI_DeviceInfo xmlns:av=”urn:schemas-sony-com:av“>

Under the X_ScalarWebAPI_DeviceInfo element the X_ScalarWebAPI_BaseURL element contains the correct path for the Audio Control API on the product.

How do you use the Endpoint URL?

Use the endpoint URL to access the API via the HTTP POST method. It is composed of two parts, a Base_URL and the API service divided by a /. For example:

URL: <Base_URL>/<API service>

Both the Base_URL and API service are obtained through the device discovery process. The Base_URL is defined by the content of the av: X_ScalarWebAPI_BaseURL tag in the Device Description. The API service is defined by the content of the av:X_ScalarWebAPI_ServiceType tag.

Note that the X_ScalarWebAPI_BaseURL and X_ScalarWebAPI_ServiceType may vary depending on model. For example, Home Audio products usually use port 10000 and Personal Audio products usually use port 54480. For more information about the different API services, see the API references.

For example, given the following information in the Device Description:

<av:X_ScalarWebAPI_BaseURL>http://192.168.1.123:10000/sony</av:X_ScalarWebAPI_ActionList_URL>

The resulting URL is:

http://192.168.1.123:10000/sony/audio