Tutorial - Introduction to Jamoma 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…

Jamoma modules

We could start these tutorials with a lengthy discussion on what Jamoma is all about. But it is probably better to introduce the concepts along the way in situations where we can play around with them and get a hands-on experience and understanding. So for now we will stick to a very simple description: Jamoma is a bunch of patches that can be loaded in other patches in a modular way.

In Max terminology patches wrapped so that they can behave as objects in other patches are sometimes called abstractions.


This tutorial assume:
  • You are running Max 5.1.9 or later (Mac or Windows).
  • You have sound working. If not please refer to the MSP tutorials.
  • Jamoma is properly installed.
  • You have a basic knowledge of Max and MSP itself.

Building a simple patch using Jamoma modules

We will start out with a new patcher window, create two modules, connect them, and play around with them. In the process of doing so, we will introduce some fundamental concepts.

If you haven't already, now is the time to start Max. If it running already, it might be an idea to close all open patches, in particular patches processing audio, and then open a new blank patcher window.

Instantiate modules

In this tutorial we will use two simple audio modules, one providing audio input and the other one audio output.

As stated above, Jamoma moduels are patches or abstractions, so they can be instantiated by typing the name of the module into a new object box. We will start of with jmod.input~, and give it the argument /myinput~.

As you can see we get an object with one input and three outputs. If we double-click it a nice little interface shows up:

Instantiating a module as an object

The interface seems handy to have available in the patcher itself, so we will delete the object and recreate it as a bpatcher instead:
  • Delete the object.
  • Create a new bpatcher object:

    Create a bpatcher
    Picture 3.png
  • Open the inspector and set the patcher file to be jmod.input~ and provide /myinput~ as argument to the bpatcher:
Instantiating a module as bpatcher
Image 9.png
  • This is what your patch is supposed to look like now if you lock it for edits:
    Patch with one module
    Patch with one module.png
  • We will make one more module in the same way by creating another bpatcher, but this time in the bpatcher inspector the Patcher File should be jmod.output~ and the argument to the bpatcher will be myoutput~. When done you're patch should look like this:
Patch with two modules
Patch with two modules.png
As you can see Jamoma modules strive for a common look. Maybe you have noticed that behind the scene the bpatchers have been automagically resizing themselves to fit the size of the modules?

We could also have created these modules as well by using the _Jamoma_Patcher_ template from the New from template item of the Filemenu... which can be easier for people not used to Max MSP. If you want to give it a try, the way to go is documented directly in the patch...

Give your modules a name

In the examples above, we have provided an argument to the module (/myinput~ and /myoutput~ respectively). The argument gives the module a name. At the top menu bar of each module, you can see the name displayed with a slash prepended. Later on we will be able to address and control each of the modules based on the names we have given them. So, even though it will take a few more tutorials before it becomes apparent why it is useful, we strongly suggest that you right away get into the habit of naming your modules.

Connecting modules

we now have one module that generate audio input to the patch, and another providing audio output from the patch. In order to start using the modules, we need to connect them. The way we do this might look strange at first:

Connecting modules
Connecting modules.png
As you can see, we do not follow the MSP convention of the leftmost outlets and outlets being used for audio. Instead Jamoma introduce another convention:

In Jamoma modules the leftmost inlet and outlet is reserved for control messages to and from the module. All remaining inlets and outlets are used for passing signals in and out of the module.

Let's play!

Now we have all that is required to start playing:
  • In the input module:
    • Click the Open button and find a sound file to play.
    • Click the Play button.
    • Click the Audio On/Off button in the toolbar of the module to start audio.
    • Bring the horizontal level slider up.
  • In the output module:
    • The output module have a separate slider controlling output level. You need to bring this up as well to get sounding output.
  • You can use the DSP button in the menu bar of either module to bring up the DSP Status window.

    Jamoma modules in action
    Jamoma modules in action.png
The two modules we have created are useful as generic audio input and output modules. Below we will discuss the features of each of them a little further.

A more detailed discussion of the two modules

jmod.input~ - A generic audio input module

The input module enable you to quickly switch between some common input sources using the pop-up umenu:
  • Sound file input.
    • Sound file input can be set to loop or not.
    • The name of the file and playback position will be indicated in the interface.
  • Live stereo input (from adc~)
    • Number boxes appear on the left of the level meters and can be used to control what input channels will be used. Generally audio processing need to be restarted for this to take effect.
  • Pink noise test signal
  • 1000 Hz test signal
  • a click signal with one click per second
    • With the numberbox that appears on the right side of the pop-up umenu, the clickrate can be adjusted
Some additional useful features of the module should be mentioned:
  • The output level is controlled by the horizontal slider.This slider is one of Jamoma's custom UI objects: jcom.textslider. See the Shortcuts in Jamoma to learn about the features of jcom.textslider.
  • The two meters indicate levels on a logarithmic (dB) scale. This is done using one of the custom externals developed for Jamoma; jcom.meter~. This level indicator can be useful as a GUI object on its own, and we suggest that you check out the help file for it.
  • To the left of the slider controlling output level, there's a dial for controlling panning.
  • The DSP button brings up the DSP Status window
  • The Audio On/Off button means that we don't have to add an ezdac~ or ezadc~ object to the patch to get audio started.

jmod.output~ - A generic audio output module

The output module is doing some mastering of the signal before passing it out:
  1. First saturation is applied, softening and distorting peaks in the signal.
  2. Next the signal is passed through a limiter.
  3. Third DC offset in the signal is filtered out.
  4. The final gain level of the output signal is controlled.
  5. When audio is turned on and off, a soft fade-in and fade-out is applied.
In addition the mastered signal is forwarded to a sfrecord~ object so that the signal can be recorded on the fly. The mastering DSP chain has been inspired by how mastering of the output signal was done in the eminent but now discontinued radiaL looping application, mainly developed by jhno.

The file type and bit resolution of the recorded signal can be controlled from the module interface. When you hit the Record button a dialog window prompt you to provide file name for the recorded file. Once that is done, recording will start.

Also from the module user interface saturation and limiter can be enabled or disabled, and some of the settings of the respective processing algorithms can be controlled.

The module control panel

In the toolbar of the module, in the upper right hand corner, there's a tiny "+" button. Clicking this will bring up the module control panel, a window providing access to additional parameters. This feature can be found in several modules. If the module contain parameters that will be set on initialization, but are not expected to be changed continuously in performance, the parameters might be moved from the main interface of the module to the module control panel, so that the module takes up less screen estate in the completed performance patch.


This is a list of the most important concepts introduced so far:
  • Jamoma modules are Max patches or abstractions that can be used inside other patches in a modular fashion.
  • Most often Jamoma modules are embedded in bpatchers so that the interface is available in the main patch.
  • Jamoma modules strives for a common look and feel.
  • Jamoma modules need to be named.
  • The leftmost inlet and outlet is reserved for passing control messages to and from the modules. Remaining inlets and outlets are used to pass signals.
  • In some modules additional parameters can be accessed in the module control panel.
  • jmod.input~ and jmod.output~ can be provide generic audio input and output to and from the patch.

What's next?

Now that we have audio input and output working, it is tempting to introduce some sound effect processing between the input and output module.


The patch used for this tutorial can be downloaded here:

Download file "Tutorial Introduction to Jamoma modules.maxpat"


If you like Jamoma and this tutorial, don't hesitate to show your appreciation through comments and/or donations.