1title:: Pattern Guide 08: Event Types and Parameters 2summary:: Describes the event types defined in the default event, and the parameters they expect 3related:: Tutorials/A-Practical-Guide/PG_07_Value_Conversions, Tutorials/A-Practical-Guide/PG_Cookbook01_Basic_Sequencing 4categories:: Streams-Patterns-Events>A-Practical-Guide 5 6section::Event types 7 8A common question is, "Which parameters have special meanings in Pbind?" Perhaps surprisingly, none of them do! That's because Pbind simply puts data into the result event; it doesn't care what the data are. 9 10The event prototype used when playing the pattern defines the actions to take, and it is here that parameters are defined. Most patterns will play using the default event prototype ( code::Event.default:: ), so this is the source of the parameters that will most typically be used. 11 12The default event prototype defines a number of "event types," each of which performs a different task. The code::\type:: key determines which action is taken, and the significant parameters depend on the event type. 13 14There are a lot of event types! However, only a few are commonly used. The code::\note:: event type is by far the most typical. The others are auxiliary, and most useful when writing patterns to generate a link::Classes/Score:: suitable for non-real-time rendering. 15 16Before looking at the event types themselves, let's go over some standard parameters used across many event types. (Not every common parameter is used in every event type, but these turn up in lots of places.) 17 18section::Common parameters 19 20subsection::Timing control 21 22definitionList:: 23## \delta || Number of strong::beats:: until the next event. Calculated from code::~dur * ~stretch::, if code::\delta:: is not given explicitly. 24## \lag || Number of strong::seconds:: to delay the event's server message(s). 25## \timingOffset || Number of strong::beats:: to delay the event's server message(s). In conjunction with link::Classes/Quant::, this allows control over the order of event preparation between different patterns in the client, without desynchronizing sonic events that should play together. link::Tutorials/A-Practical-Guide/PG_06g_Data_Sharing:: has an example of its use to pass data from a bass pattern to a chord pattern. 26 27## \sustain || Number of beats to wait before releasing a Synth node on the server. The SynthDef must have a code::gate:: argument for the explicit release to be sent; otherwise, the pattern assumes the note will release itself using a timed envelope. code::\sustain:: is calculated from code::~dur * ~legato * ~stretch:: if not given directly. 28 29## \sendGate || The default behavior for releasing a note is to look in the link::Classes/SynthDesc:: for an argument called \gate. If it's present, the event will send a code::node.set(\gate, 0):: message to the server. If not, no release will be sent; it's assumed that the SynthDef will release itself after a given length of time. code::\sendGate:: overrides this behavior: code::true:: means to force the release message to be sent, whether or not the argument exists, while code::false:: means to suppress the release message. 30 31It isn't typical use to override; nonetheless, for some special cases, it may be useful. 32 33## \tempo || Optional. If a value is given (in beats per second), it will change the tempo of the TempoClock playing the pattern. Here, the note duration is constant but the clock's speed changes. 34 35note::Changing the tempo will affect all patterns playing on the same clock.:: 36 37code:: 38Pbind( 39 \curve, Pseg(Pseq([0, 1, 0], 1), 15), 40 \degree, Pwhite(-7, 0, inf) + Pkey(\curve).linlin(0, 1, 0, 14).asInteger, 41 \dur, 0.5, 42 \tempo, Pkey(\curve).linlin(0, 1, 1, 10) 43).play; 44:: 45:: 46 47subsection::Node control 48 49definitionList:: 50## \addAction || How to add a synth or group node relative to the given code::\group:: in the event. See link::Classes/Synth::. 51## \amp || Not formally defined as a special parameter, but this is typically used for Synth amplitude. The SynthDef should have an code::amp:: argument and use it to control volume. code::\amp:: is optionally calculated from code::\db::. 52## \id || The desired id(s) for newly created Nodes in this event. Normally this is code::nil::, in which case the IDs will be obtained from code::server.nextNodeID::. 53## \instrument || The link::Classes/SynthDef:: name for which nodes will be created. Only one name should be given (unlike other arguments, which "multichannel expand" to create multiple nodes). 54## \group || The target node relative to which new node(s) will be created. Similar to code::target:: in code::Synth(defName, args, target, addAction)::. 55## \out || Generally used for the output bus of a link::Classes/Synth::. When using link::Classes/Pbus:: or link::Classes/Pfxb::, an audio bus is allocated to isolate the pattern's signal. All events from the pattern receive the new bus number in the code::\out:: slot, and SynthDefs being played should use an code::out:: argument for the target of output UGens, e.g., code::Out.ar(out, ...):: . 56:: 57 58subsection::User function hooks 59 60definitionList:: 61## \finish || A function that will be executed after code::play:: has been called, but before event type processing. Use this to manipulate event data. 62## \callback || A function that will be executed after the Event has finished all its work. The code::callback:: may be used for bookkeeping. Finished Events are expected to store new node IDs under code::~id::; with the IDs, you can register functions to watch node status or set node controls, for instance. The function receives the finished event as its argument. 63:: 64 65section::Event Types 66 67subsection::Node control 68 69definitionList:: 70## rest || As one would expect, a code::\rest:: does nothing except wait the required amount of time until the next event. 71 72## note || This is the default event type, used when code::\type:: is not specified. It plays one or more Synth nodes on the server, with an automatic release after code::\sustain:: beats if the SynthDef has a code::gate:: argument. 73definitionList:: 74## Standard Timing and Node control arguments || 75## sendGate || Override SynthDef behavior for the code::gate:: argument. If the SynthDef as code::gate::, setting code::sendGate = false:: prevents the release message from being sent. Rarely used. 76## strum || If multiple notes are produced (usually a chord, given by providing an array to one of the pitch parameters), code::\strum:: is the number of beats to delay each successive note onset. When using code::\strum::, another key is active, code::\strumEndsTogether::. If false (the default), each strummed node will play for its full duration and the releases will be staggered. If true, the releases will occur at the same time. 77 78code:: 79p = Pbind( 80 // array is "multichannel expanded" into one Synth each 81 \degree, #[2, 5, 8, 11, 13, 16], 82 \octave, 3, 83 \dur, 2, 84 \sustain, 3, 85 // non-zero strum staggers the entrances 86 \strum, 0.12 87).play(quant: 2); 88 89p.stop; 90:: 91:: 92 93## on || Start a Synth node (or nodes) without releasing. The node ID(s) are in the event's code::~id:: variable. Those IDs can be used with the off, set and kill event types. 94definitionList:: 95## Standard Timing and Node control arguments || 96## (sendGate and strum parameters are not used) || 97:: 98 99## off || Release server nodes nicely if possible. If the SynthDef has a code::gate:: argument, the gate will be set to code::0:: or a user-specified value. Otherwise, the nodes are brutally killed with code::n_free::. 100definitionList:: 101## Standard Timing control arguments || 102## hasGate || True or false, telling the event whether the SynthDef has a code::gate:: argument or not. The default is assumed true. 103## id || The node ID(s) must be given explicitly. 104## gate || By default, the gate will be set to code::0::. Negative values trigger a "forced release" in EnvGen. See the link::Classes/EnvGen:: help file for details. 105:: 106 107## kill || Immediately remove nodes using code::n_free::. 108definitionList:: 109## Standard Timing control arguments || 110## id || The node ID(s) must be given explicitly. 111:: 112 113## set || Send new values to the control inputs of existing nodes. 114definitionList:: 115## Standard Timing control arguments || 116## id || The node ID(s) must be given explicitly. This may be an integer ID or Synth/Group node object. 117:: 118:: 119 120There are two ways to specify argument names: by emphasis::instrument:: and by emphasis::argument array::. 121 122- emphasis::By instrument:: : 123 124definitionList:: 125## instrument || The SynthDef name should be given again, so that the event knows which event values are relevant for the nodes. 126## args || By default, the code::\args:: key contains the control names for the default synthdef. To take argument names from the instrument name, you must override this default with an empty array (or any non-collection object). 127 128code:: 129( 130SynthDef(\event_set, { |freq = 440, gate = 1, amp = 0.1, lagTime = 0.1, 131 ffreq = 2000, detune = 1.005, out = 0| 132 var sig = Saw.ar(Lag.kr(freq, lagTime) * [1, detune]).sum * amp 133 * EnvGen.kr(Env.adsr, gate, doneAction: Done.freeSelf); 134 Out.ar(out, sig ! 2); 135}).add; 136) 137 138a = Synth(\event_set); 139 140( 141p = Pbind( 142 \type, \set, 143 \id, a, 144 \instrument, \event_set, 145 \args, #[], 146 \freq, Pexprand(200, 600, inf), 147 \dur, Pwhite(1, 5, inf) * 0.125 148).play; 149) 150 151p.stop; 152a.free; 153:: 154:: 155 156- emphasis::By argument names:: : 157 158definitionList:: 159## args || Provide a list of the Synth argument names as an array here, e.g. code::[\freq, \amp, \pan]::. There is no need to provide the instrument name this way. 160 161code:: 162a = Synth(\event_set); 163 164( 165p = Pbind( 166 \type, \set, 167 \id, a, 168 \args, #[\freq], 169 \freq, Pexprand(200, 600, inf), 170 \dur, Pwhite(1, 5, inf) * 0.125 171).play; 172) 173 174p.stop; 175a.free; 176:: 177:: 178 179definitionList:: 180## monoNote || 181## monoOff || 182## monoSet || These event types are used internally by Pmono and PmonoArtic. They should not be used directly. 183:: 184 185subsection::Server control 186 187definitionList:: 188## group || Create a new group (or groups). 189definitionList:: 190## Standard Timing and Node control arguments || 191## id || (Optional) IDs for the new groups. If not specified, the new ID (for one group only) can be found in the event after code::.play::. To create multiple groups, you must provide an array of IDs. 192:: 193 194## bus || Set the value of a control bus, or contiguous control buses. This assumes that you already have the bus index. 195definitionList:: 196## Standard Timing control arguments || 197## array || The value(s) to send to the bus(es). If it's only one value, it doesn't have to be an array. 198## out || The first bus index to be set. A Bus object can be used. 199:: 200:: 201 202subsection::Buffer control 203 204All of these buffer event types expect the buffer number to be provided. They will not automatically get a buffer number from the server's buffer allocator. A Buffer object is allowed -- you could create the Buffer first using code::Buffer.alloc:: or code::Buffer.new:: and then use this object in the control events. See also link::#Event types with cleanup:: below for other, user-friendlier Buffer control options. 205 206definitionList:: 207## alloc || Allocate memory for a buffer on the server. Only one buffer may be allocated per event. 208definitionList:: 209## Standard Timing control arguments || 210## bufnum, numchannels, numframes || See the link::Classes/Buffer:: help file. 211:: 212 213## free || Deallocate the buffer's memory on the server. 214definitionList:: 215## Standard Timing control arguments || 216## bufnum || Buffer number to free (one only). 217:: 218 219## gen || Generate wavetable data in the buffer, using one of the server's code::b_gen:: plug-ins. The link::Classes/Buffer:: help file has more detail on the standard plug-ins. 220definitionList:: 221## Standard Timing control arguments || 222## bufnum || 223## gencmd || The generator plug-in name: code::\sine1::, code::\sine2::, code::\sine3::, code::\cheby::. 224## genflags || Three flags, associated with numbers: normalize = code::1::, asWavetable = code::2::, clearFirst = code::4::. Add the numbers for the desired flags. Normally the flags are all true, adding up to code::7::. 225## genarray || Data parameters for the plug-in. See the link::Reference/Server-Command-Reference:: help file for details on the format for each plug-in. 226:: 227 228## load || Allocate buffer memory in the server and load a sound file into it, using code::b_allocRead::. 229definitionList:: 230## Standard Timing control arguments || 231## bufnum || 232## filename || Path to disk file. 233## frame || Starting frame to read (default code::0::). 234## numframes || Number of frames to read (default code::0::, which loads the entire file). 235:: 236 237## read || Read a sound file into a buffer already allocated on the server. This event type is good to cue a sound file for use with DiskIn. 238definitionList:: 239## Standard Timing control arguments || 240## bufnum || 241## filename || Path to disk file. 242## frame || Starting soundfile frame to read (default code::0::). 243## numframes || Number of frames to read (default code::0::, which loads the entire file). 244## bufpos || Starting buffer frame (default code::0::). 245## leaveOpen || code::1:: = leave the file open (for link::Classes/DiskIn:: use). code::0:: = close the disk file after reading. Default = code::0::. 246:: 247:: 248 249subsection::Event types with cleanup 250 251These event types uniquely have automatic cleanup event types associated with them. Playing one of these event types allocates a server resource. Later, the resource may be freed by changing the event type to the corresponding cleanup type and playing the event again. While the resource is active, the event can be used as a reference to the resource in other events or Synth messaging. 252 253code:: 254// create a buffer 255b = (type: \allocRead, path: Platform.resourceDir +/+ "sounds/a11wlk01.wav").play; 256 257a = { PlayBuf.ar(1, b, doneAction: Done.freeSelf) }.play; 258 259// remove buffer 260EventTypesWithCleanup.cleanup(b); 261:: 262 263See the Pproto example in link::Tutorials/A-Practical-Guide/PG_06f_Server_Control::, showing how these can be used to clean up server objects at the end of a pattern. 264 265definitionList:: 266## audioBus || Allocate an audio bus index from the server. 267definitionList:: 268## channels || Number of channels to allocate. 269:: 270 271## controlBus || Allocate a control bus index from the server. 272definitionList:: 273## channels || Number of channels to allocate. 274:: 275 276## buffer || Allocate a buffer number if not specified, and reserve the memory on the server. 277definitionList:: 278## bufNum || (Optional) Buffer number. If not given, a free number will be obtained from the server. 279## numBufs || Number of contiguous buffer numbers to reserve (default = code::1::). 280## numFrames || Number of frames. 281## numChannels || Number of channels. 282:: 283 284## allocRead || Read a disk file into server memory. The file is closed when finished. 285definitionList:: 286## bufNum || (Optional) Buffer number. If not given, a free number will be obtained from the server. 287## path || Path to the sound file on disk. 288## firstFileFrame || Where to start reading in the file. 289## numFrames || Number of frames. If not given, the whole file is read. 290:: 291 292## cue || Cue a sound file (generally for use with DiskIn). 293definitionList:: 294## bufNum || (Optional) Buffer number. If not given, a free number will be obtained from the server. 295## path || Path to the sound file on disk. 296## firstFileFrame || Where to start reading in the file. 297## numFrames || Number of frames. If not given, the whole file is read. 298## firstBufferFrame || Where in the buffer to start putting file data. 299## leaveOpen || code::1:: = leave the file open (for link::Classes/DiskIn:: use). code::0:: = close the disk file after reading. Default = code::0::. 300:: 301 302## table || Fill a buffer with preset data. This uses code::/b_setn:: to transfer the data, so all of the data must fit into one datagram. It may take some experimentation to find the upper limit. 303definitionList:: 304## bufNum || (Optional) Buffer number. If not given, a free number will be obtained from the server. 305## amps || The values to put into the buffer. These should all be Floats. 306:: 307 308## cheby || Generate a Chebyshev transfer function for waveshaping. 309definitionList:: 310## bufNum || (Optional) Buffer number. If not given, a free number will be obtained from the server. 311## numFrames || Number of frames, should be a power of 2. 312## numChannels || Number of channels. 313## genflags || Three flags, associated with numbers: normalize = code::1::, asWavetable = code::2::, clearFirst = code::4::. Add the numbers for the desired flags. Normally the flags are all true, adding up to code::7::. 314## amps || The amplitude of each partial (i.e., polynomial coefficient). 315:: 316 317## sine1 || Mirrors the code::sine1:: method for link::Classes/Buffer::, generating a wavetable with an integer-multiple harmonic spectrum using the given partial amplitudes. 318definitionList:: 319## bufNum || (Optional) Buffer number. If not given, a free number will be obtained from the server. 320## numFrames || Number of frames, should be a power of 2. 321## numChannels || Number of channels. 322## genflags || See above. 323## amps || Array of amplitudes for each partial. 324:: 325 326## sine2 || Like strong::sine1::, but the frequency ratio of each partial is also given. 327definitionList:: 328## Same arguments as sine1, plus: || 329## freqs || Array of frequencies for each partial. code::1.0:: is the fundamental frequency; its sine wave occupies the entire buffer duration. 330:: 331 332## sine3 || Like strong::sine2::, but the phase of each partial may also be provided. 333definitionList:: 334## Same arguments as sine1, plus: || 335## phases || Array of phases for each partial, given in radians (0.0 - 2pi). 336:: 337:: 338 339subsection::MIDI output 340 341definitionList:: 342## midi || Sends one of several types of MIDI messages to a MIDIOut object. 343definitionList:: 344## Standard Timing control arguments (except timingOffset, which is not used) || 345## midicmd || The type of MIDI message to send. This also determines other arguments that should be present in the event. 346## midiout || The MIDI out object, which connects to one of the MIDI devices listed in code::MIDIClient.destinations::. 347## chan || The MIDI channel number (0-15) on the device that should receive the message. This applies to all midicmds except the global ones ( strong::smpte::, strong::songPtr::, strong::sysex:: ). 348:: 349:: 350 351definitionList:: 352## Available midicmds: || 353 354definitionList:: 355## noteOn || Starts a note, and optionally stops it. If multiple frequencies are given, one noteOn/noteOff pair is sent for each, and code::\strum:: is also supported. 356definitionList:: 357## chan || MIDI channel (0-15). 358## midinote || Note number to trigger. This may be calculated from the standard pitch hierarchy described in link::Tutorials/A-Practical-Guide/PG_07_Value_Conversions:: (with the exception that only 12TET can be supported). 359## amp || code::MIDI velocity = amp / 12::. 360## sustain || How many beats to wait before sending the corresponding note off message. If not given directly, it's calculated as code::~sustain = ~dur * ~legato * ~stretch:: (just like the standard code::\note:: event type). 361## hasGate || Normally true. If false, the note off message will not be sent. 362:: 363 364## noteOff || Send an explicit note off message (useful if strong::hasGate:: is set false in the note on event). 365definitionList:: 366## chan || MIDI channel (0-15). 367## midinote || Note number. 368## amp || Release velocity (supported by some synthesizers). 369:: 370 371## allNotesOff || "Panic" message, kills all notes on the channel. 372definitionList:: 373## chan || MIDI channel (0-15). 374:: 375 376## control || Continuous controller message. 377definitionList:: 378## chan || MIDI channel (0-15). 379## ctlNum || Controller number to receive the new value. 380## control || New value (0-127). 381:: 382 383## bend || Pitch bend message. 384definitionList:: 385## chan || MIDI channel (0-15). 386## val || New value (0-16383). 8191 is centered. 387:: 388 389## touch || Aftertouch message. 390definitionList:: 391## chan || MIDI channel (0-15). 392## val || New value (0-127). 393:: 394 395## polyTouch || Poly aftertouch message (not supported by all synthesizers). 396definitionList:: 397## chan || MIDI channel (0-15). 398## midinote || Note number to get the new after touch value. As in note on, it may be calculated from the standard pitch hierarchy. 399## polyTouch || New value (0-127). 400:: 401 402## program || Program change message. 403definitionList:: 404## chan || MIDI channel (0-15). 405## progNum || Program number (0-127). 406:: 407 408## smpte || Send MIDI Time Code messages. 409definitionList:: 410## Arguments || frames, seconds, minutes, hours, frameRate 411:: 412 413## songPtr || Song pointer message. 414definitionList:: 415## songPtr || Pointer value (0-16383). 416:: 417 418## sysex || System exclusive messages. 419definitionList:: 420## array || An link::Classes/Int8Array:: with the sysex bytes in order. 421note:: 422Very important: Arrays normally multi-channel expand in patterns. So, you must wrap the Int8Array inside another array to prevent this. Write code::[Int8Array[...]]::, not just code::Int8Array[...]::. 423:: 424:: 425:: 426:: 427 428subsection::Miscellaneous 429 430definitionList:: 431## composite || Perform any number of event types, given as ~types. You should ensure that parameters are compatible. It is possible, using code::\composite::, to play a synth and send MIDI for the same pitches. It is not possible to use one frequency for the synth and a different one for MIDI, in the same event (you would need two different events for that case). 432 433definitionList:: 434## types || An array of Symbols, listing the Event types to be performed. 435:: 436 437code:: 438MIDIClient.init; 439m = MIDIOut(0); 440 441// should play a synth *and* an external MIDI note simultaneously 442(type: \composite, types: [\note, \midi], midiout: m, degree: 0, dur: 3).play; 443:: 444 445## phrase || See link::Tutorials/JITLib/recursive_phrasing::. 446 447## setProperties || Set variables belonging to a given object. One possible use is to control a GUI using a pattern. 448definitionList:: 449## receiver || The object to be modified. 450## args || The list of variable names to set in the receiver. The receiver should have a setter method -- variableName_ -- for each of these. New values will be looked up in the event. 451:: 452 453code:: 454// Visualize Brownian motion 455w = Window("Brownian motion", Rect(10, 100, 500, 50)); 456x = Slider(w, Rect(10, 15, 480, 20)); 457w.front; 458 459p = Pbind( 460 \type, \setProperties, 461 \receiver, x, 462 // this means, call x.value_() on every event 463 \args, [\value], 464 // and look for the value under \value 465 \value, Pbrown(0, 1, 0.1, inf), 466 \delta, 0.1 467).play; 468 469p.stop; 470:: 471:: 472 473Previous: link::Tutorials/A-Practical-Guide/PG_07_Value_Conversions:: 474 475Next: link::Tutorials/A-Practical-Guide/PG_Cookbook01_Basic_Sequencing:: 476