kyma•tweaky . Learn . OpenSoundControlImplementation

Kyma Open Sound Control Protocol

Paca(rana) OSC Protocol

Response Routing
Message Arguments Result
⇒ /osc/respond_to,i port Informs the Paca(rana) of the port number where it should send replies
When the Paca(rana) sends a reply to a message it receives, it always replies to the sender's IP address, but uses a different UDP port number.

Use this message to tell the Paca(rana) to direct all replies from your software (when it uses the same IP address and port number as was used to send this message) to the UDP port number given in the integer argument.

If the port number argument is zero, the Paca(rana) will no longer send replies to your software.

If your software does not send this message, the Paca(rana) will, by default, use Bonjour to see if there is a published entry for the _osc._udp service associated with the IP address of the message it wishes to reply to. If so, the Paca(rana) uses the published port number. If not, no reply is sent.

See this discussion for more information about this message.

The Paca(rana) replies to this message with /osc_response_from,i (see below).
⇐ /osc/response_from,i port Reply to /osc/respond_to,i message
Your software will receive this message as a reply to sending /osc/respond_to,i. The integer port number argument will be the UDPport number that your software used to send the original message.
⇒ /osc/respond_to_default,i port Informs the Paca(rana) of the port number where it should send all replies
Use this message to tell the Paca(rana) to direct all replies to messages from the sender's IP address to the UDP port number given in the integer argument. If the port number argument is zero, the Paca(rana) will no longer send replies to messages sent from the sender's IP address.

See this discussion for more information about this message.

The Paca(rana) replies with /osc_response_from_default,i (see below).
⇐ /osc/response_from_default,i port Reply to /osc/respond_to_default,i message
Your software will receive this message as a reply to sending /osc/respond_to_default,i. The integer port number argument will be the port number that your software used to send the original message.
Controlling Notification
Message Arguments Result
⇒ /osc/notify/vcs/...,i onOff Request notifications to changes in the VCS
Use this message to inform the Paca(rana) that your software would like to be notified when the VCS in Kyma changes.

