Open Sound Control is a protocol that was originally developed for communication between synthesizers, musical instruments, and other multimedia devices but has transformed into a popular tool for interactive installations, particularly as an alternative for MIDI. Lightform devices can be controlled through OSC to create interactive experiences. The information and tables on this page include all the information you need to know when mapping OSC controls with other applications.
The first two things to know when working with OSC are the IP Address and Port.
- IP Address: This is the IP address of your Lightform device. You can find this by going to the Control page in Lightform Creator and it is listed as Hostname.
- Port: The port for all Lightform devices is 8000
To control a specific property such as switching to the next slide or increasing the speed of an effect, you need to know some information about it so you can control it by sending an OSC message from another application.
OSC Messages can consist of three parts:
- Command Path: an OSC-string beginning with the character '/' (forward slash)
- Type Tag: Lightform properties use the following types:
- f : float (a number that has a decimal place)
- b : boolean
- i : integer
- Argument(s): The actual value you want to set, which is a number within a range
For example, to decrease the brightness of the projection to half, you would send the message: /brightness f 0.5
Global Controls
The following table includes information about Global properties that can be controlled through OSC. Global properties can be controlled simply by sending a message with just the command path except for brightness and set slide, those require a type tag and argument as well.
| Name | OSC Message |
| Play | /play |
| Pause | /pause |
| Stop | /stop |
| Next Slide | /next |
| Previous Slide | /prev |
| Set Slide Index |
/slide f 0.0 (first slide) |
| Brightness | /brightness f [0.0-1.0] |
| Set Slide Index (normalized) |
/slide/norm f [0.0-1.0] Example: If you have 4 slides: |
OSC Controls for Live Effects
When you make an effect or generator live (see Live Effects) and publish, it's parameters will be controllable through OSC commands. The command path takes the form of:
-
- /<Slide Name>/<Parameter Name>
During playback, you will be able to see the command paths on the device control page, on the "Slides" tab. For example when you publish a slide with a live Checkerboard generator:
In this example, the parameters accept the following commands:
| Parameter | OSC Message | Notes |
| Loop Count | /Slide/loopCount i [0-20] /Slide/loopCount f [0.0-20.0] |
|
| Color A | /Slide/colorA f [red] f [green] f [blue] f [alpha] | Colors in [0.0-1.0] |
| Color B | /Slide/colorB f [red] f [green] f [blue] f [alpha] | Colors in [0.0-1.0] |
| Correct Aspect |
/Slide/coorectAspect b [true|false] |
0.0 -> false >0.0 -> true |
|
Grid Size X |
/Slide/gridSizeX i [1-128] /Slide/gridSizeX f [1.0-128.0] |
|
|
Grid Size Y |
/Slide/gridSizeY i [1-128] /Slide/gridSizeY f [1.0-128.0] |
|
|
Animate |
/Slide/animate b [true|false] |
0.0 -> false >0.0 -> true |
In addition to the commands listed on the device page, you can append addition options that change the behavior of the command:
Range Normalized Commands: /slide/parameter/norm f [0.0-1.0]:
Remaps the range [0.0-1.0] to the min/max range of the parameter. This is useful for tools (such as Ableton) that only support sending float values from 0.0-1.0
Checkerboard above also accepts the following command for example:
| Parameter | OSC Message | Notes |
| Loop Count | /Slide/loopCount/norm f [0.0-1.0] | Remaps input to [0.0-20.0] |
| Grid Size X | /Slide/gridSizeX/norm f [0.0-1.0] | Remaps input to [1.0-128.0] |
| Grid Size Y | /Slide/gridSizeY/norm f [0.0-1.0] | Remaps input to [1.0-128.0] |
Indexed Commands
Indexed commands let you change a single component in multi-valued parameters (colors, 2D positions). By appending /1 you can change the x coordinate or red value, or appending /2 the y or green value. This lets you control these values in tools (such as Ableton) that only support sending one value per message.
Checkerboard above also accepts the following command for example:
| Parameter | OSC Message | Notes |
| Color A | /Slide/colorA/1 f [0.0-1.0] /Slide/colorA/2 f [0.0-1.0] /Slide/colorA/3 f [0.0-1.0] /Slide/colorA/4 f [0.0-1.0] |
Red Green Blue Alpha |
| Color B | /Slide/colorB/1 f [0.0-1.0] /Slide/colorB/2 f [0.0-1.0] /Slide/colorB/3 f [0.0-1.0] /Slide/colorB/4 f [0.0-1.0] |
Red Green Blue Alpha |
Learning Command Paths
When you press the "Learn" button on the device control page the device will enter a state of listening for the next OSC message it receives. The command path in the message will replace the path of the listened parameter. This is useful for tools that uses default paths for sliders, knobs or other controls, and you can quickly assign parameters by listening and then triggering the control.
Sending OSC Commands through sendosc
sendosc is a command line tool for sending OSC messages. You can learn more about it here.
A sendosc command requires: sendosc + <IP address of your Lightform device> + 8000 (port info) + OSC message
For example, to switch to the next slide, the command will be:
sendosc 192.168.0.21 8000 /next
To increase the amount of noise in the Depth Trace effect on Slide 2, the command will be:
sendosc 192.168.0.21 8000 "/Slide 2/noise" f 1.0
Note: If your OSC path has spaces, you need to surround the path with quotes, like in the above example "/Slide 2/noise".
Comments
3 comments
Could we get a tutorial video on this? I bought a stream deck and would like to add this OSC and STream Deck to the lightform for our YouTube shows and Media
Hi Joseph Hernandez, have you checked out this article about using Stream Deck: https://guide.lightform.com/hc/articles/360043472593
I wish we had DMX control...
Please sign in to leave a comment.