Interfacing Max/MSP and NoteAbility Pro


A. Controlling Max/MSP with NoteAbilityPro

Setting up NoteAbility to send Max/MSP messages

The first part of this tutorial describes how NoteAbility can be used as a real-time sequencer to control Max/MSP. Max/MSP messages can be placed on NoteAbility tracks to be sent to Max patches during playback.

  1. Go to NoteAbilityPro Preferences > Sound/MIDI, and check the box beside "Play Messages on Max" under Playback Settings. Click OK.

    Ex. 1-1

  2. Create a new NoteAbility document with the desired number of staves, including at least one that will be used exclusively for Max/MSP data.
  3. Click Audio/MIDI > Track Setup to open the MIDI and Audio Track Setup window, shown in Ex. 1-3. Down the left side of this window are listed the Staff ID numbers in your score, each of which corresponds to a MIDI or Audio track. If you click on the dialog box for a given track, you can select the output for the data contained on that track:

    Ex. 1-2

    Set the track(s) that you want to use for Max/MSP messages to Net Message. Now that one of your tracks will be sending data to a network port, it is necessary to set up the network configuration.

  4. Still in the MIDI and Audio Track Setup window, click on the Network Setup button. This opens a drawer that displays the 16 possible network connections, their IP addresses and Port numbers. If you are running Max/MSP and NoteAbility on the same computer, you can either enter your computer's IP address or simply type "localhost" under the IP address heading. If you are controlling Max/MSP on another computer, enter that computer's IP address. You can find a computer's IP address under System Preferences > Network. The port numbers used by Max/MSP and NoteAbilityPro are 3000 and 3001 (using UDP protocol); you should check to make sure that your access to these ports is not restricted by a firewall.

    Once you have specified the IP address and Port number for a particular network connection, you need to specify which network connection is to be used by your Net Message tracks. Down the right side of the MIDI and Audio Track Setup window are listed the Network Connections for each track; by entering the number of a network connection into one of the boxes, you can specify which connection a given track will send its data on. Note that several tracks can use the same connection.

    In the example below, two network connections have been made. The first is to the same computer that NoteAbility is running on (localhost), and is utilizing port 3000. The second connection employs another computer to run Max/MSP (at IP address and uses port 3001. Three tracks have been set to use these connections: track 2 is sending through network connection 1, while tracks 3 and 4 are both sending through network connection 2.

    Ex. 1-3

Setting up Max/MSP to receive from NoteAbilityPro

Create a bpatcher in your Max/MSP patch, and use the Get Info... dialog box under Options to load "netReceiverBP.pat" from the UBC Toolbox. This module accepts data from network ports 3000 and 3001 and sends it to Max/MSP objects the way a "Send" object would. (A detailed description of the Net Receiver module can be found by clicking the cursive "i" icon when the patch is locked.) Turn the module on by either clicking on the On/Off button or by sending the message "1" to its right inlet, and create receive objects that will correspond to the Max Text "sends" in your NoteAbilityPro score (Max Text is described below). Two LEDs will indicate when messages are being received on either of the two ports.

Ex. 2-1

Entering Max/MSP data into a NoteAbilityPro track and receiving data in Max/MSP

Now that at least one track has been set up to send information to Max/MSP, we can enter Max/MSP data into the score. From NoteAbilityPro's toolbar, select the Max Text tool.

Ex. 3-1

This allows you to create a text box at any point in the score, the contents of which will be sent to Max/MSP in the same manner as the "Send" object does within Max/MSP. (Note that neither the send command nor a semicolon is used to preface the contents of a Max Text box, as would normally be the case within Max/MSP. If you want to include multiple message sends in a single text box, however, these must be separated by a semicolon.) In addition to the text that you enter, a Max Text box displays a number indicating the beat location in the measure at which the signal is sent, expressed as a floating-point number where the first beat of the measure is given the value 0. Example 3-1 shows a variety of Max Text boxes entered on track 1.

Ex. 3-2

As the above NoteAbility score plays back, the message "bang" will be sent to Max/MSP at beat location 0.307 (the arrow on the text box indicates the position in the measure at which the message is sent), and will be received by a receive object with the name "Shorty" (assuming the Network Receiver bpatch is active in Max/MSP and there exists an appropriately named receive object, as in Ex. 2-1.) Note that the chronological time at which messages are sent is contingent upon NoteAbility's tempo setting. Once created, Max text boxes can be moved to different positions in the score, either by dragging or by cutting, copying, and pasting. When using the paste function, your Max text boxes will be entered at the position of the entry cursor; this method is useful for placing text boxes at specific points in the score. The appearance of Max text can be altered just as any other type of text: select the text using any text tool (Page Text, Measure Text, or Max Text,) and then click on Font > Show Fonts... to open a window that allows you to change the font type, style, size, and colour.

The messages that are sent to Max/MSP can be used to control UBC toolbox modules; Ex. 3-1 includes examples of messages that will be received by the FM player. Just after the fourth beat (beat location 3. 053,) a Max text box will send a "1" to fmOnOff, turning the module on, and will send "100" to fmVol, setting the module's volume at a value of 100. At beat location 1.010 in the second measure, the FM player will receive a note data list via an fmNote message, telling the module to play a note with the specified pitch, velocity, etc. The protocol for the note data list can be found in the file "toolkitProtocols.txt" ?(should I list them? is this file included in the toolbox?)

To find the names of the receives that exist in a particular module, open the module in a bpatcher, lock the patch, and click on the cursive "i" to open the information window about that module. Ex. 3-2 shows the FM player and its information window, listing the kinds of messages that the module can receive.

Ex. 3-3

Extended Notes

If you are sending a complicated series of notes to Max/MSP (to be received by a module such as the FM player or the Sample player,) it may be cumbersome to create a Max text message for each note. By using extended notes, pitches can be entered as usual and subsequently assigned values for other parameters (such as velocity, panning, c to m ratio, etc.) that will be sent to Max/MSP during playback. Compare examples 4-1 and 4-2, both of which will send identical messages to Max/MSP (although these messages will be sent to differently named receive objects: "fmNote" in Ex. 4-1 and "naNoteIn" in Ex. 4-2):

Ex. 4-1

Ex. 4-2

Once you have entered the pitches that you want to be sent to Max/MSP, you will first need to convert them from regular notes into extended notes. Open the Extended Notes Panel under the IIMPE menu, select the notes you want to convert, and click Convert to Extended (see Ex. 4-3.) You will notice that the selected notes are no longer black; the colour of the extended notes indicates which channel the note is assigned to. For notes on certain channels, small numbers (showing the pitch and velocity of the note) appear under the notes. This indications are particularly useful when notes are being used to trigger sample numbers.

Ex. 4-3

Now that the passage has been converted to extended notes, the Extended Notes Panel can be used to edit the information attached to each note. With the Extended Notes Panel open, select one or more extended notes in the score. You can view the information assigned to each note in the selection by clicking on First Note and then running through the subsequent notes by clicking on Next Note. (A value of -1 indicates that a parameter will be ignored.) It should be noted that First Note must be clicked even if only one note has been selected. To edit the data for a particular note, enter the desired values for each parameter and then click Set Data; this will assign the values you entered to the current note and then change the display to the data for the next note. To quickly edit the spatialization parameters of a note, use the positional controls in the lower right corner of the panel, remembering to click Set Data to set the values. If you would like to set a particular parameter for each note in the selection to the same value, use the Parameter slider and the Set button. For example, if you want all selected notes to be assigned to channel 5, move the Parameter slider to 3 (since Channel is the third parameter), enter 5 in the message box, and click Set.

Assuming that the track containing the extended notes is set to transmit Net Messages and that Max/MSP has a NetReceiver bpatcher that is set to receive messages (as described above), the data attached to each note will be sent to Max/MSP when the NoteAbility score is played. In the Max/MSP patch, the note data can be received with a receive object entitled naNoteIn, as shown in Ex. 4-4:

Ex. 4-4

B. Controlling NoteAbilityPro with Max/MSP

NoteAbilityPro can be set to receive messages from Max/MSP using network connections, enabling you to control score playback in real-time. To set up a network connection on which messages can be received, select Network Port Panel... from the IIMPE (Integrated Interactive Music Performance Environment) pull-down menu. Under the heading "Incoming Data" is a list of the network port numbers that are available for incoming messages, from 3002 to 3009. Select the port numbers that you want NoteAbility to be listening to. If the "Show Activity" option is checked, the light next to each port will flash if there is input at that port (use this option only for setup and troubleshooting, since it consumes unnecessary computing power.)

Ex. 5-1

In a Max/MSP bpatcher, load the "netSenderBP.pat" module. To establish a connection to a particular computer and port, send a "connect" message to the module's left inlet, with arguments specifying the IP address and port number. For example, "connect localhost 3002" will connect to port 3002 if you are running both applications on one computer, and "connect 3009" will send to the computer at IP address on port 3009.

Ex. 5-2

Once a connection has been established, the large LED on the left side of the module will light. Network Sender will then transfer messages from its middle inlet to NoteAbility, enabling control over NoteAbility's playback parameters. At the moment, NoteAbilityPro accepts the following messages:

Message NoteAbilityPro Response
pause 1 pause playback
pause 0 resume playback
tempo (int) set the playback tempo to "int"
sync (beat location * 1000) adjusts the playback position to this beat location (according to score following setting in the Network Port Panel)

C. Non-Real-Time Interaction between NoteAbilityPro and Max/MSP

Information contained in a NoteAbilityPro score can be exported in a format that Max/MSP can read independently of NoteAbilityPro, using the Max object "qlist" and the qControl.abs patch (included in the UBC Toolbox.) Clicking on the Save To... option under NoteAbility's File menu opens a window that allows you to save your score in various file types:

Ex. 6-1

Max/MSP qlist objects

Selecting Max 'qlist' creates a Max patch that contains a 'qlist' object within a patch that controls its playback, s hown in Ex. 6-2. All of the Max/MSP messages as well as all of the notes in the score are included in the qlist, unless you modify the QList panel (under Tools > Max Settings...) Double-clicking on the 'qlist' object while the patch is locked will open the text file to which this object refers, shown in Ex. 6-3; this file contains the messages from your score, separated by numbers indicating the difference in time (in milliseconds) between each message. Note that these times are calculated relative to the current tempo setting in NoteAbilityPro.

Ex. 6-2

Ex. 6-3

Clicking start on this qlist patch will play through the qlist, sending the sequence of messages separated by the specified times. The qlist in Ex. 6-3 will thus play as follows: after 204 ms, a "bang" will be sent to a receive named "Shorty" 239 ms after that, the note data "64 80 4 111" will be sent to a receive named "note" 111 ms after that, another note will be sent, and so on.

It is also possible to create a qlist containing information from only a portion of the score. Clicking on Tools > Copy Types... will open a window that allows you to select the type of information that will be copied when using the "Copy All Types" command from the Edit menu. Check the box beside "Max qlist", select a passage from the score using the select arrow, and then click Edit > Copy All Types. To place this information into a qlist object in Max/MSP, double-click on the qlist object (when the patch is locked) and paste it into the qlist file at the desired location. In order for your changes to this file to be saved, the patch containing the qlist object must be saved.

Max/MSP detonate objects

It is also possible to save a NoteAbilityPro score as a detonate object using the Save To.. menu item in the File menu and selecting Max 'detonate' as the file type.

Detonate objects can be used to playback scores from Max/MSP or they can be used for score following. Only the notes in NoteAbilityPro score are converted into the 'detonate' object - Max messages, dynamics and other score markings are ignored. For simplicity, all notes are saved in channel 1. In the example below, a short musical excerpt is saved as a detonate object. The tempo of the score is q=120.

The score in NoteAbilityPro appears as:

Ex. 7-1

In Max/MSP, the detonate object appears as:

Ex. 7-2

- Max/MSP support in NoteAbilityPro will continue to evolve as better score following strategies are developed. For example Max/MSP patches, example NoteAbilityPro scores and updated documentation, please contact the author.

© 2006 David Litke and Keith Hamel