Using TouchOSC with Isadora Print

(Click here to jump to a discussion of this Knowledge Base article in the TroikaTronix Forum.)

Hexler’s TouchOSC is a powerful “virtual control surface” that runs on iOS and Android devices. It communicates with Isadora using the Open Sound Control (OSC) protocol. Below you will find step-by-step instructions on how to get Isadora and TouchOSC to work together.

STEP 1: CONNECT TO A NETWORK

Isadora and TouchOSC need to be on the same WiFi network to talk to each other. Just follow the normal procedures to connect to the computer running Isadora and your iOS/Android device to the same WiFi network.

IMPORTANT: Some networks or Firewalls will block unknown ports, preventing TouchOSC and Isadora from communicating with each other. If you’re using your own WiFi connection, then you’ll probably be OK. But if you’re using a corporate or university WiFi connection, you may run into trouble.

See the section labeled “Troubleshooting” below for more help.

STEP 2: FIND THE IP ADDRESS OF YOUR COMPUTER

Mac OS X: Open the System Preferences, click on Network, and then click on Airport or WiFi in the left hand pane. On the right, next to “Status” you will see the text “AirPort is connected to MyWifiNetwork and has the IP address xxx.xxx.xxx.xxx“

xxx.xxx.xxx.xxx is your computer’s IP address.

Windows: To open a Command Prompt, first click Start and then typing cmd into the search box. The click the "Command Prompt" result. In the window that appears, type ipconfig and hit return. The result will look something like this.

Connection-specific DNS Suffix. . : someplace.net.
IP Address. . . . . . . . . . . . : xxx.xxx.xxx.xxx
Subnet Mask . . . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . . . : 192.168.201.1

xxx.xxx.xxx.xxx is your computer’s IP address.

STEP 3: SET UP TOUCHOSC

Start TouchOSC on your iOS or Android device.

You’ll first be presented with the TouchOSC Configuration panel show below.

For now you can work with the default layout. But, later, if you wish to try other layouts, click Layout to select other options.

You need to click on the first line, labeled OSC. This will open the OSC setup panel.

• Make sure that the Enabled switch is on.
• Click on Host and enter the IP address of your computer from Step 2. Hit “Done” or “Enter”
• Go to Isadora. Open the Isadora Preferences and click the “Midi/Net” tab. The port number on which Isadora will receive OSC messages is shown under Open Sound Control (OSC) Port Number. (The default value is 1234.)
• Go back to TouchOSC. Click on Port (outgoing) and enter the port number you found in the previous step.
• Also take note of the Port (incoming) and Local IP Address fields. These give you the IP Address and port number on which TouchOSC can receive messages from Isadora. We’ll use these in the last part of this primer.
• Click the TouchOSC button to return to the TouchOSC Configuration panel

Finally, click Done in the TouchOSC Configuration panel to show the TouchOSC control surface. What you see will vary depending on the configuration, but it should look something like this.

STEP 4: SET UP ISADORA

Now, back in Isadora:

• Choose Stream Setup from the Communications menu. A dialog will appear that looks like this.
  
• The Stream Select menu will already be set to Open Sound Control.
• Click the Auto-Detect Input checkbox to enable the auto-detect feature.
• Then, start touching some of the sliders and buttons on TouchOSC’s control surface. You should see some lines of information appear in the Isadora’s Stream Setup Window, as shown in the picture below. (If you don’t see any lines appear, see the “Troubleshooting” section at the end of this tutorial for help.)

  

In this example, the first line is from a fader (i.e., slider), the second is from a push button, and the last line is from a rotary (i.e., dial) control. Each control on the panel has its own, unique identifier.

To the right of each control identifier you will see the last value received from the control. Sliders, dials, and other “continuous controllers” will send values ranging from 0.0 to 1.0. Buttons send a 1.0 when pressed, and a 0.0 when released.

To finish the Isadora setup, you need to assign a “channel” number to each control. (Note: this parameter used to be called “port” in older versions of Isadora before 1.3.1f03) This channel number is used by Isadora to “listen” to the control.

Why do we use these channel numbers and not the OSC address itself? Because, later you may want to switch to another controller with different OSC addresses. If that were the case, all you would need to do is to edit the OSC addresses in the Stream Setup window and your Isadora patch will work exactly as it did before.

An easy way to set up the port numbers is to click the Renumber Channels button. It will automatically fill in the channel numbers for you. After pressing this button, our setup looks like this:

Now you’re ready to receive the values in Isadora.

Take note of the first two or three entries in the list, remembering which control is assigned to channel 1, which control is assigned to channel 2, etc.

Click OK to close the Stream Setup Dialog

STEP 5: RECEIVE THE VALUES IN ISADORA

Now, in your Isadora patch, add an OSC Listener actor. The ‘channel’ input is set to 1 by default.

