OSC Reference Documentation

KLANG OSC Reference Documentation

KLANG:fabrik and KLANG:vier are entirely remote controlled with Open Sound Control (OSC) UDP network messages.

Details on OSC protocol: http://opensoundcontrol.org/
Only single messages are used for KLANG remote, i.e. no OSC 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 change with KOS updates.

KOS 2.2.11 or higher required.

Details on how to send OSC commands and examples how to convert MIDI to OSC are listed here:

blog-osc-automation-block2-01

1 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) (KLANG:vier uses the strings KLANGfabrik and Kf as well)
  • 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 long pattern OSC message with exactly 32 characters identifying the remote device uniquely, e.g.: ‘XxxxxxxxXxxxxxxxXxxxxxxxXxxxxxxx’

Example:

  • /KLANGfabrik/user/MasterSlider, ‘fs’, 1, ‘XxxxxxxxXxxxxxxxXxxxxxxxXxxxxxxx’
  • Send to address /KLANGfabrik/user/MasterSlider one float (f) which is ‘1’ and one string (s) which is ‘XxxxxxxxXxxxxxxxXxxxxxxxXxxxxxxx’.

UDP Ports and Answer Messages

Answers if required are sent back to the device that requested an answer. Devices are recognized according to their UID and not according to their IP address when using long pattern OSC messages.

OSC is send via UDP packets strictly on port 9110 to KLANG hardware (KLANG:fabrik / KLANG:vier).

The KLANG hardware sends back answers on the specified <ReceivePort> – default value is 9111.

2     Remote 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

 

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

MADI not listed yet.

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.

Madi not listed yet

Presets & Snapshots

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

  • /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>
  • /Kf/co/takeSnapshot, s <SnapshotName>

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, i[s]s, <SnapshotID> , [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>
  • /Kf/co/recall, i[s]s, <SnapshotID> , [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>

Recall First Snapshot

  • /KLANGfabrik/control/RecallFirstSnapshot, [s]s,  [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>
  • /Kf/co/recallFirst, [s]s,  [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>

Recall Next Snapshot

  • /KLANGfabrik/control/RecallFirstSnapshot, [s]s,  [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>
  • /Kf/co/recallNext, [s]s,  [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>

Recall Previous Snapshot

  • /KLANGfabrik/control/RecallPreviousSnapshot, [s]s,  [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>
  • /Kf/co/recallPrev, [s]s,  [“RecallSafe”, <recallSafeOption1>, <RecallSafeOption2>,…],<UID>

Update Snapshot

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

Recall Safe Options

KOS 2.2. and above

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

5    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, PDF & Email