Connecting OSC Messages to Kyma Event Values

In Kyma, you can associate incoming OSC messages with Kyma Event Values in several ways:

  • remap individual VCS widgets to respond to specific OSC messages
  • use OSC Event Values in parameter fields of Sound
  • program an external OSC device to send messages that are automatically recognized
Learn or Map to an OSC message in the VCS

In the Virtual Control Surface (VCS):

  • right-click the widget
  • choose Learn from the pop-up menu
  • send OSC message from device

To map to any OSC message received in the past:

  • in the VCS, right-click the widget
  • choose Controller and then OSC from the pop-up menu
  • select the desired OSC message

If the incoming message is a vector, Kyma will “learn” the first element of the Vector. (The same is true for learning in parameter fields).

Learn or Enter an OSC message in a Parameter field

To control a Kyma Sound parameter with an OSC message, use the learn function in the parameter field:

  • click in the parameter field
  • press the escape (ESC) key on your computer keyboard
  • send the OSC message to Pacamara or Paca(rana)

If you “learn” an OSC message that is a vector, the first element of the vector will be captured.

You can also type the OSC Event Value name directly into the parameter field using a specially formatted OSC Event Value. To transform your OSC message into a Kyma OSC Event Value:

  • replace each slash in the address with underscore
  • use the prefix: !osc

Here are some examples of Kyma OSC Event Values and their corresponding OSC messages:

Event Value OSC message
!osc_1_fader1 /1/fader1
!osc_4_xy__1 /4/xy//1
Program OSC Source to send specific messages to Kyma

Instead of re-mapping each individual Kyma widget or parameter with an OSC message one-by-one, you can, alternatively, program your OSC device or application to send specific messages to control Kyma using the message address format:

/vcs/name/channel

Where name is the name of the Kyma Event Value, and channel is the MIDI channel of the controller. Even though you are sending OSC (and not MIDI), the channel identifiers are retained as a convenient way to organize controllers (for example, by default each track of the Timeline is associated with its own controller channel).

If your Sound had Event Values !Vol, !Amp, !Density, for example, you could program your device to send the OSC messages:

/vcs/Vol/1

/vcs/Amp/1

/vcs/Density/1

This automatically maps to Kyma Event Values !Vol, !Amp, !Density. (Note that you can still, optionally, remap individual VCS widgets to different control sources.)

How OSC values are used by Kyma Event Values

By default, Kyma is expecting OSC message values to be in the range of zero to one. When an OSC message is received, the message value is automatically scaled to match the minimum-to-maximum range associated with the mapped Event Value in the VCS.

This automatic scaling makes it easy to use zero-to-one range OSC message sources to control any Event Value in the VCS without needing to change the range of values sent via OSC.

Sometimes OSC messages have a range different from zero-to-one; for example, the range of an accelerometer OSC message value may be ±1 G or even ±250 G.

For these types of messages, you have several ways to use the message value to control a Kyma Event Value:

  • If the OSC message value already has the right range, you could set the VCS widget range to zero-to-one so that Kyma will not alter the OSC value. In this situation, the numerical display of the widget will show the received OSC value but the graphical display may be pinned (for example, a fader might be pinned at the top or the bottom of its graphical range).
  • If you want both the numerical and graphical display in the VCS to accurately show the received OSC message value, you could use a MapEventValues Sound to map the OSC message to the Kyma Event Value rather than performing the map in the VCS as described at the top of this page. In addition to mapping the OSC message to an Event Value, MapEventValues can be use to transform the OSC message value before it is used as an Event Value in the Sound.

If you would like all OSC messages from a specific OSC source to be used directly without scaling by Kyma, send a message from the source to the Pacamara or Paca(rana) in the form: “/osc/receive_raw,i 1“, where “/osc/receive_raw” is the OSC message address, “,i” is the argument-type list (in this case, it is a single integer), and “1” indicates that subsequent OSC message values should be used raw (unscaled).

For Software Developers

One of the advantages of OSC is that it is an open standard that invites you to write your own applications or translators for communicating between computers, devices, and applications and Kyma. Here is some information you will need for writing your own OSC application, translator, or device that can communicate bi-directionally with Kyma.

Finding a Pacamara or Paca(rana)

The Pacamara and Paca(rana) advertise its IP address and port via Bonjour (Zeroconf). The OSC service is advertised as

_osc._udp

Program your device or application to send OSC messages to port 8000 of:

mara-serial_nbr.local for Pacamara

beslime-serial_nbr.local for Paca(rana)

where serial_nbr is the serial number of your Pacamara, Paca or Pacarana (note that some applications do not display the .local part of the name). Note that some software expects a trailing period for local addresses:

mara-serial_nbr.local. for Pacamara

beslime-serial_nbr.local. for Paca(rana)

OSC Messages

The Pacamara and Paca(rana) respond to messages having from 1 to 256 arguments.

An OSC message should take the form:

address, argument type list, argument values

Address

The address of the message can be any string, but controllers typically send the name of widget that changed. The Pacamara and Paca(rana) respond automatically to a few, predefined addresses (for example, the names of the widgets in the currently active VCS in Kyma). Any other addresses can be arbitrarily re-mapped to event values in Kyma.

Argument type list

The type list may be floats: ‘,f’, ‘,ff’, ‘,fff’, or integers: ‘,i’, ‘,ii’, ‘,iii’, .

Arguments

For automatic mapping, each argument should be a float in the range of 0 to 1, but any 32-bit floating point or integer value can be used.

Multi-argument messages

Messages with 2 or more arguments are split within Kyma. Kyma associates each individual component with one control widget. For example:

/4/xy,ff

becomes

/4/xy//1,f

and

/4/xy//2,f

Miscellaneous random tidbits…
  • Kyma ignores the time tag of bundle messages.
  • Kyma performs case-insensitive address comparisons.
  • There is no pattern matching at this time.

Establishing two-way communication between Kyma and OSC Sources

Please see Two-way communication between Kyma and OSC sources

Sending MIDI Streams Over OSC

Please see Sending MIDI Streams Over OSC

Kyma OSC Standard Protocol

You can write software that communicates bi-directionally with Kyma using OSC, including MIDI note events and graphics, by following the Kyma OSC Standard Protocol for communicating with Kyma via OSC.

Two-way OSC Communication Demonstration Software

Tool for debugging and demonstrating two-way OSC communication.