Usage of Spectera API

Enabling API Access

Sennheiser devices cannot be accessed via the API in factory default state. In order to enable it, you have connect to the Base Station via Sennheiser LinkDesk or Spectera WebUI and set a password. The Spectera Security Guide explains in detail how to set a device password.

Connecting to the Base Station

Use the IP address of the device and the HTTPS port 443 to form the base URL for the connection requests, e.g. "https://192.168.0.1:443".

CAUTION

Since the 3rd-party "API" access level is not implemented yet on Spectera, you have to use the existing access level used by our Sennheiser applications and NOT the "API" access level mentioned inside the general SSCv2 documentation.

  • Using HTTP basic authentication

  • Username: controlSennheiser

  • Password: configured using Sennheiser LinkDesk or WebUI

Communicating with the API

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 Sennheiser Sound Control Protocol (v2.3) - Specification.

Please also have following Spectera specific recommendations in mind:

Tip

Use subscriptions for update notifications

  • We always recommend to use the subscription mechanism to receive updates when resources/objects have been changed instead of polling the resource/object with the GET method.

  • The SSC server on the Base Station has a limit on how many connections can be handled concurrently. For the sake of fairness to other potential clients, try to keep the number of parallel open connections as less as possible. E.g. keep just one connection for asynchronous (subscriptions) and another for synchronous communication open or open them just on demand.

Tip

Coordinating Multi-Client-Write-Access

  • Currently the Multi-Client-Write-Access is not fully implemented and tested yet and might have side effects if more than one client is writing to a resource at the almost same time. Therefore the usagemark property comes into place. /api/ssc/usagemark.

  • There is no active lock of write access, but the usagemark can be used to inform other clients, that they are connected with the Base Station and doing write requests. Other clients shall switch actively into "read-only" access, if the usagemark is or is getting set by another client. By setting the usagemark property a timeout has to be applied, when the usagemark get's reset automatically by the Base Station.

  • Please be fair with the usagemark and do not hold it longer than necessary.

  • More details are below in example section and the YAML spec.

Managing Mobile Devices

Don't get confused with the abbreviation "MT" or "MTs" in the API paths or in general. It's a synonym for "Mobile Device".

Each Mobile Device (SEK, SKM, etc.) which is connected to the Base Station is handled as a dynamic resource and can be accessed via a unique URI (Uniform Resource Identifier). A group of multiple devices are handled with collections or lists of resources. Each collection can be managed with the typical REST API methods GET/PUT/POST/DELETE.

There are 2 collections for handling the Mobile Devices depending on their current state of relation to the Base Station.

ListAPI pathDescription
Pairable Devices/api/mts/pairableContains all the objects representing the Mobile Devices which are currently connected to the Base Station (in Pairing Mode) and can potentially get paired
Paired Devices/api/mts/paired/allContains all the objects representing the Mobile Devices which are currently paired to the Base Station regardless of whether they are currently connected or disconnected

Specific devices can be accessed by GET and PUT methods on the dedicated resource containing the specific mtUid, e.g. /api/mts/pairable/{mtUid} or /api/mts/paired/all/{mtUid}

mtUid vs. serial number

The mtUid is an unique identifier for each Mobile Device inside the Spectera system regardless the type of device. At the API the property mtUid is used to address a specific Mobile Device resource.

The serial number is an unique identifier for each type of Mobile Device. That means that different types of Mobile Device can potentially have the very same serial number. Therefore it can not be used as unique identifier to address a specific Mobile Device resource at the API. Nevertheless can it be read with the property serial of an Mobile Device resource. The serial number is also printed at the housing of a device.

Pairing a Mobile Device

Before configuring Audio Links on a specific Mobile Device it needs to be paired to the Base Station. This can be done by using the Spectera WebUI (Pairing/unpairing mobile devices) or by using the API.

Basic steps are:

  1. Activate the Pairing Mode of the Base Station - PUT /api/mts/pairing with enable:true
  2. Set the Mobile Device into Pairing Mode - Switching the SEK on and off
  3. Check the list of Pairable Devices - GET /api/mts/pairable
  4. Verify/Compare the PairingPinCode of the specific Mobile Device going to be paired - GET /api/mts/pairable/{mtUid}
  5. Add the Mobile Device to the list of Paired Devices - POST /api/mts/paired/all with the mtUid
  6. The Mobile Device reconnects and will be available in the list of Paired Devices - GET /api/mts/paired/all
  7. Deactivate the Pairing Mode of the Base Station - PUT /api/mts/pairing with enable:false

A Mobile Device in the list of Pairable Devices can be forced to search for another Base Station to connect to by removing it from the list. DELETE /api/mts/pairable with the mtUid

Unpairing a Mobile Device

A Mobile Device can be actively un-paired from the Base Station by removing it from the list of Paired Devices. DELETE /api/mts/paired/all/{mtUid}

Command Mode

Command Mode feature has been officially introduced with the Spectera API version 18.1. In previous API versions, this feature is not officially supported. Please check the Supported API versions for more details on available firmware versions.

About Command Mode

The feature Command Mode provides the possibility for the user of a Mobile Device to trigger a custom routing of the audio signal on the Base Station by pressing a dedicated Command Button at the Mobile Device.

The custom routing in Command Mode is only available for MIC Audio Links respectively Audio Outputs at the Base Station and not for IEM Audio Links and Audio Inputs.

Following functionality can be configured:

  • The Command Mode can be enabled for each Mobile Device separately.
  • The Command Button behavior can be configured to be either "Momentary" or "Latching". In "Momentary" mode the button needs to be pressed and held to activate the command, in "Latching" mode one press activates the command and another press deactivates it.
  • For Command Buttons with LED indication (e.g. SKM COM) the color can be customized for all the available Command Mode states.
  • For each Audio Output at the Base Station the routing to the Audio Interface (AoIP, MADI1, MADI2) can be configured individually for the Command Mode being enabled or not. This allows to have a custom audio routing when the Command Mode is active, e.g. for a talkback function.
  • The audio routing behavior can be configured in 2 styles:
    • Mute: The audio signal is muted when the Command is triggered and unmuted if not
    • Talk: The audio signal is unmuted when the Command is triggered and muted if not
  • Since an Audio Link can be assigned to several Audio Outputs, the Command Mode can be used for custom audio routing of one Mobile Device to different Audio Outputs, depending on the Command trigger.

Additionally the state of the Command Button can be accessed via the API and used for triggering other actions on the Base Station or at the client side, e.g. for controlling external devices or for visualizing the state of the Command Button.

Configuration

The Command Mode behavior and audio routing can be configured by modifying the properties of a paired Mobile Device and of the Audio Outputs at the Base Station.

Configuring the Command Mode always consist of two basic steps:

  1. Enable the Command Mode for the desired Mobile Device by defining the behavior (Momentary or Latching) at the property commandBehavior - PUT /api/mts/paired/all/{mtUid}
  2. Configure the state dependent audio routing (On, Off, Mute, Talk) for the Command Mode at the desired Audio Outputs by defining the desired routing at the properties aoIpEnableIfCommandIsEnabled, madi1EnableIfCommandIsEnabled, and madi2EnableIfCommandIsEnabled - PUT /api/audio/outputs/{outputId}
Tip
  • The interfaces of an Audio Output with an Audio Link assigned must not all be Off.

  • Even with Command Mode enabled the routing can be set to On or Off. In this case the Command trigger will not change the routing, but the state of the Command Button can still be accessed via the API and used for other purposes.


Spectera Audio Routing with Command Mode

Retrieve Live Monitoring Data with Level Recording

Level Recording has been introduced with the Spectera API version 18.1 as preliminary feature which will continuously evolve. It is not available in previous API versions. Please check the Supported API versions for more details on available firmware versions.

About Level Recording

The feature Level Recording provides a stream of telemetry data, e.g. audio metering, Mobile Device parameters, antenna and RF channel parameters, which can be used for monitoring and debugging purposes. A certain set of parameters, which can be accessed via the SSCv2 API, are available through Level Recording but are provided as a high-efficient binary stream encoded with FlatBuffers instead of JSON. The Level Recording API is designed as a sub-schema of the SSCv2 Control API and therefore follows the same authentication and subscription mechanism as the main SSCv2 OpenAPI. The only difference is that the payload of the SSE events is encoded as FlatBuffers and not JSON.

The Base Station is generating the Level Recording data as snapshots in regular intervals of around 1 second and provides it via a dedicated endpoint as SSE events with FlatBuffers-encoded payload (Frame). Each Frame is structured in different "sections" for better maintainability. Each section contains a set of parameters related to a specific topic, e.g. audio metering, etc. The sections are defined in a dedicated FlatBuffers schema (*.fbs file). Some of these sections contain bulk data of the 1 second snapshot, e.g. the audio metering data provides 64 values per audio channel for each Frame.

Additionally to the live stream of monitoring data, the Base Station also provides the possibility to retrieve historical data of the last 1 hour with a time resolution of around 1 second. This option will mainly used to cover lost live data or to analyze past events. The historical data is provided with the same structure and schema as the live data, but only on demand when requested by the client. This can be achieved by providing the desired range (start and end index) of historical data to the dedicated endpoint for historical data retrieval. The Base Station will then send all available Frames of the requested range as SSE events with FlatBuffers-encoded payload.

Brief outline on FlatBuffers

FlatBuffers is a serialization library and format developed by Google. It allows to define data structures in a schema and serialize them into a compact binary format. The main advantage of FlatBuffers is that it allows zero-copy deserialization, which means that the data can be accessed directly from the serialized buffer without the need for parsing or unpacking, making it very efficient for real-time applications. The schema of the FlatBuffers data is defined in a *.fbs file, which can be compiled to generate code for different programming languages to easily encode and decode the data.

Schema Versioning

The FlatBuffers schema has its own life-cycle and therefore versioning independent of the SSCv2 API versioning. A new version of the FlatBuffers schema will be introduced and announced with at least a change of the minor SSCv2 API version, but not necessarily with every new API version.

Sennheiser follows the official FlatBuffers schema evolution guidelines with the primary goal of wire compatibility of the binary payload across minor schema versions:

  • Wire compatibility across minor schema versions: The binary format remains decodable across minor schema version changes (e.g. 1.0 → 1.1). Newer clients can decode older payloads and vice versa.

  • Feature compatibility is not guaranteed across minor schema versions: While the binary format stays decodable, individual fields may be deprecated (returning default/zero values). Features depending on deprecated fields will no longer receive meaningful data. Refer to the release notes for details on deprecated and newly introduced fields.

  • Major schema versions may break wire compatibility: A major schema version increment (e.g. 1.x → 2.0) may require client-side decoder updates.

Since the FlatBuffers schema covers a similar set of parameters as the SSCv2 API, the schema evolution will be primarily driven by the changes in the SSCv2 API schema. Deprecated parameters and breaking changes in the FlatBuffers schema will be announced in the release notes.

Tip

Level Recording clients should use the schema version reported by /api/levelrecording/version as their version contract and check it at connection time to detect schema changes independently of the SSCv2 API version. As the Level Recording feature is still preliminary, the versioning and evolution policy may be refined in future API versions.

Endpoints overview

GET /api/levelrecording/version

  • Get the Level Recording schema version

Example Response Body:

{
  "protocol": "flatbuffers",
  "schema": "1.0",
  "schemaDetailed": "1.0.0"
}

The version information is relevant for decoding the FlatBuffers payload of the Level Recording data. The client needs to ensure that the schema version is compatible with the version it supports to be able to decode the payload correctly.

GET /api/levelrecording/info

  • Get information about currently available indices and buffer fill level of the historical level recording data.

Example Response Body:

{
  "session_uuid": "42b3f67c-9ee5-438b-ac92-00fa71e040e2",
  "start_index": 0,
  "size": 148
}

This information is relevant for retrieving historical data with the endpoint /api/levelrecording/history as it provides the valid range of indices for the historical data and the session UUID to be used for retrieving the historical data. The session UUID is unique for each Level Recording session and can be used by the client e.g. after a reconnection to check if the historical data has been reset or if it is still available for retrieval. Every restart or reset of the Base Station will reset the Level Recording session and therefore all historical data will be lost and a new session UUID will be generated.

