MaxMSP is a visual programming language that helps you build complex, interactive programs without any prior experience writing code.  MaxMSP is especially useful for building audio, MIDI, video, and graphics applications where user interaction is needed.  This Instructable is part of a 3-part workshop I'm running at Women's Audio Mission, it's part one of three Instructables that I'll be publishing over the course of the next week.  (Part 2 - intermediate MaxMSP) (Part 3 - getting Max to talk to hardware)

MaxMSP is split into several parts - "Max" handles discrete operations and MIDI, this is the easiest place to start getting familiar with the tool.  "MSP" deals with signal processing and audio.  And "Jitter" is for graphics rendering and video manipulation.  This course will cover Max and MSP.

Here are some examples of awesome things you can do with Max.  My favorite Max applications are the ones that incorporate some kind of hardware interface.  There's tons of way to do this, here are a few:

ReacTIVision is a free, open source tool that communicates with MaxMSP and allows you to track objects with a camera by printing out and attaching small paper markers on them.  The software tracks x and y position and rotation and it's great for incorporating real world objects into your MaxMSP patch and making table top interfaces.  It was originally written for the ReacTable, a table top multitouch instrument:

Some examples of ReacTIVision and MaxMSP:

An interactive dining table (by my friend Evan!):

Table Top mixer:

Interactive structure:

