Manuals

OSC Reference Documentation

KLANG:app and the KLANG Immersive In-Ear Mixing Processors communicate exclusively via Open Sound Control (OSC) UDP network messages. Messages to a KLANG processor need to be sent to port 9110. Messages to KLANG:app need to be sent to 9111 (by default).
Routing and configuration of the Dante modules inside KLANG:fabrik/KLANG:vier/KLANG:vokal cannot be remote controlled in this way. Audinate’s Dante Controller has to be used instead.
DISCLAIMER: 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 change with KOS and :app updates in the future.

How to send OSC and test the command?

Send Custom OSC

In KLANG:app use keyboard shortcut

  • Mac: CMD + Shift + O
  • Windows: Ctrl + Shift + O

At the bottom the syntax for our command line tool KLANGosc will be shown, e.g. KLANGosc 10.11.12.201 9110 /test i 1

KLANGosc | The command line tool

KLANG has developed a command line tool for Windows and Mac. This can be used to easily send OSC from the command line and try the commands described above.

Syntax:
KLANGosc <IPaddress> <portNumber> <OSCaddressPattern> <argumentType1> <argument 1> <argumentType2> <argument2> …

Most OSC commands can be used with KLANG:app’s built in offline editor (Open KLANG:app > CONFIG > CONNECT > Click on Offline Editor). If you use KLANGosc on the same computer as KLANG:app, simply use the command:
KLANGosc 127.0.0.1 9110 /<yourOscMessage>

This guide describes <OSCaddressPattern> <argumentType1> <argument 1> <argumentType2> <argument2> …

There are examples in the batch and shell scripts included in the download.

Downloads

KLANGosc

Definitions

Naming and Typing Convention

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

  • For KLANG hardware – it is always called fabrik regardless of the processor type – /Kf (short pattern) or /KLANGfabrik (long pattern, only required for some specific messages)
  • For KLANG:app – /Ka (short pattern) or /KLANGapp (long pattern)
Long patterns have mostly become obsolete and wherever there is a short pattern (that does not require any prior handshake) it will be used in this guide instead.

Argument Types used in this Guide:

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

For long syntax OSC messages, a unique identifier <UID> is required to be attached as a string in the end of each long pattern OSC message with exactly 32 or 4  characters identifying the remote device uniquely, e.g. use a string like: “ABCD”

Example:

  • /KLANGfabrik/user/MasterSlider f 1 s "ABCD"
  • Send OSC address /KLANGfabrik/user/MasterSlider and attach one float (f) which is ‘1’ and one string (s) which is "ABCD".
In some applications, e.g. QLAB the argument type does not need to be specified. In this case /KLANGfabrik/user/MasterSlider 1.0 would send the command using a float argument.

UDP Ports and Reply Messages

OSC is send via UDP packets strictly on port 9110 to KLANG hardware. The OSC prefix is always /KLANGfabrik or /Kf regardless if the processor is a :fabrik or something else.

The KLANG processor replies back on the specified <ReceivePort>default value is 9111 – Range 1–65535 (KOS 5.7 and prio, the upper limit was 12000).

For long syntax OSC addresses, devices are recognized by the KLANG processor/kontroller/app according to their UID and not according to their IP address. 

Controlling the mix/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 mix.

KLANG:app can listen on an additional custom Receive Port. This can be configured via KLANGosc 127.0.0.1 9111 /Ka/customReceivePort i <CustomReceiverPortNumber>. Leave blank to delete this additional port again. It can also be set in KLANG:app ppf/settings with the identifier: customReceivePort

The second approach encodes the mix number in the address pattern and as referred to as SHORT in the following.

Handshake (required for LONG syntax only)

faq icon to expand accordian

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 syntax messages.

    • /KLANGfabrik/control/ConnectRequest i <ReceivePort> s <UID>
    • ReceiverPort must be in the range 1–65535. (KOS 5.7 and prior, upper limit was 12000)

Replies to this handshake are included in:

    • /KLANGapp/control/UserInfo

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

Switch mix/user

faq icon to expand accordian

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

    • /KLANGfabrik/control/SwitchUser i <MIXnumber> s <password> s <UID>

    • <MIXnumber> 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

faq icon to expand accordian

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 > s <UID>

Relayed messages

faq icon to expand accordian

Deactivate the relay of incoming messages to KLANG hardware from another remote control to your remote control device.

    • /KLANGfabrik/user/DeviceWantsRelayedMessages b <ONorOFF> s <UID>