GET /api/levelrecording/live

  • Request Level Recording Live Data by initiating a subscription to the live stream of Level Recording data as Server Sent Events (SSE) with FlatBuffers-encoded payload.

This GET request will not return a single response body, but initiates a subscription to the live stream of Level Recording data as Server Sent Events (SSE). The client will receive an SSE event every second with the latest snapshot of monitoring data encoded in the payload as FlatBuffers binary data according to the Level Recording schema. The client needs to decode the FlatBuffers payload according to the schema to access the monitoring data.

Following SSE event types are available in the live stream:

event:open\ndata:<json-data>\n\n

  • This event is sent once when the subscription to the live stream is established. The data payload contains a JSON object with the session UUID, the start index for the first FlatBuffers Frame, the current buffer fill level of the historical data, and the version of the FlatBuffers schema (schemaDetailed).

Example Payload:

{
  "session_uuid": "42b3f67c-9ee5-438b-ac92-00fa71e040e2",
  "start_index": 0,
  "size": 148,
  "version": "v1.0.0"
}

event:message\ndata:<json-data>\n\n

  • This event is sent for each new snapshot of Level Recording data. The data payload contains a JSON object with the index, timestamp, and the FlatBuffers-encoded data.

Example Payload:

{
  "index": 149,
  "time_stamp": 1770207951507,
  "payload": "GAAAAAAAEgAga..."
}

event:close\ndata:"goodbye"\n\n

  • This event is sent when the subscription to the live stream is closed from server-side for any reason.
Tip
  • The Level Recording data is only available as SSE stream. Therefore the connection needs to be kept open. There is no possibility to retrieve the data with single synchronous GET requests.

  • We recommend to use a dedicated connection/socket for the live stream and not share it with other requests.

  • The stream can be stopped by closing the connection.

CAUTION

This endpoint can not be subscribed with the usual SSCv2 subscription mechanism via /api/ssc/state/subscriptions.

GET /api/levelrecording/history

  • Get historical Level Recording data by providing the start and end indices of the data to be retrieved.

This GET request will not return a single response body, but initiates a stream of historical Level Recording data as Server Sent Events (SSE). The client will receive SSE events as fast as the server can provide them. The client needs to decode the FlatBuffers payload according to the schema to access the monitoring data.

The SSE event types are the same as for the live stream, but the payload contains only the historical data of the requested range of indices.

Tip
  • As with the live stream, the historical Level Recording data is only available as SSE stream.

  • If the requested range of historical data is not available anymore, e.g. due to a session reset or because the requested indices are out of range, the server will send at least all the data still available within the requested range.

  • We recommend to use a dedicated connection/socket for the historical stream and not share it with other requests.

  • The stream can be stopped by closing the connection.

  • The stream will be automatically stopped by the server (with a close event) after sending the requested range of historical data.

CAUTION

This endpoint can not be subscribed with the usual SSCv2 subscription mechanism via /api/ssc/state/subscriptions.

Examples of basic requests for 3rd-party access

Here are a few examples which resources might be useful for the 3rd-party access.

GET /api/ssc/version

  • Get the SSCv2 protocol and schema (interface) versions

Example Response Body:

{
  "protocol":"2.3",
  "schema":"17.0",
  "schemaDetailed":"v17.0.0+0-g7081b87f"
}

GET /api/ssc/usagemark

  • Check if the device is "in use"

Example Response Body, if the device is "in use":

{
  "usedBy": "LinkDesk.JaneDoe-12345abcdef",
  "timer": 5
}

Example Response Body, if the device is NOT "in use":

{
  "usedBy":"",
  "timer":300
}

PUT /api/ssc/usagemark

  • Set the device as "in use" for the next 10 seconds.

Request body:

{
  "usedBy": "3rd-party.JoeDoe-12345abcdef",
  "timer": 10
}

GET /api/device/identity

  • Get the device identity

Example Response Body:

{
  "product":"Spectera-Base-Station",
  "hardwareRevision":"0594192-08",
  "serial":"1424000001",
  "vendor":"Sennheiser electronic SE & Co. KG"
}

PUT /api/device/identification

  • Sets the state of device identification. Let the LED of Base Station flash for identification.

Request body:

{
  "visual": true
}

GET /api/firmware/update/state

  • Get the state of a firmware update process incl. version. For 3rd-party only the firmware version of the Base Station and of the Dante module might be of interest.

Example Response Body:

{
  "deviceVersion":"v1.3.0",
  "aoIpVersion":"1.1.0",
  "state":"Idle",
  "progress":0,
  "lastStatus":"None",
  "lastStatusDetailed":"NONE"
}

GET /api/rf/channels

  • Get the list of RF channels and their settings.

Example Response Body:

[
  {
    "rfChannelId":0,
    "txPower":50,
    "frequency":522000,
    "bandwidthMode":8000,
    "rfRestrictionViolation":false,
    "rfState":"RfActive",
    "rfStateOnStartup":"RfMuted"
  },
  {
    "rfChannelId":1,
    "txPower":50,
    "frequency":554000,
    "bandwidthMode":8000,
    "rfRestrictionViolation":false,
    "rfState":"RfActive",
    "rfStateOnStartup":"RfMuted"
  }
]

GET /api/mts/paired/all

  • Get the list of all paired Mobile Devices and all of their properties.

You will get an array of all Mobile Devices paired with the Base Station. Each entry contains all the properties of each single device. You can use the "mtUid" for further requests on a dedicated Mobile Device.

Example Response Body:

[
  {
    "mtUid":16789965,
    "type":"SEK",
    "frequencyRange":"UHF",
    "rfChannelId":1,
    "identify":false,
    "reverseIdentify":false,
    "name":"SEK",
    "serial":"1495000001",
    "sleep":false,
    "state":"Connected",
    "lastConnected":"NotAvailable",
    "version":"v1.3.5",
    "versionMismatch":false,
    "fccId":"DMOSEKUHF",
    "batteryFillLevel":100,
    "batteryRuntime":65535,
    "batteryLow":false,
    "ledBrightness":"Standard",
    "connectedStateColor":"#00A100",
    "swUpdatePossible":true,
    "swUpdateNotPossibleReason":"",
    "swUpdateProgress":-1,
    "micAudiolinkId":39,
    "iemAudiolinkId":-1,
    "micAudiolinkActive":true,
    "iemAudiolinkActive":false,
    "headphonePlugState":"Unplugged",
    "headphoneVolume":-20,
    "headphoneVolumeMax":27.5,
    "headphoneVolumeMin":-100,
    "headphoneBalance":0,
    "headphoneMonoBalanced":false,
    "micPreampGain":12,
    "micLowCutHz":20,
    "micTestToneEnabled":false,
    "micTestToneLevel":-60,
    "micLineSelection":"Auto",
    "micLineSelectionAutoValue":"Mic",
    "cableEmulation":"Off",
    "commandState":"NotAvailable",
    "iemLqi":0,
    "micLqi":4,
    "interference":
    {
      "severity":"Low"
    },
    "dominantAntenna":"d",
    "rssi":-42
  }
]

PUT /api/mts/paired/all/{mtUid}

  • Modify the properties of a paired Mobile Device given by the "mtUid" and "type", e.g. let the LED flash to identify.

Example Request Body:

{
  "mtUid":16789965,
  "type":"SEK",
  "identify":true
}

GET /api/audio/levels

  • Get the audio input (IEM) and audio output (MIC) levels at the Base Station.

You will get the audio input and output levels of all audio channels for all interfaces (Madi1, Madi2 and Dante).

Tip

We recommend to subscribe for that resource than pulling it with a GET request. You will receive always the full set of audio levels for all 32 input and 32 output channels on the Base Station. There is no dedicated resource or property to get the audio level of one dedicated Mobile Device. If you would like to know the mapping of a Mobile Device to an Audio Channel you have to do "reverse engineering" by reading out the Audio Links configured for a dedicated Mobile Device.