Watch out, this tutorial covers features that are only available in Live and Trial. Start users, you can upgrade now!

 

 

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. The first part details the instructions for the setup with a smartphone and tablet app and you’ll also find the complete list of OSC messages at the bottom of the page.

 

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! Here, we’ll focus on how to control HeavyM from an iOS and Android app, with tools that allow for a quick and easy setup.

Note: if you want to go further and build your own installation, we have listed all the OSC messages you can use to control HeavyM at the bottom of this page. 

 

Finding a layout

example of OSC layout
Example of TouchOSC 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.  

But creating a layout or customizing a template requires time and some coding. That’s why we have created a ready-to-use layout for HeavyM, that works for the TouchOSC app. This app is available for about $5 (USD) on Android and iOS devices. (We promise we’re not sponsored by this app.)

So you have three 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 Editor (on Mac/Windows/Linux and free, but your layout will only work with apps that support .touchosc layouts).

Building a layout requires creating the elements of the user interface and assigning HeavyM commands to it. The complete list of OSC messages for HeavyM is detailed at the bottom of this page.

 

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.

You need to associate actions with buttons, using the HeavyM OSC messages listed at the bottom of this page. Again, you can use TouchOSC Editor to do so for example.

 

Option 3: use the HeavyM TouchOSC layout

The last solution (maybe the best!) is to download the HeavyM Live TouchOSC pattern from our Resources page. This layout was built by our team and is ready-to-use with HeavyM: the control panels are organized and linked with HeavyM commands. It is also regularly updated with new features that come with new HeavyM versions.

Note: if you want, you can still edit our HeavyM layout to customize it and adapt it to your project. You might need to use the last update of TouchOSC Editor to edit it, for compatibility reasons.

The next paragraphs will give specific instructions to help you get set up with the TouchOSC app and HeavyM.

 

Setting up TouchOSC with HeavyM

To follow these instructions, you need to open HeavyM, TouchOSC and to have a layout ready.

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 Android version of the app. The iOS interface is slightly different but the actions are similar.

 

TouchOSC app home page
TouchOSC app home page

1. First, you need to import your layout. Transfer it to your device and, in TouchOSC, go to Layout → Add from File, then browse your files to find it. Then if you click on Done in the home page, you should have access to your layout.

 

HeavyM OSC layout
A tab of the HeavyM layout in TouchOSC

2. Now you need to configure the connection. Come back to the home page by clicking on the button with the grey circle on the top-right corner. Then, go to the OSC menu.

 

TouchOSC menu
TouchOSC menu

In the Host input field, you need to enter your computer’s IP address. You can usually find it under Settings or System Preferences, in the Network properties.

3. Don’t change the other settings, but keep this menu open because you’ll need some info from it in the next steps.

In HeavyM

1. In the Controls menu, select OSC Control. Make sure there is a small tick next to it that indicates it is activated.

HeavyM Controls menu

 

2. Still in the Controls menu, select OSC Settings…. This will open a window to let you configure the connection.

 

 

3. Under Osc ports, in Incoming, you need to put the number that is indicated in the Port (outgoing) field in TouchOSC. Inversely, in Outgoing, type in the number that is indicated in the Port (incoming) field in TouchOSC.

 

HeavyM OSC ports settings
Ports numbers in TouchOSC (left) and HeavyM (right)

4. Under Remote Device IP, type in the Local IP Address that is given to you in TouchOSC, in the OSC page.

Now, go back to the home page in TouchOSC and click on Done. Try to play with some buttons or other elements and you should see that your actions are replicated in the software.

If you are using the HeavyM layout, you’ll see there are different tabs: the first one lets you access sequences, player, tempo and group selection features and the last five tabs correspond to the five categories of effects you can find in HeavyM. You’ll see that the operation of these different panels is quite similar to what you are used to in the software.

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.

 

List of OSC messages

When you use an OSC message, you usually have to send an argument with a value with it. In HeavyM, arguments are integer numbers.

Depending on the type of element you want to control in HeavyM, the range of values you need to send will be different:

  • You’ll see that when you want to control a value slider, you need to send an int between 0 and 127 (except for the BPM value). These values allow you to cover the full range of values of a slider, 0 being the minimum and 127 the maximum (for example, for the Border – Thickness slider, 0 corresponds to 0 and 127 to 15).
  • Now if you want to control a push button or selection, simply send 1 and that’ll trigger it. (Technically, any other value between 1 and 127 will also work.)
  • Finally, for toggles you’ll usually need to send either 0 or 1 to get the desired state (0 for OFF and 1 for ON for instance).  (Technically, any other value between 1 and 127 will also work for the second state.)

