1. overview
the mapd window is separated into two main fields.
- on the left side there is a virtual monome for selecting buttons to assign to widgets and to monitor button presses and widget status.
- on the right side, preferences retaining to the creation of a widget, or to the behavior of a selected widget becomes visible when needed.
2. adding a widget
mapd allows the user to select a number of buttons on the virtual monome on the left hand side of the mapd window, by either clicking and shift-clicking any number of buttons, or by dragging a square over the virtual monome.
once one or more buttons have been selected on the virtual monome, the right hand side will change to an interface that allows the user to select one of four basic widget types:
- press button
- toggle button
- radio button
- slider (1d and 2d)
3. configuring a widget
once a widget type has been chosen, the right hand side changes to an interface that allows the user to configure the parameters of each widget. all of the widgets share the same basic behavior.
host address
first you define the host address. this is:
- the ip address of the computer that is running the software you are targeting,
- a colon, (:)
- and the port that you are addressing.
most of the current max patches will respond to localhost:8000. each widget can be set to a different host address. this may not seem important, but that means that you can easily communicate with many different pieces of software at the same time by assigning different ports, and even use a single monome to operate software on multiple computers simultaneously on the same local network by assigning different ip addresses to the different widgets.
address pattern
the address pattern is the osc message that will be used to identify a message sent over OSC (currently serialio uses /box/press 0 0 1; /box/led 7 0 0; etc…).
one of the lovely things about mapd is that you can use any naming convention that fits OSC (see OpenSound Control) and mapd will check to see if the address pattern is legal. if it isn’t, a little yellow triangle will pop up on the right hand side of the address pattern box. if you click on the triangle, a message box with a more detailed error message pops up.
To insert a variable, use $1 and $2 to designate where the variable should fall in the OSC message ($2 is only needed in a two dimensional slider).
By using the same address pattern for more than one widget, a network of widget behaviors can be set up, so that for example one slider will interpolate, a series of radio buttons will assign different values and a second slider will not interpolate but have more steps than the first one, all only by using the same address pattern. play around with this to get a good feel for this feature of mapd.
Each of the widgets also has an option to set it so that mapd sends out osc messages that interpolate between the current and new values. The interpolation occurs over a time-interval defined by the interpolation time (you can only set the interpolation time once you have clicked the initial condition toggle button.
Each widget also allows the user to store an initial value for the widget. By clicking the send initial condition toggle button, the initial value will be sent out on load or any time that the current mapping gets turned on.
press button
the preferences and proposed conventions vary in different ways over the four basic widget types. the press button allows you to set a down value and an up value to send over OSC. let us say that you want it to send out the value 1 when you press it down and the value 0 when you release it. if the host address is localhost:8000 and the address pattern is /rock/lobster, it will send the message /rock/lobster 1 when you press it and /rock/lobster 0 when you release it.
you can enable interpolation by clicking the interpolation toggle button. mapd will send out 10 values a second between button down value and button up value. if both values are integers, mapd will output a series of integer messages, and if both values are floats, mapd will output a series of floats.
both press and toggle buttons allow you to send out osc messages when you either press or release a button on the 40h. this is done by leaving either the up or down value for the given widget empty.
you can delete the widget using the delete this widget button.
toggle button
the toggle button behaves very similarly to the press button, except you need to push it twice to turn it on and off.
radio button
the radio button widget allows the user to set a separate return value for each button in the widget. interpolation is allowed, but as usually, only as long as all values are of the same type (i.e. integer or float). values are assigned by pressing on the corresponding button in the edit button graphic.
1d slider
to create a 1d slider, select a number of buttons on the virtual monome that all belong to the same row or column. you then assign a min and max value for the slider, and mapd will map the steps in-between on the selected buttons. otherwise it works similar to the toggle and press buttons.
2d slider
once again there is not a gigantic leap of functionality between the widget preference settings. the main difference with the 2d slider is that each axis of the slider can be assigned to a different host address and a different address pattern. independent ranges can be set for the x and y so that each dimension can send out different values to different programs on different computers.
clearing space on the 40h
when you want to delete a widget, or place a widget where you have previously placed a widget, select the buttons you want to use, and mapd will ask you if you want to delete all widgets that use any button that you have just chosen. yes will delete these widgets. re-select the buttons and assign the new widget.
mappings
mapd allows the user to create mappings. a mapping is a complete set of pages, presets and layout for the 40h. mappings allow the user to switch easily between instruments or song setups. when mappings are switched, all temporary information of the old mapping get cleared away, and all initalization values get sent out.
pages
pages allow the user to set the 40h to use multiple different layouts or maps in a single patch. each page contains a number of widgets. when a page gets switched, all the temporary data on the page stays unchanged, and the temporary state of the new page gets recalled. when a page is switched, no information gets sent out. we can think of pages as a way of extending the 40h into multiple levels, allowing us to use more than just 64 buttons to control an instrument (an example would be the pattern and step-sequencer views in 64 step).
by setting a button down so that it sends the message:
/system/page pagenamewe can switch between pages on the fly.
presets
presets store and recall the temporary state of a given mapping. you can add presets using the + button, and remove them with the – button. you store and recall the presets using the S and R buttons.
by setting a button down so that it sends the messages:
/system/preset/save presetname
/system/preset/recall presetnameyou can store and recall presets on the fly.
midi address patterns
so you want to send midi? okay, okay, I guess you can send midi, but at least PRETEND you’re using open sound control! I’m going to describe the make-believe osc address pattern and value structure for sending midi, but there are a few things you need to know.
mapd let’s you select 4 different midi destination to send message to. these devices can anything connected to your computer or any piece of software that knows how to create a virtual midi endpoint (that’s what the ‘to Max/MSP1’ and ‘to Max/MSP 2’ devices are that show up when you open Max/MSP). within an address pattern, these devices are represented by the letters a, b, c, and d. in the midi setup dialog you can select which device is represented by each letter.
the second thing you need to know is that mapd lets you send 3 different types of values: integers, floating point decimal numbers, and strings. when I tell you how to send a certain type of midi message, I’m going say something incomprehensible, like “note on messages must have the following structure:
”/midi/note_on device:(string)a-d velocity:(int)0-127”
and you’re going to know that I want you to write something like:
/midi/note_on a 60 64 1
to send out a note_on midi for note number 60 with velocity 64 to device ‘a’ on channel 1.
what the hell are you talking about?
[device:(string)a-d] means that that this place in the address pattern tells mapd what devviice to send midi to and must be an atom of the type string that is one of the following letters: ‘a’, ‘b’, ‘c’, or ‘d’.
[note:(int)0-127] means whatever is in this place in the address pattern tell mapd what midi note number to output. it must be an integer between 0 and 127, inclusive.
[velocity:(int)0-127] means whatever is in this place in the address pattern tells mapd what midi velocity to output. it must be an integer between 0 and 127, inclusive.
[channel:(int)1-16] means that whatever is in this place in the address pattern tell mapd what midi channel to send the note on to. it must be an integer between 1 and 16, inclusive.
got it? good! here we go:
note on
/midi/note_on device:(string)a-d velocity:(int)0-127
example: /midi/note_on a 60 64 1
note off
/midi/note_off device:(string)a-d [channel:(int)1-16]
example: /midi/note_off a 60 1
after touch
/midi/aftertouch device:(string)a-d pressure:(int)0-127
example: /midi/aftertouch 60 126 1
control change
/midi/controller device:(string)a-d controller value:(int)0-127
example: /midi/controller a 7 127 1
the midi spec has some special controllers than generally do the same thing on every midi device. for example, controller number 7 usually controls the volume. there are also some controller types are actually controlled by two controller numbers. did you know that on most midi devices you can set a 14bit volume by sending the high 7 bits to controller number 7 and the lower 7 bits to controller number 39? mapd has some special address patterns to make this easy for you. they take the form
/midi/controller device:(string)a-d value:(int)0-127|(float)0.0-1.0
here we go!
here are the mapd extended midi messages