OSC Reference Documentation

General

KLANG:fabrik and KLANG:vier can be entirely remote controlled with network message. The widely used Open Sound Control (OSC) protocol is used for communication and control between all KLANG devices and the remote devices.

Documentation on the Open Sound Control protocol can be found at: http://opensoundcontrol.org/ For the control of the KLANG:fabrik only single messages are used, i.e. no bundles.

Routing and configuration of the Dante modules inside KLANG:fabrik/KLANG:vier cannot be remote controlled in this way. Audinate’s Dante Controller has to be used instead.

It is recommended to use KLANG:app officially released by KLANG:technologies! Communication and functionality cannot be guaranteed when experimenting with own implementations of the remote control protocol as disclosed in this document.

Make sure that your KLANG operating system version is compatible with this documentation. Syntax, Protocol and labels might be changed in future by KOS updates.

Current KOS 2.1.9 / KOS 2.2 (beta)

Definitions

Naming and Typing Convention

The receiving device’s type is encoded in the address pattern:

  • For KLANG hardware – /KLANGfabrik (long pattern) or /Kf (short pattern)
  • For KLANG:app – /KLANGapp (long pattern) or /Ka (short pattern)

In the following the OSC syntax is shown for the long pattern:

  • String – s (we use hyph)
  • Integer – i
  • Float – f
  • Bool – B – possible argument is <ONorOFF> which is either 1 | TRUE or 0 | FALSE.

A user identification number <UID> is required to be attached as a string in the end of each OSC message with exactly 32 characters identifying the remote device uniquely, e.g.: ‘xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx’

Example:

  • /KLANGfabrik/user/MasterSlider, ‘fs’, 1, ‘xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx’

Ports and Answers

Answers are sent back to the device that requested an answer. Devices are recognized according to their UID and not according to their IP address.

OSC is send via UDP packets strictly on port 9110 to KLANG hardware.

The hardware answers are sent back on <ReceivePort> – default value is 9111.

3     Control user settings

Controlling the user settings is implemented in two ways. The first approach uses a handshake prior to sending controls of e.g. level or position for this particular user. The second approach encodes the user number in the address pattern and as referred to as SHORT in the following.

Handshake

A handshake and a switch user command must be sent before using any long format OSC messages. in the normal format syntax, since the user number is not encoded in the message. This handshake ist not required for the short synthax messages.

  • /KLANGfabrik/control/ConnectRequest,’is’,<ReceivePort>, <UID>

Answers or responses to this handshake are:

  • /KLANGapp/control/HereIam
  • /KLANGapp/control/UserInfo

The latter one is followed by these arguments ‘Name’,’ Icon’, ‘outputUser’, ‘password’, ‘SN’, ‘localIP’, ‘localPort’, ‘typeOfProduct’, ‘Firmware’, ‘LinkedOutput’, ‘UID’. Furtermore, relayed messages may be sent.

Switch user

Switch to another user to accept the subsequent control messages of e.g. level and position.

  • /KLANGfabrik/control/SwitchUser, ‘iss’, <USERnumber>, <password>, <UID>
  • <USERnumber> corresponds to the labeling of the analog outputs in normal configuration USER1 to USER8. If not routed to the DAC or something else is changed in routing it corresponds to the output channels of the DSP in the following way: USER1 – channel 1–2, USER2 – channel 3–4 etc. This option should be preferred.
  • <password> is an empty string if not changed.

Level meters

Meters are continuously sent (every 50–200ms) to remote control devices with the following syntax:

  • /KLANGfabrik/user/OutputLevelMeterUpdate, ‘iffiff…’
  • /KLANGfabrik/user/InputLevelMeterUpdate, ‘iffiff…’
  • Devices that did not send any message for more than 60 seconds will not receive any further messages.

These messages can be disabled by:

  • /KLANGfabrik/user/wantsMeterUpdates, ‚B’ <ONorOFF >, <UID>

Relayed messages

Deactivate the re-direction of incoming messages to KLANG:fabrik from another remote control to THIS remote control device.

  • /KLANGfabrik/user/DeviceWantsRelayedMessages, ‘Bs’, <ONorOFF>, <UID>

Master fader

Controls the overall level of the entire mix of a user.

  • /KLANGfabrik/user/MasterSlider, ‘fs’,<GAIN>,<UID>
  • /Kf/ui/ <USERnumber> /gain, ‘f’, <GAIN>
  • <GAIN> floating point number between 0 (-infinity dBFS) and 1 (0 dBFS) in linear scale.

