Jamoma uses the OSC (Open Sound Control) protocol. This is a protocol for communication among computers, sound synthesizers, and other multimedia devices that is optimized for modern networking technology.
OpenSoundControl basically means that all parameters that we might want to access or monitor, have been given an address in the form of a Max message or symbol. The addresses are organized in a tree-like structure, with the slash (/) sign prepending each branch. The result is straight-forward and resembles the last part of common Unix or URL paths. Here are some examples of possible OSC addresses:
We will continue to work with a simple patch containing modules for audio input and output, and one module doing effect processing. It will be useful to use an effect module where it's very simple to hear subtle changes to the parameters, so this time we will be using the jmod.tremolo~ module.
Make the patch much the same way as in the previous tutorial, and while you are at it, connect a message box to the leftmost output of the tremolo module as illustrated below.
Now we have to set up each of the modules so that we have some sound to play around with:
You will notice that whenever you change a parameter in the tremolo module, this gets reported out the left outlet of the module and shows up in the message box. In the screen shot above you can see that the audio gain level has been set to 100.
The messages sent out from the module are all OSC messages, containing the OSC address and the value of the parameter. Here are some examples of output from the tremolo module:
/audio/gain 100./audio/mix 100./audio/mute 0/lfo/frequency 5./lfo/depth 50.
One of the benefits of OSC is that the messages above are easy to read and we quickly get an idea of what parameter each of them are referring to.
We can pass messages to the module the same way. Let us try adjusting the LFO frequency and depth by sending messages to the module, by doing a few additions to the patch:
Now you are able to control the LFO frequency and depth not only in the GUI of the module, but also by passing OSC messages to the module.
Passing OSC messages this way cause the module to update to the new parameter value instantly. In real use we often want changes to happen more gradually. For instance we might want the LFO depth to change gradually from 0 % to 100 % over 5 seconds. This is something that Jamoma excels at.
Let's make two more message boxes and connect to the leftmost inlet of the tremolo module. The content of the two message boxes will be /lfo/depth 0 ramp 5000 and /lfo/depth 100 ramp 5000 respectively:
Now try clicking first one and then the other message box. You will see that the LFO depth gradually moves to 0 % and 100 % respectively over 5 seconds (5000 ms), starting of from the value it had just before the ramp was triggered. The syntax to achieve this is really simple: Just add ramp and the amount of time you want the ramp to last for, expressed in milliseconds, to the end of the OSC message.
If you try starting one ramp before the other one is done, the new ramp takes precedence, starting from whatever value the parameter had just before.
If you change the parameter while the ramp is still running, either by interacting with the GUI of the module, or by sending a new OSC message to the module, you will see that this brings the previous ramp to a hault.
You can also try adding more message boxes to the patch, so that you can interact with several parameters simultaneously. You will find that the module is able to cope with several parameters ramping at the same time, each of which can be started independently and run for different amounts of time.
In this example, the ramp is linear. In a later tutorial we will look further into ramping in Jamoma, and see how we can use different ramping curves and more.
Fortunately we don't have to remember the OSC address of each and every parameter of all the Jamoma modules we use in order to address them. Jamoma offers several ways of helping us discovering the OSC namespace of each module.
If you instead click further to the left, you will bring up another pop-up menu. In the previous tutorial we used this to peek inside the module, by choosing the "View Internal Components" menu item. Now it is time to try a few other options that aid in documenting the module.
If you select "Open reference Page" a web page will show up in your default web browser. This will provide you with a detailed list of all parameters, messages and returns, a description explaining what the parameter does, and additional information on how it behaves, e.g:
Some of this will make more sense as we move further.
Finally, if you select "Open Help Patch" from the pop-up menu, a help patch opens up, where you can interactively examine the module. The help file also contains links to the HTML reference page, and offers simple ways of viewing what issues or bugs (if any) are currently registered for the module.
The patch used for this tutorial can be downloaded here: