practical starting guide to max/msp/jitter

bodsiin htarva project

foreword and methodological approach
It is a commonly spread the idea that the learning curve in Max is quite high when compared to
other similar composing software like Ableton or Reason to mention some.

We would like to present here an approach to learn Max targeted mainly to beginners based on
some principles:

1. quick and dirty: our objective is that the newbie starts asap experimenting with Max, so
we had to reduce profusion and order
2. divergent: our approach is to learn by doing, not always necessarily explaining concepts
in a constructive way but letting the user explore
3. no patches: although we could have include them, we do not deliver any patches with
the guide, all of them must be built by you, the reasons are:
a. we believe the best way to learn is to create patches from scratch
b. in a patch usually there is hidden info (inspector, values inside hidden elements,
dependencies, configurations...) critical for its understanding that could mislead
you
c. a patch lets you operate something, but you usually don’t learn how to build this
something
4. but lots of images: we propose lots of Max patches in this guide and provide (hopefully)
the additional textual information for a newbie to implement it him/herself in Max
a. objects are written in bold letters
b. messages are written in italic
c. images should contain every detail you need to build the patch, if not ask us to
change it
5. you: this is the important part, as this method requires probably a lot of interest in Max
from your side and some faith leaps
6. not complete: sorry, but we do not have enough resources, this is only a selective bite to
the huge Max cake
The objective of this guide is that a newbie can feel comfortable enough to make a deeper use
of the excellent available documentation like the Max documentation itself, Cycling74 tutorials
and forums, CNMAT tutorials or the excellent BAZ and PAD tutorials in youtube.

This project is a work in progress and more modules are being thought. We will be glad to
receive feedback in our gmail named bodsiin, but now let’s start:

programming and music, why?

Actually programming music must not be always so difficult as it may seem and in exchange we
will have quite a number of advantages. Nowadays sound and visual artists can benefit from a
number of intuitive (at least more than programming itself) graphical programming environments
such as Puredata and Max/MSP.

Instead writing the lines of code which describe what the program does, you will be able to
manipulate visual objects on-screen. Your program will be called patch and you will design it by
placing objects (functions or methods that deliver a result) on the screen. These objects are
clever enough to understand some instructions that we will call messages and also interact with
each other when connecting them.

Furthermore, all this works in real time. That means that certain changes can be made in the
objects even as the program is running so you can see or hear the results immediately. This
makes it a powerful tool also for artists who perform live.

how a real time graphical programming environment

looks like?
Programmers are typically able to abstract the idea of object-oriented programming but it is also
in everyday life. You can think about an object as a person with a certain profession or
qualification. That person is able to understand a task (method) in a certain language and
perform it. The complex interaction of a good number of persons with different qualifications can
deliver an interesting result.

With this analogy in mind, programming would be like organizing and coordinating the work of
lots of people. The organizer (programmer) thus must have a good knowledge about:

● the people available (objects instantiated)

● the tasks that different objects understand (messages)
● a lenguage to express the task to the person (methods and arguments)
● a communication channel to deliver the message (patch cords)
● which ears (inlets) receive information and which mouths (outlets) send information
Let’s make a non-Max example in Max to illustrate it. Let’s suppose we organize the work in a
hospital. A patient arrives and we need to know his diagnosis. We want to design a general
procedure. How do we proceed? First of all we decide that we will use the doctor object to
perform this task because we know in advance that a doctor can deliver us a report. We design
then the part of the program to send the necessary information to the object:

1. Create a doctor object (let’s suppose that the syntax is ID of the object followed by the
name of the object)
2. Create a message with the task (method) to perform (in this case diagnose) followed by
the surname and name of the patient (arguments)
3. Create a communication channel between the message and the object (patch cord)
Note: this example is shown for pedagogical purposes and of course does not work in Max ;-)

Then we design the part of the program to receive the information we need from the object:

1. Create a bell that rings in our office when the task is finished (bang)
 2. Leave space for a new incoming report in our office with the detailed information of the
diagnose
The program would look more or less like this:

(text boxes with dotted borders are the comments of the program)

OK, the program seems to be ready, but now, how we execute it? We have to switch from the
designing mode (unlocked) to the operation mode (locked). The program looks pretty much
similar as before except we cannot edit anymore and the messages are clickable.

In operation mode by clicking on the message diagnose followed by the arguments we trigger
the following:

1. sends the message with method and arguments (task to perform and patient) to the
doctor with ID p
2. doctor p knows that when he receives a patient (argument) and the task diagnose
(method) must make a report and when finished:
a. ring the bell to the right outlet (bang illuminates)
b. send a message with the report content to the left outlet (report appears)
So, every time we program in Max, we have two faces: one face is the one of the programmer
and the other is the one of the program operator. This is the main advantage of Max against
other music programs that allow you only to operate the program but not to create your own
program.

It is important to know in detail which tasks can perform which objects. In our imaginary
example, we could not send the method diagnose like this to a person that repair bikes, it must
be directed to a doctor object, or maybe a nurse object. The person that repair bikes maybe
accept the methods checkbrakes or changewheel but definitely not diagnose (at least, not in the
sense of medical diagnose)

Thus, the steps to gain knowledge of Max could be:

● knowing the different objects

● knowing its main methods and arguments (or main tasks they can perform)
● knowing the responses (in which format, through which outlet) the main methods trigger
for different objects
● learn different practical ways of interaction between objects
So let’s get started. Open Max.

first steps in Max and shortcuts

Here we present some useful shortcuts that you will use more and more as soon as you get
used to Max environment.

Note: replace Apple with CTRL in windows

Shortcuts
Duplicate objects many times in a geometrically pleasing manner:

1. option-shift-drag for the second

2. apple + d for the rest
Clear Max window:

1. apple + m (shows Max window)

2. apple + a (select all lines)
3. delete
Help files:

● select an object and press apple + shift + h

Other shortcuts:

● Press m to instantiate new messages

● Press i to instantiate a number object (integer)
● Press f to instantiate a flonum object (float)
● 3 is an integer while 3. is a float (notice the point)
● Select an object and press apple + shift + h to show help
● Press c to instantiate a comment box
● Press b to instantiate a bang
● Press t to instantiate a trigger
● Press p to show object palette
● Press r to show object palette/recents
 ● Press j to create a jitter object
