Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time


This tutorial document gives an introduction to the creation of a piece and its preparation for rehearsals and concerts. We will refer to the project called Tutorial found in Bear in mind that every project needs to reside in this folder and needs to have a particular folder structure which you can generate in the Client by clicking on "Create Local Project..." in the Client Project preferences pane. This structure needs to be adhered to so that your files will be properly loaded when you open your project.

Tutorial Folder

A typical Project folder thus contains the following sub folder:

  1. Audio-Extensions
  2. Clips
  3. Conductor
  4. Inputs
  5. Instruments
  6. Local
  7. Maps
  8. Processes
  9. Resources
  10. Samples
  11. Tunings
  12. Viewer

Top level

The only file residing at top-level can be a bank file, used by the Sampler. It contains a reference to instruments. The bank will be loaded automatically once a project has been chosen, but can also be opened and edited manually in the Sampler Preferences. The tutorial comes with a bank called consisting of a number of old synth sounds, among others.


Audio-Extension While also supports VST plugins for audio processing and sound generation, Audio-Extension offer a very simple means to extend simply by adding Max patches to this particular folder. In the Client there are two slots for each player, for a total of 10 (see the Plugins preferences pane) These patches can also both be used for processing and generation.

Sound processing

The Tutorial/Audio-Extension folder contains two patches which are quite simple in nature. All you need is two inlets for each of the two stereo channels as well as the same number of outlets for further processing (reverb, spatialization and limiting). In your patcher, you create audio processes by using MSP signal objects for each channel, add Max GUI objects (such as a number box) for the parameters you wish to control locally or remotely and expose them to the pattr system by means of an autopattr object.

Sound generation

In order for events to be passed to the sound generator you'd have to add a receive object with #1extention as an argument. The messages routed to this receive object are in this format:

  • note midi_cent_value velocity_value and note_id (if pitch and volume of a note ought to be controlled individually, usually 0); Example: note 4900 113 0
  • bend pitch_deviation volume and note_id (id of the note the message is supposed to be applied to); Example: bend 0 113 0


Clips contain the movie clips to be used by the Viewer in a particular project. When the project is selected in the Conductor, the Viewer will set the path to that folder and load the media contained in them automatically. If there are sub folders named 1 through 5 in them, the Viewer will assign the media to the corresponding movie player instance.


Control Panel in Patcher View This folder contains the MaxScore xml file and the control panel which will be shown on the bottom of the Conductor when a project loads. The control panel is used for the following functions:

  • Start and stop timer
  • Initialize the settings for a particular piece
  • Communicate and coordinate with the participants during a concert and rehearsals
  • Execute actions according to current time (sequencer) or particular cues
  • Compose and/or send scores to the Client
  • Control the appearance of the score
  • Scroll the score or portions of it
  • Control the movement of cursors
  • Draw shapes to the Clients

Control Panel in Presentation View


Inputs are Max patches sending input received from the periphery to either the Server from where the events are are distributed to the other participants or to the Mapper (see below) where they are mapped onto a parameter for further distribution. An input require following components to operate and need to be saved as foo.input.maxpat:

  • a "r inputPanel" object connected to a "route foo" (foo being the name of the input patch) connected to a "route open enable local". The first outlet of this route object triggers a front messages to thispatcher which prompts the GUI to open when it receive an open message from the Preferences Input panel. When receiving enable 0 or 1, the patcher either disables or enables output from the input patch by closing or opening a gate, while the local 0 or 1 message will either route the events either directly to the network or to the mapper via the "s client-tcpsender" and "s toClientMapper", resp. Note that while "s client-udpsender" will also work, the events will currently still be sent via TCP.
  • A "Preferences::Inputs::foo::enable 1" should be sent to "s toClientPattrstorage" if the input is supposed to be auto-enabled.
  • Messages generated by an input can either be events (notes, bends or raw MIDI messages) or in double colon syntax to communicate directly with an object in the Client/Conductor/Viewer hierarchies of patcher attributes (e.g. "/client synthesis::spat::p1::x") Otherwise, messages may need to be first mapped by the Mapper to something meaningful.