Discover Devices on the Network

Send a broadcast message to port 9110 as follows:
KLANGosc 255.255.255.255 9110 /KLANGfabrik/control/ConnectRequest i 9112 i 50609 i 40 s "macOrWindows" s "ABCD"

Devices will reply with /KLANGapp/control/UserInfo for each mix they offer on the specified port (default 9111).

Mix Settings on KLANG Processor

Mix Master Volume

Controls the overall level of the entire mix of a user. <linearGAIN> floating point number between 0 (-infinity dBFS) and 1 (0 dBFS) in linear scale.

  • /Kf/ui/<MIXnumber>/gain f <linearGAIN>
  • /Kf/ui/<MIXnumber>/gaindB 'f' <GAIN in dB>

Mix Name

  • /Kf/ui/ <MIXnumber> /name s <mixName>

Channel GAIN

Set the volume for a input channel <ChannelNumber> for a particular mix <MIXnumber>. The <ChannelNumber> is the number of the input channel to the 3D in-ear mixing engine as shown unter CONFIG > CHANNELS > INPUT.

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/gain f <linearGAIN>
  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/gaindB f <GAIN in dB>

Channel ACTIVITY / VISIBLE

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

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/visible b <ONorOFF>

Channel MUTE

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/mute b <ONorOFF>

Channel SOLO

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/solo b <ONorOFF>

Channel NAME

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/name s <channelName>

Channel COLOR

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/color s <channelColorAs8DigitHexValue>
  • channelColorAs8DigitHexValue contains alpha, red, green, blue, e.g. FFFF0000 is red

Channel ICON

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/name s <iconName>

Channel STEREO LINK

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/stereo i <otherChannelNumberToBeLinked>
  • -1 to unlink

Channel GROUP ASSIGN

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/grp i <groupIndexStartWithZero>

Change GROUP Gain

Set Gain: /Kf/ui/<MIXnumber>/grp/<GroupNumber>/set f <GainInDB> f <LinearMaxValue> B <relativeMixing>

<relativeMixing> true will affect the other group gains as well.

<LinearMaxValue> is 1 for 0dB maximum Fader gain and 2 for +6dB and 3.16 for +10dB.

Increase Gain: /Kf/ui/<MIXnumber>/grp/<GroupNumber>/inc f <IncreaseInDB> f <LinearMaxValue> B <relativeMixing>

The value <IncreaseInDB> can also be negative. Alternative use this to decrease by the amount of <DecreaseInDB>

Kf/ui/<MIXnumber>/grp/<GroupNumber>/inc f <DecreaseInDB> f <LinearMaxValue> B <relativeMixing>

Placement, Panning

The general placement mode for a mix can be set by

  • /Kf/ui/<mixNumber>/mode i <PlacementMode>

PlacementMode: 1=mono, 2=stereo, 3=3D, 4=i3D

Channel ELEVATION

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber>/ele f <ElevationAngleInDegrees>

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

Channel AZIMUTH

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber> /azi f <AzimuthInDegrees>

<AzimuthInDegrees> is the angle in degrees between 0° (in front), 90° (right) 180° (behind), -90 or 270 (left) and 360° (in front again) for sources placed in 3D and i3D orbit. For sources placed in stereo (inside the head) -90 (left), 0 (center), +90 (right).

Channel WIDTH (for stereo linked channels)

  • /Kf/ui/<MIXnumber>/ch/<ChannelNumber> /width f <WidthInDegrees>

Channel MODE

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/<MIXnumber>/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. <MIXnumber> is the source of the signal defined by the user number. To disable the CUE mode set <MIXnumber> to 0.

  • /KLANGfabrik/user/LinkMonitorOutput i <MIXnumber> s <UID>

Clock Source

  • /KLANGfabrik/Hardware/ClockSource i <ClockSource> s <UID>

Snapshots & Show Files

This section describes how to load show files on a KLANG processor directly or fire and save KLANG snapshots on the KLANG processor. It is also possible to send snapshot commands to an Admin mode KLANG:app as described in this section below.

Show Files

Request the list of presets. Reply contains this list as strings.

  • /KLANGfabrik/control/RequestListOfPresets

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

  • /KLANGfabrik/control/presetSelect s <presetName>

Save a preset with a new KLANG show file name

  • /KLANGfabrik/control/presetSave b 1 s <presetName> b 1