● Press l to create a live object
● Connect one outlet to many inlets by holding the shift button before you click on the
outlet
● Shift and click to create a non lineal patch
● Apple + b to show the file browser
● Apple + e to lock/unlock the patch
● Control-option-click any object to see a complete list of messages that the object will
accept.
● unlock: apple-click on any empty space of patch
When you locate the pointer over an inlet, a red circle appears stating info about function and
data type permitted. Moreover, if you click inside the red circle, appears a list of all messages
that can be sent to this particular inlet, if you click any element of the list, it creates the
appropriate message with a patch connected to the inlet.

new document
By now probably you would like to create your first program. Creating a program is the same as
creating a new document (or patch). Pressing apple + n, you will create a window similar to this:
The name of the Max document (hereinafter patch) is located at the top bar of the document
and by default is Untitled followed by a number that depends on how many documents you
created in the current session.

lock/unlock mode
By default you also see in brackets the word unlocked, that means that you can edit the patch.
To operate the patch you have to lock the patch clicking the padlock. Click now the padlock on
and off to get familiar with this feature. Another way of locking/unlocking is clicking with the
Apple key pressed in an empty space of the patch. Another way is apple + e.

objects
They do something in Max/MSP, usually takes something in and puts something out.
You create a new object pressing n in an empty space on a document (patch) and typing the
name of the object. (Be aware that the object will be inserted in the place where you had the
pointer when n was pressed)

Max 5 has implemented an autocomplete feature that brings a list as you type. You just have to
select the object from the list, give some arguments if needed (leave a space between the
object name and the first argument and also between the different arguments) and hit enter.

You can also create an object bringing the object palette, pressing p (as when you create an
object directly, the object will be inserted in the place where you had the pointer when p was
pressed)

The inlets (always up) receive information and the outlets (always down) send information out.
In this example, the + object receives two numbers in its inlets (above) and returns the sum in
the outlet (below)

As a general rule, the bangs are received in the left inlet, when information received in other
inlets, will not trigger the outlets of the object. (Exceptions: gate, funnel and pak)

Note: a bang is an undifferentiated, unqualified event, which most objects interpret as a command to
trigger whatever it is that action they perform as max objects

When objects have more than one inlet, the right inlets are usually for setting values
(arguments) before the left inlet input causes a reaction. These arguments do different things.
You should always check the help patch for the object to learn what arguments the object
accepts and to do what.

When editing a patch (unlocked mode), moving the mouse over any inlet or outlet you will get a
small dialog describing what that input/output does.

Abstractions are similar to objects, but their components are other objects, example: create a
new object pressing n and type pan2 then press enter

To create a new patch press apple + n or click File → New Patcher in the main menu.

Press n to instantiate new objects or double click in the canvas to recall the object manager.
The data that comes after the name of an object is called argument, and usually sets up the
initial behaviour of the object. Maybe you can try to make a patch similar to this one, the
speaker is an audio out object called ezdac~

drag and drop from the file browser

When pressing apple + b, the file browser window appears. This is a useful tool to find the
objects, patches, audio... you want to use in your patch. You can browse on the left column or
use the search engine and drag and drop to the patch the file selected, take your time to explore
a bit the file browser:
messages
Technically, messages are objects also, but we will see them separately. They usually tell other
objects to do something. They travel instantly along patch cords. They can also receive
variables (numbers, symbols, lists...) via inlet and use them with $1, $2 and so on:
We can send two messages together separating them by a comma.

The special symbol semi-colon ; inside a message box tells that the next item will be the name
of a receive object, we can include as many as we want in a message:

A receive or r object is a special object that allows to receive messages without a patch cord,
the other way to send remotely a message in Max is to use a send or s object:

Note: in Max, the receive object has exactly the same effect as r and send as s.

The yellow triangle on the float object (the number box on the left) indicates that it is selected. A
float object is an object that we can instantiate (create an actual copy of the object in our patch)
by pressing f anywhere in the patch window and offers an interface to generate float (real)
numbers.

Note: a real number is a value that represents a quantity along a continuum of numbers, here we show
some examples of real numbers:

● 5 is an integer or just a number

● 3/4 is a rational number, this means that that can be expressed as the quotient or fraction a/b of
two integers, with the denominator b not equal to zero
● 8.6 is a rational number expressed in decimal representation
 ● pi is 3.1415926535..., an irrational number, meaning that has an infinite number of decimals with
no pattern, most of the real numbers are of this type.
In the case of pi or rational numbers with a large amount of decimals, you will realize that they are
truncated to 6, this is due to the precision that Max supports by default. So, in fact we mainly will be
dealing in Max only with rational numbers expressed in decimal representation.

A message can receive the message color space number (between 0 and 15) to set up its
background color:

Other messages you can send to the left inlet of a message:

● set sends whatever follows as the content of the message (set 1 3 5 7 to the left inlet will
set the message to 1 3 5 7)
● set alone clears the message

inspector and attributes

When you select an object in a patch and click apple + i, the inspector window shows up. It
shows the default attributes of the object organized in tabs presenting the attributes row by row,
colour-coded for clarity, with font selectors, colour swatches, menus and tick boxes as
appropriate. From the inspector you can change any aspect you desire from each object in Max.
It is possible also

Let’s see an example: we have created a metro object in a new patch by pressing n, typing
metro and clicking enter, once done the patch should look like this:
Now if we select the object and click Apple + i to show the inspector, we see all available
attributes that we can change for the given object.
To change attributes in this way you must be in edit mode, but there is a (sometimes less
known) way to change attributes also when operating the patch in locked mode. One of the
design aims of the attribute system was that an object should be able to accept an attribute
change by receiving a message via a patch cord. Now, if you drag a row from the inspector
window onto the object, Max will magically create a message box with the correct text to alter
that attribute.
This is particularly useful for Jitter users, where attributes are so crucial to the control of video
and matrix objects, but is also a really handy shortcut in the Max world, allowing to control
attributes that modify the object behavior itself, appearance and so on.

