78

Open Sound Control API

BHBN edited this page 2025-11-18 13:15:52 +01:00

Table of Contents

• 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

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 f. (or in some specific case strings s)

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 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).
To target the source currently active, use the target current (see below).
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

Dynamic targeting and naming

To use a temporary alias to target a source, define the alias as follows

Examples;
/vimix/#0/alias s vivi ; defines the alias vivi to target the source #0,
Afterwards, the target vivi will be accepted as alias:
/vimix/vivi/alpha f 0 will change alpha of source #0.

The alias is valid until vimix is closed, the session loaded notwithstanding

To rename a source to be able to use a new name as target,

Examples;
/vimix/#0/rename s vivi ; renames the source #0 as vivi
Afterwards, the target vivi will be accepted as a normal source name.
/vimix/vivi/alpha f 0 will change alpha of source #0 (now named vivi)

The source will be saved with this new name when saving the Session

Attributes to control a source

When the target is able to identify a source by its name, by its index, as an alias, or as the current active source, the following attributes are used to modify it.
NB: only latest version of vimix supports all attributes.

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. It is simply the logical opposite of play, provided for convenience.
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 [-1 +1] is used to set the source opacity in the mixing circle. For values between 0.0 (transparent) and 1.0 (visible), the source is inside the mixing circle. For negative values, the source is outside the mixing circle (transparent) and can be deactivated if outside of mixing area.
Example; send /vimix/current/alpha f 0.3 to set source opacity to 30% (70% transparency).
Example; send /vimix/current/alpha f -1.0 to place the source outside of mixing area where it will be deactivated.
Optional argument : a second value defines the duration, in millisecond, of the animation to reach the given value.
Example; /vimix/current/alpha ff 1.0 1000 triggers a 1000 ms (1 second) animation to reach maximum alpha.

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

Mandatory argument : the value [0 2] is used to set the source transparency. For values between 0.0 (visible) and 1.0 (transparent), the source is inside the mixing circle. For values above 1.0, the source is outside the mixing circle (transparent) and can be deactivated if outside of mixing area. It is the logical opposite of alpha, provided for convenience.
Example; send /vimix/current/transparency f 0.3 to set source transparency to 30% (70% alpha).
Example; send /vimix/current/transparency f 2.0 to place the source outside of mixing area where it will be deactivated.
Optional argument : a second value defines the duration, in millisecond, of the animation to reach the given value.
Example; /vimix/current/transparency ff 1.0 500.0 triggers a 500 ms (0.5 second) animation to reach maximum transparency.

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) Optional argument : a second value defines the duration, in millisecond, of a looming animation.

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 towards 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.
Optional argument : a third value defines the duration, in millisecond, of the animation to reach the given position.
Example; /vimix/current/position fff 0 0 1000 triggers a 1000 ms (1 second) animation to return to center.

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.
Optional argument : a second value defines the duration, in millisecond, of the animation during which the source is grabbed.

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 reset the source width and height scaling (i.e. original size)
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.
Optional argument : a third value defines the duration, in millisecond, of the animation to reach the given size.
Example; /vimix/current/size fff 1 1 1000 triggers a 1000 ms (1 second) animation to restore original source size.

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.
Optional argument : a second value defines the duration, in millisecond, of the animation during which the source is resized.

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).
Optional argument : a second value defines the duration, in millisecond, of the animation to reach the given angle.
Example; /vimix/current/angle ff 0 1000 triggers a 1000 ms (1 second) animation to restore original source orientation.

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.
Optional argument : a second value defines the duration, in milliseconds, of the animation.
Example; /vimix/current/turn ff 0.2 5000 triggers a 5000 ms (5 second) rotation at 0.2 radians/second.

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.

corner : Change the corners coordinates (Geometry view)

Mandatory arguments : 8 floats f are used to indicate the (x,y) coordinates of the 4 corners of the source in the Geometry View in the order A (lower left), B (upper left), C (lower right) and D (upper right):
B (-1, +1) O---------------------------O D (+1, +1)
| | |
| + (0,0) |
| | |
A (-1, -1) O---------------------------O C (+1, -1)
Corners can only remain into their original quadrant.
Example; send /vimix/current/corner ffffffff -1 -1 -1 1 1 -1 1 1 to reset the four corners to their original coordinates.
Optional argument : a second value defines the duration, in milliseconds, of the animation.
Example; send /vimix/current/corner fffffffff -0.5 -1 -0.5 1 1 -0.5 1 0.5 2000 to trigger a 2 second animation.

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).
Optional argument : a second value defines the duration, in millisecond, of the animation to reach the given value.
Example; /vimix/current/depth ff 2.0 500.0 triggers a 500 ms (0.5 second) animation to reach depth 2.0.

Nota Bene: depth < 2.0 is in background, depth > 10.0 is in foreground, else is in workspace

blending : Set the blending mode of the source

Mandatory argument : a string s sets the blending to use, by name (case insensitive).
The valid strings are: Normal, Screen, Subtract, Multiply, Hard light, Soft light, Soft subtract, Lighten only.
Example; /vimix/current/blending s 'hard light'

Alternative argument : a value f (instead of the string) representing the index of the filter.
The valid values are: 0: Normal, 1: Screen, 2: Subtract, 3: Multiply, 4: Hard light, 5: Soft light, 6: Soft subtract, 7: Lighten only.
Example; /vimix/current/blending f 4 sets blending to Hard light.
NB: Floating point values are rounded to nearest integer.

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 millisecond, 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 millisecond, 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 millisecond, 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 millisecond, 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 millisecond, 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 millisecond, 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 millisecond, 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 millisecond, of the animation to reach the given value.
Example; /vimix/current/speed ff 5.0 1000.0 triggers a 1000 ms (1 second) animation to reach play speed.

ffwd : Fast-forward playing the source : Media source only

Mandatory argument : the value is used to set the duration of the fast-forward jump, in millisecond.
Example; send /vimix/current/ffwd f 500 to fast-forward jump by 500 millisecond.
Optional argument : a second value defines the duration, in millisecond, during which the fast forward is applied.
Example; /vimix/current/ffwd ff 50 1000 triggers a fast-forward play with 50ms jumps during 1000 ms (1 second).

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 pay duration: float [0..1]
  Example; send /vimix/current/seek f 0.5 to seek to frame at t=50% of the segments duration of the current media source (i.e. from 0% to 100% of the actual playing duration, discarding the cut segments).
• Time as Hours minutes seconds milliseconds: 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 millisecond.

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

Optional argument : the value sets the flag id number to jump to in a video. No value means 'go to next'. If the source has no flag, nothing happens.
Example; send /vimix/current/flag to seek to next flag.
Example; send /vimix/current/flag f 2 to seek to 3rd flag (flags are numbered ; <0>, <1>, <2>).

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

filter : Set Filter : Clone source only

Mandatory argument : a string s sets the filter to use, by name (lower case). If the source is not a Clone, nothing happens.
The valid filters are: none, delay, resample, blur, sharpen, smooth, edge, alpha, custom.
Example; send /vimix/current/filter s blur to set the filter of the current source, assuming it is a clone source.

Optional arguments :

1. a second string s sets the method or type of algorithm of the filter (lower case), as listed in the user interface.
2. a value f sets the main value associated to the filter, as listed in the user interface.
3. a second value f defines the duration, in millisecond, of the animation to reach the previous value.

Example; send /vimix/current/filter ss blur gaussian sets the filter to blur with method gaussian with default value.
Or send /vimix/current/filter ssff blur gaussian 1.0 1000 to set the filter to blur with method gaussian and to trigger a 1000 ms (1 second) animation to reach value of 1.0 (the blur radius in this case).

Using the Nil argument :

a type N can replace an argument type in the argument list, allowing to skip this argument.
Example; sending /vimix/current/filter NNf 0.7 will set the filter value to 0.7 without changing the filter type and method.
Or send /vimix/current/filter Ns gaussian to only set the method to "gaussian", assuming it will be meaningful for the current filter (i.e. works only for a "blur" filter).

Here are valid filter arguments;

• none : no argument, i.e. only /vimix/current/filter none is meaningful. This removes any filter to the clone source.
• delay : only the f value argument is used, i.e. /vimix/current/filter sNf delay 0.1 sets delay of 0.1 second.
• resample : only the s method argument is used. It can be double, half or quarter, e.g. /vimix/current/filter ss resample half sets resampling method to half resolution.
• blur : method can be gaussian, scattered, opening, closing and fast. The value argument corresponds to the Radius parameter of the blur (except fast which ignores it).
• sharpen : method can be unsharp, convolution, edge, white and black. The value argument corresponds to the Amount or Radius parameter of the sharpen method, depending on the case.
• smooth : method can be bilateral, kuwahara, opening, closing, erosion, dilation, denoise, noise and grain. The value argument corresponds to the Factor, Radius or Amount parameter of the smoothing or noise effect, depending on the case.
• edge : method can be sobel, freichen, thresholding and contour. The value argument corresponds to the Factor or Threshold parameter of the edge detection method, depending on the case.
• alpha : method can be chromakey, lumakey and fill. The value argument corresponds to the Tolerance parameter of the keying method, ignored for alpha filling filter.
• custom : second s argument is considered as a filename containing a GLSL shader code, e.g. /vimix/#1/filter ss custom '/home/username/shadertoycode.glsl'

uniform : Set uniform variable of Filter : Clone source only

Mandatory arguments : a string s defines the variable to change (case sensitive) and a value f sets the value. If the source is not a clone, nothing happens.
The variable names are defined in the GLSL code of the filter; e.g., user declared with uniform float pix = 0; in the Shader editor.

Example; send /vimix/#0/uniform sf pix 0.9 to set the value of the uniform variable 'pix' to 0.9, assuming source #0 is a clone source.

---

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.

A source name : Set source by name as current.

Example; send /vimix/current/abc to set source named 'abc' to be current.

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

srt-start : Launch SRT video broadcasting

Optional argument : the value indicates the PORT to use for the SRT broadcast.
Example; send /vimix/output/srt-start f 7070 to launch SRT broadcast on port 7070.

srt-stop : Ends SRT video broadcasting

Example; send /vimix/output/srt-stop to stop SRT broadcast.

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

0. Launch vimix
1. In one terminal, run oscdump 7001
2. 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