Chain reaction arpeggiator (I don't think this actually used reacTIVision, but it could):

The XBox Kinect is a hackable depth sensing camera and gesture tracking device.  Data from the Kinect can be imported into MaxMSP through an application called Synapse.  Synapse allows you to track x, y, and z coordinates of each major joint of the body (head, elbow, hand, knee, etc).  Here are some cool projects that use Max and the Kinect:

Gestural instrument/Composition

Little Boxes: interactive installation

Arduino is a tiny computer that can be programmed to control circuits in all kinds of crazy-cool projects.  With the addition of Arduino, it's possible to extend your MaxMSP patches into the physical world.  There are a lot of ways to get Arduino and Max to talk (I will definitely be writing an Instructable about this in the future), including MIDI, Serial, and any of the options listed on the Arduino website.  Some options (like Arduino2Max) allow you to read directly from the Arduino pins, and others rely on USB communication.    Here are some examples of projects that use a combination of MaxMSP and Arduino to facilitate unique physical interactions:

Robotic Drum Kit

Noisy Jelly - Tangible Jelly synthesizer interface

Musical Iron:

Fine Collection of Curious Sound Objects (this actually uses Processing instead of Max, but it could be done with Max)

Underwater - A realtime visualization of ocean data

There is a third type of MaxMSP object that I won't have time to get into here, but once you've got Max and MSP down you should check out Jitter.  Jitter lets you manage video and graphics inside Max, so you can import data from a camera or create realtime visuals for your app.

Dyskograf - a drawing based sequencer:

Audio Interface with realtime video output

Interactive projection mapping

The MaKey MaKey is a usb device that you can clip to anything conductive to transform that thing into an interface.  Essentially what it does is trick your computer into thinking that it is an external keyboard, then the things you clip to it become keys.  You can read these commands using the "key" object in max, no external software required.  This one is super easy and fun!

Vegetable Instruments:

One last note: Pure Data is essentially the free, open source version of Max.  The main ideas and most of the objects are nearly identical, though I've found that I prefer Max's interface a little better.  But if you don't have the funds to shell out for a copy of Max, Pure Data is an excellent option.

Step 1: Example Projects - Max and MIDI

Chopin: as you play piano, the patch listens to what you're playing and plays an accompaniment:

Harmonic Table Sequencer: a 2D spatial sequencer based on the harmonic table

Visual Arpeggiator

Generative physics sequencer:

Polyrhythmic sequencer

Tree Ring Music Player


Step 2: Getting Started With MaxMSP

Documents in MaxMSP (I will be referring to it as "Max" going forward) are called "patchers", but you'll hear a lot of people refer to them as "patches".  To create a new patch, go to File>>New Patcher (Command+N / Ctrl+N).  Be sure you are running MaxMSP and not Max Runtime, the Runtime version will not allow you to edit patches.

Max patches are composed of many "objects" that at wired together.  To create an object, put your cursor over the blank patch and press the n key.  You will see an oval appear, this is where you tell Max what type of object you want to create.  One of the most simple objects is the button object, create a button object by typing "button" into the blank oval object you have just created and hit enter.  You can also find the button object on the right menu under the header "Basic" and drag it into the patch.

Objects in Max can be resized by dragging the bottom right corner.  Move an object by selecting it and dragging it around the patch.  Copy an object by holding down option and dragging, then place your copy somewhere in the patch.

Now you should have two button objects.  Connect the objects by clicking the "outlet" (the dark grey box on the bottom left) of the top button and dragging your mouse over the the "inlet" (the dark grey box on the top left) of the bottom button.  This action will create a patch cable between the two objects.

To interact with these objects, put your patch into lock mode by clicking the lock icon in the bottom left corner of the window (Command+E / Ctrl+E).  Now click on the top button, you will see it light up and also cause the bottom button to light up.  When a button is clicked, it lights up and sends a message called a "bang" out its outlet.  When a button receives a bang, it lights up and passes the bang through its outlet.  

Notice how clicking the top button causes the bottom button to light up, but pressing the bottom button does not cause the top button to light up.  In Max, information flows into inlets and out outlets of objects, so each connection is a one way street where messages can pass between objects.

Step 3: Your First Max Patch

Put your patch back into edit mode by click the lock icon in the bottom left corner of the window (Command+E / Ctrl+E).  Create a counter object by creating a new object (N key) and writing "counter" in the oval, or selecting it from the right menu under the "Control" header.  The counter object increments its count by one every time it receives a bang.  To set the limits that the counter object will count to, add the numbers 1 and 3 to the object.  Now the counter starts at one and counts up to 3 each time it receives a bang.  When it reaches 3 it starts over again at 1.

Mouse over each of the inlets and outlets of the counter object to see what they do.  The top left inlet of the counter receives bang messages, wire the button's outlet to this inlet.  The bottom left outlet outputs the current count.  Create a "number" object and wire its top left inlet to the counter's outlet.  Now put the patch back into lock mode and click on the button to see the counter in action.

Now let's hook the button up to a "random" object.  By sending a bang to a random object, it will generate a random number within a specified range and output that number out its outlet.  Lets set the range to 50 and wire the output from the random object to a second number object.  Put the patch back in lock mode to see the random object output numbers between 0 and 49 each time the button is pressed.  Since the counter object is still wired up, it should still be working as it was before random was added.

Next we'll add some sound with MIDI.  MIDI is a language that computer software, controllers, digital synthesizers use to communicate with each other.  The types of messages they send to each other are things like "note on", "note off", "channel", and "pitchbend".  

To create MIDI notes, add a "makenote" object to your patch.  Add the arguments 100 and 300 to the object to set the default values of velocity(100) and duration(300).  In MIDI, the loudness of a note is communicated through a message called "velocity".  This term originates from one of the first MIDI instruments: the electronic keyboard.  As keyboards became more advanced, they started to be manufactured with sensors in each key that detected how quickly the key was struck: the key's velocity.  This value was incorporated into MIDI protocol to allow the performer to control the volume (and sometimes even the timbre) of a note by varying the speed of their keystrokes, much in the way an acoustic piano works.  Duration is exactly what you would expect, it's the amount of time that passes before the makenote object sends a note off message to turn off the note.  Duration is measured in milliseconds (where 1000ms = 1 second), we'll stick with 300ms for now.

Now we need to tell the makenote object which note we want it to make.  Notes in MIDI are set with a number that ranges from 0 to 127, where 60 is middle C (C3).  Create a number object and wire it up to the pitch input of the makenote object.  It's nice to change the settings on this number object so that it tells us which MIDI note it corresponds to, rather than displaying a number between 0 and 127.  In Max you can use the Inspector to change the way an object looks or behaves; access the Inspector by selecting an object and clicking on the inspector tab in the right menu, or by right clicking on an object and selecting inspector.  Open the Inspector for the number object and select MIDI from the Display Format menu (if you don't see it, be sure you have All selected in the filter settings at the top of the Inspector).  Wire up the number between the button and the left inlet of makenote.

MIDI notes do not make sounds by themselves.  They need to be interpreted by a MIDI synthesizer to output audio.  You can build something like this in Max, or you could route the MIDI into another program like Ableton, you could even send the MIDI to a real instrument, but for now let's just use the default MIDI synth that comes installed with your operating system.  First create a "noteout" object to send your MIDI messages out of Max.  Notice that the outlets of the makenote object are labeled pitch output and velocity output, wire these up to the corresponding inlets on the noteout object.  Put the patch in locked mode and double click on the noteout object to select where the MIDI will be routed to.  The default synth on Mac is called AU DLS Synth, and on Windows it is called MS GS Wavetable Synth, select either of these from the dropdown menu.  Now click on the button to send MIDI notes, if you can't hear anything, make sure your computer's volume is on and set the MIDI note to something reasonable like C4 (do this by clicking and dragging up or down on the number object).

Step 4: Your First Max Patch Part 2

Next we'll string these concepts together to make something a little more interesting.  Create a "select" object and add the arguments 1 2 and 3. The select object receives message through its left inlet and sorts them out a variety of outputs.  This select object will output a bang from its leftmost outlet when it receives a 1 message, the next outlet will bang when it receives a 2, and a third outlet from the left will bang when it receives a 3.  If we wire this up to the outlet from the counter, the select will bang out one outlet, then the next, then the next, and repeat over and over.

Copy the MIDI part of the patch two times (select the parts you want to copy and press alt or option + drag) and connect the number objects to the select outlets.  Change the value of the number objects to output three distinct notes (I set mine up to create a C4 Major Chord).  Now lock the patch and try it out, you should hear the patch cycle through each note.

Set the notes to play on a timer by adding a "metro" object and connecting its outlet to the button inlet.  The metro outputs a bang at a specified time interval.  ​I added the argument 300 so that the metro outputs a bang every 300ms.  Add a "toggle" to the left inlet of the metro (the shortcut to creating a toggle is pressing the "t" button) - this will act as an on/off switch.  Lock and patch and press the toggle to hear the metro trigger MIDI notes.

Clean the patch up a little by deleting the two extraneous makenote and noteout objects, we can send all the pitch values coming from the number object into the same makenote/noteout chain.  I also added a number object to the right inlet of the metro, so that I could override its default argument and change the tempo of the patch.  Put the patch in lock mode, click the toggle, and change the number object to hear its effect on the tempo.

A "kslider" is a virtual keyboard that you can stick in your Max patches.  It outputs the MIDI note number from its left outlet and the velocity (which is controlled by clicking on a key at different heights) out the right outlet.  We're going to wire the kslider up so that we can set the notes in the arpeggio.

In order to keep the relationship between the three notes in my patch a major chord, I added 4 and 7 to the output of the kslider.  (The second note in a major chord is 4 semitones above the base note, and the third note is seven semitones above the base note.)  Wire these up to the number objects that are sending note messages to makenote.  Then start he metronome and see what happens when you click keys on the kslider.

We can even wire up the velocity output from the kslider to the velocity input from makenote to override the default value of 100 that we set earlier.  Try clicking on the top and bottom of the keys in kslider to hear the difference.

Next use the random number generator to send the base note of these major chords.  To keep this a little more listenable, I changed the random range to 20 and added 50 to the output, so the number generated is always between 50 and 69.  Now start the patch and see what happens when you click the button attached to random.  What happens if you connect the output from the metronome to the random button?

Throughout this Instructable I'll be posting my patches in two formats.  The first is shown below, it's a condensed code format that's really easy to work with.  To use it, copy the code below onto your clipboard.  Then in Max go to File>>New From Clipboard and the patch should appear.  You can also paste the code into any existing patch.  To generate this compressed code from your own patch, select the things you want to copy and go to Edit>>Copy Compressed.  I'll also attach .maxpat files to this Instructable, download the final patch from this step in the attached file (below the compressed code).

Step 5: MaxMSP Help Files

As you continue to use Max, you will need to use the Help Files to learn about objects that you're not familiar with.  Create a "metro" object in your patcher, right click and select "Open metro Help" in the menu (or option/alt + click).  This will open a help window that gives an explanation of the object and some examples of how to use it with other objects.  The great thing about Max help files is that they are interactive, so you can actually try things out and even copy the examples straight into your own patch.

