Open Sound Control API

Overview

The OSC messages that vimix accepts (and sends) are in the form:

 /vimix /[target] /[attibute]  { arguments }

Where

the /vimix prefix is always present,
[target] is the object targeted by the message,
[attribute] is the parameter of the target that is affected by the message.

Depending on the [attribute], the OSC message can be associated with a list of { arguments }.
Arguments for vimix messages must be of type float.

If the first part of the OSC address pattern is well-formed, the remaining of the address is silently ignored.
If the address pattern cannot be treated successfully, a warning messaged appears in vimix logs.

Target a source

Several ways to identify the source target

To target the source currently active, use the target current (see next section).
To target a source by name, use the exact string of characters (case sensitive).
To target a source by # + index, use its position (index) in the left source panel (starting at #0).
NB: If the name or the index are not valid, the call is ignored (an error message is logged).

Examples;
/vimix/SrcName/alpha f 1.0 sets alpha of the source named 'SrcName' to 100% opacity
/vimix/#1/alpha f 1.0 sets alpha of the source at index #1 to 100% opacity
/vimix/current/alpha f 1.0 sets alpha of the current source to 100% opacity

Attributes to control a source

When the target is able to identify a source by its name, by its index, or as the current active source, the following attributes are used to modify it.

play : Set source to Play

Optional argument : if a value is passed, it is considered as true (>0.5) or false (<0.5) to play or pause the source.
Example; send /vimix/current/play to set the source to play, /vimix/current/play f 0.0 set the source to pause.

pause : Set source to Pause

Optional argument : if a value is passed, it is considered as true (>0.5) or false (<0.5) to pause or play the source.
Example; send /vimix/current/pause to set the source to pause, /vimix/current/pause f 0.0 set the source to play.

replay : Restart the source to its beginning

Example; send /vimix/current/replay to ask the source to restart

alpha : Set the opacity of the source (Mixing view)

Mandatory argument : the value is used to set the source opacity between visible (1.0) and transparent (0.0).
Example; send /vimix/current/alpha f 0.3 to set source opacity to 30% (70% transparent).

tranparency : Set the transparency of the source (Mixing view)

Mandatory argument : the value is used to set the source transparency between transparent (1.0) and visible (0.0).
Example; send /vimix/current/transparency f 0.3 to set source transparency to 30% (70% opacity).

loom : Change the alpha of the source (Mixing view)

Mandatory argument : the value is used to indicate the speed (amplitude) of the change of alpha to apply.
Example; send /vimix/current/loom f 1.0 to increase the alpha by 1.0 per second (at 60Hz, that makes 1/60th of change per frame)

position : Set the position of the source (Geometry view)

Mandatory arguments : two floats ff are used to indicate the target position to place the source in the Geometry View.
Example; send /vimix/current/position ff 1.0 1.0 to put the source at the upper right corner (+1 in x and +1 in y).
To set only one coordinate (x OR y), set one type to Nil N in the OSC argument list.
Example; send /vimix/current/position Nf 1.0 to set the Y coordinate to 1.0 without affecting X.

grab : Change the position of the source (Geometry view)

Mandatory arguments : two floats ff are used to indicate the speed (direction and amplitude) of movement to move the source in the Geometry View
Example; send /vimix/current/grab ff 1.0 1.0 to grab the source towards the upper right (+1 in x and +1 in y).
To change only one coordinate (x OR y), set one type to Nil N in the OSC argument list.
Example; send /vimix/current/grab Nf 1.0 to grab in the Y direction without affecting X.

size : Set the size of the source (Geometry view)

Mandatory arguments : two floats ff are used to indicate the size of the source in the Geometry View
Example; send /vimix/current/size ff 1.0 1.0 to set the source width and height to a square
To set only one coordinate (x OR y), set one type to Nil N in the OSC argument list.
Example; send /vimix/current/size Nf 1.0 to set the height to 1.0 without affecting the width.