lists
A list consists of a group of integers, floats or symbols separated by spaces. The zl object with
its different parameters offers many ways to operate on lists:
The List package is another good tool to work with lists with ready-to-use java objects. They are
located in the Cycling74 folder of your Max instalation, in Cycling '74/java/help

Locate the file named listpackage.maxpat and open it. In general, a good way of knowing what
is possible to do with an object is by opening the file with extension .maxhelp

patch cords
When you click in an outlet and move the mouse, you will see that a patch starts to appear in
the screen, take it to the inlet of another object and release the button. Your first patch cord is
created. Three types of cords: Max cords (black) transport information, MSP (dotted yellow)
audio signal and Jitter (dotted green) video signal:

Hold down the shift key, click on the outlet you want to connect, release the shift key, use
mouse clicks to create segmented patch cords (alternatively you can check segmented patch
cords in the main menu by selecting Options → segmented patch cords). Segmented patch
cords can cause problems when you try to rearrange the position of things later:
Max works at control rate and MSP at audio rate
Most parameters controlling a transformation do not change very fast. The control rate is
typically no more than about 1 kHz, which results in a time granularity of approximately 1 ms
(control tick). This is supposed to be fast enough for typical nonaudio data. Furthermore, the
data flow at control rate is asynchronous, which means that data can be passed, but if a
parameter value is constant over a longer period of time need not be sent at every control tick
but only when a change of the value occurs.

MSP objects work with audio rate that usually is set up to 44.1 kHz, which is the sampling rate
used for Compact Disc and it is synchronous, meaning that whenever audio is on, there will be
a flow of data.

The message domain in Max objects is for most systems also capable of handling non-
numerical data.

Max/MSP objects
messengers
print object prints in the max window the message received in its inlet.

printit prints in addition a complete breakdown of a max data structure

timer reports in its left outlet the elapsed time between two events. The time starts counting by
sending a bang to the left inlet. The elapsed time output each time a bang is sent to the right
inlet can be set for milliseconds or ticks (the smallest increment of time as measured by a
computer system).

unpack object receives a list and breaks it into individual messages:

 ● The number of arguments determines the number of outlets
● A bang object connected to the inlet outputs of what is stored in unpack
This is how the help file looks like (create an unpack object and select it, then press apple +
shift + h):

Conversely, the pack object creates a list from separate elements. Try to reproduce the patches
shown in the images (without the comment text) from now on. In this one you have to press
twice f, once n and type pack, once m and make the connections.

pak object outputs a combined list when any element changes:

t or trigger puts out the argument no matter what goes in:

Check the max window to see the results. i stands for integer, f for float, s for symbol, b for bang
and l for list. Another example: the same output can generate different types of data:

gate object passes the message from the right inlet to the outlet if the gate is open.

● A non-zero integer sent to the left inlet opens the gate, zero closes it
● The integer sent to the left inlet specifies the open outlet
● The argument is the number of outlets and by default is 1
● If the input is bigger than the argument, the last outlet will be active
● Can take a second argument that is the default gate open before sending anything to the
left input
funnel object receives data in the number of inlets given by its argument and outputs an
indexed list with two elements, the first one is the number of the inlet (index) and the second is
the value received.

spray object takes a list as input. The first number is taken as the outlet number, and one or
more numbers that follow are sent out that outlet and those to its right, in right-to-left order. The
argument sets the number of outlets (there is no set limit). The default number of outlets is 2.

switch object switches between 2 or more inputs

● First argument is number of switches

● Second argument is number of inlet ON by default
A number sent to the left inlet opens the corresponding switch (if 0 closes all)

There is also a graphical version called gswitch under buttons section in new object palette
(double click in an empty space of a patch to access new object palette)
route object takes an incoming message in inlet and tries to match its first argument to the
object's own arguments, sending the result to the outlet

● receives in the inlet a list

● if the first element of the list matches with any of the arguments, the rest of the list is
sent to the appropriate outlet
● if a number is received, sends a bang to the appropriate outlet
● there are as many outlets as arguments + 1
● the last outlet is reserved in case the first element of the list does not match any
argument

matrix~ is an array of signal connectors and mixers, an easy way to control it is connecting a
matrixctrl object to its inlet

● first argument: the columns of matrixctrl represent the number of incoming signals (and
inlets)
● second argument: the rows of matrixctrl represent the outputs
● dump message in the left inlet sends the current gains of all connections out the
rightmost outlet, in lists of this form: <input output value>
● ramp message with an argument in ms sets ramping time over which the gain values are
changed
● signals entering at each inlet can be routed to one or more of the outlets
router object lets you patch multiple sources of Max data to multiple destinations dynamically,
as matrix the first argument is the number of inputs and the second is the number of outputs. It
is designed to work best with the matrixctrl user interface object that we saw above and uses a
syntax equivalent to the MSP object matrix~
select or sel object outputs a bang in the left outlet if the input matches argument and outputs
the value in the right outlet if different. Set a value to be sent to the right inlet and see what
happens when you move the left slider.

Note: the objects that feed the floats are slider objects.

split object receives a value in the left inlet and outputs it through the left outlet if the value is in
the range defined by the arguments. If not, it sends it to the right outlet.

change object stores the number that we send to the inlet. If a new number is sent, it will output
it to the left outlet only if it is different from the stored number and will reset the stored number to
that differing input number

● mid outlet sends the value "1" for logical transitions from zero to non-zero value
● right outlet sends “1” if the transition was from non-zero value to zero
loadbang object sends a bang to its outlet when the patch that includes it is loaded. Useful to
set some initial conditions.

loadmess object sends a message (argument) to the outlet when the patch is loaded.

send or s and receive or r objects allow message transmission without connectors. The send
object receives a message in the inlet that is sent to the outlet of the receive object with the
same name (argument).

The equivalents send~ and receive~ transport audio signals instead of messages but they
have a CPU cost since they copy the audio into memory. The effect will not be noticed unless
there are hundreds of send~ and receive~

generators
button object (shortcut b) sends a bang when any message is received in its inlet or when the
button itself is clicked in unlocked mode.