Take snapshot:

  • /KLANGfabrik/control/TakeSnaphot s <SnapshotName>
  • /Kf/co/takeSnapshot s <SnapshotName>

Delete Snapshot

by <SnapshotID>. This is is the ID shown in the KLANG:app > CONFIG > PRESET > Snapshot list with the prefix “ID: “

  • /KLANGfabrik/control/DeleteSnaphotById i <SnapshotID> s <UID>

Move up Snapshot by ID

  • /KLANGfabrik/control/MoveSnapshotUp i <SnapshotID> s <UID>

Move down Snapshot

  • /KLANGfabrik/control/MoveSnapshotDown i <SnapshotID> s <UID>

Recall Snapshot by ID

  • /Kf/co/recall i <SnapshotID> [s "RecallSafe", <recallSafeOption1>, <RecallSafeOption2>,...]

Recall Snapshot by Index

This is the position in the current snapshot list shown in KLANG:app. (zero index, the first snapshot has index=0)

  • /Kf/co/recallInd i <SnapshotPositionInTheList>

Recall First Snapshot

  • /Kf/co/recallFirst [s "RecallSafe" <recallSafeOption1> <RecallSafeOption2>,...]

Recall Next Snapshot

  • /Kf/co/recallNext [s "RecallSafe", <recallSafeOption1> <RecallSafeOption2>...]

Recall Previous Snapshot

  • /Kf/co/recallPrev  [s "RecallSafe" <recallSafeOption1> <RecallSafeOption2> ...]

Update Snapshot

  • /Kf/co/updateSnaphot i <SnapshotID>

Without any integer argument, the current snapshot will be used instead:

  • /Kf/co/updateSnapshot

Recall Safe Options

Optional: To every command you can append (prior to the UID) the string “RecallSafe” followed by a list of strings including the options that should not be recalled by this command.

  • “OutputLevel”
  • “Mode”
  • “ChannelGain”
  • “LocationX”
  • “LocationY”
  • “LocationZ”
  • “ChannelMode”
  • “Solo”
  • “Mute”

Example:

  • /Kf/co/recallNext, ssss,  “RecallSafe”, “Mute”, “Solo” ,<UID>
  • Recalls the next snapshot but keeps the current solo and mute states.

Request List of Snapshots

/KLANGfabrik/control/RequestListOfSnapshots s <UID>

Tracker Commands for i3D

Use the offline editor to test these commands first. Connect to mix 1 and make sure to have at lease some icons on the i3D orbit in STAGE view in this mix. We use the UID “ABCD” for both the tracker.

KLANGosc 127.0.0.1 9110 /KLANGfabrik/control/ConnectRequest i 9113 i 50610 i 40 s "ABCD"
KLANGosc 127.0.0.1 9110 /KLANGfabrik/control/SwitchUser i 1 s "" i 40 s "ABCD"
KLANGosc 127.0.0.1 9110 /KLANGfabrik/control/changeTracker s "ABCD" s "ABCD"

Send Quaternion to rotate the instruments on i3D by 90 degrees counter clock-wise:

KLANGosc 127.0.0.1 9110 /KLANGfabrik/vektor/Orientation f 0.071 f 0 f 0 f -0.071 s "ABCD"

Send Quaternion 1 0 0 0 to revert to default viewing direction:

KLANGosc 127.0.0.1 9110 /KLANGfabrik/vektor/Orientation f 1 f 0 f 0 f 0 s "ABCD"

Request list of trackers. Reply contains the list.

/KLANGfabrik/control/RequestListOfTrackers

Additional Commands

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

/KLANGfabrik/Hardware/Restart (no arguments)

Set Clock Speed Mode:

  • KLANGfabrik/Hardware/SetSRMode i <mode> (requires restart!)
  • 1: single speed, 2: double speed

Set EQ mode:

  • KLANGfabrik/Hardware/SetEQMode, bool, <mode> (requires restart!)
  • true: on, false: off

Set second MADI port input/output (:fabrik ONLY):

  • /KLANGfabrik/Hardware/SetMadiDirections i 2 b <mode>
  • true: (second) input, false: output

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

  • /KLANGfabrik/Hardware/DisplayBrightness f <Brightness> s <UID>

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

  • /KLANGfabrik/Hardware/StatusUpdate

Set Device Name:

  • /KLANGfabrik/Hardware/UnitName s <UnitName>

