⭐ This article revolves around a Pro feature.
In addition to the possibility to assign your own OSC adresses with the Learning Mode, you can use the default OSC address that are already in place.
Each assignable element of the interface has been given at least one address. If it has more than one address, it means the same result can be achieved in multiple ways. For instance, if you want to edit a sequence, you can reach it via its name or by its position, which means there are 2 addresses for an action.
Ready-to-use templates using the OSC API
The API can be used to build custom templates that can be used with any project, without having to go through the Learning process. To make your life easier, we've build a few ones using the popular OSC app TouchOSC. You can use them as is or quickly copy-paste objects to build your own quickly.
| File | Description | HM v. | Format | Project |
| Sequencer_v1 | a template focusing on live Sequences control, with 4 tabs of 8x8 sequences and a few Master Shaders shortcuts | 2.11 |
2160×1620 |
- |
| GroupEffects_v1 | a simple template containing Group effects parameters (no LFO control) | 2.11 |
2160×1620 |
- |
| Mix_v1 |
a template with an A/B crossfader, intended to control the simple mix of 2 blended Groups. As it is a bit out of the usual HeavyM use, an example project is provided! (see 4th column) |
2.11 |
2160x1620 |
example |
Screenshot of Sequencer_v1
up next: Timeline control, group effects with LFO controls
API reading instructions
The full list of messages in the API can be found in the tables below. Each table uses the same structure:
- 1st column: description of the action
- 2nd column: default OSC address(es)
- 3rd column: argument (always float unless stated)
Note: the value in this 3rd column also usually reprensents what is sent back via feedback. For Coordinates and Dimensions feedback is disabled though, as it can cause infinite loop issues
You'll see it gets veeeery long real quickly so we've used abbreviations throughout the article. In a table, if you see a word between [brackets], please refer to the following instructions to understand what's expected in the address:
[n] corresponds to a integer number, for instance the number of the row where a sequence is, or the position of a group in the Layers list, etc. For shader and group lists, the count starts from the bottom, at 1.
[seqName] corresponds to the name given to the sequence, without spaces. For instance, if you've named it "Act 1-2", then [seqName] = act1-2
[groupName] corresponds to the name given to the group, without spaces. For instance, if you've named it "Group 4", then [groupName] = group4
[mapName] corresponds to the name given to the map, without spaces. For instance, if you've named it "Map 12", then [mapName] = map12
[shapeName] corresponds to the name given to the shape (face or player), without spaces. For instance, if you've named it "Face 4", then [shapeName] = face4
[playerName] corresponds to the name given to the player, without spaces. For instance, if you've named it "Player 4_2", then [playerName] = player4_2
[vertexName] corresponds to the name of the vertex displayed in the header of the Properties panel when it is selected, without spaces. For instance, if your point is named "Vertex 192", then [vertexName] = vertex192.
[cueName] corresponds to the name given to the cue, without spaces. For instance, if you've named it "Play Act 1-2", then [cueName] = playact1-2
[shaderName] corresponds to the name of the shader displayed in the interface, without spaces and file extension. For instance, if your shader is named "Chroma Zoom", then [shaderName] = chromazoom
[parameterName] corresponds to the name of the parameter displayed in the interface, without spaces. It always relates to shaders. For instance, if your parameter says "master_zoom", then [parameterName] = master_zoom
[variable] depends on the type of parameter you're targeting. For group effects, [variable] always refers to a parameter using a slider. For shaders, there are a few additionnal possibilities. Here is what [variable] can mean (with arguments between parenthesis):
-
If the parameter uses a slider, you can target its value but also the properties linked to its LFO variations:
- value (0.0 (0) to 1.0 (100))
- lfo/mode (0.0 Fixed ; 0.1 Sine ; 0.2 Triangle ; 0.3 Trapezoid ; 0.4 Square ; 0.5 Saw Up ; 0.6 Saw Down ; 0.7 Noise ; 0.8 Bass ; 0.9 Mid ; 1.0 High)
- lfo/min (0.0 (0) to 1.0 (100))
- lfo/max (0.0 (0) to 1.0 (100))
- lfo/tempo (0.0 (0) to 1.0 (100))
- lfo/speed (0.0 (0) to 1.0 (100)) - If the parameter uses a checkbox: value (0.0 (unchecked) ou 1.0 (checked))
- If the parameter uses a list: value (0.0 (top item) to 1.0 (bottom item))
- If the parameter is an event, using a button: trigger (1 to trigger)
-
If the parameter is a point, using an x and y graph:
- x (0.0 (min) to 1.0 (max))
- y (0.0 (min) to 1.0 (max))
[colorVariable] is used when the parameter is a color and depends on whether you are targeting a Fixed color or a color of another LFO type. Here is what [colorVariable] can mean (with arguments between parenthesis):
-
Fixed or single color:
- r/value (0.0 (0) to 1.0 (255))
- g/value (0.0 (0) to 1.0 (255))
- b/value (0.0 (0) to 1.0 (255))
- h/value (0.0 (1) to 1.0 (360))
- s/value (0.0 (0) to 1.0 (100))
- v/value (0.0 (0) to 1.0 (100))
- a/value (0.0 (0) to 1.0 (100))
- [n]/select (1.0) with [n] being the position of the saved color from 1 (top left) to 20 (bottom right) -
LFO colors:
- lfo/mode (0.0 Fixed ; 0.1 Sine ; 0.2 Triangle ; 0.3 Trapezoid ; 0.4 Square ; 0.5 Saw Up ; 0.6 Saw Down ; 0.7 Noise ; 0.8 Bass ; 0.9 Mid ; 1.0 High)
- lfo/min/r/value (0.0 (0) to 1.0 (255))
- lfo/min/g/value (0.0 (0) to 1.0 (255))
- lfo/min/b/value (0.0 (0) to 1.0 (255))
- lfo/min/h/value (0.0 (1) to 1.0 (360))
- lfo/min/s/value (0.0 (0) to 1.0 (100))
- lfo/min/v/value (0.0 (0) to 1.0 (100))
- lfo/min/a/value (0.0 (0) to 1.0 (100))
- lfo/min/[n]/select (1.0) with [n] being the position of the saved color from 1 (top left) to 20 (bottom right)
- lfo/max/r/value (0.0 (0) to 1.0 (255))
- lfo/max/g/value (0.0 (0) to 1.0 (255))
- lfo/max/b/value (0.0 (0) to 1.0 (255))
- lfo/max/h/value (0.0 (1) to 1.0 (360))
- lfo/max/s/value (0.0 (0) to 1.0 (100))
- lfo/max/v/value (0.0 (0) to 1.0 (100))
- lfo/max/a/value (0.0 (0) to 1.0 (100))
- lfo/max/[n]/select (1.0) with [n] being the position of the saved color from 1 (top left) to 20 (bottom right)
- lfo/tempo (0.0 (0) to 1.0 (100))
- lfo/speed (0.0 (0) to 1.0 (100))
Don't worry, examples will be given throughout the article!
List of default OSC messages
Here are the tables you'll find below:
-
Master
Master opacity / Master shaders -
Sequencer
Sequence controls / Sequence transitions / Sequence shaders / Tabs / Autopilot / Timeline / Audio Analysis / Tempo -
Groups
Group selection / Group properties / Group shaders / Group effects -
Shapes
Coordinates / Dimensions / Player shaders -
Sources
Playback / Video / Shader / Text
Master
Master opacity
| Opacity |
/master/opacity/value |
0.0 (0%) to 1.0 (100%) |
Master shaders
| Toggle all |
/master/shaders/all/toggle |
1 (on) or 0 (off) |
| Toggle one |
/master/shaders/[shaderName]/toggle |
1 (on) or 0 (off) |
| Parameters |
// Color parameters |
depends on [variable] or [corlorVariable] |
// examples for Chroma Zoom.fs, in second position from the bottom of the list
/master/shaders/chromazoom/toggle
/master/shaders/2/toggle
/master/shaders/chromazoom/master_zoom/value
/master/shaders/chromazoom/master_zoom/lfo/mode
/master/shaders/chromazoom/master_zoom/lfo/min
/master/shaders/chromazoom/master_zoom/lfo/max
/master/shaders/chromazoom/master_zoom/lfo/tempo
/master/shaders/chromazoom/master_zoom/lfo/speed
/master/shaders/2/master_zoom/value
...
Sequencer
Sequence controls
| Edit |
/sequences/[seqName]/edit |
1 |
| Play |
/sequences/[seqName]/play |
1 (play) or 0 (stop) |
| Play previous |
/sequences/playprevious |
1 |
| Play next |
/sequences/playnext |
1 |
| Play blackout |
/sequences/blackout |
1 |
// examples for a sequence named "Seq 1-2"
// located in the second tab, row 2 & column 2
/sequences/seq1-2/edit
/sequences/tabs/2/rows/2/columns/2/edit
/sequences/seq1-2/play
/sequences/tabs/2/rows/2/columns/2/play
Sequence transitions
| Parameters |
/sequences/[seqName]/transition/[parameterName]/[variable] |
depends on [variable] |
// examples for a sequence named "Seq 1-2"
// located in the second tab, row 2 & column 2
// with an Angular transition
/sequences/seq1-2/transition/startingangle/value
/sequences/edited/transition/startingangle/value
/sequences/tabs/2/rows/2/columns/2/transition/startingangle/value
/sequences/seq1-2/transition/startingangle/value
/sequences/seq1-2/transition/startingangle/lfo/mode
/sequences/seq1-2/transition/startingangle/lfo/min
/sequences/seq1-2/transition/startingangle/lfo/max
/sequences/seq1-2/transition/startingangle/lfo/tempo
/sequences/seq1-2/transition/startingangle/lfo/speed
/sequences/edited/transition/startingangle/value
...
Sequence shaders
| Toggle |
/sequences/[seqName]/shaders/[shaderName]/toggle |
1 (on) or 0 (off) |
| Parameters |
// Color parameters |
depends on [variable] or [colorVariable] |
// examples for a sequence named "Seq 1-2"
// located in the second tab, row 2 & column 2
// with Chroma Zoom.fs, in second position from the bottom of its list
/sequences/seq1-2/shaders/chromazoom/toggle
/sequences/edited/shaders/chromazoom/toggle
/sequences/tabs/2/rows/2/columns/2/shaders/chromazoom/toggle
/sequences/seq1-2/shaders/2/toggle
/sequences/edited/shaders/2/toggle
/sequences/tabs/2/rows/2/columns/2/shaders/2/toggle
/sequences/seq1-2/shaders/chromazoom/master_zoom/value
/sequences/seq1-2/shaders/chromazoom/master_zoom/lfo/mode
/sequences/seq1-2/shaders/chromazoom/master_zoom/lfo/min
/sequences/seq1-2/shaders/chromazoom/master_zoom/lfo/max
/sequences/seq1-2/shaders/chromazoom/master_zoom/lfo/tempo
/sequences/seq1-2/shaders/chromazoom/master_zoom/lfo/speed
/sequences/edited/shaders/chromazoom/master_zoom/value
...
Tabs
| Select |
/sequences/tabs/[tabName]/select |
1 |
| Select previous |
/sequences/tabs/selectprevious |
1 |
| Select next |
/sequences/tabs/selectnext |
1 |
// examples for a tab named "Draft 1", in second position from the left
/sequences/tabs/draft1/select
/sequences/tabs/2/select
Autopilot
| Toggle |
/autopilot/toggle |
1 (on) or 0 (off) |
| Select direction |
/autopilot/direction |
0 (left to right) or 1 (random) |
Timeline
| Play / Pause |
/timeline/play |
1 (play) or 0 (pause) |
| Stop |
/timeline/stop |
1 |
| Playhead position |
/timeline/playhead/position |
0.0 (start) to 1.0 (end) |
| Go to cue |
/timeline/cues/[cueName]/goto |
1 |
| Go to next cue |
/timeline/next |
1 |
| Go to previous cue |
/timeline/previous |
1 |
| Cue timestamp |
/timeline/cues/[cueName]/timestamp |
0.0 (start) to 1.0 (end) |
// examples for a cue named "Play Seq 1-2", in second place from the left
/timeline/cues/playseq1-2/goto
/timeline/cues/2/goto
/timeline/cues/playseq1-2/timestamp
/timeline/cues/2/timestamp
Audio Analysis
| Toggle |
/audioanalysis/toggle |
1 (on) or 0 (off) |
| Global gain |
/audioanalysis/gain/global |
0.0 (min) to 1.0 (max) |
| "Bass" gain |
/audioanalysis/gain/bass
|
0.0 (min) to 1.0 (max) |
|
"Mid" gain |
/audioanalysis/gain/mid |
0.0 (min) to 1.0 (max) |
| "High" gain |
/audioanalysis/gain/high |
0.0 (min) to 1.0 (max) |
Tempo
| BPM Value |
/tempo/bpm |
0.0 (20) to 1.0 (999) |
| TAP |
/tempo/tap |
1 |
| Resync |
/tempo/resync |
1 |
| Toggle Ableton Link |
/abletonlink/toggle |
1 (on) or 0 (off) |
Groups
Group selection
| Select |
/sequences/[seqName]/groups/[groupName]/select |
1 |
| Select above |
/sequences/edited/groups/selectabove |
1 |
| Select below |
/sequences/edited/groups/selectbelow |
1 |
// examples for a groupe named "Group D"
// in fourth position from the bottom of the list
// in a sequence named "Seq 1-2"
/sequences/seq1-2/groups/groupd/select
/sequences/edited/groups/4/select
Group properties
| Opacity |
/sequences/[seqName]/groups/[groupName]/opacity/[variable] |
depends on [variable] |
// examples for a groupe named "Group D"
// in fourth position from the bottom of the list
// in a sequence named "Seq 1-2"
/sequences/seq1-2/groups/groupd/opacity/value
/sequences/edited/groups/4/opacity/value
/sequences/edited/groups/selected/opacity/value
/sequences/seq1-2/groups/groupd/opacity/lfo/mode
/sequences/seq1-2/groups/groupd/opacity/lfo/min
/sequences/seq1-2/groups/groupd/opacity/lfo/max
/sequences/seq1-2/groups/groupd/opacity/lfo/tempo
/sequences/seq1-2/groups/groupd/opacity/lfo/speed
/sequences/edited/groups/4/opacity/lfo/mode
...
Group shaders
| Toggle |
/sequences/[seqName]/groups/[groupName]/shaders/[shaderName]/toggle |
1 (on) or 0 (off) |
| Parameters |
// Color parameters |
depends on [variable] or [colorVariable] |
// examples for a groupe named "Group D"
// in fourth position from the bottom of the list
// in a sequence named "Seq 1-2"
// with Chroma Zoom.fs, in second position from the bottom of its list
/sequences/seq1-2/groups/groupd/shaders/chromazoom/toggle
/sequences/edited/groups/4/shaders/chromazoom/toggle
/sequences/edited/groups/selected/shaders/chromazoom/toggle
/sequences/seq1-2/groups/groupd/shaders/2/toggle
/sequences/edited/groups/4/shaders/2/toggle
/sequences/edited/groups/selected/shaders/2/toggle
/sequences/seq1-2/groups/groupd/shaders/chromazoom/master_zoom/value
/sequences/seq1-2/groups/groupd/shaders/chromazoom/master_zoom/lfo/mode
/sequences/seq1-2/groups/groupd/shaders/chromazoom/master_zoom/lfo/min
/sequences/seq1-2/groups/groupd/shaders/chromazoom/master_zoom/lfo/max
/sequences/seq1-2/groups/groupd/shaders/chromazoom/master_zoom/lfo/tempo
/sequences/seq1-2/groups/groupd/shaders/chromazoom/master_zoom/lfo/speed
/sequences/edited/groups/4/shaders/chromazoom/master_zoom/value
...
Group effects
| Toggle effect |
// Addresses follow this structure: |
1 (on) or 0 (off) |
| Select mode |
// Addresses follow this structure: |
1 |
| Border parameters |
// Color (2.13) |
depends on [variable] or [colorVariable] |
| Line parameters |
// Color (2.13) |
depends on [variable] or [colorVariable] |
| Color parameters |
// Color (2.13) |
depends on [variable] or [colorVariable] |
| Special parameters |
// Color (2.13) |
depends on [variable] or [colorVariable] |
| Snake parameters |
// Apply on |
depends on [variable] |
| Rotation parameters |
// Path |
depends on [variable] |
| Structure parameters |
// Color (2.13) |
depends on [variable] or [colorVariable] |
Shapes
Coordinates (2.13)
| X coordinate (shape) |
/sequences/edited/shapes/selected/x/value |
depends on [variable] |
| Y coordinate (shape) |
/sequences/edited/shapes/selected/y/value |
depends on [variable] |
| X coordinate (vertex) |
/sequences/edited/vertex/selected/x/value |
depends on [variable] |
|
Y coordinate (vertex) |
/sequences/edited/vertex/selected/y/value |
depends on [variable] |
| X coordinate (center) |
/sequences/edited/shapes/selected/center/x/[variable] |
depends on [variable] |
|
Y coordinate (center) |
/sequences/edited/shapes/selected/center/y/[variable] |
depends on [variable] |
// examples for a shape named "Player 2"
// with a vertex named “Vertex 192”
// in a map named "Map 1-2"
/sequences/edited/shapes/selected/x/value
/maps/map1-2/shapes/player2/x/value
/sequences/edited/shapes/selected/y/value
/maps/map1-2/shapes/player2/y/value
/sequences/edited/vertex/selected/x/value
/maps/map1-2/shapes/player2/vertex/vertex192/x/value
/sequences/edited/vertex/selected/y/value
/maps/map1-2/shapes/player2/vertex/vertex192/y/value
// possible addresses for center
/sequences/edited/shapes/selected/center/x/value
/sequences/edited/shapes/selected/center/x/lfo/mode
/sequences/edited/shapes/selected/center/x/lfo/min
/sequences/edited/shapes/selected/center/x/lfo/max
/sequences/edited/shapes/selected/center/x/lfo/tempo
/sequences/edited/shapes/selected/center/x/lfo/speed
/sequences/edited/shapes/selected/center/y/value
/sequences/edited/shapes/selected/center/y/lfo/mode
/sequences/edited/shapes/selected/center/y/lfo/min
/sequences/edited/shapes/selected/center/y/lfo/max
/sequences/edited/shapes/selected/center/y/lfo/tempo
/sequences/edited/shapes/selected/center/y/lfo/speed
Dimensions (2.13)
| Width (shape) |
/sequences/edited/shapes/selected/w/value |
depends on [variable] |
| Height (shape) |
/sequences/edited/shapes/selected/h/value |
depends on [variable] |
// examples for a shape named "Player 2"
// in a map named "Map 1-2"
/sequences/edited/shapes/selected/w/value
/maps/map1-2/shapes/player2/w/value
/sequences/edited/shapes/selected/h/value
/maps/map1-2/shapes/player2/h/value
Player shaders
| Toggle |
/sequences/[seqName]/shapes/[playerName]/shaders/[shaderName]/toggle |
1 (on) or 0 (off) |
| Parameters |
// Color parameters |
depends on [variable] or [colorVariable] |
// examples for a player named "Player 2"
// in a sequence named "Seq 1-2"
// with Chroma Zoom.fs, in second position from the bottom of its list
/sequences/seq1-2/shapes/player2/shaders/chromazoom/toggle
/sequences/edited/shapes/player2/shaders/chromazoom/toggle
/sequences/seq1-2/shapes/player2/shaders/2/toggle
/sequences/edited/shapes/player2/shaders/2/toggle
/sequences/seq1-2/shapes/player2/shaders/chromazoom/master_zoom/value
/sequences/seq1-2/shapes/player2/shaders/chromazoom/master_zoom/lfo/mode
/sequences/seq1-2/shapes/player2/shaders/chromazoom/master_zoom/lfo/min
/sequences/seq1-2/shapes/player2/shaders/chromazoom/master_zoom/lfo/max
/sequences/seq1-2/shapes/player2/shaders/chromazoom/master_zoom/lfo/tempo
/sequences/seq1-2/shapes/player2/shaders/chromazoom/master_zoom/lfo/speed
/sequences/edited/shapes/player2/shaders/chromazoom/master_zoom/value
...
Sources
Playback
| Playback mode |
/sources/[n]/playbackmode |
0.0 Normal |
| Toggle "Restart with sequence" |
/sources/[n]/restartwithseq |
1 (on) or 0 (off) |
| Trigger media |
/sources/[n]/medias/[n]/trigger // for playlist sources
|
1 |
| Trigger next media |
/sources/[n]/next // for playlist sources
|
1 |
| Trigger previous media |
/sources/[n]/previous // for playlist sources
|
1 |
| Restart playlist |
/sources/[n]/restart // for playlist sources
|
1 |
| Media loop mode |
/sources/[n]/loop // for solo sources |
0.0 Loop 0.33 Follow (only playlist) 0.66 Pause 1.0 Stop |
// examples for a solo source in 1st position from the top left
/sources/1/playbackmode
/sources/1/restartwithseq
/sources/1/loop
// examples for a playlist source in 2nd position from the top left
// with at least 2 medias
/sources/2/playbackmode
/sources/2/restartwithseq
/sources/2/medias/2/trigger
/sources/2/next
/sources/2/previous
/sources/2/restart
/sources/2/loop
/sources/2/medias/2/loop
Video
| Play / Pause |
/sources/[n]/play // for solo sources |
1 (play) or 0 (pause) |
| Rewind |
/sources/[n]/rewind // for solo sources |
1 |
| Volume |
/sources/[n]/volume // for solo sources |
0.0 (mute) to 1.0 (max) |
// examples for a solo video source in 1st position from the top left
/sources/1/play
/sources/1/rewind
/sources/1/volume
// examples for a playlist source in 2nd position from the top left
// with a video in 1st media position
/sources/2/play
/sources/2/rewind
/sources/2/medias/1/volume
Shader
| Parameters |
// Color parameters |
depends on [variable] or [colorVariable] |
// examples for Bricked.fs in a solo shader source
// in 1st position from the top left
/sources/1/tile/value
/sources/1/tile/lfo/mode
...
// examples for a playlist source in 2nd position from the top left
// with Bricked.fs in 1st media position
/sources/2/medias/1/tile/value
/sources/2/medias/1/tile/lfo/mode
...
Text
| Parameters |
/sources/[n]/align // for solo sources |
0.0 Left 0.5 Center 1.0 Right |
// example for a solo text source in 1st position from the top left
/sources/1/align
// example for a playlist source in 2nd position from the top left
// with a text in 1st media position
/sources/2/medias/1/align