opendialog object opens a dialog window to ask for a file or folder when a bang is received in
its inlet.

● argument(s) specify file type(s) (AIFF, AIFF-C, Wave...)

● if no argument any file can be opened
● to specify a folder, set fold as argument
● takes a list of one or more file types and allows you to select a file from among those
types
● when bang received in inlet, the entire pathname of the file or folder chosen is outputted
● this path can be passed to any Max object after the word read or load (depending on the
object that reads/loads)
● bang reported to the right outlet when user cancels and does not choose a file
● when a file type is received in the inlet (for example TEXT), this file type is enabled and
opens dialog
● set message followed by a file type to the inlet (for example JSON), sets file type but
don’t open the dialog window
● sound to the inlet sets the sound file types and opens the dialog
uzi object generates a specific number of bang messages when a a bang is received in its inlet.

● 1st argument is the number of bang messages to send

● bangs are received in the left inlet and index in the right inlet
● 2nd optional argument sets offset index (default 1)
● pause and break stop sending bangs
● resume or continue start sending bangs again

counter object without arguments: given a bang in left inlet, incrementally increases number.

● counter 1 16 with 2 arguments that indicates min and max.

● 2nd inlet sets direction of counter 0=up 1=down 2=up-down
● 3rd inlet resets counter on number sent next bang
 ● 4rd inlet resets counter immediately (if a number above the range is sent and you're
going downwards then it reaches zero and stays in the range)
● 5th inlet sets count maximum (also can be done by 2nd parameter)

metro object outputs a bang at regular intervals determined by the argument (in milliseconds):

● starts with a bang in the left inlet

● the argument can be modified sending a message to the right inlet

tempo object output numbers at a metronomic tempo

● bang on the left inlet activates it

● number to the second inlet (first argument for initial value) sets beats per minute (BPM)
● number to the third inlet (second argument for initial value) sets beat multiplier
● number to the fourth inlet (third argument for initial value) sets divisions of a whole note
(default 16, range 1-96)
del or delay object receives a bang and then holds onto it for a specified amount of time in ms
before sending the bang to the next object. Optional int or float argument to initialize delay time.

zl group creates a list made with the stream of items received in the left inlet after a given
number of items (sent to the right outlet) is received:
Note: see more zl objects to operate with lists in the help file.

pipe object delays numbers or lists. Numbers are sent to the inlets but the last, the last inlet is
reserved to control the delay time in ms.

line object output numbers in a ramp from one value to another in an specified time in ms:

● first argument sets initial value and output type (int or float)
● second argument sets time grain (int or float regardless of the output type), default is
20ms. Int/float in right inlet sets the time grain
● int/float in middle inlet sets ramp time
● bang in the right outlet is output when the ramp is over

random object when triggered by a bang in the left inlet causes a random number output within
0 and the argument -1.
drunk object also causes a random number output but the difference between two consecutive
numbers must be in the step size specified by the 2nd argument

urn object generates random numbers but without duplicates, when all numbers is a range have
been generated, outputs a bang in the right outlet.

decide object chooses randomly between on/off (0/1)

prob object accepts a list of three numbers, the third number represents the weight of the
probability of going from the states represented by the first to the second number
mousestate object reports the status and location of the mouse, all data shown in pixels. Delta
is the variation in this example every 200ms. The mouse button is sampled every 50ms.

Sending the message poll, output values as the mouse create those values.

key object reports key presses on the computer keyboard in 4 formats corresponding to 4
outlets:

keyup object reports keys releases on the computer keyboard

matrixctrl object is a matrix switch control operated by cells that live in a rectangular grid as we
saw, here is more detail of its behaviour:
 ● clear to the inlet deletes every cell in the matrix
● All of the cells in a matrixctrl object have the same appearance and behavior
● By default, the cells have two states 0/1
● You can create cells with any number of states
● Clicking on a cell increases its state by one
● Alternatively, you can change the cell state by sending a message with a list of three
numbers to the inlet:
○ 1st number: x coordinate
○ 2nd number: y coordinate
○ 3rd number: how much will the state increase (can be also dec for decrementing
or inc for incrementing in one unit)
○ you can also compose more than one triad in one single list
● every time the state of a cell is changed, a list with the triad is return in the left outlet
● After a cell reaches its last state, it returns to its zero state when clicked again
● the message active followed by 0 deactivates the object and follow by 1 activates it
● getrow message and a number retrieves the values of the appropriate row on the right
inlet
● getcolumn message and a number retrieves the values of the appropriate column on the
right inlet
date object accepts three messages in the inlet: data, time and ticks. Object reports:

● date as a list of three numbers (day, month, year) in the first inlet
● time as a list of three numbers (hour, minute, second) in the second inlet
● number of 1/60th-of-a-second ticks since startup as an integer in the third inlet
makenote object creates a note with arguments MIDI amplitude (range 0-127) and duration of
the note in ms.

● 1st inlet sets pitch (range 0-127) and starts the note
● 2nd inlet sets MIDI amplitude (range 0-127)
● 3rd inlet sets duration in ms
● 1st outlet sends the pitch when the note starts and again when the note ends
● 2nd outlet sends the amplitude when the note starts and 0 when it ends
noteout object plays a MIDI note, usually you connect the two outlets of makenote to the 2 first
inlets of noteout (MIDI pitch and amplitude). The third inlet of noteout can receive the MIDI
channel.
Note: to create the keyboard, instantiate the kslider object.

lorenz object is an external designed at CNMAT that generates a lorenz attractor. This is a
curve in 3 dimensional space that recalculates its position every given timestep h, the
coordinates of the new point are:

● xnew = x + (10h(y-x))
● ynew = y + (h(28x-y))
● znew = z + (h((xy)-((8/3)+z)))
A bang in the left trigger generates the next point on the graph. Values of x y z h are inserted as
arguments and default are 0.6 0.6 0.6 0.01

storage
value object takes a symbol as argument through which all value objects of the same name are
linked
lcd object draw graphics in a patcher window receiving in its inlet messages with four
arguments (left, top, right, bottom) and sometimes a fifth (color index range 0-255) or fifth to
seventh to specify RGB.

● frameoval draws a circle/ellipse

● paintoval the same but filled
● framerect draws a rectangle
● paintrect draws it filled
● linesegment draws a line (arguments startX, startY, endX, endY)
It is possible also to draw other shapes and to draw with the mouse in the object, in which case
the mouse position (in pixels, being 0 0 the top left corner of the lcd) is retrieved by the left
outlet.

bucket object passes numbers received from outlet to outlet in order. The number of outlets is
initialized by its argument and controlled by sending the message set and a number to the left
inlet:
table object allows to store numbers by a certain index

● table size is the size of the index (you can see it also as the x axis)
● table range is the the range of possible values (you can see it as the y axis if you think in
terms of a function)
● to store values in a table, send to the left inlet a list of 2 numbers, the first is the index
and the second is the value
● store also a value sending it to the right inlet and after sending the index to the right inlet
● to recall values from a table, send an integer to the left inlet, the value will be shown in
the left outlet
● to see the table, double click the table object, a window will appear where you can edit
directly the table in a graphical way
● to see the table it is possible also to send the open message to the left inlet
● you may name the table giving an argument to the table object
Sending a bang to the left inlet of the table object, we receive in the left outlet an index that
belongs to the table size. The higher its value on the table, the more probabilities for the index
to be shown. The indexes with value 0 cannot be reached with a bang no matter how many
times we bang the table object. So, used in this way, table can be a generator object that stores
a probabilistic function that is used to decide among the indexes with non-zero value:
pattr object is a named data wrapper

● first argument is the name of the pattr object

● second argument specifies the named object to which pattr left outled is bound by
default
● to change the 2nd argument, send a message bindto and the name of the new argument
pattrstorage object is used to store presets of multiple interfaces. Do this:

1. Give a name to the interface objects you want to remember (scripting name)
2. Create a pattrstorage object and name it with an argument
3. Create an autopattr object
4. Connect the left outlet of autopattr to the inlets of every interface object you want to
remember
To check that everything is OK so far, send the message clientwindow to the inlet of your
pattrstorage object. A window should appear with the name you gave to every interface object
and the current value. If everything went fine, lets start to store values in the pattrstorage
object.

5. To store the first value, first select in the interfaces the positions you want to store, then
send the message store 1 to the left inlet of pattrstorage. Repeat this with incremental
integers as many times as presets you need
6. To see what is stored, send the message storagewindow to the left inlet of pattrstorage
 7. To recall the presets, send an integer to the left inlet of pattrstorage

autopattr object finds all objects in the patch with scripting name and pattrstorage access to
the values of these named objects in order to store their current value for later use. If you want
to recall a preset continously, connect a float object to the inlet of pattrstorage.
 When you save a patch with a pattrstorage object in it,
after saving the patch you will se a dialog to save an xml
file, which store the data of pattrstorage.

preset object stores and recall the settings of other

objects, when you mouse over the buttons, you will see
the number (default 24 presets)

● click on a circle to recall

● shift + click on a circle to store
● If no objects are connected to a preset's outlet,
all objects in the patcher window are stored
multislider object can receive a number and show the
value in the slide, conversely it is possible to move the
slide and send the value to the outlet. Open the
inspector and experiment with the attribute Sliders
Output Values.
umenu object can be used to display text associated to incoming numbers that start at 0

coll (collection) behaves as a table in the sense that stores values at indexes, but both values
and indexes can be anything e.g. int, flot, symbol, list...

Like in a table, you store things by sending two things to the inlet where the first thing is the
index and the second is the value e.g. 3 23 4 56 stores the list 23 4 56 on the index 3.

To recall the data, send the index to the inlet.

When sending the following messages to the inlet:

● clear erases everything

 ● remove 1 deletes the thing associated with the index 1
