Manuals

OSC Reference Documentation

KLANG:app and the KLANG Immersive In-Ear Mixing Processors communicate exclusively via Open Sound Control (OSC) UDP network messages on port 9110 and 9111.

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

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 patter (that does not require any handshake) it will be used in this guide instead.

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

  • String – s (we use hyph)
  • Integer – i
  • Float – f
  • Bool – b/B – 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 Answer 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 sends back answers on the specified <ReceivePort> – default value is 9111.

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.

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

  • /KLANGfabrik/control/ConnectRequest i <ReceivePort> s <UID>

Answers or responses 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 9111 i 50414 i 45 s “macOrWindows” s “ABCD”

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

Controlling KLANG Hardware

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

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>/icon 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>

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).

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>

Show Files

Request the list of presets. Answer 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

Snapshots

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.

Tracker Commands

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 40199 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. Answer contains this 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. Answer is an XML file in one single string.

  • /KLANGfabrik/Hardware/StatusUpdate

Set Device Name:

  • /KLANGfabrik/Hardware/UnitName s <UnitName>

Remote control :kontroller

Dark Mode | Blackout

Switches the LEDs and Displays of a :kontroller off. Send this OSC to the :kontroller IP on port 9111. Alternatively, send to a broadcast IP to switch off all :kontrollers on the network with one message.

/Ka/Kc/OverlayMessage s “DARK” s “DARK”

To remove the dark mode send:
/Ka/Kc/RemoveOverlayMessage s “DARK” s “DARK”

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>

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

Switch to Meters-View

  • /Ka/screen/METERS

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

  • /Ka/screen/CONFIG

Change User

  • /Ka/screen/user i <userID>

Connect to KLANG processor

  • /Ka/control/connect s <remoteAdress> i <userID>

Change App User-Mode (MUSICIAN = 10, PMM = 20, TECHNICIAN = 30, ADMIN = 40)

  • /Ka/control/mode i <mode>

Still Have Questions?

Contact us here