:kontroller | Remote Control

:kontroller Dark/Dim Mode | Blackout

Switches the LEDs and Displays of a :kontroller off (or dims them). Send this OSC to the :kontroller IP address on port 9111. Alternatively, send to a broadcast IP to switch off all :kontrollers on the network with one message, e.g. to 192.168.255.255 or 192.168.1.255

Enter Dark mode<kontrollerIP> 9111 /Ka/Kc/Display/Dark i 1
<kontrollerIP> 9111 /Ka/Kc/Display/Dark True
Remove Dark mode<kontrollerIP> 9111 /Ka/Kc/Display/Dark i 0
<kontrollerIP> 9111 /Ka/Kc/Display/Dark False
Dim :kontroller Displays<kontrollerIP> 9111 /Ka/Kc/Display/Dim i 1
<kontrollerIP> 9111 /Ka/Kc/Display/Dim True
Full lid :kontroller Displays<kontrollerIP> 9111 /Ka/Kc/Display/Dim i 0
<kontrollerIP> 9111 /Ka/Kc/Display/Dim False

In case you want to send these commands from a DiGiCo console:

Display a message on :kontroller

To send a custom message to a :kontroller send this OSC to the :kontroller IP address and port 9111. Alternatively, use the broadcast IP address to display this message on all :kontrollers on the network.

/Ka/Kc/OverlayMessage s "yourMessage"

To delete the message again, send:
/Ka/Kc/RemoveOverlayMessage s "yourMessage"

Personal Preset Load & Save

Send the following to the :kontroller on port 9111 and adapt 01 to one of the 64 preset banks.

/Ka/control/PresetLoad s "SLOT_01.kup"

/Ka/control/PresetSave s "SLOT_01.kup"

KLANG:app | Remote Control

KLANG:app can be remote controlled via UDP Port 9111. When using KLANGosc on the same computer as KLANG:app simply use:
KLANGosc 127.0.0.1 9111 /<yourOscMessage>

Control KLANG:app Screens and Settings

Switch to Fader-View
/Ka/screen/FADERS1

Switch to Group-View
/Ka/screen/FADERS2

Switch to Stage-View (Orbit)
/Ka/screen/STAGE1

Switch to Ch-Focus in Stage-View (Orbit) KLANG:app 5.7+
/Ka/screen/STAGE1 i <hwChNumber>

Switch to Stage-View (Landscape / Elevation)
/Ka/screen/STAGE2

Switch to Ch-Focus in Stage-View (Landscape / Elevation) KLANG:app 5.7+
/Ka/screen/STAGE2 i <hwChNumber>

Engage Channel Focus and switch to STAGE1 if not already in Stage View KLANG:app 5.7+
/Ka/screen/CHANNELFOCUS i <hwChNumber>
use hwChNumber = -1 or 0 to switch off (this will not activate STAGE view)

Switch to Meters-View
/Ka/screen/METERS

Switch to Config-View (Last page that was selected)
/Ka/screen/CONFIG

No Screen, simple black background:
/Ka/screen/NONE

Channel Details:
/Ka/screen/CHANNELDETAILS i <ChannelNumber>

Trigger any Keyboard Shortcut

  • e.g. /Ka/shortcut s "CMD + SHIFT + S"
  • For a list of shortcuts go to KLANG:app > ? click on the question mark in the lower left corner and then on the orange keyboard icon.

Change User:

  • /Ka/screen/user i <userID>
  • /Ka/screen/nextUser
  • /Ka/screen/previousUser

Connect to KLANG processor:
/Ka/control/connect s <remoteAdress> i <userID>

Change App User-Mode:
/Ka/control/mode i <mode>

  • Musician Mode = 10
  • Personal Mode = 20
  • Show Mode = 30
  • Admin Mode = 40

Snapshot Commands via KLANG:app in Admin mode

The commands can be sent to a KLANG:app in Admin mode and it will trigger the action on its connected KLANG processor. This is very useful, if you want to send OSC messages to your KLANG:app on your computer via localhost IP address 127.0.0.1 and rely on KLANG:app to communicate with the connected KLANG processor.

