====== MIDI and Kyma Control Changes ======

===== The virtual MIDI Output =====

All MIDI events are sent to a Virtual MIDI Output.  This can be seen just as a real MIDI port but software only.  A MIDI compliant application (like Logic Pro or Live) can receive the events from the virtual port named ''OSCulator Out''.


===== MIDI CC =====

This event converts an OSC message in the range of ''0.0'' to ''1.0'' to a MIDI Control Change in the range of ''0'' to ''127''.  It will be sent on the specified MIDI Channel((third column in the main window)).


===== MIDI CC Toggle =====

This event converts an OSC message in the range of ''0.0'' to ''1.0'' to a MIDI Control Change that only has the values ''0'' and ''127''.

In practice, this very useful event can be used for example to toggle an effect in a sequencer from a sudden acceleration of the Wiimote((See example "Midi Note" in the Wiimote/Ableton Live folder of the Sample Patches)).  In can also be used to convert a OSC fader control to a MIDI toggle. 

Like any event that is triggered, the threshold is set at ''0.5'', meaning that the toggle switches its position when the input value crosses ''0.5''.


===== Controlling the routing of MIDI messages =====

If you want to route those messages to a "real" MIDI device, like a synthesizer, you will have to use a "patchbay" application which will take the events from ''OSCulator Out'' and send them to a MIDI port available on your MIDI interface.

There are several free programs that can do that for you:
  * [[http://notahat.com/midi_patchbay/|MIDI Patchbay]] written by Pete Yandell.
  * [[http://web.mac.com/nicowald/SubtleSoft/MidiPipe.html|MidiPipe]] written by Nico Wald.

Note to long time MIDI users: the the IAC driver is no longer the preferred way to send MIDI messages across applications.  Virtual MIDI Ports, like the one OSCulator uses, are made for that and are much more efficient.  If however, your target application needs a IAC based port, you can use the previously mentioned softwares to do the proper routing.

==== Sending MIDI over the Network ====

There is a very underestimated feature of Mac OS X which is the Networked MIDI driver. You can control it in the Audio MIDI Setup application.

Here is an example on how to configure the MIDI Network Driver in order to control many computers running Mac OS X and the [[http://www.resolume.com/|Resolume Avenue VJ software]].

  * First, configure OSCulator so it controls one instance of Avenue with MIDI messages.
  * On the master computer (running OSCulator), go in the **Audio MIDI Setup** application and click on the **MIDI Devices** tab.
  * There is a Network interface, double click on it.
  * Select ''Session 1'', and click the **Enabled** checkbox.
  * On the other computers, open **Audio MIDI Setup** as well, and enable ''Session 1'', change "Who may connect to me" to ''Anyone''.
  * Back to the master computer, connect to each slave computer.  This will add them to the list of participants.
  * Last step in **Audio MIDI Setup**: In the ''Live Routings'' section (lower right), select ''OSCulator Out'' in the first drop down menu.  This will send event coming from ''OSCulator Out'' to all the participants in the network.
  * On each computer (master and slave), change **Avenue** settings and tell it to use the ''Network Session 1'' virtual MIDI interface, instead the previously configured ''OSCulator Out''.

Using a wireless WiFI network, the latency is about 3 ms, which is ten times less than a frame duration at 30fps, which makes is usable for live VJ performance.

===== Kyma =====
==== Control Changes (Kyma CC) ====

By sending ''Kyma CC'' events, you can control the Hot Variables specified in your sounds.  Kyma Control Changes are like MIDI Control Changes at the difference they are directly sent over FireWire to the connected Parana or Capybara sound workstation.

A few more differences can be noted:

  * OSCulator can use the global map to map the control change numbers (from 0 to 127) to hot variable names (e.g. ''<color #ed1c24>!Attack</color>'')((you can define the global map in the [[Application Preferences|Preferences]] window))
  * ''Kyma CC'' are automatically setup when the OSC message name matches a known Hot Variable name, for example:
    * ''/foo.cc34''((it doesn't care if slashes '/' or dots '.' are used as a separator, though the usual convention is to use slashes.)) is automatically mapped to ''<color #ed1c24>!cc34</color>''
    * ''/synth/attack'' is automatically mapped to ''<color #ed1c24>!Attack</color>'', if it is defined in the global map
==== Extended Control Changes (Kyma Ext) ====

Kyma actually defines control changes whose number is higher than 127.  They are called Extended Control Changes and are reserved for external devices like the Wacom Tablet, the Wiimote or the Nunchuk.

They work exactly as the ''Kyma CC'', but are just grouped in another category:  Thus, if you have sounds that use Hot Variables referring to those devices, you can directly change their value by using these extended control changes.