resize : Change the size of the source (Geometry view)

Mandatory arguments : two floats ff are used to indicate the speed (direction and amplitude) of scaling to change the size of the source in the Geometry View
Example; send /vimix/current/resize ff 1.0 1.0 to enlarge the source width and height,
/vimix/current/resize ff -1.0 -1.0 to reduce the source width and height.
To change only one coordinate (x OR y), set one type to Nil N in the OSC argument list.
Example; send /vimix/current/resize Nf 1.0 to enlarge the height without affecting the width.

angle : Set the angle of the source (Geometry view)

Mandatory argument : the value is used to indicate the angle of rotation to apply on the source in the Geometry View
Example; send /vimix/current/angle f 3.1416 to set the source orientation to 360 degrees (PI).

turn : Change the angle of the source (Geometry view)

Mandatory argument : the value is used to indicate the angular speed (direction and amplitude) of rotation to apply on the source in the Geometry View
Example; send /vimix/current/turn f 1.0 to turn the source in clockwise direction.
/vimix/current/turn f -0.2 to turn the source in counter-clockwise direction, slowly.

reset : Reset the position, scale and angle of the source (Geometry view)

Example; send /vimix/current/reset to restore source position to the center, scale to its original aspect ratio, and no rotation.

depth : Set the depth of the source (Layer view)

Mandatory argument : the value is used to set the source depth, its position in the Layers View between 0.0 (back) and 12.0 (front).
Example; send /vimix/current/depth f 6.0 to set source depth to 6.0 (middle of the workspace).

lock : Lock/unlock the source

Mandatory argument : the value is used to decide to lock ( > 0.5) or unlock (<0.5) the source.
Example; send /vimix/current/lock f 0.0 to unlock the current source.

correction : Enable/Disable color correction of the source

Mandatory argument : the value is used to decide to enable ( > 0.5) or disable (<0.5) the color correction of the source.
Example; send /vimix/current/corection f 0.0 to disable color correction of the current source.

color : Set the gamma color of the source (if color correction enabled)

Mandatory argument : 3 values are used to set the source RGB gamma color.
Example; send /vimix/current/color fff 0.0 0.0 1.0 to set gamma color to blue.
Optional argument : a 4th value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/gamma ffff 0 0 1 1000 triggers a 1000 ms (1 second) animation to reach blue gamma color.

gamma : Set the gamma of the source (if color correction enabled)

Mandatory argument : the value is used to set the source gamma between -1.0 and +1.0.
Example; send /vimix/current/gamma f 1.0 to set gamma to maximum.
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/gamma ff 1.0 1000.0 triggers a 1000 ms (1 second) animation to reach maximum gamma.

brightness : Set the brightness of the source (if color correction enabled)

Mandatory argument : the value is used to set the source brightness between -1.0 and +1.0.
Example; send /vimix/current/brightness f 1.0 to set contrast to maximum.
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/brightness ff 1.0 1000.0 triggers a 1000 ms (1 second) animation to reach maximum contrast.

contrast : Set the contrast of the source (if color correction enabled)

Mandatory argument : the value is used to set the source contrast between -1.0 and +1.0.
Example; send /vimix/current/contrast f 0.0 to reset contrast to no change.
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/contrast ff 1.0 1000.0 triggers a 1000 ms (1 second) animation to reach maximum contrast.

saturation : Set the saturation of the source (if color correction enabled)

Mandatory argument : the value is used to set the source saturation between -1.0 (grayscale) and +1.0.
Example; send /vimix/current/saturation f -1.0 to change to grayscale.
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/saturation ff 1.0 1000.0 triggers a 1000 ms (1 second) animation to reach maximum saturation.

hue : Set the hue shift of the source (if color correction enabled)

Mandatory argument : the value is used to set the source color hue shift between 0.0 (disabled) and 1.0.
Example; send /vimix/current/hue f 0.5 to change hue to the opposite (50%).
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/hue ff 1.0 1000.0 triggers a 1000 ms (1 second) animation to go through all hue.

posterize : Set the color posterization level of the source (if color correction enabled)

Mandatory argument : the value sets the number of colors used to render the image, between 1 and 256, 0 to disable.
Example; send /vimix/current/posterize f 12 to set a posterization in 12 colors.
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/posterize ff 256 1000.0 triggers a 1000 ms (1 second) animation to reach 256 colors.

threshold : Set the threshold of the source (if color correction enabled)

Mandatory argument : the value is used to set the source threshold between 0.0 (disabled) and 1.0.
Example; send /vimix/current/threshold f 0.5 to set threshold.
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/threshold ff 1.0 1000.0 triggers a 1000 ms (1 second) animation to reach threshold.

invert : Set the color invert mode of the source (if color correction enabled)

Mandatory argument : the value is used to set the source invert mode; 0 for None, 1 for RGB invert and 2 for luminance invert
Example; send /vimix/current/invert f 1 to set RGB color inversion.

reload : Reloads the source (e.g., reloads video file of a Media source)

Example; send /vimix/#0/reload to trigger the reloading of source at index #0.

sync : Request synchronization status bundle of Sources

Example; send /vimix/#0/sync to request response bundle status of source at index #0.

Attributes to control different types of sources

speed : Set the playing speed of the source : Media source only

Mandatory argument : the value is used to set the source play speed between 0.1 and 10.0.
Example; send /vimix/current/speed f 2.0 to set play speed to x2 for current source.
Optional argument : a second value defines the duration, in miliseconds, of the animation to reach the given value.
Example; send /vimix/current/speed ff 5.0 1000.0 triggers a 1000 ms (1 second) animation to reach play speed.

seek : Set target position in a video : Media source only

Mandatory argument : the value sets the target time to seek to in a video. If the source cannot seek, nothing happens.

Time as percentage of duration: float [0..1]
Example; send /vimix/current/seek f 0.5 to seek to frame at t=50% of the video duration of the current media source.

Time as Hours minutes seconds mili-seconds: 4 integers
Example; send /vimix/current/seek iiii 0 2 34 56 to seek to frame at t = 0 hours 2 min 34 second and 56 milisecond.

contents : Set text contents : Text source only

Mandatory argument : the string value sets the text to display of a Text source. If the source is not text, nothing happens.
Example; send /vimix/current/contents s "hello" to set the text of the current text source.
NB; text can be empty

Target multiple sources

All above attribute changes on one targeted source can also be applied to multiple sources with one single OSC message by targeting all sources, the current selection of sources, or a saved selection in player.

Target `all` or a `selection` of sources

The target all applies the attribute change to all sources in the session.

Example; /vimix/all/alpha f 0.0 sets alpha of all sources to 0% opacity

The target selection applies the attribute change to currently selected sources in user interface (i.e. user selected).

Example; /vimix/selection/alpha f 0.0 sets alpha of selected sources to 0% opacity

Target a `batch#` of sources

The target batch suffixed with # and a number to identify the batch stored in the media Player.

Example; /vimix/batch#1/play Plays all sources of the stored batch #1

The `current` target

The target current sets which source is active or changes the attribute of the currently active source.

Attributes to change active source

next : Set next source as current.

Example; /vimix/current/next is equivalent to pressing [TAB] in vimix

previous : Set previous source as current.

Example; /vimix/current/previous is equivalent to pressing [SHIFT]+[TAB] in vimix

A number N : Set source at index N as current.

Example; send /vimix/current/0 to set source at index 0 to be current, equivalent to clicking on source at index 0 (first in list) in the left source panel of vimix.

sync : Request synchronization status bundle of Sources

Optional argument : if a value is passed (to sync or other current targets above), it is used for the sending back the status of all sources.

Change attributes of the active source

The target current can also be used to identify the source to modify (see previous section).

The `output` target

The target output affects the global output window rendering.
The possible attributes are:

enable : Enables the output window

Optional argument : if a value is passed, it is considered as true (>0.5) or false (<0.5) to enable or disable the output.
Example; send /vimix/output/enable to enable the output, /vimix/output/enable f 0.0 to disable the output.

disable : Disables the output window

Optional argument : if a value is passed, it is considered as true (>0.5) or false (<0.5) to disable or enable the output.
Example; send /vimix/output/disable to disable the output, /vimix/output/disable f 0.0 to enable the output.

fading : Apply a fading mask on the rendering output

Mandatory argument : the value is used to configure the fading mask on the rendering output.
A fading of 0.0 does not affect the output, a fading of 1.0 entirely hides the output (black screen).
Example; send /vimix/output/fading f 0.5 to set fading to 50%.

Optional second argument : the value is used to animate the fading mask for the given duration (in milisecond).
Example; send /vimix/output/fading ff 0.0 500.0 to launch a smooth fade-out animation lasting 500 ms.

fade-out : Increment fading

Mandatory argument : the value indicates the percentage of increase of fading applied to the rendering output.
Example; send /vimix/output/fade-out f 1.0 to increase fading by 1% (+0.01).

fade-in : Decrement fading

Mandatory argument : the value indicates the percentage of decrease of fading applied to the rendering output.
Example; send /vimix/output/fade-in f 100.0 to decrease fading by 100%.

sync : Request synchronization status bundle of Output

The `session` target

The target session allows accessing the session in vimix.

version : Trigger the restore of a version of the session.

Mandatory argument : the value is used to indicate the index of the version to restore, sorted from the most recent (0) to the oldest.
Example; sending /vimix/session/version f 0 will restore the last version

sync : Request status bundle of session.

Optional argument : if a value is passed, it is transferred to get the status of sources.

open : Trigger the loading of a .mix session file

Mandatory argument : the filename to open, with absolute file path.
Example; send /vimix/session/open s /home/username/mysession.mix to open the session file.
Optional argument : duration, in seconds, of the loading transition.
Example; send /vimix/session/open sf /home/username/mysession.mix 3.5 to start a transition of 3.5s to this session file.

close : Trigger the closing of the current session

Optional argument : duration, in seconds, of the closing transition.
Example; send /vimix/session/close f 2.0 to trigger a smooth transition to black of 2 second before closing the session.

save : Trigger the saving of the current session

Example; send /vimix/session/save to save the session.

The `info` target

The target info can be useful to communicate with vimix. It also allows testing if vimix receives messages from this sender.
Possible attributes are;

log : Forward the message to vimix log window

Example; after receiving /vimix/info/log/hello f 4 vimix should append the following line in the logs:

OSC: received '/vimix/info/log/hello f 4.00' from 127.0.0.1

notify : Forward the message to vimix notification bar and log window

Example; sending /vimix/info/notify/connected will pop-up the notification in vimix.

All other attributes are silently ignored

Example; sending to /vimix/info/ignore can be useful to avoid vimix from generating warning messages in case you cannot avoid that your OSC sender sends a message (e.g. some events you want to ignore).

Automatic translation

Because many applications sending OSC have fixed message patterns, it can be useful to convert a messaged received by vimix into a well-formed message that can be used. vimix will thus pre-process all incoming OSC messages using a translation table. The arguments are passed without change.

Users are responsible for entering the translations in the osc.xml configuration file (located in the settings directory; you can access it from the settings panel).

The default osc.xml dictionary is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!--The OSC translator converts OSC address patterns into other ones.
Complete the dictionnary by adding as many <osc> translations as you want.
Each <osc> should contain a <from> pattern to translate into a <to> pattern.
More at https://github.com/brunoherbelin/vimix/wiki/Open-Sound-Control-API.-->
<osc>
    <from>/example/osc/message</from>
    <to>/vimix/info/log</to>