You can also select the Reference tab from the right menu of your patch to learn about the arguments and messages that an object accept, and find a list of object with similar functionality.

Step 6: Setting Up a MIDI Controller With Your Computer

Max receives incoming MIDI messages with the "notein" object.  Create a new patcher (Command+N / Ctrl+N) and put a "notein" object inside it.  Connect one "number" object to each of its three outputs.

In order to send MIDI into Max, you will need to connect some kind of MIDI controller to it.  You can do this one of two ways:

Hardware - If you have a midi keyboard or other MIDI controller available, find a way to plug it into your computer's usb port (you may need to get a MIDI to usb adapter).  To connect to Max, put your patch in locked mode (click on the lock icon in the bottom left hand corner of the window or Command+E / Ctrl+E) and double click on the notein object.  You will see a dropdown list of all the available MIDI ports.  Select your controller from the list, if you do not see it listed, consider using a software controller instead.

Software - There are many free programs that allow you to use the keys on your computer as a MIDI keyboard.  A great, cross-platform solution is the Virtual MIDI Piano Keyboard. Download and run the program.   Press the bottom two rows of keys on your keyboard and notice how they activate the keys on the virtual keyboard.  To connect to Max, put your patch in locked mode (click on the lock icon in the bottom left hand corner of the screen or cmd+E/control+E) and double click on the notein object.  You will see a dropdown list of all the available MIDI ports.  Select "to MaxMSP 1" from the list.  Then go to the virtual keyboard and select Edit>>MIDI Connections.  In the MIDI output field, select "to MaxMSP 1".  Please note - I have only tried this on Mac, if you have trouble getting this up and running on Windows you may need to install something like MIDI Yoke.

Now that you have everything hooked up, play a key.  You should see numbers come out of the notein object in Max.

Step 7: MaxMSP and MIDI

Add a button to one of the outlets of the notein object so you can see when messages are sent.  Play the keyboard and watch the output in Max.  You'll notice that a message is sent each time a key is pressed and each time a key is released.

The messages sent when a key is pressed are called "note on" messages.  Each of these messages returns a pitch, velocity, and channel.  As I said before, pitch returns a value between 0 and 127, where pitch = 60 corresponds to C3 (in the third octave), pitch = 61 corresponds to C#3, etc.  Attach another number object to this outlet and set it to display in MIDI to see the pitch.  Each note on message also contains a non-zero velocity.  If you have a velocity sensitive keyboard connected to Max, try pressing on the key with different amounts of pressure to see how it affects velocity.  The maximum value of velocity is 127.

The messages sent when a key is released are called "note off" messages.  Note off messages also have pitch and velocity.  The pitch corresponds to the note that is being turned off.  The velocity of a note off message always equals 0.  In fact, every time you set the velocity of a note to 0 with MIDI, you are sending a note off message.

Let's take a closer look at the makenote object from the last example.  Wire up the makenote outlets to two number objects and also connect a button object to a makenote outlet so you can see when messages are sent.  Set the makenote's arguments to velocity = 100 and duration = 1000ms (1 second) and wire up a message with the number 60 to the makenote pitch inlet (message objects are buttons that send any message out their outlet when pressed, create a message object by pressing the "m" key).  

Now press the 60 message to create a MIDI note. You should see the button light up twice, once for a note on message with pitch = 60 and velocity = 100 and a note off message a second later with pitch = 60 and velocity = 0.  Wire up a noteout object and listen to the note as you watch the MIDI messages in Max.

Create a "slider" object and wire it up to the velocity inlet of the makenote object.  Now try adjusting the slider and see how it affects the MIDI messages and the sound.

We can also create MIDI messages without a makenote object.  Create the following 3 message objects: 60, 127, and 0.  Wire up the 127 and 0 messages to the velocity inlet of a noteout object.  Connect the 60 message to the pitch inlet of the noteout object.  Then create two buttons, one will send note on messages and the other will send note off messages.  Connect the outlet of the note on button so that it triggers the 60 and 127 messages and sends them to noteout.  Then wire the outlet of the note off button so that it triggers the 60 and 0 messages and sends them to noteout.  Try out the patch, experiment with it and see what happens when you change the values of the message objects.

Finally, you can wire up a noteout object to the numbers connected to notein.  Press the keys on your external keyboard, you should hear the notes patched through into your computer's software synth.