Messages for general commands

Group selection

MESSAGE ARGUMENT ACTION
/SelectGroup0 (int) send 1 to trigger Select Group 0 (white)
/SelectGroup1 (int) send 1 to trigger Select Group 1 (green)
/SelectGroup2 (int) send 1 to trigger Select Group 2 (light blue)
/SelectGroup3 (int) send 1 to trigger Select Group 3 (dark blue)
/SelectGroup4 (int) send 1 to trigger Select Group 4 (purple)
/SelectGroup5 (int) send 1 to trigger Select Group 5 (pink)
/SelectGroup6 (int) send 1 to trigger Select Group 6 (orange)
/SelectGroup7 (int) send 1 to trigger Select Group 7 (red)

 

 

Sequencer

MESSAGE ARGUMENT ACTION
/changeSeq (int) use sequence number as argument Select sequence
/SeqControlPlay (int) send 1 to trigger Play/Pause timeline
/SeqControlPrevious (int) send 1 to trigger Select previous sequence / Restart current sequence if playback is on
/SeqControlNext (int) send 1 to trigger Next sequence
/SeqControlStop (int) send 1 to trigger Stop playback
/SeqControlShuffle (int) send 0 to toggle OFF / 1 to toggle ON Toggle random sequence playback
/SeqControlAdd (int) send 1 to trigger Add sequence
/SeqControlDelete (int) send 1 to trigger Delete selected sequence

 

 

Tempo

MESSAGE ARGUMENT ACTION
/Tempo (int) range 20-400 Change BPM value
/TapTempo (int) send 1 to trigger Trigger TAP module

 

 

Players

MESSAGE ARGUMENT ACTION
/PlayerPlayPause/idPlayer (replace “idPlayer” in the message by player number) Play/Pause player
/PlayAllPlayers (int) send 1 to trigger Play all players in sequence
/PauseAllPlayers (int) send 1 to trigger Pause all players in sequence
/StopAllPlayers (int) send 1 to trigger Stop all players in sequence

 

Messages for effects

Border effect

MESSAGE ARGUMENT ACTION
/BorderActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/BorderMode (int) send 1 to trigger Switch mode
/BorderColor (int) range 0-127 Change color
/BorderWidth (int) range 0-127 Change thickness value
/BorderSpeed (int) range 0-127 Change speed value
/BorderPhase (int) range 0-127 Change phase value

 

 

Line effect

MESSAGE ARGUMENT ACTION
/LineActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/LineMode (int) send 1 to trigger Switch mode
/LineColor (int) range 0-127 Change color
/LineWidth (int) range 0-127 Change thickness value
/LineLength (int) range 0-127 Change length value
/LineNumber (int) range 0-127 Change number of dashes
/LineSpeed (int) range 0-127 Change speed value
/LinePhase (int) range 0-127 Change phase value
/LineDirection (int) send 1 to trigger Switch direction

 

 

Repeat effect

MESSAGE ARGUMENT ACTION
/RepeatActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/RepeatNumber (int) range 0-127 Change number of duplications
/RepeatDepth (int) range 0-127 Change depth value
/RepeatCenter (int) send 0 for Default / 1 for Custom Toggle origin

 

 

Color effect

MESSAGE ARGUMENT ACTION
/FillColorActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/FillColorNormalActivated (int) send 1 to trigger Select Plain Color mode
/FillColorNormal (int) range 0-127 Change Plain color
/FillColorGradientActivated (int) send 1 to trigger Select Gradient mode
/FillColorGradient1 (int) range 0-127 Change Gradient color 1
/FillColorGradient2 (int) range 0-127 Change Gradient color 2
/FillColorGradientMode (int) send 1 to trigger Switch Gradient motion mode
/FillColorGradientDirection (int) range 0-127 Change angle for Gradient direction 1
/FillColorGradientDirection2 (int) range 0-127 Change angle for Gradient direction 2
/FillColorGradientSpeed (int) range 0-127 Change Gradient speed value
/FillColorGradientPhase (int) range 0-127 Change Gradient phase value
/FillColorRandomActivated (int) send 1 to trigger Select Random mode
/FillColorRandom1 (int) range 0-127 Change Random color 1
/FillColorRandom2 (int) range 0-127 Change Random color 2
/FillColorRandom3 (int) range 0-127 Change Random color 3
/FillColorRandom4 (int) range 0-127 Change Random color 4
/FillColorRandom5 (int) range 0-127 Change Random color 5
/FillColorRandomWeight1 (int) range 0-127 Change weight of Random color 1
/FillColorRandomWeight2 (int) range 0-127 Change weight of Random color 2
/FillColorRandomWeight3 (int) range 0-127 Change weight of Random color 3
/FillColorRandomWeight4 (int) range 0-127 Change weight of Random color 4
/FillColorRandomWeight5 (int) range 0-127 Change weight of Random color 5
/FillColorRandomMode (int) send 1 to trigger Switch Random shuffle mode
/FillColorRandomTempo (int) range 0-127 Change Random speed/tempo value
/FillColorRandomTransition (int) send 0 for None / 1 for Smooth Toggle Random transition mode

 

 

