MSP Basics Tutorial 1: Test Tone
Click here to open the tutorial patch: 01mTestTone.maxpat
MSP objects are pretty much like Max objects
MSP objects are for processing digital audio (i.e., sound) to be played by your computer. MSP objects look just like Max objects, have inlets and outlets just like Max objects, and are connected together with patch cords just like Max objects. They are created the same way as Max objects - just by placing an object box in the Patcher window and typing in the desired name - and they co-exist quite happily with Max objects in the same Patcher window.
...but they're a little different.
A patcher containing interconnected MSP objects works a little differently from a patcher containing standard Max objects.
One way to think of the difference is just to think of MSP objects as working much faster than ordinary Max objects. Since MSP objects need to produce enough numbers to generate a high fidelity audio signal (commonly 44,100 numbers per second), they must work faster than the scheduler used by standard Max objects, which typically runs around a thousand times per second.
Here's another helpful way to think of the difference. Think of a patch of MSP objects not as a program in which events occur at specific instants (as in a standard Max patch), but rather as a description of an instrument design - a synthesizer, sampler, or effect processor. It's like a mathematical formula, with each object constantly providing numerical values to the object(s) connected to its outlet. At any given instant in time, this formula has a result, which is the instantaneous amplitude of the audio signal. This is why we frequently refer to an ensemble of inter-connected MSP objects as a signal network.
So, whereas a patch made up of standard Max objects sits idle and does nothing until something occurs (a mouse click, an incoming MIDI message, the clock firing on a metro object, etc.) causing one object to send a message to another object, a signal network of MSP objects, by contrast, is always active (from the time it's turned on to the time it's turned off), with all its objects constantly communicating to calculate the appropriate amplitude for the sound at that instant.
...so they look a little different
The names of all MSP objects end with the tilde character (~). This character, which looks like a cycle of a sine wave, just serves as an indicator to help you distinguish MSP objects from other Max objects.
The patch cords between MSP objects have stripes. This helps you distinguish the MSP signal network from the rest of the Max patch.
MSP objects are connected by striped patch cords
Take a look at the tutorial patcher. You'll see that we have six items of our patcher's canvas. Three of them should be familiar to you: we've got a Max comment box ("warning:loud") and two message boxes labelled
stop. The bulk of the patcher logic consists of three objects we've never seen before: a cycle~ object, an ezdac~ object, and something that looks suspiciously like a slider object but is actually a gain~ object. Let's look at these objects in turn, starting with the dac~ at the bottom of the patcher and returning from there to the top of the chain.
Digital-to-analog converter: ezdac~
The digital-to-analog converter (DAC) is the part of your computer that translates the stream of discrete numbers in a digital audio signal into a continuous fluctuating voltage which will drive your loudspeaker.
Once you have calculated a digital signal to make a computer-generated sound, you must send the numbers to the DAC. So, MSP has an object called ezdac~. This object is generally the terminal object in any signal network, and is required for any signals generated by MSP to make it out of your computer as sound. The ezdac~ object receives the signals you wish to hear in its inlets, and has a stereo configuration talking to the first two channels of your audio hardware - this is why there are two inlets on the ezdac~ in our patcher. If you were using more elaborate audio output hardware that required more than two channels, you would use the ezdac~ object's cousin the dac~ object, which lets you specify other audio channels as outlets using typed-in arguments.
Important! ezdac~ must be receiving a signal of non-zero amplitude in order for you to hear anything. ezdac~ expects to receive signal values in the range -1.0 to 1.0. Numbers that exceed that range will cause distortion when the sound is played.
A simple wavetable oscillator: cycle~
The best way to produce a periodic waveform is with cycle~. This object uses the technique known as ‘wavetable synthesis’. It reads through a list of 512 values at a specified rate, looping back to the beginning of the list when it reaches the end. This simulates a periodically repeating waveform.
You can direct cycle~ to read from a list of values that you supply (in the form of an audio file), or if you don't supply one, it will read through its own table which represents a cycle of a cosine wave with an amplitude of 1. We'll show you how to supply your own waveform in a later tutorial; for now we'll use the cosine waveform.
Graph of 512 numbers describing one cycle of a cosine wave with amplitude 1
The cycle~ object receives a frequency value (in Hz) in its left inlet, and it determines on its own how fast it should read through the list in order to send out a signal with the desired frequency.
Technical detail: To figure out how far to step through the list for each consecutive sample, cycle~ uses the basic formula
where I is the amount to increment through the list, ƒ is the signal's frequency, L is the length of the list (512 in this case), and R is the audio sampling rate. cycle~ is an ‘interpolating oscillator’, which means that if I does not land exactly on an integer index in the list for a given sample, the cycle~ object interpolates between the two closest numbers in the list to find the proper output value. Performing interpolation in a wavetable oscillator makes a substantial improvement in audio quality. The cycle~ object uses linear interpolation, while other MSP objects use very high-quality (and more computationally expensive) polynomial interpolation.
The cycle~ object has a default frequency of 0 Hz. So in order to hear the signal, we need to supply an audible frequency value. This can be done with a number argument as in the example patch, or by sending a number in the left inlet, or by connecting another MSP object to the left inlet. If we listen to the output of this signal with its frequency set in an audioble range, we should hear a sine wave, the purest (in terms of spectrum) sound that we can make.
A volume control: gain~
If we were to directly connect our cycle~ object to a dac~ object and start the audio, we could easily damage our speakers or, more importantly, our ears. MSP objects that generate audio (such as cycle~) generally do so at a normalized dynamic range of -1 to 1, which the dac~ object will interpret as being the loudest signal possible. To avoid these dangers, it's important to have an object in-between to control the amplitude of the signal going to our speakers. The gain~ slider performs just such a function:
The gain~ slider in the Explorer
The gain~ slider multiplies its incoming signal by a factor based on the position of the slider which, for all but the uppermost reaches of the object, is a number less than 1. As a result, the gain~ object almost always attenuates (or turns down) the volume of what comes in, much like a fader on an analog mixing desk. The gain~ object is in several ways a graphical version of a *~ object, which we'll look at in a later tutorial.
Starting and stopping signal processing
In this set of tutorials, we're using the ezdac~ object to turn audio off and on our patches. While it's great to be able to click on the icon and to see whether or not audio is on in the Patcher window, the The ezdac~ object is hard-wired to output channels 1 and 2 on your audio device, which might not make it appropriate for working with multi-channel sound. For our tutorials, however, it should be fine.
The ezdac~ object is one of five MSP objects (along with adc~, ezadc~ and ezdac~, and adstatus) that can turn on and off the MSP audio network from within your patcher. There are two common ways of turning audio on and off used in these tutorials - by clicking on the ezdac~ object in a patch, or sending a
0 to the left inlet of a ezdac~ object (or an ezadc~ object).
Important! Since you generally don't want to enable or disable processing for all open signal networks in all currently open Max patchers (which might mean you'd hear things you don't expect) the ezdac~ object has an attribute called local which can be set using the Inspector. When the local attribute is enabled, turning audio on or off will only affect the local Max patch (and its subpatches).
Although ezdac~ is part of a signal network, it also understands certain Max messages, such as
1. Many MSP objects function in this manner, accepting certain Max messages as well as audio signals.
Listening to the Test Tone
The first time you start up Max, it will try to use your computer's default sound card and driver (CoreAudio on Macintosh or MME on Windows) for audio input and output. If you have the audio output of your computer connected to headphones or an amplifier, you should hear the output of MSP through it. If you don't have an audio cable connected to your computer, you'll hear the sound through the computer's internal speaker.
In order to get MSP up and running properly, we recommend that you start the tutorials using your computer's built-in sound hardware. If you want to use an external audio interface or sound card, please refer to the Audio Input and Output chapter for details on configuring MSP to work with audio hardware.
- Set your audio amplifier (or amplified speakers) to their minimum setting, then click on the ezdac~ object in the tutorial patcher. Click and drag on the gain~ slider until it's set to somewhere in the middle of its length. Adjust your audio amplifier to a comfortable setting. Once you're satisfied that the patcher is working, click on the ezdac~ object to turn off that annoying test tone.
If you don't hear any sound coming from your computer when you click on the ezdac~ in this example and turn up the gain~ slider, check the level setting on your amplifier or mixer, and check all your audio connections. Check that the sound output isn't currently muted. On Macintosh, the sound output level is set using the Sound preferences in the System Preferences application. On Windows, the sound output level is set using the Sounds and Audio Devices setup (Start - Control Panels - Sounds and Audio Devices).
If you are still are not hearing anything, choose Audio Status from the Options Menu and verify that the Core Audio Built in Controller for Macintosh or MME driver for Windows is selected in the Driver pop-up menu. If it isn't, choose it.
A signal network of connected MSP objects describes an audio instrument. The digital-to-analog converter of the instrument is represented by the ezdac~ object; ezdac~ must be receiving a signal of non-zero amplitude (in the range -1.0 to 1.0) in order for you to hear anything. The cycle~ object is a wavetable oscillator which reads cyclically through a list of amplitude values, at a rate determined by the supplied frequency value. Signal processing is turned on and off by clicking on the object or by sending a
0 message to it.
cycle~ - Table lookup oscillator
gain~ - Exponential scaling volume slider
ezdac~ - Audio output and on/off