Channel faders

Set the volume for an instrument for a particular user:

  • /KLANGfabrik/user/ChannelFader, ‘ifs’, <ChannelNumber>, <GAIN>, <UID>
  • /Kf/ui/ <USERnumber> /ch/ <ChannelNumber> ‘/gain’ , ‘f’ , <GAIN>

Visible, MUTE, Solo

Setting the visibility of an input channel (invisible channels are inherently muted):

  • /KLANGfabrik/user/ChannelVisible , ‘iBs’, <ChannelNumber>, <ONorOFF>, <UID>
  • /Kf/ui/ <USERnumber> /ch/ <ChannelNumber> /visible , <ONorOFF>

Muting a channel:

  • /KLANGfabrik/user/ChannelMute , ‘iBs’, <ChannelNumber>, <ONorOFF>, <UID>
  • /Kf/ui/ <USERnumber> /ch/ <ChannelNumber> /mute , <ONorOFF>

Soloing a channel:

  • /KLANGfabrik/user/ChannelSolo , ‘iBs’, <ChannelNumber>, <ONorOFF>, <UID>
  • /Kf/ui/ <USERnumber> /ch/ <ChannelNumber> /solo , <ONorOFF>

 

Channel positions

The position of the instruments or channels is controlled in cartesian coordinates with 3 separate variables <X>, <Y>, <Z>.

  • /KLANGfabrik/user/ChannelPosition , ‘ifffs’ , <ChannelNumber>, <X>, <Y>, <Z>, <UID>

<X>, <Y> position the instruments in the same manner as the ORBIT view in KLANG:app. The value of the norm of the defined by the 3 coordinates is used to distinguish between i3D (radius = 0.85), 3D (0.64) and standard stereo panning. Between i3D (radius), 3D and standard stereo panning. A mono setting is achieved by the coordinates 0, 0, 0. The following screenshot illustrates the axis used.

Elevation is modified by:

  • /Kf/ui/ <USERnumber> /ch/ <ChannelNumber> /theta , ‘f’, <Theta>

<Theta> is the angle in degrees between –90° (below), 0° (on the horizon) and 90° (above).

Azimuth is modified by:

  • /Kf/ui/ <USERnumber> /ch/ <ChannelNumber> /phi , ‘f’, <Phi>

<Phi> is the angle in degrees between 0° (in front), 90° (left) 180° (behind) and 360° (in front). Counter clockwise.

The source is transfered from mono to stereo, to the 3D and i3D orbit by the following message with <Mode> being 1, 2, 3, and 4 respectively:

  • /Kf/ui/ <USERnumber> /ch/ <ChannelNumber> /mode , ‘i’, <Mode>

 

Cue mode

The CUE mode mirrors the output of one user to another user. A handshake has to be passed at least once in the past. Switch to the user you want to receive the copy of the mix from another user. <USERnumber> is the source of the signal defined by the user number. To disable the CUE mode set <USERnumber> to 0.

  • /KLANGfabrik/user/LinkMonitorOutput , is, < USERnumber >, <UID>
  • Kf/ui/ <USERnumberTO>, <i>, <USERnumberFROM> TODO

4    KLANG:vektor controls

Configuration – WIFI and network settings

The KLANG:vektor receives OSC commands. These can be used to configure the KLANG:vektor to connect to a different WiFi network, e.g. when currently connected in AccessPoint (AP) mode.

Regular working mode

The BATT led states the voltage and the NET led blinks cyan when orientation packets are sent

Self identification

Let the device LED blink green four times to attract attention.

  • /KV/CMD, s, <“BLINKLED”>, Port 8484

Manual Referencing

The “REF” (look to the front and hold the REF-Button) and “NOD” (look down and release the REF-Button) can be done with the following two OSC commands:

  • /KV/CMD, s, <“REF”>, Port 8484
  • /KV/CMD, s, <“NOD”>, Port 8484

Activate Access-Point mode

Stops sending orientation packets and enters the Access Point mode.

  • /KV/CMD, s, <“APGP”>, Port 8484

Warning: doing so in live usage will immediately stop the head tracking function!

Self identification on the network