DescriptionOSC Message
Fire first snapshot/Ka/control/FirstSnapshot
Reload the current snapshot/Ka/control/ReloadSnapshot
Fire next snapshot/Ka/control/NextSnapshot
Fire previous snapshot/Ka/control/PrevSnapshot
Recall snapshot by its position in the list of snapshots/Ka/control/RecallSnapshotByIndex i <PositionInList>
Recall snapshot by its ID as shown in PRESET menu/Ka/control/RecallSnapshotByID i <SnapshotID>
Update current snapshot (KLANG:app 5.7.14+)Ka/control/UpdateSnapshot

Display a message on a remote KLANG:app

Send this to the KLANG:app IP address on port 9111. Alternatively, use the broadcast IP address to send this to all KLANG:apps on the subnet.

/Ka/control/confirmation s "Just a simple message"

Request Info from KLANG:app

Send the following requests to KLANG:app’s IP address on port 9111 to get a reply to the requester’s IP address on port 9111.

Currently loaded Preset (KLANG show file) Name/Ka/request/CurrentPresetName/Ka/reply/CurrentPresetName s <name>
Currently loaded Snapshot name, UID and position in Snapshotlist/Ka/request/CurrentSnapshot/Ka/reply/CurrentSnapshot s <name> i <ID> i <positionInList>
Mix name and number KLANG:app is currently logged in to/Ka/request/CurrentMix/Ka/reply/CurrentMix s <mixName> i <mixNumber>
IP and name of connected KLANG processor/Ka/request/CurrentProcessor/Ka/reply/CurrentProcessor s <IP> s <deviceName>
These commands are available with version 5.7+

Save Backup&Logs

Write logs via OSC to KLANG:app /Ka/control/collectLogs s <optionalFilenameSuffix>

This OSC needs to be sent to a KLANG:app in Admin mode. Logs will be saved in the export directory that shows up when you manually click the collect logs button. This OSC just automates the button presses and includes an optional filename. <date> _<optionalFilenameSuffix>_KLANGlog.zip

Forwarding Messages

With KOS 5.7 new forwarding messages have been introduced (KKA-1373)
OSC MessageDescription
/Ka/ToProcessor/<yourOscAddress> <yourArguments>Forward to the connected processor/itself on port 9110
/Ka/ToOthers/<yourOscAddress> <yourArguments>Short for /Ka/ToProcessor/KLANGfabrik/control/RelayToOthers s "yourOscMessageAsString" (processors sends it out on port 9111 )
/Ka/ToBroadcast/<yourOscAddress> <yourArguments>Sends /<yourOscAddress> as a broadcast on port 9111
/Ka/MsgToOther s <yourMessage>Sends a message to all apps and :kontrollers connected to the same processor as this KLANG:app.

via KLANG:app to KLANG Processor

You can also send a forwarding OSC message to KLANG:app (to KLANG:app’s IP address on port 9111) with the OSC address prefix /Ka/ToProcessor/. KLANG:app will forward this message to its connected KLANG processor

Example: Set gain of channel 2 on mix 1 to -11 dB
Direct Command for KLANG processor:
KLANGosc 10.10.10.10 9110 /Kf/ui/1/ch/2/gaindB f -11
Command via local KLANG:app to be forwarded to KLANG processor:
KLANGosc 127.0.0.1 9111 /Ka/ToProcessor/Kf/ui/1/ch/2/gaindB f -11

via App or Processor to Other Apps and Kontrollers

Send a message with the prefix /Ka/ToOthers via a KLANG:app or directly to the KLANG processor on port 9111 so the processor fowards it to all its connected devices on port 9111.

Example: you want to send all KLANG:apps the command to switch to FADER view: /Ka/screen/FADERS1. Instead of sending this message to every single KLANG:app separately, send /Ka/ToOthers/Ka/screen/FADERS1 to the KLANG processor on port 9111 or e.g. your local KLANG:app on port 9111.

To the Entire Network

Send a message with the prefix /Ka/ToBroadcast to a KLANG:app or a KLANG processor on port 9111 so it forwards this message as a broadcast to the entire network on port 9111.

Example: you want to send all KLANG:kontrollers on the network (not only the ones connected to one specific KLANG processor) the command to switch LEDs and Display to dark: /Ka/Kc/Display/Dark i 1

Instead of sending this message to every single KLANG:kontroller IP address or the broadcast IP address e.g. 10.11.12.255 (on a /24 subnet), simply send /Ka/ToBroadcast/Ka/Kc/Display/Dark i 1 to the KLANG processor on port 9111 or e.g. your local KLANG:app on port 9111. Both devices can forward it to the correct broadcast IP address for you.

Still Have Questions?

Contact us here