Manuals

KLANGosc

KLANG has developed a command line tool for macOS and Windows. KLANGosc sends Open Sound Control (OSC) messages to a KLANG processor or to KLANG:app straight from a Terminal, a Command Prompt or a script, so you can try a command out before you build it into a console macro, a show control cue or your own software. Every message described in the KLANG OSC Reference Guide can be sent this way.

KLANGosc is available for macOS and for Windows. The download buttons below always carry the current version.

Downloads

KLANGosc 2.1.1 Mac KLANGosc 2.1.1 Win

Installing KLANGosc

There is one download per platform, each a ZIP archive. The archive contains the installer for that platform plus an examples script and a README.txt.

The archive deliberately carries no loose executable: the licence agreement is a step of the installer.

macOS

Unpack the ZIP and double-click the .pkg file inside it. The package is signed and notarized by KLANG, so macOS installs it without a Gatekeeper warning, and it also installs on a machine that is offline.

The installer shows the licence agreement, then puts a universal binary into /usr/local/bin, which is already on your PATH. One package covers both CPU types: Apple Silicon and Intel are in the same file, so there is no separate download to choose. Open a Terminal afterwards and check the installation:

KLANGosc --version

To remove KLANGosc again, delete /usr/local/bin/KLANGosc and the folder /usr/local/share/KLANGosc.

Run from a Terminal, KLANGosc does not ask for macOS Local Network permission and does not appear under System Settings > Privacy & Security > Local Network. Apple exempts command line tools from that prompt.

Windows

Unpack the ZIP and double-click the .exe file inside it. One installer covers both CPU types: it carries an x64 build (Intel or AMD, most PCs) and an arm64 build (Snapdragon, Surface Pro X) and installs whichever matches your machine. If you are unsure which one you have, look under Settings > System > About > System type.

The installer shows the licence agreement, then installs into Program Files. On the last page it offers the tick box Add KLANGosc to the system PATH, which is ticked by default and lets you call KLANGosc from any Command Prompt or PowerShell window. Open a new window afterwards (an already open one still has the old PATH) and check the installation:

KLANGosc --version

The Windows installer is not code signed yet, so Windows warns that the publisher is unknown before it starts. The file offered on this page is the one published by KLANG. Continue with More info > Run anyway if you want to install it.

Uninstall KLANGosc like any other Windows program, from Settings > Apps > Installed apps. The PATH entry is removed with it.

Sending a message

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

Instead of an IP address you can also give a hostname or a .local name, or a broadcast address to reach every device on the network at once. The OSC address pattern and its arguments are the part described in the KLANG OSC Reference Guide.

Messages to a KLANG processor need to be sent to port 9110. Messages to KLANG:app need to be sent to 9111 (by default). The receive port of an app is shown on CONFIG > CONNECT, bottom right.

Argument types

Every argument is written as a type followed by its value. The type has to match what the message expects, otherwise KLANGosc refuses the send instead of putting a wrong value on the network.

TypeMeaningExample
i32 bit integeri 1
i64 (or h)64 bit integeri64 4294967296
ffloating point numberf -6
bboolean, true/false or 1/0b true
stext, in quotes if it contains spacess "MySong01"

Examples

Solo channel 5 in mix 1 on a processor at 192.168.1.163:
KLANGosc 192.168.1.163 9110 /Kf/ui/1/ch/5/solo b true

Set the gain of that channel to -6 dB:
KLANGosc 192.168.1.163 9110 /Kf/ui/1/ch/5/gaindB f -6

Switch a KLANG:app on the same computer to the Fader view:
KLANGosc 127.0.0.1 9111 /Ka/screen/FADERS1

A successful send is confirmed on screen, for example sent /Kf/ui/1/ch/5/solo (24 bytes) to 192.168.1.163:9110. OSC is a one-way protocol over UDP, so this confirms that the message left your computer, not that the device acted on it.

No processor at hand? Most commands can be tried against KLANG:app’s Offline Editor (CONFIG > CONNECT > OFFLINE EDITOR). It runs on the same computer as KLANG:app, so send to 127.0.0.1 port 9110:
KLANGosc 127.0.0.1 9110 /<yourOscMessage>

Several messages in one send

Separate messages with a comma and KLANGosc packs them into an OSC bundle, so the device receives and applies them together. This is the way to change a gain and a mute without the two arriving as separate events.

KLANGosc 10.0.0.5 9110 /Kf/ui/1/ch/5/gaindB f -6 , /Kf/ui/1/ch/5/mute b false

Long lists are split over several bundles automatically. A single message is still sent on its own, exactly as before.

Finding the right message

KLANGosc carries a catalog of KLANG OSC messages inside the tool, so you can look an address up without leaving the command line:

KLANGosc list lists everything it knows.
KLANGosc list LEDBlink lists the entries whose address or description contains that text.
KLANGosc list /Ka/ lists the KLANG:app control surface.

Addresses that carry a mix or channel number are not listed one by one. The list ends with those patterns, so you can see how to build them.

When you send an address that is not in the catalog, KLANGosc prints a warning and sends it anyway. That way a typo is visible immediately, while messages that are newer than the catalog still go out.

OSC addresses are case-sensitive, so /Kf/ping is not /Kf/Ping and a device simply ignores the wrong spelling. KLANGosc points this out with its own warning when an address differs from a known one only in capitalisation.

KLANGosc --help prints the syntax, the argument types and two examples. KLANGosc --version prints the installed version. The full message reference stays the KLANG OSC Reference Guide.

The example walkthrough

There are examples in the batch and shell scripts included in the download: KLANG_OSC_examples.command on macOS (double-click it in Finder) and KLANG_OSC_examples.bat on Windows. Both cover the same ground in the same order and are meant to be read and edited, not just run.

Pass the address of your processor as the first argument, for example ./KLANG_OSC_examples.command 192.168.1.163 on macOS or KLANG_OSC_examples.bat 192.168.1.163 on Windows. Without an argument the script uses the address set in KFIP at the top, so edit that line if you prefer to double-click the script. Everything else sits in variables at the top of the script: KFport for the processor port, and appIP and appPORT for the computer running KLANG:app.

From there the script walks through:

  • Setting gain, elevation, azimuth, mute and solo on a channel, then storing the result as a snapshot and recalling it again
  • Switching a KLANG:app between its Fader, Stage and remote user views
  • Sending values to a processor, including a preset save and a change of HRTF
  • Initialising every channel of every mix in a loop, which is the pattern to copy for your own bulk changes
The walkthrough changes the settings of the device it is pointed at, and the loop at the end overwrites the name, position and gain of every channel in every mix. Run it on a processor you are free to reconfigure, or on the offline editor, and not on a system that is in use.

When a message does not arrive

Work through these first:

  • The port: 9110 for a processor, 9111 for KLANG:app
  • The spelling of the address, including its capitalisation
  • The argument types, checked against the KLANG OSC Reference Guide
  • Whether your computer and the device are on the same network

For use in scripts, KLANGosc reports what happened as an exit code: 0 the message was sent, 1 the command line was wrong, 2 the message could not be put on the network.

Still Have Questions?

Contact us here