The Development of Jamoma

    The Jamoma Project recently released version 0.2 of its modular framework for Max, MSP, and Jitter. Despite the low version number this software is actually quite mature, which years of development and experience forming the basis of the framework. Given that this is a significant release in Jamoma's roadmap, I thought I would talk about both Jamoma and it's development.

    What is Jamoma?

    So, the first thing you are probably wondering about is what Jamoma is all about. Jamoma is a structural framework for creating, composing, and performing interactive music with Max. It does this by providing a set of guidelines for the construction of interchangeable, reusable, functional blocks (patches), called modules. In addition to the guidelines, the Jamoma Project has also produced an implementation of those guidelines.
    Jamoma has been built around the advanced features in Max 4.5.5. Jamoma modules may encapsulate any type of functionality that can be performed by Max, MSP, Jitter, its components (such as Java or Javascript), or any third-party objects. It provides features such as fast DSP routines, XML-based preset storage, preset interpolation on both local and global layers, parameter mapping, and realtime CPU-load management.


    The promises of any object-oriented environment is that components can be created, and then freely re-used. This is certainly true of Max as well. However, when a user tries to substitute a component of their patch, there is generally no standard to which the components (patches) are structured. This is actually a strength of Max, as it doesn’t impose its vision of how one should work on you.
    Unfortunately, it is rare that patches can actually be interchanged between users (and auditioned) without a significant amount of work - work both learning the ins and outs of the new patch, and configuring the patch to work in the user’s own system of patches. This is the first of Jamoma’s primary goals: to provide a standard to which patches/modules are structured to allow for easy interchange and integration.
    A second goal of Jamoma is to provide standard tools - that are virtually always required - with a minimum of time needed to set them up. As an example, audio modules will almost always benefit from a mute button, a bypass button, a gain control, signal level meters, etc. Video modules will benefit similarly from bypass, mute, and freeze controls as well as a preview pane. Jamoma provides templates and tools that incorporate these features with a minimal amount of setup time.
    The third goal of Jamoma is provide hierarchical organization of the parameter space. Every module maintains its state, and provides a mechanism for reading and writing preset files specific to that module. Furthermore, global snapshots or presets may be created and maintained that apply to all instantiated modules via the use of Max’s standard pattrstorage object. This also provides a means to interpolate smoothly between presets to simplify complex transitions.


    Jamoma grew out of initial research and development that was conducted as part of the Jade interactive performance environment. Jade is an application that hosts modules, which allows for script-based automation of these modules. Initial development on Jade began in early 2001 as a means to aid my own compositional work. It was released to the public at the end of 2002, which was followed by a significant update to version 1.1 in mid-2003. It was at this time that the great benefit of having modules directly within Max was realized - and Jamoma was born.
    The Jamoma project was started as an Open Source project hosted on SourceForge. After some initial work activity died off until it was revived in March 2005 by myself and Trond Lossius.

    Module Structure

    Every module will have one or more inlets and one or more outlets. The first inlet is used for receiving all commands to the module. Likewise, the first outlet is used to report the state of the module and return parameter values when they change. Additional inlets and outlets are the inputs and outputs for data streams that are to be processed or synthesized by the module. This includes audio, midi, and video signals.

    Standard Elements

    The JIG specifies a variety of essential elements to ensure that modules are both interchangeable and compatible with each other. This includes the size(s) of the user interface, standard features, and reserved messages and syntax.
    For example, every audio module is expected to implement the ‘gain’ parameter, which attenuates or boosts the output signal, specified in decibels. Each audio module should also implement the mute and bypass messages. No module may implement a message called bang, it is considered a reserved name due to its special nature in the Max environment.

    Hierarchical Parameter Space

    Building Modules

    Our screenshot shows the construction of a simple Jamoma module. This module consists of several key components:
    • GUI Component: The black metal background, which includes built in signal meters, bypass and mute buttons, sample-rate reduction (for managing CPU load), gain control, and module menu. The standard Jamoma package includes a variety of these in different sizes. It is automatically configured (using Max’s scripting) for use in audio, video, or control contexts. It is also skinnable - meaning that the appearance can be customized for a look other than the brushed metal that is the default.
    • jmod.hub: The core of the message handling, preset management, and additional functionality. This component shares an invisible connection to the Gui Component to link them. It is connected to a pattrstorage to provide a tie into Max’s pattr system.
    • poly~: Most audio modules will use a patch (in this case degrade.lib) that is loaded in a poly~ object. This provides the mechanism for downsampling and muting. Additional options are available. For example, many Tap.Tools 2.0 externals have integrated mute, downsampling, and bypass capabilities. Video or control modules can use a simple patcher.
    • jmod.parameter: this object creates a parameter and links it to the jmod.hub component. Various attributes can be established such as enabling automatic ramping capability (as seen in a previous section of this paper), decibel conversion, or the filtering of duplicate values.

    Automatic Documentation

    One particulary time-saving feature for module developers is a built-in facility for producing module documentation based on the patch. Using a combination of patching and JavaScript developed by Trond Lossius, this allows you to send a message to a module and save an HTML pages with all of the information on how to use that module.

    Recapitulation in the Key of Licensing

    When a user begins with Max/MSP, they are presented with the paradigm of a blank document (see David Zicarelli’s CMJ article “How I Learned to Love a Program that Does Nothing). This proves to offer the user the ability to work with the software in any way that they like, offering no preconceived notions about how a module should be structured. This is both a blessing and a curse. While not limiting the user, it also provides no guidelines to help the user get started. It is our hope that Jamoma will be helpful for both long time users and beginners alike.
    By providing a mechanism by which a patch must be structured, interchangeability can also be guaranteed. Many new Max users can thus be re-assured that any patch they develop will be able to be re-used. They will also find that they can use a variety of patches developed by others that conform to the JIG. Jamoma also encourages good structure and form for students beginning to use Max.
    Jamoma is licensed under the terms of the LGPL, thus making it freely available for use in both commercial and non-commercial applications. This licensing was chosen for the purpose of helping to establish and encourage adoption of the system.