A newer version of Max is available. Click here to access the latest version of the Max documentation

detonate Reference

Play a score of note events

detonate

Description

Provides score playback managed using Max messages. The score may be loaded from a MIDI file, or generated using Max functions. The score is not limited to MIDI notes and values; any information can be stored and played back with detonate.

Examples

Note events are recorded with a delta time, which can be used to play notes back in rhythm

Discussion

When detonate receives a start message or a startat message in the left inlet, it sends out the delta time of its starting note event (or of the note after the found note, in the case of startat). After that, each time detonate receives a next message, it sends out all the other note data for that event, and the delta time of the next event, progressing through the score. Thus, the numbers coming out the left outlet can be used to control the playback rhythm, by delaying for the specified time and then triggering the next message.

When detonate receives an nth message (or receives a number, while stopped) in the left inlet, it uses that information as an index number (starting at index number 0 for the first note event) and sends out all note data for the indexed event. Instead of sending the note's delta time out the left outlet, however, it sends the start time of the note--the total time since the beginning of the score.

After detonate has received a follow or followat message in the left inlet, if a number is received in the 2nd inlet that matches the pitch of the current note in the score (or one of the two notes immediately after it), all the data for the matched note is sent out, except for the delta time.

Arguments

label [symbol]

Supplies a name for the object. Any detonate objects with the same name argument will share the same event data.

Attributes

Common Box Attributes