Step 8: The Interval Harmonizer

The interval harmonizer is a patch that outputs a chord for every MIDI note that comes into Max.  Start with the simple MIDI out patch from the last step.  Add a + object and add a small, whole number to the pitch output from notein.  Then send this transposed number out noteout.  Do this several more times to add more notes to your chord, be sure to transpose the base note by different increments.

My interval harmonizer adds 4, 7, and 12 to the base note to create a 4 note chord.

Step 9: Arpeggiated Chord

Starting with the interval harmonizer from the last step, delete the connections between the extra notes and the noteout pitch inlet.  Only the base note should stay connected, so pressing a key on your keyboard only results in one note played.

The "pipe" object is a type of delay that keeps track of more than one message at a time.  By sending the note and velocity of a MIDI message to a pipe object, we can delay the note by a specifies time interval.  To tell the pipe object how many messages we want to store at a time, we use arguments.  Type the placeholders 0 and 0 after the word pipe so that the pipe knows to store two messages, then type the duration of the delay (I used 300ms).  The pipe object creates two inlets and two outlets, one for each message to be stored.  Wire up the second note from the interval harmonizer to the left inlet of pipe and the velocity from notein to the second message inlet on pipe.

Now press a key on the keyboard, you should hear the second note a moment after the first is played.  Follow this same pattern for the remaining notes from the interval harmonizer.  You will have to set the delay time for the third and fourth notes to be longer than you did for the second note.


Step 10: Messages, Hot/Cold Inlets

Let's take a closer look at the message object.  Create a message object by pressing the "m" key and typing your message into the oval.  Messages can be anything: numbers, words, sentences, lists, etc.  Create a message with your name in it and connect the output to a "print" object.  Lock the patch and click the Max tab of the right menu.  Click the message, it will send whatever's inside it to the print object, which will print the message in the Max Window.  The print object is really useful when you're trying to solve a problem in your patch.

You may have already noticed that some other objects are useful for debugging patches: buttons, toggles, number objects all give you feedback about what messages are being sent between objects.  The message object can be used in a similar way.  Create a blank message object and wire up the right inlet of the new object to the outlet of the name message.  Now lock the patch and click the name message.  Since the print object is still wired to the message you just pressed, you should see a second print of your name in the Max Window, you should also see your name inside the second message.  So by sending messages in the right inlet of a message object, you can set the message object to whatever you want.

Disconnect the print object from the first message and connect it to the outlet of the second (downstream) message object.  Now click the top message object again.  You should not see any additional prints of your name in the Max Window.  In Max, every inlet and outlet has a Hot and Cold designation.  You can tell whether an inlet/outlet is hot or cold by mousing over it and noticing the color of the circle that highlights it - either red or blue.  When a message or a bang is sent to a hot inlet, it causes the object to evaluate the message and send something out at least one of its outlets.  When a message is sent to a cold inlet, the object evaluated the message, but it will not cause output.

Wire up a button to the left inlet of the downstream message object.  Click it and see how the message stored in the object is printed in the Max Window.  Try attaching other objects to the left inlet of the message object: a number, a "slider".  They will all change the content of the message object, but not cause output.  If you hook them up to the left inlet of the message object you'll see that they cause the message to output, but they do not change the message.

There is one exception to this, mousing over the left inlet of a message object tells you "set change the message", create a message called "set 4.67" and wire it up to the left inlet of another message object.  Click on set 4.67 and see that it changes the value of the message, but it does not cause it to output the value 4.67.
Using this knowledge, we can go back and make the "Your First Max Patch" even better.  The way it was set up before, when a new set of notes was selected, the pitches were sent to the hot inlets of 3 number objects, which caused the pitches to be sent into the makenote object immediately.  So each time a new set of notes was selected, the patch output a three note chord immediately, and then started arpeggiating.

Instead, we can set the new pitches of these notes without disrupting the arpeggio, using the concept of cold inlets.  Since number objects only have one inlet, we have to replace them with message objects.  Replace all three number objects connected between the select and makenote objects in the patch with messages.  Then wire the three outputs from the random chord generator to the cold inlets of the messages.  The transistions will sound much more smooth after these changes.

Step 11: Optional Arguments