</osc>

To add a translation, you should enter an <osc> XML node containing 2 nodes: <from> and <to>. The OSC address pattern in <from> will be translated into the address pattern in <to>.

<osc>
    <from> [ pattern received ] </from>
    <to>   [ translation ] </to>
</osc>

Example 1: Download and install LittleOSC (Android). Run it and set the IP Address and Port to target vimix host.
LittleOSC can only send the pre-defined OSC messages /1/push1, /1/push2, /1/push3, and /1/push4 when one of its buttons is pressed. With the translation below, vimix will show the sources 0 to 3 when pressing a button on LittleOSC.

<?xml version="1.0" encoding="UTF-8"?>
<!--LittleOSC translations -->
<osc>
    <from>/1/push1</from>
    <to>/vimix/0/alpha</to>
</osc>
<osc>
    <from>/1/push2</from>
    <to>/vimix/1/alpha</to>
</osc>
<osc>
    <from>/1/push3</from>
    <to>/vimix/2/alpha</to>
</osc>
<osc>
    <from>/1/push4</from>
    <to>/vimix/3/alpha</to>
</osc>

Example 2: Download and install MIEM Play (Android, iOS). Run it and set the IP Address and Port to target vimix host. Using the default session configuration of the app, the following translations will allow controlling source 0 to 5 in vimix.

<?xml version="1.0" encoding="UTF-8"?>
<osc> <from>/miem/1</from> <to>/vimix/0/alpha</to> </osc>
<osc> <from>/miem/2</from> <to>/vimix/1/alpha</to> </osc>
<osc> <from>/miem/3</from> <to>/vimix/2/alpha</to> </osc>
<osc> <from>/miem/4</from> <to>/vimix/3/alpha</to> </osc>
<osc> <from>/miem/5</from> <to>/vimix/4/alpha</to> </osc>
<osc> <from>/miem/6</from> <to>/vimix/5/alpha</to> </osc>
<osc> <from>/voice</from> <to>/vimix/info/ignore</to> </osc>
<osc> <from>/drums</from> <to>/vimix/info/ignore</to> </osc>
<osc> <from>/lights</from> <to>/vimix/info/ignore</to> </osc>
<osc> <from>/reverb</from> <to>/vimix/info/ignore</to> </osc>
<osc> <from>/synth1</from> <to>/vimix/info/ignore</to> </osc>
<osc> <from>/synth2</from> <to>/vimix/info/ignore</to> </osc>

Please note:

the /vimix/info/ignore message is useful here to avoid logging errors for unsupported messages.
the layout can be compact as far as the xml syntax is valid

Messages sent by vimix

vimix sends an OSC bundle of messages back to the sender upon specific events.
These messages can then be used by the OSC client to update the information shown to its user.

Status bundle of Session

After receiving the message /vimix/session/sync, vimix sends;

the status bundle of Output
the status bundle of all sources

Status bundle of Output

After receiving the message /vimix/output/sync or a message to fade-in or out, vimix sends some information on the output back to the sender.

The message bundle on the output status looks like:

/vimix/output/enable f { 1.0 if enabled, 0.0 otherwise }
/vimix/output/fading f { fading value }

Status bundle of all sources

After receiving /vimix/current/sync or any message that changes the current source, vimix sends the status of its sources back to the sender.

Bundle list of sources

A first bundle is send containing the list of sources and their basic status (current, alpha)

Example; after receiving /vimix/current/next, vimix sends back:

/vimix/current/0 f { 1.0 if current, 0.0 otherwise }
/vimix/0/alpha f { alpha value of source 0 }
/vimix/0/name s { name of source 0 }
/vimix/current/1 f { 1.0 if current, 0.0 otherwise }
/vimix/1/alpha f { alpha value of source 1 }    
/vimix/1/name s { name of source 1 }
... 
etc., for as many source currently available in vimix

Optional argument : if a value is passed to /vimix/current/sync or others, it indicates the size of the list of source to return.

Example; after receiving /vimix/current/0 f 3, vimix sets the source 0 as current and sends back information about exactly 3 sources. If for instance there are currently only 2 sources in vimix, information sent for the (non existing) 3rd source has default values. The bundle of message would then be:

/vimix/current/0 f 1.0
/vimix/0/alpha f { alpha value of source 0 }
/vimix/0/name s { name of source 0 }
/vimix/current/1 f 0.0 
/vimix/1/alpha f { alpha value of source 1 }
/vimix/1/name s { name of source 1 }
/vimix/current/2 f 0.0
/vimix/2/alpha f 0.0
/vimix/2/name f ""

Bundle current source

A second bundle is sent with several attributes giving the status of the source currently active.

The bundle of message looks like this:

/vimix/current/name  s { string name of source }
/vimix/current/lock  f { 1.0 if locked, 0.0 otherwise }
/vimix/current/play  f { 1.0 if playing, 0.0 otherwise }
/vimix/current/depth f { depth value }
/vimix/current/alpha f { alpha value }

Testing OSC

Install package liblo-tools from the Lightweight OSC library to obtain the oscsend and oscdump commands (e.g. run sudo apt install liblo-tools under Ubuntu, install from Homebrew on OSC).

Example: sending osc message to vimix on the same machine to change alpha of first source

oscsend localhost 7000 /vimix/0/alpha f 0

Example: request sync of sources and read data sent by vimix

Launch vimix

In one terminal, run oscdump 7001

In another terminal, run oscsend localhost 7000 /vimix/current/sync f 3

The oscdump should print out the following:

~$ oscdump 7001
e575a8c5.ea38971f /vimix/current/0 f 0.000000
e575a8c5.ea38971f /vimix/0/alpha f 0.000000
e575a8c5.ea38971f /vimix/current/1 f 0.000000
e575a8c5.ea38971f /vimix/1/alpha f 0.000000
e575a8c5.ea38971f /vimix/current/2 f 0.000000
e575a8c5.ea38971f /vimix/2/alpha f 0.000000
e575a8c5.ea3cd9a4 /vimix/current/name s ""
e575a8c5.ea3cd9a4 /vimix/current/lock f 0.000000
e575a8c5.ea3cd9a4 /vimix/current/play f 0.000000
e575a8c5.ea3cd9a4 /vimix/current/depth f 0.000000
e575a8c5.ea3cd9a4 /vimix/current/alpha f 0.000000

Installation guide

Help and guides

User Manual

Advanced features

Filters and Shadertoy

SRT network streaming

Command line

Video tutorials

Troubleshooting

Open Sound Control

OSC API

OSC Mapping

Touch OSC

About vimix

Manifesto

Future plans

Help Needed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Open Sound Control API

Overview

Target a source

Several ways to identify the source target

Attributes to control a source

Attributes to control different types of sources

Target multiple sources

Target `all` or a `selection` of sources

Target a `batch#` of sources

The `current` target

Attributes to change active source

Change attributes of the active source

The `output` target

The `session` target

The `info` target

Automatic translation

Messages sent by vimix

Status bundle of Session

Status bundle of Output

Status bundle of all sources

Bundle list of sources

Bundle current source

Testing OSC

Clone this wiki locally

Open Sound Control API

Overview

Target a source

Several ways to identify the source target

Attributes to control a source

Attributes to control different types of sources

Target multiple sources

Target all or a selection of sources

Target a batch# of sources

The current target

Attributes to change active source

Change attributes of the active source

The output target

The session target

The info target

Automatic translation

Messages sent by vimix

Status bundle of Session

Status bundle of Output

Status bundle of all sources

Bundle list of sources

Bundle current source

Testing OSC

Clone this wiki locally

Target `all` or a `selection` of sources

Target a `batch#` of sources

The `current` target

The `output` target

The `session` target

The `info` target