● delete 1 as remove but decrementing higher indices
● write writes to a file
● read reads from a file (optional filename argument specifies file in Max's search path)
If you want to save coll data in the patch, don’t give it a name.

qlist is a container that holds a table of events. Each event can start with a symbol (name) in
which case, it will be sent not only to the left outlet but to the receive with the same name. To
see the content of qlist, like coll double click the object to see or edit the contents. This is an
example, each row represents an event:

Each row represents an event. The events that start with a name, like variable1 can be received
in a r object:

buffer~ object stores audio samples

● first argument names the sample to use by other objects

● send read message to inlet to open a sound file
● filename optional second argument specifies file to read in Max’s search path
● buffer-duration optional argument in ms
 ● to see the wave stored on the buffer~ object, double click it
● when clicking or dragging over a sample, left outlet reports the mouse position in
milliseconds

In this example, it is shown how can we load different samples and create an interface to play
each of them separately:

Sending the message import and a file name to the inlet of buffer~ it is possible to store any file
compatible with quicktime (for example .mp3 or .caf)
polybuffer~ object allows you to store several buffers in the same object. The buffers can be
played with groove~ as usual.

Clicking the message open a dialog will appear inviting you to drop a folder with audio files:
It works with any sound file quicktime can play. Here is an example on how to control which file
is being played with a number object:

capture~ object stores the values of a signal in a text file

 ● to see the text file, double click the capture~ object
● the capture only starts when the signal is routed to the speakers
● 1st argument: optional f to enable first mode, it collects the data up to a specified
number since the signal starts (default last mode so the new data replaces the old
values)
● 2nd argument: number of values to capture (default 4100)
● 3rd argument: decimal precision (default 4 decimals)
● 4th argument: a list of up to 10 indices within a signal vector (default records the entire
signal vector)
● send the message write to save the data to a text file
● send clear to erase the data in the object
Important note: the text window that appears when we double click the object may only hold a limited
amount of data. In the written file you can see all the data.

To start storing, just click the ezdac~ object (speaker). This activates the audio (DSP on). Then,
when capture~ is double clicked, the 101 first samples of a 440Hz cosine signal appear in the
text window:
dropfile object lets you define a region of the patcher to drag and drop a file/folder

● send message type with the extensions you want to allow (default accepts all files)
● left outlet sends full path of the dropped file/folder
● right outlet sends extension (type code)
jit.cellblock object provides storage, viewing and editing of two-dimensional data in a
spreadsheet-similar format. The current cell location, format, display and contents within
jit.cellblock can be set with the mouse or using Max messages:

● click a cell to send its location and data to the left outlet
● send the message select with the column number and row number to the left inlet to
select it and to retrive a cell’s data
● a bang to the left linlet retrieves the information of the selected cell
● the output format when you click a cell is a list with three values: column number, row
number and information stored in cell
● clear followed by the column number and the row number deletes the value stored
● to set the value of a cell, send a select message followed by three values: column
number, row number and value
● to synchronize two different instances of jit.cellblock, connect the third outlet of each with
the right inlet of the other
● readonly message will prevent value changes if set to 1. If the jit.cellblock is in "inline
edit" mode, no editing will take place on readonly cells
● to prevent value changes on the entire spreadsheet, send the message readonly 1 to the
left inlet
jit.cellblock can serve as a visualization of coll object. As the coll's contents change, the format
and contents of jit.cellblock are changed to match:

1. name the coll object giving it an argument

2. send the message refer followed by the name of the coll object to the left inlet of
jit.cellblock (if you want to stop the visualization of coll, send deref)
 3. all values in coll will be reflected in the jit.cellblock object, also when coll is modified
with a new value

freesoundsearch external (non-comercial extension object developed by Nao Tokui) allows to

search and preview an audio file from Freesound, a collaborative database of Creative
Commons licensed sounds. Download it from here:

http://www.sonasphere.com/blog/?p=1201

Once installed, you can recall it as any other object pressing n in an empty space of your patch:

● sending login to the inlet with arguments username and password sets the
authentication
● when login is correct, the 3rd outlet sends a 1
● sending search with argument “search query terms” (with quotation marks) sets the
seach text
● min_duration followed by a float sets the minimum duration of the sample
● max_duration followed by a float sets the maximum duration of the sample
● the same with min_bitrate, min_bitdepth, min_samplerate
● messages available to specify the search target (adding 0 or 1):
○ search_descriptions
○ search_tags
○ search_filenames
○ search_usernames
● download_dir and the path (beware: you must specify a UNIX path instead of a Max
path)
○ "/Users/bodsiin/Experiments" - good!
○ "Snow Leopard:/Users/bodsiin/Experiments" not good
● search result is available in the left outlet
● when search is finished, a bang is sent to the 4th outlet
jit.uldl object uploads and downloads from internet
jit.str.regexp perform regular expression analysis with Jitter matrices. As an application, it can
parse an HTML previously downloaded with jit.uldl to extract for example a gif file.

conversors
fromsymbol transforms a symbol into individual numbers or messages.

tosymbol converts messages, numbers, or lists to a single symbol.

sampstoms~ converts time from samples to milliseconds and mstosamps~ the opposite.

sprintf combines symbols, organize lists of numbers, or format messages or menu items.

regexp object searches for in the string or text sent to it and can perform several operations:
patcher or p object creates a subpatch that lives in the patcher object.

● To see the content of the patcher double-click it

● The number of inlets in a patcher object is determined by the number of inlet objects
contained within its subpatch window.
● The messaging which the patcher object can handle depends upon the patch you
embed within it.
● apple + shift + e encapsulates selected elements in a patch object.
● apple + shift + d decapsulates selected patch object.
poly~ object is similar to patcher but allows one or more instances (copies) of a patcher to be
loaded.

● The patcher filename and the number of instances are arguments.

● The maximum number of instances is 1023.
● You can have multiple in and out object with the same index.
zl is a list processing object, with the argument delace de-interlieves a list. For example, given
the list “a 6 d 6 f 9 n 3 j 6” in the left inlet, would send the list with the odd elements “a d f n j” to
the left inlet and the list with the even elements “6 6 9 3 6” to the right inlet.

ftom object converts frequency in Hz to MIDI pitch or note number (0-127).

mtof object converts MIDI note number to Hz

Both ftom and mtof have signal equivalents ftom~ and mtof~

atodb object converts linear amplitude (0. to 1.) to decibels (-inf to 0.)

dbtoa objects converts decibels to amplitude

iter object breaks up a list into a series of numbers.

scale object maps a given range of values into a different one.

● scale 0 127 -1. -1. accepts in the left inlet any number (integer) from 0 to 127 and
transforms it in a float between -1. and 1. in a linear way
● The 5th argument that scale can take is exponential base value (default 1 means linear)
● If all 4 first arguments are integers, the output will be integer, otherwise float
jit.rgb2luma object converts the RGB video signal that receives in the inlet to monochrome
video signal that sends to the left outlet.

function object transforms values from a certain range to another following a breakpoint
injective function, so f(x)≠f(x’) for all x, x’ that belongs to the domain (x axis)

● to add a new point, just click (in locked mode) on the function object canvas
● sending a message with a list of two values, adds the point (first value=x, second
value=y)
● sending clear message to the inlet we erase the function
● sending dump message to the inlet sends all points out dump outlet (third outlet),
optional argument names receive object
● listdump message send all points out dump outlet as one list, optional argument names
receive object
● float in the left inlet produces interpolated y for this x at left outlet
● bang in the left inlet outputs all breakpoints in line format (initial value followed by a list of
deltatime-value pairs) in the second outlet
● bang in the 4th outlet is received when function is changed by mouse action
notein object converts received MIDI notes (for example played with a MIDI keyboard) to
numbers where the pitch or frequency of the note (range 0-127) is sent to the first outlet, the
velocity which is more or less the volume of the note (range 0-127) is sent to the second outlet
and the MIDI channel is sent to the third outlet.

operators
arithmetic

You can flip the order of the operation with the character !

sumlist is a Jasch external that calculates the sum of a list.

Note: download Jasch externals from http://www.jasch.ch/dl/

expr object evaluates an expression involving the first (up to) nine inlets.

● Inlets can receive variables or constants: integers ($i1-$i9), floats ($f1-$f9) or symbols
($s1-$s9)
● The operators are +, -, *, /, &, |, &&, ||, !, ~, and ^

vexpr object behaves like expr but we can operate with lists also:

when scalarmode 1 is sent to vexpr, input of length 1 is applied to each element of the other
lists:

logic
Evaluating if two numbers are equal:
The same is valid for not equal, greater, greater or equal and so on...

Logical AND OR:

statistics
mean finds the running average of a stream of incoming numbers.

● stream input can be numbers or floats

● when a list is received, past numbers are cleared and gives average of list
● average float is received in left outlet
● right outlet keeps track of the number of elements considered in the average
computation
audio signals
cycle~ object is an oscillator which its default waveform is one cycle of a cosine wave.
Frequency is set initially by the argument and can be modified by the left inlet.

Phase can be controlled via the right inlet.

noise~ generates a signal consisting of uniformly distributed random white-noise values

between -1 and 1

sig~ object converts a float or int to a signal. (It also accepts a signal in, which it ignores)

snapshot~ converts signal values to numbers

● signal goes on the left inlet

● a trigger on the left inlet sends the converted value to the outlet
● on the right inlet is possible to set up a sampling interval in ms
● when sampling time is set, turn clock on/off sending start or 1 to left inlet (by default, the
clock will be on if a non-zero interval is supplied on the right inlet)
biquad~ implements a two-pole, two-zero filter specified by 4 coefficients a0, a1, a2, b1, and b2
as signals or floats following the equation:

y(n) = a0*x(n) + a1*x(n-1) + a2*x(n-2) - b1*y(n-1) - b2*y(n-2)

where y(n) is the resulting signal and x(n) the incoming signal at sample n.

● The coefficients are received on the 2nd-5th inlet

● If the filter explodes by making the b coefficients too high, you can recover (after
lowering them) sending the clear message to the left inlet or by turning the audio on and
off)