Special effect

MESSAGE ARGUMENT ACTION
/FillSpecialActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/FillSpecialSwipeSolo (int) send 1 to trigger Select Swipe (solo) mode
/FillSpecialInside (int) send 1 to trigger Select Inside mode
/FillSpecialOutside (int) send 1 to trigger Select Outside mode
/FillSpecialCorner (int) send 1 to trigger Select Corner mode
/FillSpecialStairs (int) send 1 to trigger Select Stairs mode
/FillSpecialSwipeGlobal (int) send 1 to trigger Select Swipe (global) mode
/FillSpecialHypnotic (int) send 1 to trigger Select Hypnotic mode
/FillSpecialStripes (int) send 1 to trigger Select Stripes mode
/FillSpecialMosaic (int) send 1 to trigger Select Mosaic mode
/FillSpecialColor (int) range 0-127 Change color
/FillSpecialValue (int) range 0-127 Change fill percentage
/FillSpecialSpeed (int) range 0-127 Change speed value
/FillSpecialPhase (int) range 0-127 Change phase value
/FillSpecialSizeStripes (int) range 0-127 Change stripes width
/FillSpecialDirection (int) range 0-127 Change direction angle
/FillSpecialCenter (int) send 0 for Default / 1 for Custom Toggle origin

 

 

Snake effect

MESSAGE ARGUMENT ACTION
/FillSnakeActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/FillSnakeApplyColor (int) send 0 to uncheck / 1 to check Apply/don’t apply Snake on Color
/FillSnakeApplySpecial (int) send 0 to uncheck / 1 to check Apply/don’t apply Snake on Special
/FillSnakeDirection (int) send 1 to trigger Switch direction
/FillSnakeSize (int) range 0-127 (max value is the total number of faces in the group) Change number of parts
/FillSnakeSpeed (int) range 0-127 Change speed value

 

 

Rotation effect

MESSAGE ARGUMENT ACTION
/RotationActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/RotationX (int) send 0 to uncheck / 1 to check Check/uncheck X axis
/RotationY (int) send 0 to uncheck / 1 to check Check/uncheck Y axis
/RotationZ (int) send 0 to uncheck / 1 to check Check/uncheck Z axis
/RotationCenter (int) send 0 for Default / 1 for Custom Toggle origin
/RotationDirection (int) send 1 to trigger Switch direction
/RotationSpeed (int) range 0-127 Change speed value
/RotationPhase (int) range 0-127 Change phase value

 

 

Structure effect

MESSAGE ARGUMENT ACTION
/StructureActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/StructureRadialGlow (int) send 1 to trigger Select Radial Glow mode
/StructureWireframe (int) send 1 to trigger Select Wire Frame mode
/StructureOrigami (int) send 1 to trigger Select Origami mode
/StructureElasticPosition (int) send 1 to trigger Select Elastic Position mode
/StructureElasticRotation (int) send 1 to trigger Select Elastic Rotation mode
/StructureElasticScale (int) send 1 to trigger Select Elastic Scale mode
/StructureStrokes (int) send 1 to trigger Select Strokes mode
/StructureColor (int) range 0-127 Change color
/StructureWidth (int) range 0-127 Change thickness value
/StructureSpeed (int) range 0-127 Change speed value
/StructurePhase (int) range 0-127 Change phase value
/StructureNumber (int) range 0-127 Change instances number
/StructureMultiplier (int) range 0-127 Change instances multiplier
/StructureInsidePhase (int) range 0-127 Change inner offset value
/StructureCenter (int) send 0 for Default / 1 for Custom Toggle origin
/StructureSplitEllipse (int) range 0-127 Number of segments for ellipses

 

 

Start Transition effect

MESSAGE ARGUMENT ACTION
/StartTActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/StartTSwipe (int) send 1 to trigger Select Swipe mode
/StartTInside (int) send 1 to trigger Select Inside mode
/StartTOutside (int) send 1 to trigger Select Outside mode
/StartTCorner (int) send 1 to trigger Select Corner mode
/StartTStairs (int) send 1 to trigger Select Stairs mode
/StartTFade (int) send 1 to trigger Select Fade mode
/StartTBlinds (int) send 1 to trigger Select Blinds mode
/StartTFalls (int) send 1 to trigger Select Falls mode
/StartTDirection (int) range 0-127 Change direction angle
/StartTOrientation (int) send 1 to trigger Switch direction (left-right)
/StartTUpperLeft (int) send 1 to trigger Select upper left origin
/StartTUpperRight (int) send 1 to trigger Select upper right origin
/StartTCenter (int) send 1 to trigger Select center origin
/StartTBottomLeft (int) send 1 to trigger Select bottom left origin
/StartTBottomRight (int) send 1 to trigger Select bottom right origin

 

 

End Transition effect

MESSAGE ARGUMENT ACTION
/EndTActivated (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF
/EndTSwipe (int) send 1 to trigger Select Swipe mode
/EndTInside (int) send 1 to trigger Select Inside mode
/EndTOutside (int) send 1 to trigger Select Outside mode
/EndTCorner (int) send 1 to trigger Select Corner mode
/EndTStairs (int) send 1 to trigger Select Stairs mode
/EndTFade (int) send 1 to trigger Select Fade mode
/EndTBlinds (int) send 1 to trigger Select Blinds mode
/EndTFalls (int) send 1 to trigger Select Falls mode
/EndTDirection (int) range 0-127 Change direction angle
/EndTOrientation (int) send 1 to trigger Switch direction (left-right)
/EndTUpperLeft (int) send 1 to trigger Select upper left origin
/EndTUpperRight (int) send 1 to trigger Select upper right origin
/EndTCenter (int) send 1 to trigger Select center origin
/EndTBottomLeft (int) send 1 to trigger Select bottom left origin
/EndTBottomRight (int) send 1 to trigger Select bottom right origin

 

 

Post Shaders

MESSAGE ARGUMENT ACTION
/ShaderBlackWhiteActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Black & White)
/ShaderBlackWhite (int) range 0-127 Change value (Black & White)
/ShaderBlueActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Blue)
/ShaderBlue (int) range 0-127 Change value (Blue)
/ShaderBlurActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Blur)
/ShaderBlur (int) range 0-127 Change value (Blur)
/ShaderContrasteActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Contrast)
/ShaderContraste (int) range 0-127 Change value (Contrast)
/ShaderConvergenceActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Convergence)
/ShaderConvergence (int) range 0-127 Change value (Convergence)
/ShaderCutSliderActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Cut Slider)
/ShaderCutSlider (int) range 0-127 Change value (Cut Slider)
/ShaderGlowActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Glow)
/ShaderGlow (int) range 0-127 Change value (Glow)
/ShaderGreenActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Green)
/ShaderGreen (int) range 0-127 Change value (Green)
/ShaderNoiseActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Noise)
/ShaderNoise (int) range 0-127 Change value (Noise)
/ShaderOldTVActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Old TV)
/ShaderOldTV (int) range 0-127 Change value (Old TV)
/ShaderRedActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Red)
/ShaderRed (int) range 0-127 Change value (Red)
/ShaderShakerActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Shaker)
/ShaderShaker (int) range 0-127 Change value (Shaker)
/ShaderStrobeActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Strobe)
/ShaderStrobe (int) range 0-127 Change value (Strobe)
/ShaderSlitScanActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (SlitScan)
/ShaderSlitScan (int) range 0-127 Change value (SlitScan)
/ShaderSwellActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Swell)
/ShaderSwell (int) range 0-127 Change value (Swell)
/ShaderTwistActivate (int) send 0 to toggle OFF / 1 to toggle ON Toggle ON/OFF (Twist)
/ShaderTwist (int) range 0-127 Change value (Twist)