Interacting live with a video mapping
Photo mapping above : https://limbiccinema.com/portfolio-item/the-temple/
With the Keyboard
Did you know that it’s possible to control HeavyM with more than just your mouse or touchpad? Because, let’s be honest, while those tools are very convenient for drawing and adjusting settings while seated at your desk, having to scroll through panels to find a small effect button during a live performance isn’t exactly fun. That’s why you can make your life easier with external controls and use a keyboard, for instance.
Default Keyboard Shortcuts
To make your experience smoother and reduce the number of clicks needed to access certain features, some keyboard shortcuts are already built into the software. The updated list of key combinations for your version can be accessed directly in the software via the menu Controls → Keyboard Shortcuts List… or by using the shortcut [CTRL/Cmd + /].
Custom Shortcuts
In addition to these default shortcuts, you can also define your own keyboard commands for HeavyM. To do this, you need to make the application’s interface “learn” which key it should respond to.
Activating Keyboard Learning
To assign keys, you first need to activate the Keyboard Learning interface. Activate it from the menu:
Controls → Edit MIDI Assignments, or go to the Keyboard tab in the Steuerung settings window (accessible via Controls → Settings… or the icon)
From the toolbar) and click on the “Keyboard Learning mode” button. A colored filter will appear on many elements of the HeavyM interface.
With MIDI
MIDI stands for “Musical Instrument Digital Interface.” It’s a protocol used for communication between electronic instruments and other digital music tools.
You can configure a MIDI instrument to send instructions to HeavyM. In short, this protocol allows you to remotely control HeavyM features using a controller connected to your computer, usually via USB.
Since a MIDI controller typically includes various types of control elements, it offers more possibilities than a keyboard. Once configured, you won’t even need to touch your computer anymore!
Connecting a MIDI Device
Once you’ve connected your MIDI controller to your computer, go to the MIDI tab in the control settings window (accessible via Controls → Settings… or the icon:
From the toolbar) and select your device from the “Device” dropdown list.
If your device is correctly recognized, you will see values appear in the Channel/Control/Value fields when you press a button or move a fader. If there is no response, it might mean that the device is already connected to another application. Indeed, it is not possible to use the same device in multiple programs simultaneously.
Note: For now, you can only connect one MIDI instrument at a time in HeavyM.
Managing Assignments
Activating MIDI Learning
Once your controller is set up, you can assign buttons, faders, pads, or any other control elements it includes to HeavyM commands. To do this, you need to make the application’s interface “learn” which MIDI element it should respond to.
To enable the MIDI Learning interface, use the “MIDI Learning mode” button in the Controls window or go to the menu (Controls → Edit MIDI Assignments). A colored filter will appear on the interface, highlighting the buttons that can be assigned.
Adding Assignments
Select a button or slider by clicking on it (it will be highlighted in yellow), then simply move or click on the control element of your MIDI device that you want to use. This will link the two elements, and you will see the connection appear in the list in the Controls settings window.
Once you’re finished, you can deactivate the Learning mode using the same button/menu or by pressing [Escape].
If your controller supports MIDI Out, the assigned LED buttons will reflect the status of their associated action in the software. For example, on compatible controllers, the buttons will display the color of their assigned sequence in HeavyM, or if a toggle is assigned, the button lights up when it’s ON.
With OSC
What is OSC?
OSC stands for “Open Sound Control.” It’s a protocol used for communication between multimedia devices, similar to the MIDI protocol, but it allows for more data transfer, faster speeds, and works over networks like WIFI or Ethernet. In short, this protocol lets you control HeavyM features remotely, for example, using a smartphone. The good news is that there’s no need for long cables — your devices simply need to be on the same network.
This opens up endless possibilities for interactive installations!
We’ll primarily detail instructions for use with an iOS or Android app, thanks to tools that enable simple and quick setup. However, note that many other OSC connections are possible: for example, the protocol also allows you to use timeline-based automation software like Vezér or the conductor tool Chataigne.
Connecting TouchOSC and HeavyM
The following paragraphs provide specific instructions to help you connect the TouchOSC app with HeavyM. (We’re not sponsored by this app, we promise.)
To follow these instructions, you need to have HeavyM, TouchOSC, and a layout ready. If you are using another application, this guide may still help, as you’ll find many similarities. Otherwise, please refer to your application’s manual.
Note: Your devices must be connected to the same network to communicate, but they don’t necessarily need to be connected wirelessly: your smartphone can use Wi-Fi while your computer is on Ethernet, for example.
In TouchOSC
Note: These instructions outline the procedure for the iOS version of the app. The interface on Android is slightly different, but the actions are similar unless specified otherwise.
- First, open the “Connections” settings by using the button with the chain link icon in the toolbar, and go to the “OSC” tab.
- In der “Host” field of the first “Connection”, enter your computer’s IP address. You can usually find it in Settings oder System Preferences, under Network properties.
- In der “Send Port” und “Receive Port” fields, enter any numbers (different) between 7,000 and 10,000.
- Keep this tab open, as you’ll need to copy some information, and then switch to HeavyM.
In HeavyM
- Open the Steuerung settings window from Controls → Controls Settings… or the icon
and go to the “OSC” tab. Make sure that OSC Control is ON using the button at the top of the window.
- Next, in the “Incoming port” field, enter the number provided in the “Send Port” field of TouchOSC. Conversely, in the “Outgoing port” field, enter the number specified in the “Receive Port” field of TouchOSC.
- In der “Output IP address” field, enter the IP address of your phone or tablet. You can usually find it in your device’s Network settings, or some OSC apps display it directly for you.
Now, return to your layout and follow the next section of this guide to learn how to link layout elements to HeavyM commands.
Note: If you encounter difficulties after following these instructions, you can refer to the TouchOSC documentation on their website (in English). It’s quite detailed and also covers procedures for iOS devices as well as other advanced features in the app.
Managing Assignments
Using HeavyM’s OSC API
In addition to assigning your own OSC addresses with Learning Mode, you can usethe default OSC addresses already built into HeavyM.
Every assignable element of the interface is associated with at least one address. If it has more than one address, it means the same result can be achieved in multiple ways. For example, if you want to edit a sequence, you can access it by its name or by its position, meaning there are two addresses for the same action.
In this case, all assignment configuration is done directly in your OSC-sending application; HeavyM doesn’t even need to be open.
Using OSC Learning to Add Assignments
Once your connection is set up, you can assign buttons, faders, pads, or any other control element included in your layout to HeavyM commands. To do this, you need to make the software interface “learn” which layout OSC element it should respond to.
To enable the OSC Learning interface, use the “OSC learning mode” button in the Controls window or go to the menu (Controls → Edit OSC Assignments). A colored filter will appear on the interface, highlighting the buttons that can be assigned.
Select a button or slider by clicking on it (it will then be highlighted in yellow), and then simply move or click on the control element in your layout that you want to use. This will link the two elements, and you will see the connection appear in the list within the Controls settings window.
Once you’re finished, you can disable Learning mode using the same button/menu or by pressing [Escape].
Note: You can assign the same OSC control element to multiple commands simultaneously. For example, a single button on your device can be associated with multiple effect switches, meaning that when you press it, all those effects will activate at the same time!
⚠️ If you create your own templates and messages, please note that HeavyM responds to “float” arguments between 0.0 and 1.0 in OSC. For sliders, 0.0 represents the minimum value and 1.0 the maximum. For switches, 0.0 corresponds to OFF, and 1.0 to ON.
With DMX / Art-Net
DMX is a standard widely used in stage design for communication between controllers (such as software or lighting consoles) and lights or other stage special effects.
HeavyM supports DMX input control, specifically via the Art-Net protocol. This means you can use a lighting console to send commands to HeavyM over a network.
Setting Up an Art-Net Connection
First, go to the DMX / Art-Net tab in the control settings window (accessible via Controls → Settings… or the toolbar icon).
You need to configure three things:
- Network: Since Art-Net transmits messages over the network, HeavyM and your DMX transmitter must use the same connection (e.g., Wi-Fi, Ethernet, or Loopback on the same computer).
- Subnet and Universe: Set which Subnet and Universe HeavyM should listen to so that it matches your DMX transmitter (default is 0:0).
Managing Assignments
Activating Art-Net Learning
Once your connection is set up, you can assign buttons, faders, or any other elements from your DMX controller to commands in HeavyM. To do this, you need to make the application’s interface “learn” which DMX interface element it should respond to.
To enable the Art-Net Learning interface, use the “Art-Net Learning mode” button in the Controls window or go to the menu (Controls → Edit DMX Assignments). A colored filter will appear on the interface, highlighting the buttons that can be assigned.
To continue
Preparing Your Show or Exporting Your Project
This guide was written by HeavyM, a company specializing in video mapping since 2013.
For any questions, comments, advice, etc., please use this contact form: https://help.heavym.net/hc/requests/new. Response guaranteed within 24 hours.