Experiment with different inputs and values of the different coefficients, that accept also stream
values as in the example above a sinusoidal wave of 25Hz as coefficient a0.

groove~ object is a variable-rate, looping, sample-playback object which references the audio
information stored in a buffer~ object having the same name.
 ● left inlet sets speed playback in, for normal speed send the object sig~ 1.
● the mid inlet sets min loop point in ms
● the right inlet sets max loop point in ms
● sending loop 1 to the left inlet we activate the loop
● send startloop to trigger it

waveform~ object can be used to view and edit the content of a buffer~ object.

We can create a simple patch to visualize an audio file:

play~ object plays an audio file and receives which sample time to play in ms, this is why it is
typically used with line~

sfplay~ object plays audio files (aiff, au, wav and raw of 1-32 tracks). Is possible to send
messages to the left inlet to control the way it works:

● open message opens an audio file from hard disk

 ● sending 1 plays current file from beginning to end
● 2 plays cue 2 if defined and so on...
● 0 stops playing
● to define a cue, send the message preload, the number of cue, the starting point in ms
and the ending point in ms (optional)
● the first outlet is channel 1, the second channel 2 and so on...
● the last outlet is reserved to send bangs, for example when the playback ended
● sending a float to the right inlet sets the playback speed
● the message seek and two values to the left inlet plays current file from one value to
another (values are understood in ms)
● if seek is send only with one value, it plays from that value until the end of the file
Arguments of sfplay~

● (optional sflist~ name)

● channels
● diskbuffer size (0 = default)
● # of position outlets (output position in milliseconds)
● (optional name for sfplay~)
In this example, we cut all the slices of a sound file that are above -25dB, with the preload
message we store them in sfplay~ and play them back randomly.
In coll object we store the data of the different cues, with an index, starting point and end point
both in ms:
In this other example key and scale objects are used to control the playback speed of the audio
file:
avg~ reports the average amplitude of the input signal received when sent a bang

info~ object reports information about a sample named as the argument via 8 outlets when a
bang is received in inlet
sfinfo~ object reports also audio file information, here it is used to retrieve the length of the
audio file and use it to set a delay:
dspstate~ object reports the current DSP settings when a bang is received in its inlet:
mute~ provides an easy way to disable the signal objects in a subpatcher (encapsulated patch
p) by connecting its outlet to the inlet of the patcher and sending a boolean 1 to the inlet:

This is an example of an echo:

pass~ object eliminates noise in a muted subpatcher and should be placed before the outlet as
shown in the subpatcher above.

peek~ object writes sample values received as a list in the inlet. 44100 sample values are
needed to have 1 second buffer at normal speed at sampling rate 44.100KHz
signal operation
filtergraph~ object is a graphical filter editor

*~ object multiplies two signals in the time domain (convolute in frequency domain)
tapin~ and tapout~ objects make a delay, the argument is the delay time in ms

line~ generates a signal ramp or an envelope:

● int/float received in left inlet sets value immediately

● optional argument sets initial value (default 0)
● ramp: initial value plus comma plus a list with pairs of destination values and times in ms
lores~ object is a resonant lowpass filter

● first inlet receives the audio signal

● second inlet receives the low pass cutoff frequency
● third inlet receives the resonance (signal or float)
● first argument: initial low pass cutoff frequency (default 0.)
● second argument: initial resonance (range 0.-1. default 0~.)
comb~ object is an audio filter according to the formula:

y(n) = a*x(n) + b*x(n-(DR/1000)) + c*y(n-(DR/1000))

where x(n) is the original signal and y(n) is the combed signal, we can set up the object with 5
arguments:

● 1st: max delay time in ms (default 10)

● 2nd: initial delay time (controlled by 2nd inlet)
● 3rd: a coefficient (gain - controlled by 3rd inlet)
● 4th: b coefficient (feedforward - controlled by 4th inlet)
● 5th: c coefficient (feedback - controlled by 5th inlet)
● signal input goes to the 1st inlet
As an exercise, try to build a patch similar to the one we presented with biquad~
signal visualization
scope~ object monitors visual progression of a signal waveform:

● the signal goes into the left input

● a number in left inlet changes calccount (buffers per display pixel range 2-8092, default
128)
● a number in right inlet changes samples per buffer (range 8-256, default 128)
● a message to the left inlet with range followed by two numbers, changes the min and
max displayed y value (default -1 to 1)
● a message to the left inlet with delay followed by a number sets delay between each
trace of oscilloscope, in milliseconds (default 0)
To change the colors of the scope, send messages to the left inlet with bgcolor, bordercolor or
fgcolor followed by 4 floats (R, G, B and alpha):

● bgcolor = Background color (above the curve)

● bordercolor = Border color
● fgcolor = Phosphor color
The trigger mode can be set sending a message to the left inlet with trigger and a number that
can be:

● 0 - no trigger mode
● 1 - up trigger mode
● 2 - down trigger mode
X-Y mode is available when both left and right inlet receive a signal patch cord.

meter~ object is a simple signal level meter that can be attached to any signal whose level is
between -1 and 1

● Signals with greater levels should be scaled first

● meter~ outputs graphically the peak signal value received every redrawing interval
● Each "LED" on the meter represents by default a change of 3dB from the previous step
● The red "over" LED comes on if the signal is greater than or equal to 1 and lasts for
about a second
● You can change the redrawing interval sending interval to the inlet followed by the
redrawing interval in ms
● Resizing the meter gives its vertical or horizontal orientation, depending on whether its
height is greater than its width or viceversa
● Additional appearance settings, such as number of LEDs, and their colors can be set
using the object's Inspector
levelmeter~ object shows the RMS level of the incoming signal, it outputs the volume in dB:
minmax~ computes the minimum and the maximum value of a signal. It is useful to check that
the signals we are working with don’t have too much (or too less) gain.

● 2 first outlets output signal values for min and max

● outlets 3 and 4 output float values

number~ object has two different modes:

● Signal Monitor Mode (indicated by a blue tilde) displays the value of the signal received
in the left inlet
● Signal Output Mode (indicated by a blue downward arrow) displays the value of the float
or integer most recently received in the left inlet
● In the Signal Output Mode, you can type directly into the number~ box to store it and the
signal is sent out the left outlet.
● In Signal Output Mode is possible to set a ramp time sending a float to the right inlet.
Then the signal sent goes from the number stored to the received number in the ramp
time specified.
spectroscope~ object provides the visual spectogram or sonogram for signal analysis. The
display mode can be spectogram or sonogram and can be set up from the inspector.

In the spectogram mode shows peaks of amplitude at certain frequencies:

● x axis represents frequency and can be shown in a linear or logarithmic scale

● y axis represents amplitude and can be shown in a linear or logarithmic scale
This default orientation can be changed sending the message orientation 1 to the inlet, so the
frequency would be represented in the y axis.

In the sonogram mode shows frequency vs. time with amplitude displayed as color:

The drawing style of the fonogram can be controled sending the following messages to the inlet:

● scroll 0 forward draw mode

● scroll 1 reverse draw mode
● scroll 2 forward scroll mode
● scroll 3 reverse scroll mode
To change the colors of the sonogram, send messages to the left inlet followed by 4 floats (R,
G, B and alpha):

● bordercolor = Border color

● curvecolor = Curve color
● markercolor = Marker color
● peakcolor = Peak color
● peakcurvecolor = Peak curve color
● sonolocolor = Sonogram color (low)
● sonomedlocolor = Sonogram color (medium low)
● sonomedcolor = Sonogram color (medium)
● sonomdehicolor = Sonogram color (mediumhi)
● sonohicolor = Sonogram color (high)
Here are the basic ways to visualize a wave:
video signals (jitter objects)
jit.qt.movie object play and edit a quicktime movie

● read message allows to play a file we choose from the hard disk
● stop message stops the movie
● sending a bang outputs a frame of the movie
● to control the volume of the audio, send vol message with a float between 0. and 1.
Once a movie file is opened, you can hear the audio, that is being played externally by
Quicktime.

imovie object plays a QuickTime movie in a patcher window. With an unlocked patcher, drag
and drop a moviefile from the File Browser or use the imove object's Inspector to read in or
change the movie file. The name of the last file used is saved in the patcher.

playbar object is a QuickTime movie controller. Just connect it to a imovie object and ry to
play, pause a video:
spigot~ object lets you use the audio of a movie internally in MSP.

● spigot~ object always needs its own name set by the name argument
● spigot~ object work~s with a sound file, exported and cached from a movie loaded in the
jit.qt.movie object
● this audio file is played in sync with the movie
● to activate it, send the message soc followed by the name of spigot’s object to the inlet
of jit.qt.movie
● send the message soc alone to detach from spigot~
● the two outlets carry the 2 audio channels of the movie
jit.pwindow object allows to preview a movie in a resizable screen inside the patch

jit.window object creates in Max an external window to the patch to see the incoming movie
jit.qt.grab object from Jitter that digitizes video from an external source, for example a firewall
videocamera or a webcam:
jit.rota object scales and rotates a video signal
jit.rgb2luma object converts a RGB color video into grayscale

jit.change is an object particularly useful for reducing the density of dataflow and for motion
tracking applications. Only pass the next frame if the difference of the current matrix with the
upcoming matrix is less than a certain threshold (computed per cell, not per plane).

jit.op @op absdiff computes the difference between the video matrices received in inlet 2 and
inlet 1
jit.iter object returns coordinates (2nd outlet) and values (1st outlet) of a given matrix
jit.3m object reports the minimum, mean, and maximum pixel values for each plane (Alpha, R,
G, B) of a given input matrix as lists of size planecount, one value for each plane.

● the list of minimum values are sent out the left outlet of the object
● the list of mean values are sent out the middle outlet
● the list of maximum values is sent out the right outlet
jit.vcr records a video/audio signal, inlets 1 and 2 are to receive the audio and the 3rd inlet is to
receive the video signal.

● write message to the first inlet shows up a dialog to save the resultant file in your hard
disk
● stop message to the first inlet stops the recording
jit.matrixset object keeps a set of internal matrices which may be written to or read from. This
is useful for data storage and/or matrix resequencing.

● arguments: number of matrices stored, planes (4 for RGBA), type (default char),
dimensions (list in pixels e.g. 1024 768)
● to store the matrix an index is used, send a message with index and a number to store in
that index the next frame (data in matrices)
● index must be in the range set by the first argument
jit.matrix allows to storage and retrieve video frames stores in matrices