annotation [symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background [int] (default: 0)

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color [4 floats]

Sets the color for the object box outline.

fontface [int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname [symbol]

Sets the object's font.

fontsize [float]

Sets the object's font size (in points). Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden [int] (default: 0)

Toggles whether an object is hidden when the patcher is locked.

hint [symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick [int] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

jspainterfile [symbol]

JS Painter File

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation [int] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 0. 0. 0. 0.)

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect [4 floats]

g/s(set)

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size [2 floats]

g/s(set)

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor [4 floats]

Sets the color for the object's text in RGBA format.

textjustification [int]

Sets the justification for the object's text. Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname [symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

Messages

bang

Performs the same function as next.

int

Arguments

parameter [int]
After a record message has been received, all numbers received are treated as parameters of a note event.

In left inlet: The delta time (delay), in milliseconds, since the previous recorded event. This denotes the "inter-onset interval --the time between the beginnings of notes--which effectively determines the rhythm in which the events are recorded. This need not necessarily be the true time in which they occur; detonate believes any (non-negative) delta time it receives.

When detonate receives a number in the left inlet while recording, it treats the number as the inter-onset interval (the time elapsed since the previous event), combines it with the numbers most recently received in the other inlets, and records them together as a note event. As with most Max objects, the numbers received in the other inlets are stored for use in subsequent note events triggered by the receipt of a number in the leftmost inlet.

When detonate has received a follow message, a subsequent number in the 2nd inlet is treated as the key number (pitch) of a note. If the number is the same as the pitch of the current note in the score (or a nearby note), the information recorded for that note--except for the delta time--is sent out.

When detonate is neither recording nor following, a number in the left inlet has the same effect as the nth message.

  (inlet1)

Arguments

pitch [int]
In 2nd inlet: The number is treated as the key number (pitch) of the note. If no key number has ever been received, 60 is used by default.

  (inlet2)

Arguments

velocity [int]
In 3rd inlet: The velocity of the note. If the velocity is 0--indicating a note-off-- the event will be treated as the end of an earlier note-on the same key, and will determine the duration of that earlier note. If no velocity number has ever been received, it is 64 by default.

  (inlet3)

Arguments

duration [int]
In 4th inlet: In lieu of a note-off message, a note duration can be supplied as part of the note-on event. If no duration value has ever been received, and no note-off event is received to end the note, a duration of 10 milliseconds is used by default.

  (inlet4)

Arguments

channel [int]
In 5th inlet: The MIDI channel of the note. If no channel has ever been specified, notes are recorded on channel 1.

  (inlet5)

Arguments

track [int]
In 6th inlet: The number of a track on which to record the note event. Overdub recording is not possible with detonate, but each recorded note can be tagged with a track number for storing separate tracks of notes internally. If no track number has ever been received, notes are recorded on track 1.

  (inlet6)

Arguments

extra [int]
In 7th inlet: An "extra" number, which can be used for any purpose, attached to the note event. This number can be used to provide an additional event parameter, or to serve as a control value in sync with the note. If no number has ever been received in this inlet, it is recorded as 0 by default.

  (inlet7)

Arguments

extra-2 [int]
In right inlet: A second "extra" number.

float

Arguments

parameter [float]
Converted to int.

list

Arguments

event-values [list]
The first number in the list is used as the delta time, and the other numbers are treated as if they had been received in the other inlets, respectively from left to right.

clear

Erases the contents of detonate.

(mouse)

Double-clicking on the detonate object in a locked patcher opens a graphical editing window for editing the stored detonate data.

delay

Arguments

offset [int]
The message delay followed by a number will move the entire sequence of recorded note values over with the first note of the sequence beginning at the specified number.

export

Arguments

time [int]
file-format [int]
Same as write.

follow

Arguments

pitch [int]
Causes detonate to behave like a score reader, comparing incoming pitch information to the events stored in its score. When a key number is received in the 2nd (pitch) inlet, and it is the same as the pitch of the current note in the score, detonate sends out the information recorded for that event--except for the delta time--and then moves ahead to the next note event.

followat

Arguments

pitch [int]
velocity [int]
channel [int]
The word followat, followed by a pitch, a velocity, and a MIDI channel number, causes detonate to look for a note event with those attributes in its stored score. If such a note is found, detonate commences score-following from the next event onward. If not, it simply prints detonate: note not found in the Max Console.

import

Arguments

filename [list]
Same as read.

mute

Arguments

event-parameter [int]
parameter-value [int]
mute-flag [int]
Permits the selective muting of note events that meet specific criteria. The word mute must be followed by an event parameter number, a parameter value, and a value of 1 or 0 signifying "mute" or "unmute".

next

Once playback of the score has been started with a start message, next sends out the event information (except the delta time) for the current note in the score, then sends out the delta time for the next note. That delta time can in turn be used as a delay time before sending another next message to detonate. When next is received on the last note of the score, there is no note following that one, so a unique value of -1 is sent out the left outlet to signal the end of the score. If a next message is received while the score is not being played back, detonate simply prints the message not playing in the Max Console.

nth

Arguments

event [int]
The word nth, followed by a number, sends out the note information of the event in the score indicated by the number. (Events are numbered beginning with 0.) In place of the delta time for the event, the (cumulative) starting time of the event is sent out the left outlet.

open

See the (mouse) message.

params

Arguments

tolerance [int]
advance [int]
octave-match [int]
The word params, followed by three numbers, modifies the score-following behavior of detonate for cases when the received pitch does not match the pitch of the current note in the score. The first number tells detonate how many errors to tolerate before moving ahead in the score. The second number tells how many milliseconds to move ahead in the score when too many errors have occurred. The third number, if non-zero, tells detonate to treat a received pitch that is an octave too high or too low as if it were a match. For example, the message params 3 1000 1 means to allow three successive errors (with octave displacements considered to be a match) before moving ahead one second in the score and resuming. By default, detonate allows 2 errors before moving ahead 200 milliseconds, and does not consider octave pitch displacements to be a match for the stored note.

read

Arguments

filename [list]
The word read by itself opens a dialog for loading in a standard MIDI file as contents of the detonate score. If read is followed by the name of a MIDI file in Max's search path, that file is read in directly without opening a dialog box. The read message can also be followed by a number which--if non-zero--causes the time values in the file to be interpreted as milliseconds rather than as bars, beats and ticks at a certain tempo. If the number is 0 or not present, the times are read as bars and beats.

record

In left inlet: Begins recording numbers coming in the inlets, treating them as parameters of note events to be recorded. The onset of an event is recorded each time a number is received in the left inlet.

restore

Same as record.

setparam

Arguments

parameter [number]
name [symbol]
display-mode [int]
minimum [int]
maximum [int]
default [int]
interval [int]
scaling [int]
note-number [int]
The message setparam followed by nine list elements will set the parameters of the object much like entering the information into the object's inspector. The first element in the list is a number and signifies which parameter to edit. The remaining elements are the desired settings listed, from left to right, as the "parameter name", the "display mode", the "minimum value", the "maximum value", the "default value", the "graph interval", the "default scaling", and the "Display MIDI note number" flag.

start

Begins playing back the score, by simply sending out the first delta time. Once playback of the score has been started, next messages can be used to send out the next event information.

startat

Arguments

pitch [int]
velocity [int]
channel [int]
The word startat, followed by a pitch, a velocity, and a MIDI channel number, causes detonate to look for a note event with those attributes in its stored score. If such a note is found, detonate sends out the delta time of the next event, and a subsequent next message will refer to that next event. If no such note is found, detonate simply prints detonate: note not found in the Max Console.

stop

Stops detonate from recording, playing, or following. It is not necessary to stop detonate before switching directly between record, start, and follow.

unmute

Arguments

parameter [int]
value [int]
The word unmute, followed by an event parameter number and a parameter value, undoes an earlier mute of the same criterion. For example, unmute 4 10 has the same meaning as mute 4 10 0.

unmuteall

Undoes the effects of all previous mute messages.

wclose

Closes a previously opened editing window.

write

Arguments

filename [symbol]
time [int]
file-format [int]
Opens a dialog for saving the contents of detonate as a standard MIDI file. The word write may optionally be followed by up to two numbers. If the first number is non-zero, the file will be saved with time represented in milliseconds rather than as bars, beats, and ticks in a certain tempo. If the number is 0 or not present, the file is saved as beats. The second number indicates the MIDI file format: 0 (all notes on a single track) o multi-track format, using the track parameter to separate the notes). The contents of detonate are also saved as part of the patch, when the patch is saved.

writemax

Arguments

filename [symbol]
The message writemax followed by a symbol, saves the patch as a Max text file named after the symbol.

Output

int

Out left outlet: When a start, startat, or subsequent next message is received in the left inlet, the delta time of the next note event is sent out. When the last event in the score is played by a next message, there is no note following that one, so a unique delta time of -1 is sent out to signal that the last note has been played.

When an nth message is received in the left inlet (or an int if detonate is stopped), the starting time of the specified note is sent out.

Out 2nd outlet: In response to an nth message, or an int while detonate is stopped, or a next message while playing back, or a matched pitch while following, the pitch of the note is sent out.

Out 3rd outlet: The velocity of the note.

Out 4th outlet: The duration of the note.

Out 5th outlet: The MIDI channel of the note.

Out 6th outlet: The track number of the note.

Out 7th outlet: An extra value associated with the note.

Out right outlet: A second extra value associated with the note.

See Also

Name Description
follow Compare a live performance to a recorded performance
seq Sequencer for recording and playing MIDI data