Sending messages to modules


/groups/jamoma/search/index.rss?tag=hotlist/groups/jamoma/search/?tag=hotWhat’s HotHotListHot!?tag=hot10/groups/jamoma/sidebar/HotListlossiusTrond Lossius2013-01-08 11:38:51+00:002013-01-08 11:38:51updated7lossiusTrond Lossius2013-01-08 11:38:29+00:002013-01-08 11:38:29updated6Added tag - rsslossiusTrond Lossius2013-01-08 11:38:22+00:002013-01-08 11:38:22addTag5Added tag - websitelossiusTrond Lossius2013-01-08 11:38:15+00:002013-01-08 11:38:15addTag4Added tag - bloglossiusTrond Lossius2013-01-08 11:38:11+00:002013-01-08 11:38:11addTag3Added tag - hotlossiusTrond Lossius2013-01-08 11:38:08+00:002013-01-08 11:38:08addTag2First createdlossiusTrond Lossius2013-01-08 11:31:09+00:002013-01-08 11:31:09created1weblog2013-01-08T11:38:51+00:00groups/jamoma/weblog/7fcfbFalseBlog moves to new location/groups/jamoma/weblog/7fcfb/Blog_moves_to_new_location.htmlTrond Lossius7 updatesBlog moves to new location On Janary 7 2013 we launced our new web site for Jamoma, consolidating resources that previously were spread at several different locations (such as ...Falselossius2013-01-08T11:38:51+00:00lossiusTrond Lossius2011-12-30 00:09:26+00:002011-12-30 00:09:26updated9lossiusTrond Lossius2011-12-27 18:09:15+00:002011-12-27 18:09:15updated8Added tag - hotlossiusTrond Lossius2011-12-27 18:09:08+00:002011-12-27 18:09:08addTag7Removed tag - cueslossiusTrond Lossius2011-12-27 18:09:00+00:002011-12-27 18:09:00removeTag6Added tag - cue scriptslossiusTrond Lossius2011-12-27 18:08:56+00:002011-12-27 18:08:56addTag5Added tag - textmatelossiusTrond Lossius2011-12-27 18:08:49+00:002011-12-27 18:08:49addTag4Added tag - cueslossiusTrond Lossius2011-12-27 18:08:46+00:002011-12-27 18:08:46addTag3Added tag - osclossiusTrond Lossius2011-12-27 18:08:40+00:002011-12-27 18:08:40addTag2First createdlossiusTrond Lossius2011-12-27 18:02:14+00:002011-12-27 18:02:14created1weblog2011-12-30T00:09:26+00:00groups/jamoma/weblog/21170FalseTextMate bundle for cue scripts/groups/jamoma/weblog/21170/TextMate_bundle_for_cue_scripts.htmlTrond Lossius9 updatesTextMate bundle for cue scripts [TextMate screenshot] Everyone that has been doing a bit of coding, know that syntax highlighting is extremely useful. In order to simplify manua...Falselossius2011-12-30T00:09:26+00:00Added tag - 0.5.4lossiusTrond Lossius2011-10-04 09:13:36+00:002011-10-04 09:13:36addTag6Added tag - lionlossiusTrond Lossius2011-10-04 09:13:33+00:002011-10-04 09:13:33addTag5lossiusTrond Lossius2011-10-04 09:13:22+00:002011-10-04 09:13:22updated4Added tag - hotlossiusTrond Lossius2011-10-04 09:13:19+00:002011-10-04 09:13:19addTag3lossiusTrond Lossius2011-10-04 09:13:15+00:002011-10-04 09:13:15updated2First createdlossiusTrond Lossius2011-10-04 09:11:05+00:002011-10-04 09:11:05created1weblog2011-10-04T09:13:22+00:00groups/jamoma/weblog/24460FalseJamoma 0.5.4.rc1/groups/jamoma/weblog/24460/Jamoma_054rc1.htmlTrond Lossius6 updatesJamoma 0.5.4.rc1 Jamoma 0.5.4.rc1 (release candidate 1) has been uploaded. All issues related to OSX Lion are believed to be solved. There are no major changes as com...Falselossius2011-10-04T09:13:22+00:00Added tag - plugtasticlossiusTrond Lossius2011-09-13 20:04:06+00:002011-09-13 20:04:06addTag6Added tag - osx lionlossiusTrond Lossius2011-09-13 20:03:57+00:002011-09-13 20:03:57addTag5Added tag - installerlossiusTrond Lossius2011-09-13 20:03:45+00:002011-09-13 20:03:45addTag4Added tag - hotlossiusTrond Lossius2011-09-13 20:03:39+00:002011-09-13 20:03:39addTag3lossiusTrond Lossius2011-09-13 20:03:35+00:002011-09-13 20:03:35updated2First createdlossiusTrond Lossius2011-09-13 20:02:03+00:002011-09-13 20:02:03created1weblog2011-09-13T20:03:35+00:00groups/jamoma/weblog/2a41aFalseJamoma 0.5.4b1/groups/jamoma/weblog/2a41a/Jamoma_054b1.htmlTrond Lossius6 updatesJamoma 0.5.4b1 We have just uploaded a new Jamoma installer for Mac. The most important changes in this version are: Addresses a number of OSX Lio...Falselossius2011-09-13T20:03:35+00:00julienrabinJulien Rabin2011-08-11 10:42:07+00:002011-08-11 10:42:07updated10lossiusTrond Lossius2011-08-10 09:01:36+00:002011-08-10 09:01:36updated9lossiusTrond Lossius2011-08-10 09:01:13+00:002011-08-10 09:01:13updated8Added tag - hotlossiusTrond Lossius2011-08-10 09:01:11+00:002011-08-10 09:01:11addTag7Added tag - supportslossiusTrond Lossius2011-08-10 09:01:02+00:002011-08-10 09:01:02addTag6Added tag - objective-clossiusTrond Lossius2011-08-10 09:01:01+00:002011-08-10 09:01:01addTag5Added tag - submoduleslossiusTrond Lossius2011-08-10 09:00:48+00:002011-08-10 09:00:48addTag4Added tag - githublossiusTrond Lossius2011-08-10 09:00:38+00:002011-08-10 09:00:38addTag3Added tag - objectivemaxlossiusTrond Lossius2011-08-10 09:00:30+00:002011-08-10 09:00:30addTag2First createdlossiusTrond Lossius2011-08-10 08:53:51+00:002011-08-10 08:53:51created1weblog2011-08-11T10:42:07+00:00groups/jamoma/weblog/ee501FalseChanges to the ObjectiveMax repository/groups/jamoma/weblog/ee501/Changes_to_the_ObjectiveMax_repository.htmlJulien Rabin10 updatesChanges to the ObjectiveMax repository This blog post is intended at developers and users that do not use the Jamoma installers, but rather check out the code from GitHub, and compile exte...Falsejulienrabin2011-08-11T10:42:07+00:00hot/groups/jamoma/search/index.rss?sort=modifiedDate&kind=all&sortDirection=reverse&excludePages=wiki/welcomelist/groups/jamoma/search/?sort=modifiedDate&kind=all&sortDirection=reverse&excludePages=wiki/welcomeRecent ChangesRecentChangesListUpdates?sort=modifiedDate&kind=all&sortDirection=reverse&excludePages=wiki/welcome0/groups/jamoma/sidebar/RecentChangesListmodifiedDateallRecent ChangesRecentChangesListUpdateswiki/welcomeNo recent changes.reverse5searchlist/groups/jamoma/calendar/Upcoming EventsUpcomingEventsListEvents1Getting events…
In this tutorial we will look at how to communicate with the Jamoma modules, and learn the basic structures that the modules utilize for communication.

Open Sound Control (OSC)

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:

    This is all that we need to know for the time being in order to be able to use OSC with Jamoma. Later on, as we start making our own modules, we will look into how to deal with OSC messages in further detail.

    However, if you want to learn more about OSC, this is a good place to start. The Jamoma team has proposed some extensions to the OSC protocol in order to cater for functionalities required in Jamoma. These are discussed in two papers presented at the NIME 2008 and ICMC 2008 conferences. Please check the Papers section for further details.

      Messages to and from modules

      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.

      Setting up the patch

      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.

      Simple patch with tremolo module.

      Now we have to set up each of the modules so that we have some sound to play around with:

      • Input module:
        • Click the Open button and select a sound file to play. For this tutorial we recommend that you find a sound file with relative static content, e.g. a loop with one or more organ chords.
        • Turn on audio using the Audio On/Off button on top of the input module.
        • Hit the Play button, so that the sound file start playing.
        • Bring up the master gain of the input module.
      • Tremolo module
        • Unmute the module by clicking the mute button.
        • Bring up the level using the gain (green) dial in the top of the module..
        • Make sure that the output from the module is 100% wet using the mix (blue) dial at the top of the module.
      • Output module
        • Finally bring up the master gain of the output module so that you have sound coming out.

      Receiving OSC messages from the module

      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.

      Passing OSC messages to the module

      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:

      Passing messages in

      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.

      Ramping to new values

      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:

      Ramping parameter

      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.

      Documentation of the module

      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.

      Pop-up namespace reminder

      If you click and hold the mouse over the displayed name of the module (tremolo~) almost all the way to the left in the module toolbar, a pop-up menu shows up, listing all parameters, messages and returns of this particular module. We will discuss the difference between parameters, messages and returns later on. For now it is sufficient ot notice that even for such a simple module, the namespace is quite extensive.

        pop-up menu of OSC addresses

        HTML reference page

        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:

        • What type of data is expected (decimal, integer, etc.).
        • The default range of the parameter.
        • Whether it is clipping or not at the boundaries of the default range.
        • The default function used for ramping.
        • The default mechanism used to drive the ramping.
        • What dataspace the parameter use, if any.
        • Whether or not repeted values will be filtered out.

        Some of this will make more sense as we move further.

        Help files for modules

        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 leftmost inlet and outlet of modules is reserved for OSC communication to and from the module.
        • Parameters can be updated by sending OSC messages to the module.
        • Parameters can also be changed gradually by applying a ramp.
        • Each module is documented in a number of ways, including a HTML reference page and a help patch.

        What's next?

        In the next tutorial we will learn more about presets for modules.


        The patch used for this tutorial can be downloaded here:

        Download file "Messages to Jamoma modules.maxpat"


        If you like Jamoma and this tutorial, don't hesitate to show your appreciation: