Header_Audio_APIHeader_Audio_API

Develop apps to control Sony's latest home audio devices

JSON-RPC extensions and restrictions

The Audio Control API uses JSON-RPC with some extensions and restrictions. JSON-RPC is a light communication protocol.

The API uses three types of messages.

  1. Set messages: to set some parameters on the device; the response is usually empty.
  2. Get messages: to get some parameters from the device; the response contains the requested values.
  3. Notification messages: messages sent from device without a request from the client, to notify the client about a parameter change.

Get and set messages include an id parameter. The id parameter is used to associate a response with the originating request. Notifications do not include an ID.

Below are some examples:

JSON-RPC request example

{
  "method": "echo",
  "params": ["Hello Audio Control API"],
  "id": 1, 
  "version": "1.0"
}

JSON-RPC response example

{
  "result": ["Hello Audio Control API "],
  "error": null,
  "id": 1
}

The Audio Control API adapts some extensions and restrictions to keep APIs simple and easy-to-use. For information for each API, see the API references.

Extensions

  • If the request succeeds, the error member is skipped in the response. On the other hand, if the request fails, the result member is skipped.
  • The error value is an array, defined as [error_code, error_message], where error_code is an integer and error_message is a string.
  • The client must set the version member in the request. The version member is of type string, and the version format is 2 numbers separated by dot (for example, "1.0"). For details about each API version.

Restrictions

  • For each API, the params and result values are fixed-length arrays.
  • For some APIs, the result member is optional in the response.
  • The id member is an integer. The value 0 (zero) MUST NOT be used. The client can set the id, and its valid range is "1" to "2147483647" (0x00000001 to 0x7FFFFFFF), inclusive.