====== How to control TouchOSC LEDs with Ableton Live and OSCulator ======

TouchOSC features a control that displays a stylized on/off LED.  This control can not be touched, but it can be controlled with OSC messages.  The purpose of this tutorial is to explain how to control these LEDs from Ableton Live.

You can see those LEDs in the Beatmachine default layout, on page 2, there are 16 of them.  They can be activated by sending an OSC message like:

    ''/2/led3 1.0''   ... will turn the third LED on
    ''/2/led3 0.0''   ... will turn the third LED off

{{ :tutorial:img_0280.png | TouchOSC Beatmachine page 2}}
===== Overview =====

To sync the LEDs with Live's tempo, we will use MIDI notes sent to OSCulator, and convert them to OSC messages in turn sent to TouchOSC.

You will need to have TouchOSC and OSCulator correctly setup with Live [[tutorial:1:start|as explained in this tutorial]].

You can download the files used here at the end of this tutorial, however it is highly recommended to start from scratch and follow the instructions step by step.
===== Live configuration =====

  * Launch OSCulator and Live.
  * Open an empty session in Live and switch to the arrangement view (press TAB).
  * Select a region of 1 bar in an empty MIDI track:
{{ :tutorial:live1.png |Live Arrangement with 1 bar selected}}

  * Press Command-Shift-M, or right click the selection and choose "Insert MIDI Clip".  This will create an empty MIDI clip that we will fill with MIDI notes.
  * Right click the background of the MIDI editor and choose a fixed grid size of 1/16th note:
{{ :tutorial:live2.png |Selecting a grid of 1/16th}}

  * Fill the grid view with 16 consecutive 1/16th notes starting at C0 and ending at D#1((it doesn't matter what note you are starting with, any note will do)).  You can simply double-click the background of the editor to create a new note at the desired place.  Because the grid has been previously chosen to 1/16th the notes will automatically have the right length.
{{ :tutorial:live3.png |MIDI clip filled with 1/16th notes}}

  * In the arrangement, grab the clip on its right hand side (the cursor will change to a right bracket shape), and drag the clip to repeat it over a long period of time:
{{ :tutorial:live3b.png |The clip has been repeated many times}}

  * Go back to Launch mode (press TAB), and set the track's output to ''OSCulator In (8000)''.  This will have the effect of sending the MIDI notes to OSCulator.
{{ :tutorial:live4.png |The track MIDI output is set to OSCulator In (8000)}}

  * Now press play a short time to register the MIDI data in OSCulator.
  * Switch to OSCulator, a message named ''/midi/note/1'' has beed registered.
  * Still in OSCulator, select the pitch parameter, and do Edit->Demux (or Control-D).  This will turn the ''/midi/note/1'' message purple, and fold it, waiting for more data to come.
  * Go back to Live, and press play for at least one bar.  This will register new messages in OSCulator, and you will be able to access all the different notes by their respective pitch.
{{ :tutorial:osculator1.png |OSCulator has registered all the notes in the MIDI clip}}


===== OSCulator configuration =====

First of all, we will need to know what is the network host for the iPhone or iPad.
How to do this [[faq:iphone|is explained in this FAQ]] (//How do I know what is the IP address or host name of my iPhone or iPad?//).

  * Open the Parameters window (Command-Option-P) and go in the OSC Routes tab ;
  * Click on the + button to add a new routing ;
  * Change the //Host// to your's iPhone network name or IP address (we will use here ''gedeon.local'') ;
  * Set the //Port// to TouchOSC's incoming Port (this is given in TouchOSC's Network setup, and we will use 8001) ;
  * Click on the //Rewrite Address// field to edit the rewrite address, this will display the OSC editor window ;
  * In the //Target OSC address// field, type ''/2/led1'' ;
  * Back to OSCulator (don't close the OSC Editor yet), select the OSC routing you just created, and copy it (Command-C) ;
  * Paste it 15 more times to create 16 OSC routings ;
  * For each routing change the target OSC address to ''/2/led2'', ''/2/led3'', and so on ;
  * You should have this (don't pay attention to the sorting order, but you get the idea):
{{ :tutorial:osculator2.png |All teh 16 OSC routings have been created}}

  * Click OK to dismiss the Parameters window ;
  * Select every //trigger// parameters.  To do this, select the first one, then hold the Command key and click on the 15 other ones ;
  * In the //Event Type// column, select //OSC Routing// ;
  * In the //Value// column, select ''gedeon.local:8001 -> /2/led1'' (of course, this is not ''gedeon'' but your phone's network name) ;
  * Assign the other the routings by note pitch order ((you will notice that as of version 2.9.5, OSCulator doesn't sort properly the OSC routings, be sure to choose them in the correct order)) ;
  * You will end up will something like:
{{ :tutorial:osculator3.png |OSCulator with the completed OSC configuration}}

If you press play in Live, and you should be able to see the LEDs blinking in the order given by the MIDI track.
===== Further notes =====

You can download the setup files of this tutorial {{:tutorial:touchosc_live_leds_project.zip|here}}.  If you want to use these files, you will have to change the OSC Routings' target host to your phone's IP address or network host name, or it won't work.

It should be noted that the LEDs will not blink with a very precise timing, which can be disappointing.
This is due to a limitation of iPhone OS that will throttle the network input to 250 ms time slices in order to optimize battery usage.  The fun thing is that every time the phone is sending data over the network this throttling effect fades away.  You can try to move a slider quickly back and forth, and you will see that the LEDs timing becomes much more accurate.

I hope this is something Rob((the author of TouchOSC)) can fix in a future release of his great software!