Mobius may be controlled and monitored using the Open Sound Control (OSC) protocol. This is an advanced topic intended for users that are already very familar with OSC, and have a hardware device capable of sending and receiving OSC messages. Mobius OSC support was tested primarily using the popular TouchOSC application for Apple and Android mobile devices but any device that supports OSC should be usable. To get the most out of OSC it is important that the device be programmable so that it can send addresses and arguments that are compatible with Mobius. If a device sends a fixed message, such as the default layouts in TouchOSC, it is still possible to use it with Mobius but it will require more effort to configure.
OSC support is a relatively new feature that not many people use. If you have problems or suggestions, please do not hesitate to post on the Mobius forums.
To communicate with an OSC device you must set four parameters in the Global Parameters dialog under the Advanced tab.
If you don't understand what any of that means, then we're sorry but you're not ready for OSC. Post a message on the forums if you need assistance, but unfortunately OSC requires some knowledge of TCP/IP networking, and this document is not a tutorial.
The OSC Enable defaults to false so we won't open network sockets that aren't needed. This must be checked if you want to use OSC.
The OSC Input Port defaults to 7000. There is probably not a need to change this, but in rare situations there may be a conflict with another application that wants to use this port. Diagnosing port conflicts is beyond the scope of this document. Try it and if it doesn't work, post to the forum.
The OSC Output Host must be the IP address of the device that will be sending and receiving OSC messages. This is not required, but it is desireable if you want to see controls in the OSC device match the current Mobius paramters. For example, if you bind an OSC address to the Output Level parameter, we can send the device a message every time the output level changes due to a MIDI pedal, moving the UI knob, a script, or any other means of changing the parameter. An IP address has the form of four numbers seperated by periods, for home networks, the IP addres normally starts with "192.168.1" and ends with a number between 100 and 200.
The OSC Output Port defaults to 9000 which is the default port number used by TouchOSC. This must be changed if your device listens on a different port and you want the device to receive notifications when Mobius parameters change.
The OSC Trace - checkbox enables sending trace messages whenever OSC messages are received or sent. On Mac, the messages are sent to the system console. On Windows, they are send to the debug output stream and you will need to use an application such as DBWIN32 to view them. See the section Trace in the Exploring Mobius manual for more information on how to enable and view trace messages. The Trace Debug Level parameter under the Advanced tab must also be set to 2 to see OSC trace messages.
If you are setting up a new device it is recommended that you enable trace to help diagnose problems. Once the device and Mobius are working properly, disable trace to reduce clutter in the logs.
Mobius OSC messages must contain an address and usually one floating point argument without a type tag. Mobius addresses always begin with the string /mobius and follow this pattern:
/mobius/trigger/scope/target/value
The /trigger container is optional and is usually not included. It can be used to convey information about how the physical device is behaving, if this is different than the default Mobius expectations. This will be described in detail later.
The /scope container is optional and may contain one of the following values.
If a scope is not specified in the address it defaults to global. Here are some example addresses containing scopes, the first two are the same because the default scope is global:
/mobius/global/...
/mobius/...
/mobius/1/...
/mobius/A/...
The /target container is not optional, it must be the name of a Mobius function or parameter, for example "record" or "subCycles". Target names must use script names which may be different than the names displayed in the user interface. Consult the reference manual to find the script names that correspond to the display names. Often the script name is the same as the display name but with spaces removed, so what is displayed as "Auto Record" would be "AutoRecord" in the address. Case does not matter.
To change setups, presets, or binding overlays the the target names are "setup", "preset", or "bindings". These are the same as the parameter names used to select configuration objects with plugin parameter bindings. Here are some example addresses with targets:
/mobius/global/record
/mobious/global/preset
/mobius/1/quantize
/mobius/A/output
The /value container is where things start to get complicated. In order to support a wide variety of devices with different levels of programability, values can be specified in three ways.
We will discuss ways to specify target values in more detail below, here are some examples:
-- these use arguments
/mobius/global/output 0.5
/mobius/1/quantize 0.333
-- these are absolute
/mobius/global/preset/Default+Preset
/mobius/1/quantize/subcycle
/mobius/A/pan/center
/mobius/global/output/max
-- these are relative
/mobius/global/output/up 1.0
/mobius/8/feedback/down 5.0
/mobius/global/output/up/1
/mobius/8/feedback/down/5
Before determining the best way to specify Mobius addresses and arguments, we need to consider how the hardware that is sending OSC messages behaves. A device typically contains a mixture of physical controls that behave in one of these ways:
You can set Mobius parameters using any of these control types. Continuous controls are useful if you want to to sweep through the possible values of a parameter. Often the track control parameters such as "input", "output" and "feedback" are associated with physical controls that resemble sliders. Enumerated parameters such as "quantize" or "recordThreshold" might be assigned to rotary knobs.
You can also use buttons to set parameters. In this case the button will either force the parameter to a particular value (absolute), or raise and lower the value of the parameter by some amount (relative).
To execute Mobius functions you almost always use physical controls that have button behvaior. It is possible to execute Mobius functions with sliders but this can be difficult to use. When executing functions, it is important to understand the differemce between momentary, single and toggle buttons.
Many Mobius functions are "sustainable" which means they can have different behavior when a button is pressed and released, or when a button is held down for a period of time. If you wish to use any of the sustainable or long-pressable functions, you must use physical buttons that behave as momentary buttons, sending a message both when it is pressed and released. All TouchOSC buttons behave this way.
It is posssible to use single message buttons to execute functions but Mobius has to be told not to expect the extra release message. Otherwise sustainable functions will enter their long-press state because they never see the up transition of the button. This is done with a special keyword in the address and is described below.
Toggle buttons are not very useful with Mobius. They are typically used for effects parameters such as chorusing or reverb, where you want to press once to enable the effect, then press again to disable the effect. Such buttons typically send 1.0 when they are pressed once, 0.0 when pressed again, then repeat the 1.0 and 0.0 pattern forever. This behavior might be useful for some parameters, for example toggling quantize mode between "loop" and "off", but this is not recommended for executing functions.
XY controls can be used to set Mobius parameters but we have not seen many interesting examples. If you find one let us know!
The OSC devices with which we are familar send one and rarely two arguments that are floating point numbers. The argument usually has a default range of 0.0 to 1.0.
When a slider is down, the value 0.0 is sent and as it is raised the value increases smoothly until it reaches 1.0 at the top end of the slider range. Momentary buttons usually send 1.0 when the button is pressed and 0.0 when the button is released. This is the default behavior of TouchOSC controls.
To minimize the amount of programming for TouchOSC, Mobius will expect most arguments to be in the range of 0.0 to 1.0, though in some cases this can be adjusted.
To set a parmaeter with OSC arguments, use an address path without a value container, for example.
/mobius/global/output
One argument is expected to be sent with the message whose value ranges from 0.0 to 1.0. Mobius will take the floating point range and scale it into an integer or "ordinal" range for the target, in this example the output parameter. The output parameter has an ordinal range from 0 to 127, so an OSC argument of 0.0 becomes output level 0, 1.0 becomes 127 and 0.5 is approximately 64. This is almost always done when the physical device is a slider or rotary knob. This style of argument is convenient if you want to smoothly sweep the knob over all possible values of the parameter.
It is also possible to set values with a button, but this is not often done with scaled OSC arguments. To set the value of a parameter you must know the floating point range of each of the possible parmeter values. For example the quantize parameter has four possible values: off, subcycle, cycle, and loop. This divides the floating range by four, so values from 0.0 to 0.2499999 select off, values from 0.25 to 0.4999999 select subcycle and so on. It is inconveinent for the device programmer to calculate these values so instead parameters set with buttons usually use address values or ordinal arguments.
Another problem setting parameters with buttons, is that many devices use momentary buttons and send a message when it is pressed and again when it is released. When setting Mobius parameters you usually want to ignore this second message. For example, say we're configuring a TouchOSC button to set the quantize parameter to loop. You set set the high value to 1.0, but what about the low value? If you leave it at 0.0 the parameter will change twice, once when you press the button and again when you release since 0.0 is the value for "off". To avoid this you must set the low value of the button to -1.0 or any other negative number. Mobius will ignore the negative value and leave the parameter set to 1.0.
When setting parameters with buttons, the most convenient approach is to include the value you want to set in the address rather than use the OSC argument. For example:
/mobius/global/quantize/loop
The quantize parameter value will be set to loop whenever this message is received with a non-zero argument. Since the default behavior of TouchOSC is to send 1.0 on button press and 0.0 on release, the message is processed when 1.0 is sent, but the message is ignored when 0.0 is sent so we won't try to change the parameter twice every time a button is pressed.
This is convenient for two reasons, first you don't have to worry so much about the value of the argument since most devices default to 0.0 to 1.0. Second, you don't have to calculate the numeric form of each parameter value, instead you can reference them by name just as you would in a script.
When you use this style of address you normally do not send it from a slider or knob. As you sweep over the slider range, we will set the parameter to the same value many times which adds overhead and accomplishes nothing.
To set the value container, consult the reference manual for each parameter. If the parmaeter value is an enumeration the set of possible values are listed. If the value is an integer the minimum and maxmum values will be given. For example, the output level parameter range is from 0 to 127, so these are some valid example addresses.
/mobius/global/output/0
/mobius/global/output/42
/mobius/global/output/127
To change presets, setups or binding overlays, you reference the objects using the name they have in the user interface. These names often contain spaces which are not allowed in OSC addreses. You must substitute the plus '+' character for spaces in configuration object names:
/mobius/global/setup/Default+Setup
/mobius/1/preset/Glitch+Core
/mobius/bindings/Nano+Control
There are also a few special symbols that may be used instead of parameter values.
These symbolic values are the most useful for the track level parameters.
/mobius/global/output/max
/mobius/global/feedback/min
/mobius/global/pan/center
If you have an OSC device that can be programmed to send any argument value, you can choose to set the Mobius parameter to the value of the argument using ordinal nubmers. Ordinals are integers that usually have a minimum value of zero and a maximum value less than 100. A few have minimum values that are negative. To set parameters with ordinals add the keyword arg to the end of the address.
/mobius/global/output/arg
This differs from using scaled arguments in that the argument is not expected to be a floating value from 0.0 to 1.0. Instead it is expected to be an integer that fits within the range allowed by the target parameter. In this example, the target is output which expects values from 0 to 127.
Ordinal arguments accomplish the same thing as using address arguments and are a bit more obscure since they require ordinal parameter numbers, whereas address arguments may use symbolic values.
In the previous example, if the device was programmed to send an argument value of 100, the same effect could be achieved using an address argument.
/mobius/global/output/100
A variation on setting parameters with addresses is to use the address to specify a relative value. There are two special sumbols you can use in the value container to set relative values.
For example:
/mobius/global/output/up
/mobius/1/feedback/down
The amount to raise or lower the value is specified by the OSC argument. So assuming the TouchOSC default of 1.0 for button presses, the values will rise and lower by 1. If you create a custom TouchOSC layout you can adjust the maximum value to achieve higher amounts of adjustment. For example a button with a maximum value of 5.0 will raise or lower the parameter value by 5 units each press.
If you do not wish to program a custom template, you may also specify the amount of change in the address. For example:
/mobius/global/output/up/5
/mobius/1/feedback/down/20
This style of address can be used with any parameter, the value will be automatically constrained so the parameter can't go beyond it's minimum and maximum values. The value of the OSC argument doesn't matter as long as it is possitive. Positive argument values will cause the parmameter to be changed, zero or negative values are ignored, which is necessary for buttons that send 0.0 when they are released.
Setting parameters values in the address is convenient for devices that have only buttons or a limited number of sliders.
Functions are almost always executed using a physical control that behaves as a button. It is possible to execute functions with sliders but it takes more effort. Wherever possible, the button should be programmed to send an argument of 1.0 when the button is pressed and 0.0 when it is released. It doesn't really matter what the press value is but the release value must be 0.0. If the release value is not 0.0, mobius will execute the function again when the button is released which is not normally desired. Here are some examples of function addresses:
/mobius/global/record
/mobius/1/speedDown
/mobius/A/mute
If the button does not send a value on release, Mobius needs to be told this so it won't think that the button is being held down. This is important for all "sustainable" functions that may have different actions on press and release, or change behavior after a long press. If the button will not send a release value the special symbol /noup must be added to the address after the /mobius container.
/mobius/noup/global/record
When the /noup trigger qualifier is used, the value of the OSC argument is ignored. Any time a message is received with this address the function is executed, and we will not wait for a release message.
A few functions may take a single integer argument when used in scripts. Some examples are divide which instantly divides the loop by a number, and speedUp which raises the speed of the loop by a number of semitones. For those functions that recognize arguments, you may specify the argument in the address.
/mobius/global/divide/5
/mobius/1/speedDown/12
There is usually no need to combine a numeric function argument with the /noup option. Functions that take argumets are assumed to not be sustainble. There may however be scripts that are sustainable and take an argument. So it is best if you consistently add /noup if you know the device will not behave like a momentary button.
If your device does not support programmable addresses, or if you wish to use the default TouchOSC templates without creating custom templates, you can still use the device with Mobius, but it requires editing an XML file. The file is named osc.xml. On Windows it is found in the installation directory, usually c:\Program Files\Mobius 2. On Mac this is found in /Library/Application Support/Mobius 2.
You need to be comfortable with XML syntax and selecting text encodings to edit this file. See this section in the Getting Started manual for more information on the proper way to edit XML files.
The default osc.xml file contains a single <OscConfig> element which in turn contains several <OscBindingSet> elements. An <OscBindingSet> contains several <Binding> elements. Each <Binding> defines the translation between the incomming OSC address (triggerPath) and the corresponding Mobius address (targetPath).
<OscConfig>
<OscBindingSet name="Touch OSC Simple" active='true'>
<Binding triggerType='continuous' triggerPath='/1/fader1' targetPath='/mobius/1/output'/>
<Binding triggerType='continuous' triggerPath='/1/fader2' targetPath='/mobius/2/output'/>
<Binding triggerType='continuous' triggerPath='/1/fader3' targetPath='/mobius/3/output'/>
<Binding triggerType='continuous' triggerPath='/1/fader4' targetPath='/mobius/4/output'/>
<Binding triggerType='continuous' triggerPath='/1/fader5' targetPath='/mobius/global/pan'/>
<Binding triggerType='toggle' triggerPath='/1/toggle1' targetPath='/mobius/noup/record/>
<Binding triggerType='toggle' triggerPath='/1/toggle2' targetPath='/mobius/noup/overdub/>
<Binding triggerType='toggle' triggerPath='/1/toggle3' targetPath='/mobius/noup/mute/>
<Binding triggerType='toggle' triggerPath='/1/toggle4' targetPath='/mobius/noup/reset/>
...
</OscBindingSet>
<OscBindingSet name="Touch OSC Beat Machine">
...
</OscBindingSet>
<OscBindingSet name="Touch OSC Keys">
...
</OscBindingSet>
...
</OscConfig>
Only one OscBindingSet may be active at a time, this is indiciated by setting the XML attribute active to true as seen in the above example. If more than one <OscBindingSet> set is marked active, the first one is chosen. If no binding sets are active the first one in the <OscConfig> is chosen.
The active binding set is consulted whenever an OSC message is received. We search for a <Binding> whose triggerPath matches the address from the OSC message. In the examples above, the triggerPath values are the messages sent by TouchOsc in one of it's default configurations. If a matching <Binding> is found, the value of the targetPath is used to process the message instead of the one that was received from the device. targetPath values conform to the Mobius address format described earlier in this document.
The triggerType value tells Mobius about the behavior of the physical OSC trigger and the values the OSC message argument will have. This is optional because Mobius can usually figure out the appropiate trigger type based on the targetPath and trigger options such as /noup. The possible values are.
For TouchOSC, incoming paths that contain the word "fader" or "rotary" are continuous, paths with the word "toggle" are toggle, and paths with the word "push" are momentary. Mobius currently cannot make use of xy messages.
In addition to receiving OSC messages, Mobius may also send OSC messages so that the device can display the current Mobius state. By default, any OSC address whose target is a parameter and whose argument is a continuous value from 0.0 to 1.0 will be automatically exported when the parmeter is changed. So if you use an address like this:
/mobius/output
A message will be sent back to the OSC device using the same address whenever the output level changes. For this to work you must configure the OSC Output Host and OSC Output Port in the Mobius Global Parameters window.
Note that addresses that target functions, or that include specific values will not be exported. For example, these address cannot be exported.
/mobius/record
/mobius/output/127
/mobius/output/up
/mobius/output/arg
In addition the automatic export of continuous parameters, there are a few special values that may be exported but cannot be set. These are called Watch Points.
Watch points are still under development, if you have ideas about Mobius states that should be exporable as watch points please let us know.
When a watch point is continuous such as loopLocation the value will be constantly changing. The output value will be scaled to the range 0.0 and 1.0. For TouchOSC this can be used with fader or rotary controls.
When a watch point flashes it indicates that the state is instant and does not have a time duration. For example when the loop reaches the start point. For instant watch points, an OSC message will be sent with value 1.0 when the state is reached, and a short time later a message with value 0.0 is sent. This can be used to turn lights on the OSC device on and off. For TouchOSC this should be used with toggle buttons.
When a watch point is "modal" such as modeRecord it turns on and off for an undefined time. A 1.0 will be sent when the mode is entered and 0.0 when it is exited.
To export watch points, you must edit the osc.xml file and add <OscWatcher> elements. These elements appear as immediate childrenof the <OscConfig> element. For example:
<OscConfig>
<OscWatcher name='loopLocation' path='/1/fader1'/>
<OscWatcher name='loopStart' track='1' path='/1/toggle1'/>
<OscBindingSet>
...
<OscBindingSet>
...
<OscConfig>
In this example, the loop location of the currently selected track will be sent to the OSC device using the address /1/fader1. In the second <OscWathcer>, a specific track is specified so the OSC device will be send a message to /1/toggle1 only when the loop in track 1 reaches its start point.
There may be a considerable delay between the time that a Mobius watch point is reached and the OSC device responds to the message. So while watch point port export can give you a general idea of what is happening, it is not always suitable for making time critical decisions, such as synchronization or as a metronome. Mobius sends messages as fast as it can, but wireless networks and mobile devices can both add delays that are not under the control of Mobius.
If you decide to use address mapping or define watch points in the OSC configuration file (osc.xml) you will need to reload it every time you make changes. The file is loaded once when Mobius starts. If you want to reload the file without restarting Mobius, open the File menu and select the Reload OSC item.
The most inexpensive way to use OSC with Mobius is through the TouchOSC application for Apple and Android mobile devices. It is available here . TouchOSC provides a few default layouts such as Beat Machine and Keys but it is also fully programmable with the TouchOSC Editor.
The default layouts the send messages such as /1/fader1/ can be used but they require editing the Address Translation file. For most people it is easier to use the TouchOSC Editor to send address that Mobius understands without mapping.
For Mobius, the most useful layout object types are Push Button, Fader V, Fader H, Rotary V, and Rotary H. Use Push Button to execute functions or set specific parameter values, and use Fader and Rotary to sweep through paramter values.
Toggle Button can be used but it doesn't work very well since Mobius does not have many concepts that behave like toggles. You might use this to swtich between two parameter values, but it is not suitable for executing functions.
XY Pad and the various Multi types are not usable with Mobius.
The read-only status types such as LED and Battery V can be used as the targets for OscWatchers.