You've probably noticed the way arguments are being added to many Max objects in these examples patches, let's take a closer look.  Wire a "5" message, a "+", and a "number" together.  Click on the message to see that by default the + object adds 0 to whatever number comes through its hot inlet.  Create a "3" message and connect it to the cold + inlet.  Click on the 3 and then click on the 5 to evaluate, now the + will add 3 to whatever comes into its hot inlet.

Now create a + object with an argument of 4, by default this object will add 4 to whatever comes into its hot inlet.  Check to see that this is true by sending a "5" message to the + object.  You can override this argument by sending a number into the cold inlet.


Step 12: MaxMSP Inspector

I want to plug the Inspector one more time now that we've looked at a few more objects in Max.  We saw earlier that the Inspector let us change the number object so that it displayed MIDI notes in standard alphabetic form rather than as a number between 0 and 127.  Let's take a look at what else we can change.

Create a slider object and number object and connect the output from the slider to the input of the number.  Go to lock mode and drag the slider around, by default it ranges from 0-127.  Go back to edit, select the slider, and click on the Inspector tab in the right menu.

Like all Max objects, you can change the size (patching/presentation rectangle) and color of the slider.  The slider also has some unique options, including orientation, range, minimum, and multiplier.  Right now minimum is set to 0 and range is set to 128, this is what sets the minimum and maximum limits of the slider.  Multiplier is set to 1, meaning the slider will output any increment of 1 between 0 and 127, by changing this to 2, the slider will only output even values between 0 and 127.  Try changing some of the options in the Inspector and see how it affects the behavior/appearance of the slider.  (If you don't see all these options in the Inspector, make sure you have All selected in the filters at the top of the menu).

Step 13: Assignment

Create a MIDI patch that uses at least one object not covered in this Instructable.  Use the Max help files (option + click) to learn about what kinds of messages you can send to the object, what arguments it takes, and how to use it.  Some good ones to try are:

delay - delay a bang for a specified period of time

bendin / bendout - just like notein and noteout, but this object can receive pitchbend information from your keyboard, or send it out to a synth.  Hint: you need a keyboard with a pitch wheel to get this bendin to work, and some programs will not do anything with outgoing pitchbend information.  This will work with the Mac default synth (AU DLS Synth), but I'm not sure about Windows.

midiin and midiout - similar to notein and noteout, but generalized for all types of MIDI messages - note on/off, pitchbend, aftertouch, continuous controller...  Same caveats apply to these objects that apply to bendin/bendout.  You will also have to learn a bit about MIDI protocol to get this to work.

route - sort incoming data out multiple channels

pictslider - an x/y slider on top of a photo

Any of the Math objects that we didn't see yet (-/*sqrtsincos)

drunk - random number generator that does a drunk walk around its current value, instead of picking numbers completely at random.

send and receive - wireless patching, very useful for organizing a patch with lots of connections

gate - enable and disable paths

preset - save preset values of numbers, sliders, toggles, and other objects in your patch

timer - count time between two events

switch - select from multiple inputs

matrixctrl - a grid UI, great for creating sequencers and other grid based applications

key - receives key pressed from the keyboard and returns ASCII values, use in combination with "select" to listen for specific key presses.

seq - save the MIDI output from your patch into a MIDI file, also reads from MIDI files

split - check to see if an input falls within a specified range

flonum - numbers with decimals

if - if this then that

patcher - create a patch within a patch, make many copies of a repeating part of your patch, or tidy up.  Use with inlet and outlet.

Keep reading on to Part 2: Intermediate MaxMSP
<p>Excel Software makes tools to protect, license and sell any kind of software application including MAX MSP. See http://www.excelsoftware.com/max</p>
<p>Thank you, step by step and useful pics. </p>
Superb guide.
This is a fantastic resource Amanda! Really well done and SO appreciated. THANK YOU!
oh wow this is an awesome post Amanda. Looking forward to more! ;) Thank you
<3 thank you.

About This Instructable




Bio: I'm a grad student at the Center for Bits and Atoms at MIT Media Lab. Before that I worked at Instructables, writing code for ... More »
More by amandaghassaei:OTCA Metapixel - Conway's Game of Life "9 Degrees of Freedom" IMU Twitter Controlled Pet Feeder 
Add instructable to: