Sennheiser Sound Control Protocol (SSC) versatile command, control, and configuration for networked audio systems Developer‘s guide for Digital 9000 EM 9046 Sennheiser electronic GmbH & Co. KG Am Labor 1, 30900 Wedemark, Germany, www.sennheiser.com TI 1247 v1.
Table of Contents 1. Open Sound Control Overview.......................................................................................................... 7 1.1 JavaScript Object Notation Overview.........................................................................................7 2. Conventions........................................................................................................................................8 2.1 Terminology....................................................
5.2.10 /device/network................................................................................................................... 30 6. SSC Transport Layer Adaptations...................................................................................................33 6.1 UDP/IP.......................................................................................................................................... 33 6.2 TCP/IP.................................................................
7.4.40 7.5 /device/language................................................................................................................. 44 /rx* - receiver channels............................................................................................................. 44 7.5.1 RF carrier frequency presets............................................................................................... 44 7.5.2 /rx*/label.........................................................................
7.7.7 /m/divi_b............................................................................................................................... 55 7.7.8 /m/af_level............................................................................................................................ 55 7.8 /mates - detachable system components............................................................................... 55 7.8.1 /mates/active....................................................................
Introduction Modern professional audio devices are designed as building blocks for large, complex systems.
Open Sound Control Overview 1. Open Sound Control Overview Open Sound Control (OSC) is a protocol developed at The Center For New Music and Audio Technology (CNMAT) at University of California, Berkeley. The OSC specification Version 1.1 is available from the Open Sound Control website at: http://www.opensoundcontrol.org/ . It is a very simple and very extensible protocol that can be implemented easily in embedded systems.
Conventions 2. Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP14/RFC 2119, "Key words for use in RFCs to Indicate Requirement Levels". 2.
SSC Data Structure Specification 3. SSC Data Structure Specification 3.1 Applying JSON to the OSC device model OSC models the controlled device as a tree-shaped hierarchy of methods, with the method addresses constructed from the names of all the nodes in the hierarchy, written like a file path.
SSC Data Structure Specification For command and control applications it is desirable to access single properties independently. This can be achieved in JSON syntax by the simple convention, that all the properties of a SSC Server that are not mentioned in a JSON message are left unchanged.
SSC Data Structure Specification • true: the boolean true value. • false: the boolean false value. • null: indicates a missing value; used as pseudo argument for getter-methods. The SSC Server MAY auto-convert elementary data types without further indication to their specific purpose. The client is usually informed about the actual value used by the SSC Server in the response to the SSC method execution.
SSC Data Structure Specification The SSC Address of a SSC Method is a symbolic name giving the full path to the SSC Method in the SSC Address Space, starting from the root of the tree. A SSC Method’s SSC Address begins with the character "/" (forward slash), followed by the names of all the containers, in order, along the path from the root of the tree to the SSC Method, separated by forward slash characters, followed by the name of the SSC Method.
SSC Data Structure Specification 4. A comma-separated list of strings enclosed in curly braces (e.g., {foo,bar}) in the SSC Address Pattern matches any of the strings in the list. 5. Any other character in an SSC Address Pattern can match only the same character. When an SSC Address Pattern is dispatched to multiple SSC Methods, the order in which the matching SSC Methods are invoked is unspecified.
SSC Data Structure Specification TX: { "presets": { "bank1": { "carriers": null }}} RX: { "presets": { "bank1": { "carriers": [470000,470400,470800, 471200,471600] }}} TX: { "presets": { "bank1": { "carriers": [ null ,470450, null, 471250, null ] }}} RX: { "presets": { "bank1": { "carriers": [470000,470450,470800, 471250,471600] }}} 3.3.5.
SSC Data Structure Specification If the specified value for count is negative, then the array range shall contain as many elements as the array size plus the specified value (e.g., -1 indicates all but one array element). In SSC Method Replies, all values of a range specification MUST be given as positive numbers, even if they were specified with negative values in the SSC Method Call.
SSC Data Structure Specification An SSC Message may contain the SSC method /osc/timetag in addition to other methods. In this case, the SSC Time Tag indicates the time when the SSC Server shall execute all of the methods contained in an SSC Message. If the time represented by the SSC Time Tag is before or equal to the current time, the SSC Server should invoke the methods immediately (unless the user has configured the SSC Server to discard messages that arrive too late).
SSC subscriptions - /osc/state/subscribe 4. SSC subscriptions - /osc/state/subscribe A subscription request is sent by a client to a server for an address pattern to subscribe to. The SSC Server normally accepts the subscription request, and remembers that the requesting client wishes to be notified about value changes of the subscribed addresses. The SSC Server MAY refuse subscription requests, subject to device-specific policy or implementation specific limitations.
SSC subscriptions - /osc/state/subscribe Optional subscription request parameters related to termination: • "cancel" "true" cancels the subscription (default false). • "count" maximum number of notifications to send, default 1000 • "lifetime" maximum lifetime (s) of the subscription, default 10s The SSC Client may renew a subscription at any time, thereby resetting all of the lifetime limitations.
General SSC Address Schema 5. General SSC Address Schema Some parts of the SSC address space are reserved by this specification for purposes of meta-protocol information, generic device-independent features, and device capability description. The reserved parts of the address space are rooted in the addresses: /osc /device /internal The addresses and methods rooted in these reserved addresses are described in the following sections.
General SSC Address Schema TX: { "out1": { "xlr1": { "mute": true }, "xlr23": { "gain": 3 }}, "out2": { "xlr1": { "gain": 42 }}} RX: { "osc": { "error": [ { "out1": { "xlr23": [ 404, { "desc": "not found" }]}, "out2": { "xlr1": [ 307, { "desc": "not just now" }]}} ] }, "out1": { "xlr1": { "mute": true }} } If the request message violates the JSON syntax, the complete message cannot reliably be parsed and MUST NOT be partially parsed or executed, so that the SSC Server MUST send an error
General SSC Address Schema 408 request time out 409 conflict 410 gone 413 request too long 414 request too complex 416 requested range not satisfiable 422 unprocessable entity (error in a complex method parameter) 423 locked 424 failed dependency 450 answer too long 454 parameter address not found (e.g., address in a subscription request) 5.1.2.5 5xx - Server Error 500 internal server error 501 not implemented 503 service unavailable 5.1.
General SSC Address Schema Note that the responses are empty JSON objects if the address is an SSC Container for more addresses, JSON null if the address is an SSC Method Address. The method /osc/schema may be called with a null parameter. This is equivalent to querying for the root address schema.
General SSC Address Schema Examples: TX: { "osc": { "limits": [ { "out1": { "xlr1" : { "level" : null }}} ] }} RX: { "osc": { "limits": [ { "out1": { "xlr1" : { "level" : [{ "type": "Number", "min": -10, "max": 18, "inc": 3, "units": "dB", "desc": "output level" }] }}} ] }} TX: { "osc": { "limits": [ { "main_format": null } ] }} RX: { "osc": { "limits": [ { "main_format" : [{ "type": "String", "desc": "main output mode", "option": [ "analogue", "digital" ], "option_descr": [ "analogue", "digital AES3" ] }]
General SSC Address Schema If "bw" is greater than 0, then the bandwidth consumed for notification replies is tracked by the SSC Server, and notifications are suppressed when the specified bandwidth would be exceeded. If any notification has been suppressed due to bandwidth limitation, the SSC Server SHOULD send a notification about the actual value of the subscribed address as soon as the bandwidth limitation can be met again.
General SSC Address Schema message to the subscription request, with the reply value including only the successful addresses. In this case the SSC Error state MUST be set to "210 – Partial Success", and MAY be accompanied by a parameter named "failed_addresses" with an Array of Address trees composed of all the failed Method Addresses (erroneous Addresses replaced by {}), in bundled or unbundled representation.
General SSC Address Schema TX: { "osc": { "state": { "subscribe": [ { "out1": { "xlr\*": { "level": null }}} ] }}} RX: { "osc": { "state": { "subscribe": [ { "out1": { "xlr1": { "level": null }, "xlr2": { "level": null }}} ] }}} RX: ... RX: RX: ... RX: ...
General SSC Address Schema {"device":{"log": [{ "index": 1017, "count": 1 }, "required operating reactivity margin violated"] }} ... {"osc":{"error": [{ "device": { "log": [ 310, {"desc": "subscription terminates"} ] } }] }} 5.1.9 SSC reply output style - /osc/state/prettyprint An SSC Server MAY support this Method to allow the SSC Client to select a preferred formatting style for all SSC reply messages to be sent on the connection to the SSC Client by the SSC Server.
General SSC Address Schema ... 3 seconds pass .. RX: { "osc": { "ping": null }} 5.1.12 SSC Method time stamps - /osc/timestamp This method may be called as part of an SSC Message to estimate the communication delay and clock offset between SSC Client and server. Like in NTP or PTP, four timestamps are used, forming an array. The SSC Client sends the method call and provides the array containing the first, client-side timestamp.
General SSC Address Schema ? matches on partial addresses are supported [ matches on character ranges are supported Example: TX: { "osc": { "feature": { "pattern": null }}} RX: { "osc": { "feature": { "pattern": "*" }}} If the SSC Server does not support address pattern matching at all, it MAY also reply with false. 5.1.14.2 Support for time tags A client may query /osc/feature/timetag to inquire whether the SSC Server supports timed method execution.
General SSC Address Schema 5.2.4 /device/identity/vendor Read-only string: often "Sennheiser". 5.2.5 /device/name User-settable persistent device name. This name should be the preferred, and most convenient way for the customer to identify devices. If the device has a display, this name should be displayed there, preferably in the network context; if it has a menu, this name should be configurable or it COULD be derived from /device/system or/and e.g. /device/location.
General SSC Address Schema implement the IPv4 address space. 5.2.10.1 /device/network/ether/interfaces Read-only array containing a list of all the user-relevant ethernet interface of the device. The names SHALL match the user-readable labeling of the connectors of the device. If the physical port on the device do not carry a textual label, then the textual designation in the user manual of the product SHALL be used. Internal interfaces which are not accessible to the user MUST NOT be listed here.
General SSC Address Schema Read-only array relating to /device/network/ether/interfaces. The array contains numbers indexing into the array of physical interface names, and thus also into the array of interface MAC addresses at /device/network/ether/macs. The interface index array MUST contain the indices of all physical interfaces which share the IPv6 configuration accessible by the following methods. 5.2.10.
SSC Transport Layer Adaptations 6. SSC Transport Layer Adaptations The SSC data format as defined in the previous sections can be transported by different transport protocols, or stored in persistent files. This section specifies what transports are supported, and how the specific features of transport layers shall be applied to transporting SSC Messages. If an SSC Server supports more than a single transport for SSC, it SHALL behave consistently regardless of the transport used. 6.
SSC Transport Layer Adaptations 6.3 SSC Server Discovery If IP network devices implement a discovery protocol then it MUST be DNS-SD (Apple Bonjour). The discovery service CAN optionally be enabled or disabled by the application. The DNS Service-Type is specified as "_ssc". Because all networked SSC Servers must implement SSC-over-UDP, they MUST all publish a DNS-SD service under "_ssc. _udp". Those servers that additionally support TCP MUST publish another DNSSD service under "_ssc._tcp".
Developer’s Guide for EM 9046 7. Developer’s Guide for EM 9046 This chapter describes in detail how a developer should use the SSC interface as implemented for the EM 9046. 7.1 Transport layers The EM9046 provides SSC service over TCP/IPv6 port 45 UDP/IPv6 port 45 TCP/IPv4 port 45 UDP/IPv4 port 45 SSC Clients can choose the transport best suited for the specific application.
Developer’s Guide for EM 9046 RX: { "rx2": { "identity": { "product": "EM9046DRX" } }, "rx6": { "identity": { "product": "EM9046DRX" } }, "rx7": { "identity": { "product": "EM9046DRX" } }, "rx8": { "identity": { "product": "EM9046DRX" } }, "audio1": { "identity": { "product": "EM9046DAO" } }, "device": { "identity": { "product": "EM9046" } }} Metering data in container /m and transmitter information in container /mates depends on the hardware configuration, too.
Developer’s Guide for EM 9046 7.4.4 /device/identity/serial Serial number. • limits type: String const: true writeable: false subscr: true 7.4.5 /device/name Network name for identification including discovery. EM9046 names are always 8 characters long, shorter names are filled with spaces. Only characters from the set of uppercase letters A-Z, digits 0-9, and $()_~ are allowed. • limits type: String const: false writeable: true length: 8 subscr: true 7.4.
Developer’s Guide for EM 9046 7.4.9 /device/network/ipv4/netmask List of current IPv4 netmasks corresponding to list of IPv4 interfaces. • limits type: String const: false writeable: false length: 2 subscr: true 7.4.10 /device/network/ipv4/manual_netmask List of manual IPv4 netmasks corresponding to list of IPv4 interfaces. • limits type: String const: false writeable: true length: 2 subscr: true 7.4.
Developer’s Guide for EM 9046 7.4.14 /device/network/ipv4/ipaddr List of current IPv4 addresses corresponding list of IPv4 interface names * example: ["10.27.1.46”, "10.27.1.46”]. • limits type: String const: false writeable: false length: 2 subscr: true 7.4.15 /device/network/ipv4/gateway List of current IPv4 gateways corresponding list of IPv4 interface names. • limits type: String const: false writeable: false length: 2 subscr: true 7.4.
Developer’s Guide for EM 9046 7.4.19 /device/carrier_ranges/max_carrier_frequencies Antenna booster range maximum frequencies • limits type: Number count: 8 const: false writeable: false units: kHz subscr: true 7.4.20 /device/carrier_ranges/labels Antenna booster range designations, e.g. ["B1","B2","B3","B4","B5","B6","B7","B8"] • limits type: string count: 8 const: false writeable: false subscr: true 7.4.
Developer’s Guide for EM 9046 7.4.24 /device/carrier_scan/carrier_range*/control Write true to start, false to stop range scan. Read: true if scan is running, false otherwise. • limits type: Boolean const: false writeable: true subscr: true 7.4.25 /device/carrier_scan/carrier_range*/carrier_frequencies Array of carrier scan frequencies. • limits type: Number const: false writeable: false count: 960 units: kHz max: 831000 min: 470000 inc: 25 subscr: true 7.4.
Developer’s Guide for EM 9046 units: kHz max: 831000 min: 470000 inc: 25 subscr: true 7.4.29 /device/wordclock/status Wordclock state description, e.g., "external: 48.0kHz". type: String const: false writeable: false subscr: true 7.4.30 /device/wordclock/mode Wordclock setting. • limits type: String const: false writeable: true options: 1. internal 44.1kHz 2. internal 48.0kHz 3. internal 88.2kHz 4. internal 96.0kHz 5. external 6.
Developer’s Guide for EM 9046 type: String const: false writeable: true options: 70-80 names depending on software release subscr: true 7.4.34 /device/timesync_ntp Enable automatic network time synchronisation (NTP). • limits type: Boolean const: false writeable: true subscr: true 7.4.35 /device/timeprecision Time precision (0.1s) • limits type: Number const: true writeable: false units: s subscr: true 7.4.
Developer’s Guide for EM 9046 7.4.39 /device/errors Array of active error messages. • limits type: String const: false writeable: false count: 10 subscr: true 7.4.40 /device/language The language/location setting; currently always en_GB. • limits type: String const: false writeable: false subscr: true 7.5 /rx* - receiver channels These SSC containers represent the up to 8 receiver channels of the EM9046.
Developer’s Guide for EM 9046 7.5.4 type: String const: false writeable: false subscr: true /rx*/name Channel name. • limits type: String const: false writeable: false length: 8 subscr: true 7.5.5 /rx*/carrier_frequency Channel carrier frequency. • limits type: Number const: false writeable: true units: kHz max: 831000 min: 470000 inc: 25 subscr: true 7.5.6 /rx*/preset Channel carrier preset. SSC address of chosen preset carrier frequency.
Developer’s Guide for EM 9046 7.5.9 units: kHz max: 831000 min: 470000 inc: 25 subscr: true /rx*/rf_mode Channel RF modulation mode. Switches automatically to the received signal, and can not be changed. • limits type: String const: false writeable: false options: , option_desc 1. HD , high-definition rf modulation 2. LR , long-range rf modulation subscr: true 7.5.
Developer’s Guide for EM 9046 7.5.13 /rx*/mates SSC addresses of transmitters and antenna boosters associated to channel, e.g. ["/mates/antenna_booster1", "/mates/tx1" ] • limits type: String count: variable const: false writeable: false subscr: true 7.5.14 /rx*/audio SSC addresses of audio outputs connected to channel audio, e.g. ["/audio1/out3”, "/audio2/out5”, "/ audio2/out6”] • limits type: String count: variable const: false writeable: false subscr: true 7.5.
Developer’s Guide for EM 9046 const: false writeable: true subscr: true 7.5.19 /rx*/sync_settings/rf_mode Channel transmitter RF modulation mode for sync. • limits type: String const: false writeable: true options: , option_desc 1. HD , high-definition rf modulation 2. LR , long-range rf modulation subscr: true 7.5.20 /rx*/sync_settings/name Channel transmitter name for sync, always equal to /rx*/name.
Developer’s Guide for EM 9046 7.5.23 /rx*/sync_settings/lock Transmitter key-lock setting for sync. • limits type: Boolean const: false writeable: true subscr: true 7.5.24 /rx*/sync_settings/gain Transmitter audio gain for sync. • limits type: Number const: false writeable: true units: dB max: 60 min: − 6 inc: 3 subscr: true 7.5.25 /rx*/sync_settings/encryption Channel transmitter encryption mode for sync.
Developer’s Guide for EM 9046 3. type2 , cable emulation type 2 4. type3 , cable emulation type 3 subscr: true 7.6 /audio* - audio output modules The SSC tree for each audio output module depends on the type of the module. Slots OUT1 and OUT2 are represented by containers /audio1 and /audio2, respectively. Both slots can contain an analogue output module EM9046AAO or digital output module EM9046DAO. Slot MAN is represented by container /audio3. It can contain a network audio module EM9046DAN. 7.6.
Developer’s Guide for EM 9046 7.6.3 Network audio module EM9046DAN The digital output module EM9046DAN supports 16 network audio channels, in containers /audio3/ out1 to /audio3/out16. The out* containers correspond to the following network streams (as reflected in SSC methods /audio3/out*/label): out1: main audio stream 1 out2: main audio stream 2 ... out8: main audio stream 8 out9: aux audio stream 1 out10: aux audio stream 2 ...
Developer’s Guide for EM 9046 writeable: false subscr: true 7.6.8 /audio*/identity/vendor Vendor name of the product ("Sennheiser electronic GmbH & Co. KG"). • limits type: String const: false writeable: false subscr: true 7.6.9 /audio*/out*/label Audio output connector label, e.g. "XLR 3" • limits type: String const: true writeable: false subscr: true 7.6.10 /audio*/out*/inputs SSC addresses of audio sources for this output, e.g.
Developer’s Guide for EM 9046 7.7 /m - metering data All metering data is bundled in container /m, so that it can be subscribed comprehensively, and without too much overhead. All metering methods yield arrays, where each element represents data from a specific RX channel. The data sources are listed in method /m/sources as SSC addresses. The first element of /m/sources (e.g., /rx3) means that all first elements of the methods /m/rssi_a, /m/rssi_b, etc., correspond to the respective channel (e.g., CH3).
Developer’s Guide for EM 9046 7.7.1 /m/sources SSC addresses of metering sources, e.g. ["/rx1","/rx2","/rx3","/rx4"] • limits type: String count: 0-8 const: true writeable: false subscr: true 7.7.2 /m/rssi_a RF A signal strength indicator for each metering rxN source. • limits type: Number count: 0-8 const: false writeable: false units: dBm max: 0 min: -127.5 subscr: true 7.7.3 /m/rssi_b RF B signal strength indicator for each metering rxN source.
Developer’s Guide for EM 9046 7.7.6 writeable: false units: % max: 100 min: 0 subscr: true /m/divi_a RF A diversity indicator for each metering rxN source. • limits type: Number count: 0-8 const: false writeable: false units: max: 1 min: 0 subscr: true 7.7.7 /m/divi_b RF B diversity indicator for each metering rxN source. • limits type: Number count: 0-8 const: false writeable: false units: max: 1 min: 0 subscr: true 7.7.
Developer’s Guide for EM 9046 7.8.1 /mates/active list of SSC relative addresses of active connected devices, e.g. ["tx1", "tx5", "antenna_booster1", "antenna_booster2"] • limits type: String const: false writeable: false subscr: true 7.8.2 /mates/antenna_booster*/label Connector label: "RF IN A" • limits type: String const: true writeable: false subscr: true 7.8.3 /mates/antenna_booster*/identity/product Product type, e.g.
Developer’s Guide for EM 9046 • limits type: String const: false writeable: false subscr: true 7.8.8 /mates/tx*/switch1/state Channel transmitter switch state (true=pressed). • limits type: Boolean const: false writeable: false subscr: true 7.8.9 /mates/tx*/switch1/label Channel transmitter switch designation ("CMD" or ""). • limits type: String const: false writeable: false subscr: true 7.8.10 /mates/tx*/rf_mode Channel transmitter RF modulation mode.
Developer’s Guide for EM 9046 7.8.13 /mates/tx*/lock Channel transmitter key-lock setting. • limits type: Boolean const: false writeable: false subscr: true 7.8.14 /mates/tx*/gain Channel transmitter audio gain. • limits type: Number const: false writeable: false units: dB max: 60 min: -6 inc: 1 subscr: true 7.8.15 /mates/tx*/encryption Channel transmitter encryption mode. • limits type: String const: false writeable: false subscr: true 7.8.
Developer’s Guide for EM 9046 7.8.18 /mates/tx*/cable_emulation Channel transmitter cable emulation mode. • limits type: String const: false writeable: false subscr: true 7.8.19 /mates/tx*/bat_state Channel transmitter battery state, either bat_lifetime or bat_gauge. • limits type: Number const: false writeable: false subscr: true 7.8.20 /mates/tx*/bat_lifetime Channel transmitter battery lifetime in seconds.
Developer’s Guide for EM 9046 7.9 /osc - SSC features 7.9.1 /osc/state/prettyprint SSC reply output style is not supported. Returns false. 7.9.2 /osc/state/close SSC session close. 7.9.3 /osc/state/subscribe SSC subscriptions. 7.9.4 /osc/feature/array_ranges SSC array ranges are supported. Returns true. 7.9.5 /osc/feature/timetag SSC timed method execution is not supported. Returns false. 7.9.6 /osc/feature/baseaddr SSC interactive method address base is not supported. Returns false. 7.
SSC Error List 8.
Network Audio Monitoring 9. Network Audio Monitoring The EM9046 provides a network audio streaming service for monitoring purposes. 9.1 Audio Streaming Standards The audio streaming concept is based on open Internet-standards. It aims to be compatible with Ravenna, omitting the clock synchronisation features (http://ravenna. alcnetworx.com/technology/technology-overview.html).
