Cycling '74 Max Tutorial
Reviewed most recently in the October 2008 issue and a 2009 Editors' Choice Award winner, Cycling '74's Max (Mac/Win) is an extremely versatile programming application that lets you do things like build VST plug-ins, control the playback of 20 MIDI sequencers at multiple tempos from your computer keyboard, and much more. In conjunction with companion programs MSP and Jitter, Max integrates MIDI, digital audio, and video into one environment so that audio data can control MIDI, MIDI can control video, and video can control MIDI and audio. There are endless creative possibilities.
Advanced Max patches can be very complex, but getting started is easier than you may think. In this article, I'll help you build a Max patch that controls multiple MIDI sequencers and others that show you how to use sample playback with simple audio processing. You will be able to adapt and extend these examples, and with additional examples that are posted online, you will have enough to get started.
Before you begin, download a free 30-day demo version of Max 5 from cycling74.com/downloads/max5. Having the demo open while you read will make the job much easier. Also, I have provided Web Clips in the form of Max patches for each graphic in this article. Fig. 1 goes with Web Clip 1 and so on.
The Max package includes three applications: Max, which is focused on MIDI; MSP, which works with digital audio; and Jitter, which manipulates video and 3-D animation. In all cases, tasks are carried out by Objects — the basic building blocks in Max. Objects are small chunks of software that execute simple tasks such as generating, modifying, storing, or routing data. In Max, Objects are represented by icons; some icons have associated text and numbers, while others do not.
Objects are connected using virtual patch cords. Each connected Object performs a specific job and sends the results to the next Object in the chain. Only a few types of messages are sent between Objects: numbers, words, pairs or groups of numbers or words, and messages called Bangs. A Bang message is a “do it” message that can be sent to many different Objects; it causes an Object to do whatever it does. The result of these connections is a software program called a Max patch.
You construct a Max patch in the Patcher window. To place Objects in a Patcher window, simply double-click in the window, and a transparent, resizable window called the Palette appears. The Palette is Max's visual catalog of Objects; it provides an easy way to select Objects for your patch. When you place your mouse over a Palette icon, the name of the Object is shown.
The icon positioned in the upper left corner of the Palette is different from the other icons. It is called the Object box, and text that defines the Object's function is typed in there. The first word typed into the Object box is the specific name of the Object. The numbers that follow the name of the Object are called Arguments. Arguments specify how an Object will function. There may be more than one Argument, and sometimes the Argument may be a word. For instance, the Argument “120” in the metro Object specifies that every 120 ms, a Bang message will be output. The Argument “88” in the random Object specifies that all numbers output will be between 0 and 87 (a range of 88).
In our example patches, the bottoms of Objects are connected to the tops of other Objects with virtual patch cords. Inlets, where data enters an Object, are at the top of the Object; outlets, where data leaves an Object, are at the bottom. If you place your mouse directly over an Object's inlet or outlet, pop-up help appears, telling you what that particular inlet or outlet is related to. You connect Objects by clicking on an outlet, then connecting the resulting line to an inlet.
Once Objects are placed in a Patcher window, they can be freely dragged into new positions within the window. You can also use the Cut, Copy, Paste, and Duplicate commands, so it's easy to turn one sequencer into 20.
Digital audio is handled a bit differently in Max. To begin with, yellow-and-black patch cords are used to represent audio signals, helping you to visualize the difference between audio signals and MIDI and control messages. In addition, Objects that end with a tilde (~) are audio based. Be sure to check out the tips and shortcuts under the Help menu.
Whole Lotta Sequencers Goin' On
The first example patch will allow you to play multiple MIDI files triggered from your computer keyboard. Launch Max, then select New Patcher from the File menu. This will bring up a new, unlocked window called Untitled1. Double-click in this window, and you'll see the Palette.
Single-click on the Object box (far left, top) in the Palette and type the letter K. All Object names beginning with the letter K will appear in a menu. Double-click on the key Object, then click again in the white area, and you'll see the key Object appear in the Patcher.
Go back to the Palette, and this time choose the select Object using the same technique that you used to create the key Object. (You may have to scroll in the menu to find the select Object.) Connect the far left outlet of the key Object to the left inlet of the select Object.
Starting an Argument
The job of the select Object is to watch for incoming values that match its Arguments, and when there is a match, to send out a Bang from one of its four outlets. We'll supply the Arguments next.
Click in the select Object (directly after the word “select”) and type:
FIG. 1: The early stages of a Max patch that plays back Standard MIDI Files under control of a computer keyboard.
113 119 101
Leave a space between the word “select” and the first Argument, and note that there should be a space between the numbers. When the select Object receives a value of 113, a Bang will be sent from the select Object's left outlet. Receiving a 119 will trigger a Bang from the select Object's left-center outlet, and a value of 101 will trigger a Bang from the right-center outlet. Now use the Save As … option under the File menu to save your work.
It Toggles the Mind
Next, choose the toggle Object from the Palette by double-clicking in the white area in the Patcher window to bring up the Palette, single-clicking on the toggle Object in the Palette (fifth Object from left, top row), and clicking again in the white area. When you click on the toggle, it functions like a light switch, alternating between 0 and 1 states. If you send the toggle Object a Bang message, it changes state: off to on or on to off.
Create a metro Object using the technique that you used to create the key Object. The metro Object outputs Bang messages at a specified rate that is defined by the Object's Argument.
Add the Argument 20.83 to the metro Object. Drag the toggle Object so that it is below the select Object, and then drag the metro Object so that it is below the toggle Object. Connect the left outlet of the select Object to the inlet of the toggle Object, and the outlet of the toggle Object to the left inlet of the metro Object. You should now have four Objects connected together (key to select to toggle to metro). For clarity in your design, you should organize your Max patch so that data flows downward.
Next, create the seq, the midiflush, and the midiout Objects using the same technique that you used to create the key Object. Drag the midiflush Object to a location under the seq Object, and drag the midiout Object below the midiflush Object. Finally, connect the left outlet of the seq Object to the inlet of the midiflush Object, and the outlet of midiflush to the inlet of midiout.
The seq Object is a MIDI sequencer that plays back Type 0 Standard MIDI Files (SMFs). The midiout Object receives MIDI data from the seq Object. Double-clicking on the midiout Object lets you call up a menu from which you can choose a physical or virtual synthesizer to play the MIDI sequencer data.
Because this patch lets you stop playing an SMF at any point in the file, the likelihood of losing Note Off messages is high. That's why we placed the midiflush Object in between the seq and midiout Objects. The midiflush Object keeps track of all Note On and Note Off messages sent to the midiout Object. When the midiflush Object receives a Bang, it sends Note Off messages for all notes that have received Note On (but not Note Off) messages. Add the button Object (fourth Object from left, top row) to your patch using the same technique that you used to create the toggle Object. The patch should look similar to Fig. 1.
You need a way to load SMFs into the seq Object, and there are several possibilities. If you type in the name of an SMF as an Argument in the seq Object, that MIDI file will be loaded automatically when the Max patch is opened — provided that it is in the same folder as the patch.
Alternatively, by clicking on a message box with a “read” message in it, you can recall the standard Open Document dialog box so that stored MIDI sequences can be loaded into the seq Object. To do this, double-click in the white area in the Patcher window to bring up the Palette, single-click on the message box Object in the Palette (second Object from left, top row), type the word read, click in the white area again, and connect the outlet of the message box Object to the inlet of the seq Object.
FIG. 2: The same patch as in Fig. 1, but with tempo control added.
Max can control the tempo of the seq Object in real time by sending it “tick” messages at varying rates. To use this method, create a message box Object with the word tick in it and place it between the metro and seq Objects. Next, connect the outlet of the metro Object to the inlet of the message box (with the tick message), and connect the outlet of the message box to the inlet of the seq Object. By sending the seq Object tick messages rapidly, you play the sequence rapidly; by sending tick messages more slowly, you play the sequence more slowly.
To make the seq Object respond to tick messages, you must first send it the “start -1” message before you begin playing back the sequence. To deliver the start -1 message automatically each time you start a sequence playing, create a message box Object that contains the message start -1, position it to the right of the read message box, and connect it to the seq Object. Directly above the start -1 message box, place a new select Object and put in the Argument 1. Connect the left outlet of the select Object to the left inlet of the start -1 message box, and connect the toggle Object to the left inlet of the select Object. Every time the toggle Object is turned on, it outputs a 1; that 1 is sent to the select Object, which responds by sending out a Bang to the start -1 message box, which sends out the message “start -1” to the seq Object. Concurrently, the 1 from the toggle Object is sent to the metro Object so that it will start Banging out tick messages at the rate of one every 20.83 ms.
Finally, you'll want to add real-time tempo control to your seq Object. Hitting the F key is a shortcut for creating a floating-point number box. Hit F to create a number box that you will use to control the tempo. Position the number box above the metro Object and to the right of the toggle Object. Then connect the outlet of the number box to the right inlet of the metro Object. You can now change the playback rate of the seq Object by scrolling with your mouse in this number box. The value 20.83 will yield the sequence at its normal rate, 10.415 will cause the playback to be twice as fast, and 41.66 will cause it to be half as fast.
Your patch should look like Fig. 2. Save your work.
Once Is Not Enough
In its current state, your patch allows you to read SMFs into a seq Object, to start and stop playback of this seq Object by pressing Q on the computer keyboard (the Q key results in the output of 113 from the key Object), and to control the tempo with your mouse. The final step is to create two more copies of the sequencer mechanism and connect these copies to two of the outlets of the select Object.
FIG. 3: Here''s a completed Max patch that plays back three Standard MIDI Files under control of a computer keyboard, with tempo control for all three seq Objects.
Start by selecting all the Objects from toggle down through midiout by clicking-and-dragging your mouse across the area where those Objects are positioned. Next, choose the Duplicate command under the Edit menu. The resulting copy will already be selected, so drag it carefully to the right so that it does not overlap the original. Now connect the left-center outlet of the upper select Object to the toggle Object of this copied sequencer.
Make another copy in the same manner and connect this copy to the right-center outlet of the upper select Object. If you want, you can now change the Argument of each seq Object so that each one loads a different sequencer file. Your completed patch should look something like Fig. 3.
To operate your Max patch, you must first lock it. You can lock a Patcher window by Command-clicking in the open area of that window or by clicking on the Lock button in the lower left-hand corner of the window.
Sampling in Max
A good way to begin a discussion about audio in Max is by looking at the software's sampling capabilities. Using a variety of Objects, audio files can be played back from RAM or from disk. One such Object is sfplay~ (sound file play).
It's easy to build a basic sample-playback instrument. Start by creating an sfplay~ Object using the same technique that you used to create the key Object. Next, choose the toggle Object, position it above the sfplay~ Object, and then connect it to the left inlet of the sfplay~ Object. Create four message boxes with the messages open, loop 1, loop 0, and speed $1. Position these message boxes above the sfplay~ Object and to the right of the toggle Object, and then connect each one to the left inlet of the sfplay~ Object.
Now add a floating-point number box, position it just above the speed $1 message box, and connect it to the left inlet of that message box. Clicking on the toggle Object or message boxes allows you to control basic aspects of the sfplay~ Object. Clicking on “open” recalls the standard Open Document dialog box so that stored audio files can be loaded into the sfplay~ Object. Clicking on the toggle Object starts and stops the audio file playback. Clicking on “loop 1” enables the looping function, whereas clicking on “loop 0” disables it.
If you scroll in the number box, you control the rate of sample playback. A value of 1.0 is the sample's normal rate, 2.0 reads through the sample in half the time, and 0.5 reads through the sample in twice the time.
To control the signal-level output from the sfplay~ Object, you need to use the *~ Object. The *~ Object literally multiplies the value of each audio sample and outputs it. If, for example, you multiply each individual sample by 0.5, you cut the amplitude by half.
FIG. 4: This Max patch is based on the sfplay~ Object with its basic controls. The sfplay~ Object plays audio files from disk.
Using the same technique that you used to create the key Object, create a *~ Object, position it below the sfplay~ Object, and connect the left outlet of the sfplay~ Object to the left inlet of the *~ Object. Add the Argument 0.5 to the *~ Object. Next, create a dac~ Object using the same technique that you used to create the key Object. (The dac~ Object is the digital audio converter in Max; it converts all audio signals it receives to the analog domain so that they can be amplified and heard.) Position the dac~ Object below the *~ Object, and connect the outlet of the *~ Object to both the left and right inlets of the dac~ Object.
Finally, choose another toggle Object, position it above and to the right of the dac~ Object, and connect it to the left inlet of the dac~ Object. Clicking on this toggle Object turns the audio on and off. Your sample-playback patch should look like Fig. 4.
Extend your simple audio-playback patch by adding four delay~ Objects. Before you add these Objects, select the patch cord between the sfplay~ and *~ Objects by clicking on it, and delete it by pressing the Delete key. Leave the *~, dac~, and lower toggle Objects connected, but drag them farther down in the window to make space for the delay~ Objects that you are going to add.
Using the same technique that you used to create the key Object, create four delay~ Objects. Position them below the sfplay~ Object, and connect the left outlet of the sfplay~ Object to the left inlets of each of the four delay~ Objects.
Each of these delay~ Objects needs two Arguments. The first Argument specifies the maximum delay time in individual audio samples; the second Argument specifies the initial delay setting. If the sampling rate is 44.1 kHz, then 44100 equals 1 second of time.
FIG. 5: This Max patch, based on the sfplay~ Object, combines four delayed copies and the original signal.
If you connect an integer number box to the right inlet of each of the delay~ Objects, you can adjust the delay amount in real time. To add four integer-number boxes, type the letter I and then click in the white area four times. Position one of the number boxes above each of the four delay~ Objects, connecting the outlet of each number box to the right inlet of the associated delay~ Object. By scrolling in the number boxes, you adjust the delay times. Now connect the outlets of each of the four delay~ Objects to the left inlet of the *~ below them. Your patch should look something like Fig. 5.
Notice the straight patch cords in Fig. 5. To make your patch cord straight, select the one you want to square off and choose Align from the Arrange menu. Once it's squared off, you can drag the patch cord up or down. I used the Align function in Fig. 5 to help keep patch cords and Objects from colliding with each other.
These patches (see Web Clips 1, 2, 3, 4, and 5) can be altered, customized, and extended in many ways using a vast array of Objects I have not mentioned here. For instance, the vst~ Object enables you to modify audio signals with your favorite VST plug-ins, and the rewire~ Object lets you exchange audio and MIDI data with ReWire-compatible applications. This type of flexibility permits you to fully customize your individual sound-design environment.
Max also allows the creation of external Objects. An external Object, while functionally identical to regular Max Objects, is created outside the auspices of Cycling '74, Max's developer. I estimate that more than 1,000 external Objects are available, many of them for free at sites like the Max Objects Database (maxobjects.com).
One especially cool external Object is the aka.wiiremote Object written by Masayuki Akamatsu. This Object permits data to be transmitted wirelessly from the Nintendo Wii Remote into Max through a Bluetooth connection. (For more on the aka.wiiremote Object, see “Music in the Air” on p. 24 of this issue.) Professor Akamatsu has also written a magnificent 1,100-page text called 2061: A Max Odyssey that exhaustively covers Max, MSP, and Jitter. The work is written in Japanese, but all of the beautifully clear examples are posted online for free download at http://max.iamas.ac.jp/2061/?page_id=1100.
Jeffrey Stolet is a composer and professor of music at the University of Oregon. He uses wands, devices, game controllers, and other magical things to tame the sonic and videographic domains.