⭐ This article revolves around a Pro feature.
This tutorial is intended to help you understand how to use the OSC protocol, in order to control HeavyM from a remote wireless device or app.
In this guide, we’ll mostly focus on how to control HeavyM from an iOS or Android app, with tools that allow for a quick and easy setup. But know that there are many more connections possible via OSC: for example it also allows you to use the timeline-based sequencer app Vezér, or the modular machine Chataigne.
What is OSC?
OSC is the acronym for “Open Sound Control”. It’s a protocol that is used for communication between multimedia devices that is similar to the MIDI protocol, but it allows the transfer of bigger data, faster, and through networks like Wifi and Ethernet. In short, this protocol will allow you to control some features in HeavyM remotely. The great news is that there’s no need to connect everything with kilometers of cable, your devices just need to be on the same network.
This opens up endless possibilities for interactive installations!
Finding a layout
Since you won’t be using HeavyM directly on your smartphone, you need to use an app with a special layout, in order to have a functional user interface, with sliders and buttons. There are many apps that let you build these control panels or have layout templates. Here's an example of a layout in TouchOSC:
You have two options to get a layout:
Option 1: build a layout from scratch
We won’t get into details about how to create a layout here, but you can find many resources on the internet on the subject. If you have the skills and are courageous, you can code it, or you can use a WYSIWYG editor, like TouchOSC, or the Lemur Editor. In these cases, the editors are free to install on a computer, but the layouts you create will only work with the associated applications you buy from the app store. (You can usually also build a layout directly from the mobile or tablet app!)
Building a layout requires creating the elements of the user interface, importing the layout in the app if you built it on a computer and assigning HeavyM commands to them. To learn how to import your layout, please refer to the associated app's manual.
Creating a layout your own layout can be fastidious, but you'll get more control over how each element works, what information it sends to HeavyM and when, etc.
Option 2: configure an existing template
Some apps provide you with layout templates. That means that the first step is done: buttons, sliders, or other interface elements are already organized in tabs, but you still have to configure them. Indeed, these elements are “empty”, they don’t have any assignment so they are not linked to HeavyM features yet.
Using a pre-existing layout only requires assigning HeavyM commands to the elements.
⚠️ If you're building your own template and messages, know that HeavyM reacts to float arguments between 0.0 and 1.0 in OSC messages. For sliders, 0.0 represents the minimum value and 1.0 the maximum. For toggles, 0.0 means OFF and 1.0 means ON.
Connecting TouchOSC and HeavyM
The next paragraphs will give specific instructions to help you get set up with the TouchOSC app and HeavyM. (We promise we’re not sponsored by this app.)
To follow these instructions, you need to open HeavyM, TouchOSC and to have a layout ready. If you are using another app, this still might help you as you'll probably find many similarities. Otherwise, please refer to the app's manual.
Note: your devices need to be connected to the same network to communicate, but it doesn’t necessarily have to be a wireless connection: your smartphone can use the Wifi and your computer can use Ethernet for example.
In TouchOSC
Note: these instructions describe the procedure to follow with the iOS version of the app. The Android interface is slightly different but the actions are similar, unless specified.
- First, open the Connections settings by pressing the button with the chain link icon in the editor toolbar, and go to the "OSC" tab.
- There, in the "Host" input field of the first Connection, you need to enter your computer’s IP address. You can usually find it under Settings or System Preferences, in the Network properties.
- In the "Send Port" and "Receive Port" input fields, enter any number between 7 000 and 10 000. (But use different ones in both fields.)
- Keep this tab open, as you'll need information from there, and head over to HeavyM.
In HeavyM
- Open the Controls Settings window from Controls → Controls Settings... or
and go to the "OSC" tab. Make sure that OSC Control is ON with the toggle at the top.
- Then, in "Incoming port", you need to put the number that you put in the "Send Port" field in TouchOSC. Inversely, in "Outgoing port", type in the number that is indicated in the "Receive Port" field in TouchOSC.
- In "Output IP address", type in your phone or tablet's IP address. You can usually find it in the Network settings, or some OSC apps sometime display it directly.
Now, go back to your layout and follow the next section of this tutorial to learn how to connect its elements to HeavyM commands.
Note: if you are having trouble after having followed these instructions, you can consult the TouchOSC documentation on their website, it is quite thorough and describes procedures with iOS devices, as well as other advanced features in the app.
Managing Assignments
Enabling OSC Learning
Once your connection is set, you can start assigning buttons, faders, pads and anything your layout contains to commands in HeavyM. To do so, you have to make the elements in the software interface "learn" which item in your OSC layout they should react to.
For that, you need to toggle the OSC Learning interface from the Controls window ("OSC learning mode" button) or menu (Controls → Edit OSC Assignments). A colored overlay will appear over the elements you can map in the interface.
Adding assignments
Select an overlay element with your mouse or trackpad (it will be circled in yellow) and just move or hit the control item on your OSC layout that you want to use with it. This will associate the OSC and interface controls together and you'll see it appear in the list in the Controls settings window.
Once you're done, you can simply toggle the learning mode off with the same button/menu or with [Esc].
Note: you can assign the same OSC layout element to multiple commands at the same time. For example, one single button on your device can be linked to multiple effect toggles, so that when you hit it, all these effects turn on at once!
⚠️ If you're building your own template and messages, know that HeavyM reacts to float arguments between 0.0 and 1.0 in OSC messages. For sliders, 0.0 represents the minimum value and 1.0 the maximum. For toggles, 0.0 means OFF and 1.0 means ON.
Editing assignments
To edit the assignments, just turn on the learning mode again. Then, simply select the desired assignment and trigger the new OSC control you want to use.
Deleting assignments
There are 3 possibilities to delete assignments:
- When the Learning mode is ON, select an overlay and hit [Delete/Backspace]. This will remove the selected assignment.
- Right-click on a single assignment in the table in the Controls window and click on the "Delete assignment" option. This will remove the selected assignment.
- Use the "Delete all assignments" button above the table in the Controls window. This will remove all OSC assignments in the project.
Saving assignments
The OSC assignments you set are directly saved in your .hm project file.
Assignment settings
Each assignement you configure has a set of settings, as you can see in the assignments table of the Controls window.
For OSC assignments, you can edit:
- The Range: this setting appears on sliders or spinboxes for instance. By setting a Min and a Max, you can override the range of the interface element in HeavyM. For example if you set the range to 1 - 15 for the Thickness of the Border effect, when you move the fader you have assigned to it the values will only vary between 1 and 15 no matter how hard you move your fader!