Sennheiser Sound Control Protocol v2 (SSCv2)
Media Control Protocol
Document version: 0.1 01.03.2023
Sennheiser electronic GmbH & Co. KG Am Labor 1, 30900 Wedemark, Germany, www.sennheiser.com
- Sennheiser Sound Control Protocol v2 (SSCv2)
- Media Control Protocol
- Table of Contents
- Introduction
- Protocol Basics
- Usage
- SSCv2 Specifications
This document introduces the Sennheiser Sound Control Protocol v2 (SSCv2) for Sennheiser devices.
List of compatible devices:
- TeamConnect Ceiling Mic M
The Sennheiser Sound Control Protocol v2 is a secure RESTful API via HTTPS transport, suitable for command, control and monitoring of networked audio devices. It uses JavaScript Object Notation (JSON) for data serialization.
Terminology
SSCv2 server: Sennheiser device or application that receives and replies to SSCv2 messages.
SSCv2 client: third party device, application or person that sends SSCv2 messages to a Sennheiser device.
Protocol Basics
This section describes the key elements of the SSCv2 protocol.
HTTP(S)
The following optional parts of HTTP(S) have been made mandatory or are recommended for SSCv2:
- An SSCv2 server must implement HTTPS using HTTP/1.1
- An SSCv2 client should use persistent connections
OpenAPI
The SSCv2 definitions are provided as an OpenAPI specification for each Sennheiser device.
Messages
SSCv2 uses two modes of message exchange:
- Synchronous: The client sends a GET/PUT/POST/DELETE request and the server immediately sends a response
- Asynchronous: The client subscribes to parameter changes and the server notifies the client of parameter changes via a Server Sent Event (SSE). For more see SSCv2 Subscriptions.
Usage
This section describes how to use SSCv2.
Enabling Third Party Access
The Sennheiser device cannot be accessed via the API in factory default state. In order to enable it:
- Connect the Sennheiser device to Sennheiser Control Cockpit.
- Go to the device page.
- Enable third party access and configure a third party password.
Authentication
It is mandatory to authenticate on the device with each request:
- Using HTTP basic authentication
- Username: api
- Password: configured using Sennheiser Control Cockpit
Connecting to a Device
Use the device IP address and the HTTPS port 443 to form the base URL for the connection requests, e.g. "url: https://192.168.0.1:443".
SSCv2 Specifications
This section explains how HTTPS, JSON and SSE are used in the context of SSCv2.
Case sensitivity
- The path component of a URI must be case sensitive, as per RFC 3986, 6.2.2.1.
- The JSON payload must be interpreted by SSCv2 clients and SSCv2 servers as case sensitive.
Default Returns
For some generic actions, mandatory HTTP status codes have been defined:
- When a client sends a request without being authenticated, the SSCv2 server replies with 401 – "Unauthorized".
- When a client is authenticated but not authorized to access the resource, the SSCv2 server replies with 403 – "Forbidden".
- When a client is authorized and tries to access a resource that does not exist, the SSCv2 server replies with 404 – "Not Found".
- When a client is authorized to access a resource but the HTTP request method is not allowed by the SSCv2 server, the SSCv2 server replies with 405 – "Method not allowed".
- When a client is authorized to access a resource but has a format error in its request, the SSCv2 server replies with 400 – "Bad request".
- When a client is authorized to access a resource and the format is correct, but the device cannot honor the request because of the internal device status, the SSCv2 server replies with 409 – "Conflict". An example for this would be trying to configure an IP address while the device is using DHCP, without also switching to fixed addresses.
- When a client is authorized to access a resource and the format is correct, but there are semantic/logical errors, the SSCv2 server replies with 422 – "Unprocessable Entity". An example for a logical error would be using a subscription ID which does not exist.
JSON
The following optional parts of JSON have been made mandatory for SSCv2:
- An SSCv2 server returns all text-based entities as a JSON object
SSCv2 Subscriptions
The SSCv2 API allows third party clients to subscribe to parameter changes. In response, the server notifies the client of parameter changes via a Server Sent Event (SSE), formatting messages according to the EventSource specification.
Subscription Message Format
For the EventSource specification only the parameters data
and event
are used. For the parameter event
only the following events are used:
open
, at the start of a subscription.message
, when sending resource updates. As it is there by default, it MAY be omitted in the event stream.close
, when the SSCv2 client actively closes the subscription by sending DELETE to/api/ssc/state/subscriptions/{sessionUUID}
or when the subscription is closed because the device is initiating a reboot.
A full EventSource-compatible update looks as follows:
event: <eventtype>\ndata: <updatejson>\n\n
where \n
denotes the ASCII character for a linefeed.
Starting a Subscription
To initiate a subscription:
- The subscription is initialized by the SSCv2 client by issuing a GET request to
/api/ssc/state/subscriptions
- The SSCv2 server replies to the subscription request immediately either by acknowledging the request, or by sending an error reply.
- The SSCv2 server sends an initial message to the client, containing:
- The
Content-Type
set totext/event-stream
- The
Content-Location
containing the path/api/ssc/state/subscriptions/{sessionUUID}
- where
SessionUUID
is the ID generated for the subscription and associated with the HTTP session. It can be used later to modify the subscription. - The initial
open
event, with the following data:
- The
- The SSCv2 server sends an initial message to the client, containing:
{
"path": "/api/ssc/state/subscriptions/{sessionUUID}",
"sessionUUID": "{sessionUUID}"
}
- The SSCv2 subscription is initially empty without any subscribed resources, and the SSCv2 client must subscribe to resources using
/api/ssc/state/subscriptions/{sessionUUID}
and/api/ssc/state/subscriptions/{sessionUUID}/add
, respectively. - An SSCv2 client must not send further regular HTTP requests to the SSCv2 server via the connection used to request the subscription. After the initial subscription request the connection can only be used to receive events from the SSCv2 server.
The resource for starting subscription is provided in the OpenAPI snippet below.
/api/ssc/state/subscriptions:
get:
summary: Start a subscription
description: An SSCv2 Command to start a subscription
responses:
'200':
description: Successful request
headers:
Content-Location:
description: Location of the resource to be used to change the subscribed resources
schema:
type: string
content:
text/event-stream:
schema:
type: string
description: The initial subscription stream.
'403':
description: User is not authorized to subscribe to resources
'500':
description: SSCv2 Server encountered internal error
Getting Subscription Status
The SSCv2 client can request the subscription status:
- Send a GET request to
/api/ssc/state/subscriptions/{sessionUUID}
using the previously receivedsessionUUID
. - If the
sessionUUID
is incorrect, an error is returned.
OpenAPI snippet:
/api/ssc/state/subscriptions/{sessionUUID}:
get:
summary: Get the subscription list
description: An SSCv2 Command to retrieve the list of subscriptions associated with the sessionUUID
parameters:
- in: path
name: sessionUUID
schema:
type: string
required: true
responses:
'200':
description: Successful request
content:
application/json:
schema:
type: array
items:
type: string
example: /api/device/site
'403':
description: User is not allowed to get subscription list for this sessionUUID
'422':
description: sessionUUID did not exist
'500':
description: SSCv2 Server encountered internal error
Changing Subscribed Resources
It is possible to either change the full set of resources of a subscription, or to add/remove resources from the currently subscribed set.
The SSCv2 client can only subscribe to resources specifying a GET request, otherwise an error is returned.
Changing the Full Set of Subscribed Resources
The SSCv2 client can change the full set of subscribed resources:
- Send a PUT request to
/api/ssc/state/subscriptions/{sessionUUID}
using the previously receivedsessionUUID
.- The SSCv2 client must send a complete list of the resources to which it wants to subscribe.
- After accepting and setting up the subscription, the SSCv2 server sends the current state of each subscribed resource which is new or has been removed.
OpenAPI snippet
/api/ssc/state/subscriptions/{sessionUUID}:
put:
summary: Set/change the subscription list
description: An SSCv2 Command to set/change the list of subscriptions associated with the sessionUUID
parameters:
- in: path
name: sessionUUID
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: array
items:
type: string
example: /api/device/site
responses:
'200':
description: Successful request
'400':
description: The request for subscription was invalid
content:
application/json:
schema:
type: object
properties:
path:
type: string
example: /api/ssc/version
error:
type: integer
example: 403
'403':
description: User is not allowed to change subscription list for this sessionUUID
'422':
description: sessionUUID did not exist
'500':
description: SSCv2 Server encountered internal error
Adding Resources to Subscriptions
The SSCv2 client can add one or more resources to an existing list of subscribed resources:
- Send a PUT request to
/api/ssc/state/subscriptions/{sessionUUID}/add
using the previously receivedsessionUUID
. - The SSCv2 server adds the resources to the list of subscribed resources for the existing subscription.
- If even one resource in the set of resources that the SSCv2 client wants to add is not allowed, the SSCv2 server refuses the entire request and the current set of subscribed resources for the subscription is not changed.
- The SSCv2 server treats an empty resource list as no action and replies with 200 – OK.
- The SSCv2 server reports the initial values of the newly added resources using the existing subscription.
OpenAPI snippet
/api/ssc/state/subscriptions/{sessionUUID}/add:
put:
summary: Add resource(s) the subscription list
description: An SSCv2 Command to add a set of resources to the list of subscriptions associated with the sessionUUID
parameters:
- in: path
name: sessionUUID
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: array
items:
type: string
example: /api/device/site
responses:
'200':
description: Successful request
'400':
description: The request to add to the subscription was invalid
content:
application/json:
schema:
type: object
properties:
path:
type: string
example: /api/ssc/version
error:
type: integer
example: 403
'403':
description: User is not allowed to add to the subscription list for this sessionUUID
'422':
description: sessionUUID did not exist
'500':
description: SSCv2 Server encountered internal error
Removing Resources from Subscriptions
The SSCv2 client can remove one or more resources from an existing list of subscribed resources:
- Send a PUT request to
/api/ssc/state/subscriptions/{sessionUUID}/remove
using the previously receivedsessionUUID
. - The SSCv2 server removes the resources from the list of subscribed resources for the existing subscription.
- If even one resource in the set of resources that the SSCv2 client wants to remove is not allowed, the SSCv2 server refuses the entire request and the current set of subscribed resources for the subscription is not changed.
- The SSCv2 server treats an empty resource list as no action and replies with 200 – OK.
- The SSCv2 server does not terminate the subscription if the list of subscribed resources is empty after the removal of resources.
- For every removed resource the SSCv2 server sends an update, using the resource as the key and the JSON keyword "null" as the value.
OpenAPI snippet
/api/ssc/state/subscriptions/{sessionUUID}/remove:
put:
summary: Remove resource(s) from the subscription list
description: An SSCv2 Command to remove a set of resources from the list of subscriptions associated with the sessionUUID
parameters:
- in: path
name: sessionUUID
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: array
items:
type: string
example: /api/device/site
responses:
'200':
description: Successful request
'400':
description: The request to remove to the subscription was invalid
content:
application/json:
schema:
type: object
properties:
path:
type: string
example: /api/ssc/version
error:
type: integer
example: 404
'403':
description: User is not allowed to remove from the subscription list for this sessionUUID
'422':
description: sessionUUID did not exist
'500':
description: SSCv2 Server encountered internal error
Canceling a Subscription
An SSCv2 client can end a subscription either implicitly or explicitly.
- To end a subscription implicitly, the SSCv2 client simply closes the connection that receives the subscription data.
- To end a subscription explicitly, an SSCv2 client sends a DELETE request to the resource
/api/ssc/state/subscriptions/{sessionUUID}
.- The SSCv2 server sends a
close
event to the subscription before it closes the connection. - The data sent in the
close
event is the same as in theopen
event.
- The SSCv2 server sends a
The SSCv2 server terminates a subscription in the following cases:
- The subscribed client cancels the subscription explicitly.
- The SSCv2 client closes the connection.
- The transport layer of the SSCv2 connection signals a fatal communication error.
OpenAPI snippet
/api/ssc/state/subscriptions/{sessionUUID}:
delete:
summary: End an existing subscription
description: An SSCv2 Command to end the subscription associated with the sessionUUID
parameters:
- in: path
name: sessionUUID
schema:
type: string
required: true
responses:
'200':
description: Successful request
'403':
description: User is not allowed to end subscription for this sessionUUID
'422':
description: sessionUUID did not exist
'500':
description: SSCv2 Server encountered internal error
Subscribing to Multiple Addresses
The SSCv2 client may request to subscribe to multiple resources in a single request.
- If the SSCv2 server is not able to successfully subscribe to even one of the resources, it sends an error and refuses all resources.
- If there are already subscribed resources present, the previous state of the subscription remains unchanged.
Error Handling
When the SSCv2 server refuses a request for a subscription or a set of subscriptions, it returns an object containing the first resource which was not subscribable and the reason for the error.
- 403 if subscribing to the resource is not allowed.
- 404 if the resource does not exist.
Subscription Notification Syntax
A subscription notification constitutes Server Sent Event (SSE) data in the form of a JSON object, using the resource that triggered the notification as the key and the entities of the resource wrapped in a JSON object as the value.
- An SSCv2 server may combine notifications for multiple resources in one JSON object, if the updates occur at the same time.
- Since a newly created subscription of multiple addresses must report the values of the resources, this may be combined into a larger JSON object.
- If this combination of the different resources is not supported, all notifications must be sent in the stream as individual JSON objects.
The following example shows a stream containing a notification after an initial subscription and a later notification of a name change:
{
"/api/device/site":
{
"name": "MyDevice",
"location": "Chemistry Building 5, Room 15",
"site": "Left side near the big pillar"
}
}
{
"/api/device/site":
{
"name": "MyRenamedDevice",
"location": "Chemistry Building 5, Room 15",
"site": "Left side near the big pillar"
}
}
The address /api/device/site
was subscribed, the initial values were reported. After some time the name
was changed and the resulting update was sent as a second JSON object.