There are 2 possibilities to discover vektor devices on the network:

  • /KV/CMD, s, <“LIST”>, Port 8484                                      <->    /KLANGapp/vektor/HereIAm, s, <XML with Infos>*, Port 9110
  • /KLANGfabrik/control/ConnectRequest, is, Port 9111    <->    /KLANGapp/control/UserInfo

Change the target KLANG device

Saved the new target serial of a KLANG:fabrik / KLANG:vier and tries to get the device IP. When found, it will start to send orientation information to the new IP.

  • /KV/CMD, s, <“Serial”>, Port 8484

Orientation

The KLANG:vektor sends its current orientation to the destination IP address with a fixed timer (range 10–30 ms). The orientation is decoded in normalized floating point quaternions (4 values, <Q1> to <Q4>), which is sent out as:

  • /KLANGfabrik/vektor/Orientation, ffffs, <Q1>, <Q2>, <Q3>, <Q4>, <UID>
  • /Kf/Q, ffffs, <Q1>, <Q2>, <Q3>, <Q4>, <UID>

Quaternions are used as follows:

  • Looking in front direction to the horizon, both ears on same height: [1,0,0,0] – Reference direction
  • Nod 45 degrees from reference direction towards bottom (pitch): [0.9239, 0, –0.3827, 0]
  • Rotate 90 degrees from reference direction to the right (yaw): [sqrt(2), 0, 0, –sqrt(2)]
  • Roll 45 degrees to the left (left ear lower than right ear): [0.9239, 0.3827, 0, 0]
  • UID for KLANG:vektor has to start with “Kv-” to appear in the tracker list, e.g. “Kv-A”

Access Point mode

When the vektor is in access-point (ap) mode, the NET led lights blue.

Target SSID and Password

When the following two packets are received, the AP is disabled and the device tries to enter the wireless network with the given SSID:

  • /KV/SSID, s, <Target SSID>, Port 8484
  • /KV/PW, s, <Target Password>, Port 8484

If the target serial should be adressed directly after disabling the AP mode, the packets hate to be received in this order:

  • /KV/Serial, s, <Target Serial>, Port 8484
  • /KV/SSID, s, <Target SSID>, Port 8484
  • /KV/PW, s, <Target Password>, Port 8484

 

Status Data

When the ap mode is enabled, the device sends 2 types of OSC packets periodically as a broadcast:

  • /KLANGapp/control/UserInfo
  • /KLANGapp/vektor/HereIAm, s, <XML with Infos>*, Port 9110

*)

The infos included in the XML string are as follows:

[coming soon]

5     Main System controls

The following messages control the main system of the KLANG hardware.

Audio Routing Matrix

The routing of each block containing 8 channels can be set by:

  • /KLANGfabrik/Hardware/ConnectSinkToSource,’iis’, <SINK>, <SOURCE>, <UID>

The <SINK> is the destination and the <SOURCE> is the origin of an audio data stream. A sink can only be associated with exactly one source. A source can however be streamed to several sinks in parallel. Both variables can have the following values (DACs can only be a sink, None cannot be a sink) with its associated abstract descriptor:

  1. NONE, not connected – cannot be a sink
  2. Optical Input 1
  3. Optical Input 2
  4. Optical Input 3
  5. Optical Input 4
  6. DSP input | output block no.1 – channels 1–8
  7. DSP input | output block no.2 – channels 9–16
  8. DSP input | output block no.3 – channels 17–24
  9. DSP input | output block no.4 – channels 25–32
  10. Dante brooklyn module block no.1 – channels 1–8
  11. Dante brooklyn module block no.2 – channels 9–16
  12. Dante brooklyn module block no.3 – channels 17–24
  13. Dante brooklyn module block no.4 – channels 25–32
  14. Dante brooklyn module block no.5– channels 33–40
  15. Dante brooklyn module block no.6 – channels 41–48
  16. Dante brooklyn module block no.7 – channels 49–56
  17. Dante brooklyn module block no.8 – channels 57–64
  18. DAC – Digital Analog Converter – USER 1–4 | channels 1–8 – cannot be a source
  19. DAC – Digital Analog Converter – USER 5–8 | channels 9–16 – cannot be a source.

Clock Source

The clock source is set by:

  • /KLANGfabrik/Hardware/ClockSource, ‘is’, <ClockSource>, <UID>