Now, touch the control associated with channel 1. You should see the ‘value’ output of the OSC Listener change. Add another OSC Listener, and change the ‘channel’ input to 2, and touch the control associated with channel 2. Again, you should see the ‘value’ output change. You can add an OSC Listener for as many channels as you added in the Stream Setup window.

Let’s make an example. Choose an OSC Listener that is receiving a “continuous controller” like a slider or dial.

First, add a movie to the Media Window. Then, add a Movie Player and Projector actors to your Scene. Connect the ‘video’ output of the Movie Player to the ‘video’ input of the Projector. Finally, connect the ‘value’ output of the OSC Listener to the ‘intensity’ input of the Projector. Your patch should look something like this.

If you haven’t done so already, choose Show Stages from the Output menu to show the Isadora stage.

Now touch your control. The stage is dark. Why? Well, the ‘intensity’ value of the Projector is going between 1.0 and 0.0, but the ‘intensity’ value expects a value of 100.0 to show the image at its full brightness.

The problem here one of scaling. (This topic is covered in depth in the Isadora manual and in the two part video tutorial “Value Scaling” on You Tube, click here for part 1 or part 2.) But here’s how to fix it for TouchOSC and the OSC Listener.

Mini Tutorial On Scaling

• Click on the word ‘intensity’ in the Projector actor. This will open an “inspector.” Inside you’ll see the words Scale Min and Scale Max, and these values will be set to 0 and 100 respectively. That defines the range of values that the ‘intensity’ input will accept. So far so good.
• Now, click on the word ‘value’ in the OSC Listener
• In the inspector box that appears, look at the Limit Min and Limit Max parameters. They say MIN and MAX respectively. These special values mean “no limit.” Isadora cannot know what range of values an OSC device will send, each product might send a different range. When any of the scaling parameters are set to MIN or MAX, no scaling can occur because Isadora needs a valid range for both the input and the output.
• To solve this problem, the Scale Min value to 0 and the Scale Max to 1.
• Try touching the slider or dial again, and you’ll see it works.

Why? Because Isadora knows the output range of the OSC Listener is 0 to 1, and the input range of the intensity is 0 to 100. It can then automatically scale the values, so that 0.25 from the OSC Listener becomes 25 in the intensity input, 0.64 becomes 64, and so on.

Isadora’s automatic scaling is one of the most important features to understand if you want to get the most out of the program. We encourage to you read the manual and consult the tutorials if you are unfamiliar with this part of Isadora.

STEP 5: ADD A MULTI-VALUE CONTROL

Some controls send more than one number. Try clicking TouchOSC’s Tab-Bar (they light grey area at the left or top of the TouchOSC interface) to switch between layouts. One of them should have a 2D Slider, which looks something like this.

Then do the following:

• In Isadora, choose Stream Setup from the Communications window.
• Click the Auto-Detect Input checkbox to enable the auto-detect feature.
• In TouchOSC move the 2D Slider.
  A new entry should appear in the Stream Setup Window.
  

Notice that under the Data column, there are two numbers. That’s because the 2D Slider sends both the horizontal and vertical (i.e., x and y) coordinates of the slider. These appear together because the two values are “bundled” into one OSC message. (A device can attach as many numbers to a message as it likes; programs that send 3D position information often have 3 values for x, y and z.)

• Click the Renumber Channels button again to automatically assign this new control a channel number. You need to take note of this new channel number for the 2D Slider.
• Click OK to close the Stream Setup window.
• Note: in our example, as shown above, the channel number of the /3/xy2 entry was set to 4 by the Renumber Channels button.

So, we want both the x and y position of the 2D Slider, but we only assigned one port. How do we get that both numbers?

Isadora senses how many values are transmitted with each message. If a message has more than one value, then Isadora assigns the values to consecutive OSC Listener channel numbers.

So, since we set the channel number of the 2D Slider to 4, the first value (x) will arrive on OSC Listener channel 4, and the second value (y) will arrive on OSC Listener channel 5.

So now modify your patch as follows:

Don’t forget to click on the word ‘value’ set set the Limit Min and Limit Max to 0 and 1 respectively!

Now, if you move the 2D Slider, the image will move left and right according to the x-value, and up and down according to the y-value.

STEP 6: CONCLUSION

Hopefully this tutorial allowed you to get up and running with TouchOSC. If you have any comments are corrections regarding this tutorial, please post them in this topic.

TROUBLESHOOTING

Sometimes, even after following all of our instructions above, you find that your Isadora is not receiving messages from TouchOSC. This section will at least help you find out of there is a valid connection of some kind between your computer and your iOS/Android device.

iOS: I downloaded a free program from the app store called “Free Ping.” When you run it, you enter the IP address of the computer running Isadora. If there is a connection, you’ll see lines appear like

64 bytes from 192.168.0.3 icmp_seq_=1 ttl=6 time=25.2344 ms

it there is no connection, you see lines saying that the ping attempt “timed out.”

Android: I don’t have an android device, but the app “Ping DNS” seems similar. If you find other apps that do the job better, please write something about it on the forum and I’ll update this entry.