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.

KLANG osc 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> …

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 – /KLANGfabrik (long pattern) or /Kf (short pattern)
  • For KLANG:app – /KLANGapp (long pattern) or /Ka (short pattern)
Long patterns have mostly become obsolete and wherever there is a short patter (that does not require any handshake) will be chosen here 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.

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 to address /KLANGfabrik/user/MasterSlider 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 KLANG processor sends back answers on the specified <ReceivePort> – default value is 9111.

Devices are recognized by the KLANG processor/kontroller/app according to their UID and not according to their IP address when using long pattern OSC messages. 

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)

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>

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

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.

Configuration Commands

Assign a new name <NEWname> to a mix/user

  • /KLANGfabrik/control/RenameUser i <MIXnumber> s <NEWname> s <UID>

Request list of trackers. Answer contains this list.

  • /KLANGfabrik/control/RequestListOfTrackers

Change the associated motion tracker <TRACKERuid> for a user

  • /KLANGfabrik/control/changeTracker  s <TRACKERuid> s <UID>

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:

  • /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 number of input channels <NumInputs> 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 i <NumInputs > i <NumUsers> s <UID>

KLANG:app Remote Control

KLANG:app an be remote controlled from the network on UDP Port 9111.

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>

Further Commands

Set Serial Number: /KLANGfabrik/Hardware/Serial s <8digit SN starting with K…>

Set Unit Name: /KLANGfabrik/Hardware/UnitName s <UnitName>

Still Have Questions?

Contact us here