This folder contains the instrument files for the Sampler. Instruments are part of bank files and refer to any number of samples in the following format:

Index, sample_name root_key key_zone_floor velocity_zone_floor envelope loop starting_point direction;

Example: 1, 76.099998 60 0 "envelope 2 0.0000 1.0000 2000.0000 1.0000 2000.0000 0.0000 2000.0000" "noloop 0.0000 0.0000" 0. fw;


The Local folder should contain resources that you don't wish to share with other participants via Github. Create a .gitignore file with the line Local/* and put this file at top-level in your project folder. See also: and the section below on sharing resources.


This folder contains the Mapper files instructing the Mapper (part of the Client and Viewer components) how to map an input stream to an output stream. The Mapper possesses a number of methods which are detailed in the section on Using the Mapper.


The Processes folder holds Max patches which operates on events rather than audio signals or controller data. There are currently three pre-defined processes (DJster, harmonizer and transformation). Processes are listed in the process menu on the Cient's left-hand side. Any number of presets can be created for each process and selected from the menu right next to it.


Put all supporting Max patches which don't fall in any other category in here.


Audio samples in any format supported by the Max buffer~ object should go in this folder. You may also use sub folders to organize the samples according to user or sound category.


Tunings are maps mapping MIDI key numbers to MIDI cents. The file contained in the Tutorial/Tunings folder adds a tuning with 22 shrutis to the default set of tunings. You will find an example as to how to create a tuning. All tunings should map MIDI key 60 to 6000 MIDI cents.


This folder is where project-specific vgen and vfx patches should go. These patches are video generators and effect processors created for the Viewer which loads these modules dynamically. Adhere to the foo.vgen.maxpat or foo.vfx.maxpat syntax to ensure that files go to the correct destinations. The Viewer folder should also hold the optional preset file foo.viewer.json, a file holding Viewer presets.


Video generators are Max Jitter patches with a brown background. They can be called by selecting


Video effects are Max Jitter patches with either green or blue backgrounds depending on whether they perform matrix or texture processing.

curve generators

How to create an instrument or bank of instruments?


  1. Open Project or alternatively create one.

  2. Go to Inputs (Keyboard icon) - > select Sampler. Here, you can create a bank and instruments. After pressing the window will pop up, where on the left side one could see instruments area, on the right side - samples area, which show the entries for each instrument. Instruments are stored in a Bank - a collection of instruments, which belong to one project (piece). A Bank can consist of one or several Instrument(s).

  3. Create New Bank or Open existing Bank by clicking matching menu item. The Bank is a .txt document, where instruments are indicated.

  4. In order to create an instrument click on “new instrument” and give it a name.

  5. To fill an instrument with samples simply drag samples into right part of the sampler. Be sure that a Samples sub folder exists in your Project folder (look in Max 8/Packages/

A word on the duration of a sample: it is advisable to not use samples with too many events in them or longer than, say, 10 seconds, since the sound will only play back as long as you hold a key. Anyway, if it is meant for artistic purposes, it is possible to have a long sample.

Editing Samples:

On the right part of the window you can see following cells:

  • Index - sequential number of a sample

  • Name - name of a sample

  • Root Key - the key at which a sample sounds at its original pitch

  • Key Zone Floor - the starting key of a region, where a sample is “active” and transposed according to root key

  • Vel Zone Floor - velocity zone (0-127) - different samples can be assigned to the same key and will be picked according to the velocity of the key.

See: computer keyboard mapping

On the lower part of the window there are following settings:

  • Loop - adjust starting and ending points for the sample looping. Press “dump” to apply.

  • Position - the starting point for playback

  • Envelope - here one can change envelope shape. You can change it manually or use any existing presets by entering the number in the corresponded field. There are some presets you can choose and modify.

  • Edit - here you can set the normalisation value (0. - 1.) and/or crop the sample length. When done with any edits make sure to re-save the sample.

Using the Mapper

Sharing resources