The variable <ClockSource> can have the following integer values with its associated descriptor:

  1. KLANG:fabrik is master – default 48kHz
  2. Sync to Optical Input 1;
  3. Sync to Optical Input 2
  4. Sync to Optical Input 3
  5. Sync to Optical Input 4
  6. Sync to Word Clock input
  7. Sync to Dante network – Further clock settings available in the Dante Controller.

Presets & Snapshots

Request the list of presents. Answer contains this list.

  • /KLANGfabrik/control/RequestListOfPresets

Change preset (system wide, for all users). <presetName> must match exactly the name of the preset (case-sensitive) without ending (.xml).

  • /KLANGfabrik/control/presetSelect, ss, <presetName>, <UID>

Copy settings of this user:

  • /KLANGfabrik/control/SetDefaultSettings, is, <USERnumber> , <UID>

Paste settings to this user:

  • /KLANGfabrik/control/LoadDefaultSettings, is, <USERnumber> , <UID>

Snapshots

Take snapshot:

  • /KLANGfabrik/control/TakeSnaphot ,ss <SnapshotName> , <UID>

Delete Snapshot

  • /KLANGfabrik/control/DeleteSnaphotById, is, <SnapshotID> , <UID>

Move up Snapshot

  • /KLANGfabrik/control/MoveSnapshotUp , is, <SnapshotID> , <UID>

Move down Snapshot

  • /KLANGfabrik/control/MoveSnapshotDown, is, <SnapshotID> , <UID>

Recall Snapshot

  • /KLANGfabrik/control/RecallSnapshotById, is, <SnapshotID> , <UID>

Update Snapshot

  • /KLANGfabrik/control/UpdateSnaphot, is, <SnapshotID> , <UID>

Please note it says “Snaphot” without “s” in KOS 2.1.x

Optional: + pushStr(“RecallSafeOptions“) + pushInt32(RecallSafeOption1) + pushInt32(RecallSafeOption2) + … ]. RecallSafeOptions are Integers with the following representation:

  • MASTER_VOLUME = 1
  • MODE_LIMIT = 2 (mono, stereo, 3D, i3D)
  • CHANNEL_VOLUMES = 3
  • CHANNEL_POSITIONS = 4
  • CHANNEL_MODES = 5 (mono, stereo, 3D, i3D)
  • SOLO_MUTE_STATES = 6

Configuration Commands

Assign a new name <NEWname> to user

  • /KLANGfabrik/control/RenameUser, iss, <USERnumber>, <NEWname>, <UID>

Request list of trackers. Answer contains this list.

  • /KLANGfabrik/control/RequestListOfTrackers

Change the associated motion tracker <TRACKERid> for a user

  • /KLANGfabrik/control/changeTracker, ss, < TRACKERid >, <UID>

Additional Commands

Trigger a restart (system will be back to normal after reboot)

  • /KLANGfabrik/Hardware/Restart (no arguments)

Set display brightness. <Brightness> between 0 (off) and 1 (bright).

  • /KLANGfabrik/Hardware/DisplayBrightness, fs, <Brightness>, <UID>

Request information as on the INFO screen in the GUI. Answer is an XML file in one single string.

  • /KLANGfabrik/Hardware/StatusUpdate

Set number of input channels <NumIns> and number of users <NumUsers>.

  • carefully check the values with the maximum processing power as specified in the table in the manual. Overloading might lead to a device that is not able to be remote controlled. audio might have drop outs.
  • /KLANGfabrik/Hardware/SetNumberOfInputsAndOutputs, iis, <NumIns >, <NumUsers>, <UID>

6    KLANG:app Remote Control

The KLANG:app (starting from version 2.2.0) can be remote controlled from the network. Please use Port 9111 to communicate with the KLANG:app.

User Interface Commands

Switch to Fader-View

  • /Ka/screen/FADERS1

Switch to Group-View

  • /Ka/screen/FADERS2

Switch to Stage-View (Orbit)

  • /Ka/screen/STAGE1

Switch to Stage-View (Landscape)

  • /Ka/screen/STAGE2 – landscape view

Switch to Meters-View

  • /Ka/screen/METERS – orbit view

Switch to Config-View (Last page that was selected)

  • /Ka/screen/CONFIG

Change User

  • /Ka/screen/user, i, <userID>

Connect to KLANG:fabrik

  • /Ka/control/connect, si, <remoteAdress>  <userID>

Change App-Mode (0 = Musician, 1 = Technician, 2 = Admin)

  • /Ka/control/mode, i , <mode>

 

–END–

Print Friendly