Skip to main content

OSC Controls

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:

  1. Command Path: an OSC-string beginning with the character '/' (forward slash)
  2. Type Tag: Lightform properties use the following types:
    • f : float (a number that has a decimal place)
    • b : boolean
    • i : integer
  3. 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)
/slide i 0 (first slide)
/slide f 1.0 (second slide)
/slide i 1 (second slide)
etc.
Brightness /brightness f [0.0-1.0]
Set Slide Index (normalized)

/slide/norm f [0.0-1.0]

Example: If you have 4 slides:
/slide/norm f [0.0-0.25) (first slide)
/slide/norm f [0.25-0.5) (second slide)
/slide/norm f [0.5-0.75) (third slide)
/slide/norm f [0.75-1.0] (fourth slide)

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:

mceclip2.png

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]
/Slide/coorectAspect f [0.0-1.0]

 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]
/Slide/animate f [0.0-1.0]

 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".

Related articles

Comments

3 comments

Date Votes

Please sign in to leave a comment.