UBC Toolbox - Tutorial

The UBC Max/MSP/Jitter Toolbox is a collection of modules for creating and processing audio in Max/MSP and manipulating video and 3D graphics using Jitter. This tutorial explains how to use the player and effect modules, and assumes a working Max/MSP environment and a basic understanding of its usage.

If you haven't done so already, download a copy of the UBC Max/MSP/Jitter Toolbox here and follow the accompanying installation instructions.

Player Modules:

Player modules create sound using either synthesis or existing soundfiles. A complete list of player modules, with descriptive annotations, is included with the toolbox. For this tutorial, we'll start by creating an FM synthesis player (FMBP) to synthesize a sound, and later add another player module to playback a soundfile (sfPlayerBP).

FM Player

In Max/MSP, create a new patch using File > New > Patcher. Alternately, type Command-N.
Select the "Patcher-in-Box (bpatcher)" icon from the patcher window toolbar (if the toolbar isn't visible, unlock the patcher by clicking the rightmost button in the window's titlebar). Alternatively\, you can type bpatcher into the empty MaxMSO object

Click on the window. Your patcher should resemble this:

Bring up the bpatcher inspector with Object > Get Info (or Command-I) and enter the name of the player module ("FMBP.pat") in the "Patcher File" field. If you wish, you may navigate to the module using the "Choose..." button.

Close the bpatcher inspector window and UBC Toolbox module should appear in the bpatcher. You can adjust the size of the bpatcher if needed to show the entire module.

Player modules receive a variety of messages controlling their behaviour; further, we can pass those messages in different ways. All player modules have certain behaviours in common - responding to messages that turn the module on, set its volume, and so on. Other behaviours are specific to some modules, such as selecting a preset, while still other messages are exclusive to a given module; in our case, a message to change the C:M ratio.
As previously mentioned, it is possible to pass messages to a player module in different ways, including from another Max/MSP patch, a qlist, or even another application, such as NoteAbilityPro. For simplicity, we'll use a message box.
Select the "Message Box" icon from the patcher window toolbar and add an empty message to the patcher. Type the following text into it (we'll describe these messages in detail momentarily):

;
fmOnOff 1;
fmVol 63;
fmPreset 3;
fmNote 60 80 1 2000 0. -1. -1. -1. 5.

Select the "Audio Output" icon from the patcher window toolbar and add an audio output to the patcher. Connect the "Signal Out" outlet of the FMBP module to the right and left inlets of the audio outlet. Lock the patcher by clicking the bottom-right lock button on the window.

Note the current state of the FMBP module, specifically the "On/Off" switch, the volume slider, the preset, and the "C:M Ratio" dial and number box.

Click on the audio output button.
Click on the message box.

Clicking on the message box sends its text to the FMBP module, resulting in changes to the aforementioned interface widgets followed by a brief sound (if you didn't hear anything, there is an issue with either your audio equipment, your operating system audio setup, your Max/MSP environment, your UBC Max/MSP/Jitter Toolbox installation, or the execution of this tutorial).

Examining the message text in detail, we find that a group of four messages was sent - the first turned the FMBP module on, the second set its volume to 63, and the third selected preset 3. The last message is more complex - it is the Note Data List, a data structure used throughout the UBC Max/MSP/Jitter Toolbox.

Click on the FMBP module's info button - you'll notice a description of the module and its controls, the nature of its inputs and outputs, and documentation of the messages it receives. You should see the messages we sent (fmOnOff, fmVol, fmPreset, and fmNote).
Still in the info window, double-click on the "moreAboutDataStructures" patcher to learn about the Note Data List.

Soundfile Player

Adding a player module to our patcher to playback a soundfile is a somewhat different process than that of creating a player module that uses synthesis, though the initial steps are the same.

Unlock the patcher and place a second bpatcher in it. In the bpatcher inspector, set the "Patcher File" field to "sfPlayerBP.pat" (or navigate to it using the "Open..." button) and adjust both the vertical offset and the bpatcher dimensions so that the sfPlayerBP module is completely visible. Close the bpatcher inspector window.
Connect the "Signal Out" outlet of the sfPlayerBP module to the right and left inlets of the audio outlet.

The sfPlayerBP module requires information about the soundfiles it plays, specifically their numbers, durations, buffer names, and filenames. By default, a soundfile's number is the MIDI number modulo 48 in an incoming Note Data List that triggers performance of that soundfile, and the buffer name is of the form "sn" where "n" is the MIDI number (again, modulo 48). It is possible to change this mapping of MIDI to soundfile numbers by altering the table "sfTable" belonging to the sfPlayerBP module, though we'll remain with the default.

Lock the patcher, then double-click on the sfPlayerBP module's "coll sfdata" patcher to open the sfdata text file. Replace its contents with the following text; when complete, save the changes and close the window:

12, 45000 s12 bellPattern1.aif;

Unlock the patcher and add a message to turn on the sfPlayerBP module, set its volume, and load its samples.

;
sfPlayerOnOff 1;
sfPlayerVol 63;
sfPlayerLoadSamples bang

Add another message, this time a Note Data List, and connect its outlet to the "Note Data" inlet of the sfPlayerBP module.

12 80 1 45000

Lock the patcher.

If the Max window isn't visible, bring it forward using Window > Max (Command-M).
Click on the message that turns on the sfPlayerBP module, sets its volume, and loads its samples (in our case, there is only one sample to load). You should receive confirmation in the Max window that the sample stored in sfdata was loaded (it may take a moment).
Click on the Note Data List message connected to the Note Data input of the sfPlayerBP module; you should hear playback of the soundfile we specified in sfdata.
Prior to leaving this section, there are a couple of points to consider. Whenever the sfPlayerBP module receives a Note Data List with MIDI number 12, it will perform this soundfile.
Finally, it's important to observe that unlike the FMBP module, we sent a Note Data List directly to the Note Data input of the sfPlayerBP module. In the former case, we broadcast the Note Data List using the fmNote message; there is an equivalent message for sfPlayerBP, sfPlayerNote.

Effects Modules:

The UBC Max/MSP/Jitter Toolbox implements a number of effects modules; as with the player modules, a complete, annotated list is included with the toolbox. To demonstrate the use of an effect module, we'll add reverberation to our sounds.

Reverb

Unlock the patcher and disconnect the two player modules from the audio outlet. Move it aside, but don't delete it.
Add a third bpatcher; in its inspector, set the "Patcher File" field to "reverbBP.pat" and ensure that the entire module is visible by adjusting its vertical offset and dimensions.
Connect the "Signal Out" outlets of the player modules to the "Signal In" inlet of the reverbBP module.
Connect the "Signal Out" outlet of the effects module to the inlets of the audio outlet.
Add a message to control the reverbBP module:

;
reverbOnOff 1;
reverbVol 63;
reverbPreset 3

Lock the patcher.

Ensure that the audio outlet is on.
Click on the message box controlling the reverbBP module; notice the changes.
Send the Note Data List to the sfPlayerBP module.
Invoke the message to the FMBP module.

The FMBP and sfPlayerBP modules' outputs are now processed with reverberation.

Summary

This tutorial has covered the use of the UBC Max/MSP/Jitter Toolbox's player and effects modules; it should be understood that consistent implementation is an aspect of these modules, and as such the use of other players and effects is very similar. Read the documentation accompanying each module for its specific receives and other useful information.
In a parallel thread we have introduced the concept and use of the Note Data List, and shown how it can be either broadcast to modules or sent to them via direct connection.
Download this tutorial's finished patcher here.

Credits

This tutorial was written by Gregory Lee Newsome in consultation with Keith Hamel.