The ellipsis in the message should be replaced with a string unique to your computer and software (for example, it could be a concatenation of the computer's IP address and the name of your application).

The integer argument should be 1 to turn on notifications or 0 to turn off notifications.

Whenever the VCS changes, the Paca(rana) will send /osc/notify/vcs/...,i to your software (see below). Whenever the value of one or more VCS widgets changes, the Paca(rana) will send /vcs,b to your software identifying the changed widgets and their new values (see below).
⇐ /osc/notify/vcs/...,i widgetCount Notification of changes in the VCS
The Paca(rana) sends this message to your software if VCS notifications have been turned on and the VCS in Kyma has changed.

The ellipsis is the same string used when registering for VCS notifications.

The integer argument indicates the number of displayed widgets in the VCS.

Use /osc/widget,i to request information about the widgets (see below).
⇒ /osc/notify/midi/...,i onOff Request notifications to changes in the number of keyboard voices
Use this message to inform the Paca(rana) that your software would like to be notified when the number of keyboard voices (the combined polyphony of all MIDI 'instruments' on all channels) changes.

The ellipsis in the message should be replaced with a string unique to your computer and software (for example, it could be a concatenation of the computer's IP address and the name of your application).

The integer argument should be 1 to turn on notifications or 0 to turn off notifications.

Whenever the number of voices changes, the Paca(rana) will send /osc/notify/midi/...,i to your software (see below).
⇐ /osc/notify/midi/...,i voiceCount Notification of changes in the number of keyboard voices
The Paca(rana) sends this message to your software if MIDI notifications have been turned on and the number of keyboard voices has changed.

The ellipsis is the same string used when registering for VCS notifications.

The integer argument indicates the number of keyboard voices currently available.

Use /osc/voice,i to request information about the keyboard voices (see below).
⇒ /osc/notify/presets/...,i onOff Request notifications to changes in the number of VCS presets
Use this message to inform the Paca(rana) that your software would like to be notified when the number of VCS presets changes.

The ellipsis in the message should be replaced with a string unique to your computer and software (for example, it could be a concatenation of the computer's IP address and the name of your application).

The integer argument should be 1 to turn on notifications or 0 to turn off notifications.

Whenever the number of voices changes, the Paca(rana) will send /osc/notify/presets/...,i to your software (see below).
⇐ /osc/notify/presets/...,i presetCount Notification of changes in the number of VCS presets
The Paca(rana) sends this message to your software if presets notifications have been turned on and the number of VCS presets has changed.

The ellipsis is the same string used when registering for VCS notifications.

The integer argument indicates the number of VCS presets currently available.

Use /osc/preset,i to request information about the presets (see below).
Requesting Information
Message Arguments Result
⇒ /osc/widget,i index Request description of a VCS widget
Use this message to request a description of a particular VCS widget.

The integer argument is the zero-based index into the array of currently active VCS widgets. It should be between 0 and widgetCount - 1.

The Paca(rana) will reply with /osc/widget,is (see below).
⇐ /osc/widget,is index jsonString Description of the requested widget
The Paca(rana) replies with this message when the description of a VCS widget is requested.

The integer argument indicates the number of the widget being described.

The string argument is a JSON string description of the VCS widget object (see notes below). The string will be of zero length if the index is out of bounds.
⇒ /osc/voice,i index Request information on a keyboard voice
Use this message to request information on a particular keyboard voice.

The integer argument is the zero-based index into the array of currently available keyboard voices. It should be between 0 and voiceCount - 1.

The Paca(rana) will reply with /osc/voice,ii (see below).
⇐ /osc/voice,ii index voiceInfo Description of the requested keyboard voice
The Paca(rana) replies with this message when information on a keyboard voice is requested.

The integer argument indicates the number of the voice being described.

The second integer argument encodes the MIDI channel and note number range for that voice (see notes below).
⇒ /osc/preset,i index Request VCS preset name
Use this message to request the name of a particular VCS preset.

The integer argument is the zero-based index into the array of currently available presets. It should be between 0 and presetCount - 1. To obtain the name of the currently selected preset, use -1 as the index.

The Paca(rana) will reply with /osc/preset,is (see below).
⇐ /osc/preset,is index presetName Name of the requested VCS preset
The Paca(rana) replies with this message when the name of a VCS preset is requested.

The integer argument indicates the number of the preset.

The string argument is the name of the preset. The string will be of zero length if the index is out of bounds.
Controlling the VCS
Message Arguments Result
⇒ /layout,i index Select the given VCS layout
Use this message to select a particular VCS layout.

The integer argument is the one-based index into the array of VCS layouts. Use 126 to select the previous layout, 127 to select the next layout, 128 to redraw the current layout.
⇒ /preset,i index Select the given VCS preset
Use this message to select a particular VCS preset.

The integer argument is the one-based index into the array of VCS presets. Use 126 to select the previous preset, 127 to select the next preset, 128 to roll the dice, 129 to resend the current settings, 130 to save the current settings as a new preset.
⇒ /volume,i zeroToOneHundred Control the output volume of the Paca(rana)
Use this message to control the output volume.

The integer argument sets the output volume to approximately (100 - zeroToOneHundred) * -0.6 dB. The Paca(rana) outputs are muted if the argument is 0 and full volume if the argument is 100.
⇒ /vcs,if... eventID1, value1, ... Change the value of one or more VCS widgets
Use this message to change the value of one or more VCS widgets, identified by EventID. An EventID is a unique number identifying the source of control and can be obtained from the concreteEventID entry in the widget information returned by the /osc/widget,i message.

The argument is any number (up to 128) of EventID/value pairs and the number of pairs is indicated in the OSC message type. For example, to send three pairs you would use /vcs,ififif.

Also see below for a simpler message to change the value of a widget using the name instead of the EventID.
⇒ /vcs/map,if... eventID1, value1, ... Change the value of one or more VCS widgets, with mapping
Use this message to send specific physical-hardware-related EventIDs (such as MIDI cc107) that could have been mapped to control a widget in the VCS. For example, if you wanted to emulate a hardware source of control such as the Wacom tablet pen or a Peavy PC 1600, you would use the map version of the value update message.

See /vcs,if... above for more information about the message format and see below for more information about hardware EventIDs.
⇐ /vcs,b { byteCount, int_id0, float_value0, ... } Notification of change of value of one or more VCS widgets
The Paca(rana) sends this message to your software if VCS notifications have been turned on and one or more VCS widgets have changed value.

The blob argument contains big-endian data in the following format:

byteCount is the size of the blob in bytes; byteCount / 8 is the number of EventID/value pairs in the blob

int_id0, float_value0 is the 32-bit integer EventID and the 32-bit float value of the widget that changed value

... repeat EventID and value pairs for each widget that changed value.
Sending Keyboard Note Events
Message Arguments Result
⇒ /key,iifff voiceNbr, offOn, pitch, velocity, timbre Start/release/update a keyboard note on a voice
Use this message to request the Paca(rana) to start, release, or update a keyboard note associated with a voice.

The integer voiceNumber argument should be between 0 and voiceCount - 1 and indicates which Paca(rana) voice to control.

The integer argument indicates how to control the voice. Use -1 to start a new note, +1 to update the note's parameters while it is playing, and 0 to release the note.

The float pitch argument is the desired KeyPitch in Kyma nn units (middle C = 60). (Note that the pitch is not restricted to integer values, so any pitch can be represented to within 0.00152 cents.)

The float velocity argument is the desired KeyVelocity and should be between 0 and 1.

The float timbre argument is the desired KeyTimbre and should be between 0 and 1.
Controlling Individual VCS Widgets
Message Arguments Result
⇒ /vcs/<name>/<channel>,f value Change the value of the named VCS widget
Use this message to change the value of the VCS widget with the given name on the given channel.

<name> and <channel> are placeholders for the real name and channel of the widget to be changed. For example, to change the BPM fader on channel 1, you would use the message /vcs/BPM/1.

The float argument is the new value for the named widget.

See this discussion for more information about this set of messages.

The Paca(rana) replies to the sender of this message when the widget's value is changed using the VCS or other source of control of the widget (see below).
⇐ /vcs/<name>/<channel>,f port Notification of a change to the value of the named VCS widget
Your software will receive this message when the value of the named widget changes if it is the most recent OSC sender to control the widget.

The float argument is the new value for the named widget.

See Response Routing above and this discussion for information on how to set the number of the UDP port that will receive this message.
MIDI Streams
Message Arguments Result
⇒ /<anything>,m... { packed MIDI bytes } Send MIDI bytes to the Paca(rana)
Use this message to send MIDI bytes to the Paca(rana).

<anything> should be replaced with a string unique to your computer and application, to distinguish this MIDI stream from any others that might be simultaneously being sent.

The argument is an array of 32-bit integers, one for each m in the argument type list (for example, if the message was /my_midi_stream,mmm the argument would be three 32-bit integers). Each of the integers contains 3 MIDI bytes. Up to 128 arguments can be used in a single message.

See this discussion for more information about this set of messages.

The Paca(rana) will automatically start a return OSC MIDI stream to your software. It replies to the sender of this message with MIDI output bytes, when available (see below).
⇐ /midi/raw/paca-out,m... { packed MIDI bytes } MIDI output bytes from the Paca(rana)
Your software will receive this message after it has sent MIDI bytes to the Paca(rana) and the Paca(rana) has MIDI output bytes to send.

The length of this message depends on the length of the MIDI messages your software has sent to the Paca(rana). If your software has sent only one-argument OSC MIDI messages, the Paca(rana) will reply using only one-argument messages. If your software has sent any multiple-argument OSC MIDI messages, the Paca(rana) will reply with messages of up to 17 arguments.

See this discussion for more information about the OSC MIDI messages sent by the Paca(rana).
⇒ -<anything>,m... { packed MIDI bytes } Send MIDI bytes to the Paca(rana), no return MIDI stream
Use this message to send MIDI bytes to the Paca(rana) without starting a return OSC MIDI stream.

If the first character of the message is a - rather than a /, the Paca(rana) will not automatically establish a return OSC MIDI connection to your software.
Arbitrary OSC Messages
Message Arguments Result
⇒ <anything>,f... value Send value(s) to the Paca(rana)
Use this message to send value(s) to the Paca(rana). These arbitrary messages can be mapped to control VCS widgets or used directly in parameter fields.

The Paca(rana) replies to the sender of this message when the widget's value is changed using the VCS or other source of control of the widget (see below).
⇐ <anything>,f... port Notification of a change to the value
Your software will receive this message when the value changes if it is the most recent OSC sender of that message.

See Response Routing above and this discussion for information on how to set the number of the UDP port that will receive this message.

VCS Widget Description

The string argument in the /osc/widget,is message is a JSON string representation of the VCS widget object in Kyma. Essentially, this is a string containing name/value pairs describing the widget. For example, it could include the EventID, min value, max value, widget type, position on screen, value, etc. There are Open Source JSON decoders in nearly every programmming language including Objective C.

Here is an example of a JSON string sent from the Paca(rana): 

{
    "creationClass" : "VCSEventSourceComponent",
    "layout" : {
            "creationClass" : "LayoutFrame",
            "leftOffset" : 0,
            "topOffset" : 0,
            "rightOffset" : 0,
            "bottomOffset" : 0,
            "leftFraction" : 0.0,
            "topFraction" : 0.0,
            "rightFraction" : 0.125,
            "bottomFraction" : 1.0
            },
    "label" : "Amp",
    "lookOrNil" : null,
    "displayType" : "Fader",
    "concreteEventID" : 3145730,
    "minimum" : 0,
    "maximum" : 1,
    "grid" : 0,
    "taper" : "linear",
    "showNumber" : true,
    "isGenerated" : false,
    "reflectMarker" : null,
    "tickMarksOrNil" : null
    }

Decoding voiceInfo

The second integer argument (voiceInfo) in the /osc/voice,ii message is a 32-bit integer:

8' zeroes 1' endOfList 5' -midiChannel 8' -lowNN 8' highNN

To decode this value, you could use the following C code, assuming i is the index, info is the voiceInfo from the OSC message, and Voices is an array that accumulates information about the active Paca(rana) voices: 

if ( info & 0x00800000 ) {
   /* end of list, can be ignored */
}
else {
   Voices[i].channel   = - ( ( info <<  9 ) >> 27 );
   Voices[i].lowNN     = - ( ( info << 14 ) >> 23 );
   Voices[i].highNN    = info & 0x7F;
   printf (
      "%d: channel %d, range %d - %d\n",
      i,
      Voices[i].channel,
      Voices[i].lowNN,
      Voices[i].highNN );
}

About Hardware EventIDs

OSC messages with float arguments and hardware-based EventSources can be remapped to control VCS widgets (by right-clicking on the VCS widget or by using the VCS editor). If you would like your software to emulate one of the hardware-based controllers that already work with Kyma, your software can use the /vcs/map,if... message with a hardware-based EventID.

The hardware-based EventIDs are a function of the channel (between 1 and 16) and the controller number (between 0 and 254): 

((channel - 1) << 8) | (controllerNbr + 1)

The table below lists the currently defined controller numbers:

Controller Name Nbr
MIDI Controls
MIDIController0 0
... ...
MIDIController119 119
Extended MIDI Controls
MIDIPitchBend 128
MIDIChannelPressure 129
MIDIProgramNumber 130
Wacom Tablet Controls
PenX 131
PenY 132
PenZ 133
PenRadius 134
PenAngle 135
PenDown 136
PenTiltX 137
PenTiltY 138
PenTiltRadius 139
PenTiltAngle 140
PenRotation 141
PenWheel 142
PenButton1 143
PenButton2 144
Wiimote Controls
WiiAccelX 145
WiiAccelY 146
WiiAccelZ 147
WiiPitch 148
WiiRoll 149
WiiYaw 150
WiiAccel 151
WiiBarX 152
WiiBarY 153
WiiTrigger 154
Wii Nunchuck Controls
NunAccelX 155
NunAccelY 156
NunAccelZ 157
NunPitch 158
NunRoll 159
NunYaw 160
NunAccel 161
NunJoyX 162
NunJoyY 163
NunTriggerC 164
NunTriggerZ 165
WiiButtonA 166

Two-way OSC Communication Demonstration Software

Tool for debugging and demonstrating two-way OSC communication.

----- Revision r1.17 - 13 Feb 2016 - 01:16 GMT - KurtHebel
Copyright © 1999-2014 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding kyma•tweaky? Send feedback.