practical starting guide to max/msp/jitter

bodsiin htarva project

foreword and methodological approachIt 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 scratchb. 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 lettersb. messages are written in italicc. images should contain every detail you need to build the patch, if not ask us to

change it5. you: this is the important part, as this method requires probably a lot of interest in Max

from your side and some faith leaps6. not complete: sorry, but we do not have enough resources, this is only a selective bite to

the huge Max cakeThe 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 shortcutsHere 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 second2. 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 + hOther 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 browserWhen 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 attributesWhen 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 rateMost 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 inletdate 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 argument3. Create an autopattr object4. Connect the left outlet of autopattr to the inlets of every interface object you want to

rememberTo 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 storedmultislider 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 inletjit.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 argument2. 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 Inspectorlevelmeter~ 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 recordingjit.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 argumentjit.matrix allows to storage and retrieve video frames stores in matrices