?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
cmake build system: visiblity support for clang
[supercollider.git] / Help / Collections / Event.html
blobb924909a23db5a1ef308d4d001afa8a650a9fdb1
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <meta http-equiv="Content-Style-Type" content="text/css">
6 <title></title>
7 <meta name="Generator" content="Cocoa HTML Writer">
8 <meta name="CocoaVersion" content="1038.25">
9 <style type="text/css">
10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #0000ee}
13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica; min-height: 17.0px}
14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; min-height: 16.0px}
16 p.p7 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #bf0000}
17 p.p8 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco}
18 p.p9 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; min-height: 12.0px}
19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000; min-height: 12.0px}
20 p.p11 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica}
21 p.p12 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 12.0px Helvetica}
22 p.p13 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 12.0px Helvetica; min-height: 14.0px}
23 p.p14 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 9.0px Monaco}
24 p.p15 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 14.0px Helvetica; min-height: 17.0px}
25 p.p16 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 9.0px Monaco; min-height: 12.0px}
26 p.p17 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #0000bf; min-height: 14.0px}
27 p.p18 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
28 p.p19 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0000bf}
29 p.p20 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
30 p.p21 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
31 span.s1 {font: 18.0px Helvetica}
32 span.s2 {color: #000000}
33 span.s3 {color: #0000bf}
34 span.s4 {color: #007300}
35 span.s5 {font: 12.0px Monaco}
36 span.s6 {color: #bf0000}
37 span.s7 {color: #606060}
38 span.s8 {font: 12.0px Helvetica}
39 span.s9 {font: 9.0px Monaco}
40 span.s10 {text-decoration: underline ; color: #0000bf}
41 span.Apple-tab-span {white-space:pre}
42 </style>
43 </head>
44 <body>
45 <p class="p1"><span class="s1"><b>Event</b></span><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>an environment that represents an action</b></p>
46 <p class="p2"><br></p>
47 <p class="p3"><span class="s2"><b>Inherits from: </b><a href="../Core/Object.html"><b>Object</b></a><b> : </b><a href="Collection.html"><b>Collection</b></a><b> : </b><a href="Set.html"><b>Set</b></a><b> : </b><a href="Dictionary.html"><b>Dictionary</b></a><b> : </b><a href="IdentityDictionary.html"><b>IdentityDictionary</b></a><b> : </b><a href="Environment.html"><b>Environment</b></a></span></p>
48 <p class="p1"><b>Related classes: </b><a href="../Streams-Patterns-Events/Patterns/Pattern.html"><span class="s3"><b>Pattern</b></span></a></p>
49 <p class="p4"><br></p>
50 <p class="p1">An Event is an Environment that specifies an action to be taken in response to a <b>play </b>message. The key/value pairs within the Event specify the parameters of that action. Most methods, Event inherits from its superclasses, especially from <a href="Dictionary.html"><span class="s3">Dictionary</span></a>.</p>
51 <p class="p2"><br></p>
52 <p class="p2"><br></p>
53 <p class="p5"><b>Basic Usage:</b></p>
54 <p class="p2"><br></p>
55 <p class="p1">Events can be written as a series of key value pairs enclosed in parentheses.<span class="Apple-converted-space">  </span>Empty parentheses will create an empty event. They may be also used for object prototyping – <a href="Environment.html"><span class="s3">Environment</span></a> for more details.</p>
56 <p class="p2"><br></p>
57 <p class="p1"><b>Event as a name space for keeping objects:</b></p>
58 <p class="p2"><br></p>
59 <p class="p1">Because of this simple syntax, Events are often used as name space for keeping objects:</p>
60 <p class="p6"><br></p>
61 <p class="p7"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// using an event to store values</p>
62 <p class="p8"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>q = (n: 10, x: [1, 2, 3]);</p>
63 <p class="p7"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>q[</span><span class="s4">\y</span><span class="s2">] = q[</span><span class="s4">\x</span><span class="s2">] * q[</span><span class="s4">\n</span><span class="s2">]; </span>// similar to ~y = ~x * ~n, but in a separate name space</p>
64 <p class="p7"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>q.y = q.x * q.n;<span class="Apple-converted-space">  </span></span>// shorter way to do the same (pseudo-methods)</p>
65 <p class="p7"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>q.y; </span>// [ 100, 200, 300 ]</p>
66 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
67 <p class="p2"><br></p>
68 <p class="p1"><b>Event for specifying different things to happen:</b></p>
69 <p class="p2"><br></p>
70 <p class="p1">Event provides a <b>defaultParentEvent</b> that defines a variety of different event types and provides a complete set of default key/value pairs for each type. The type is determined by the value of the <span class="s5">key</span><b> \type</b><span class="s5"> </span>which defaults to <b>\note</b>. Note events create synths on the server.</p>
71 <p class="p6"><br></p>
72 <p class="p7"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>( ).play;<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// the default note</p>
73 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
74 <p class="p8"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(freq: 500, pan: -1) .play;<span class="Apple-tab-span"> </span><span class="s6">// 500 Hz, panned left</span></p>
75 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
76 <p class="p8"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(play: { ~what.postln }, what: <span class="s7">"hello happening"</span>).play; <span class="s6">// something else</span></p>
77 <p class="p10"><br></p>
78 <p class="p1">Per default, the play message derives its behaviour from the defaultParentEvent, which provides many default values, such as default instrument (\default), note (0), legato (0.8) and so on. Depending on the event type, these may differ completely and need not even represent a sound.</p>
79 <p class="p4"><br></p>
80 <p class="p5"><b>Class variables</b></p>
81 <p class="p2"><br></p>
82 <p class="p11"><b><span class="Apple-tab-span"> </span>defaultParentEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>the default event used in most cases</p>
83 <p class="p11"><b><span class="Apple-tab-span"> </span>parentEvents<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>an IdentityDictionary of useful parent events</p>
84 <p class="p11"><b><span class="Apple-tab-span"> </span>partialEvents<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>an IdentityDictionary of Events that define the default values and functions</p>
85 <p class="p11"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>for different aspects of note generation (timing, volume, pitch, server to use, etc)</p>
86 <p class="p2"><br></p>
87 <p class="p5"><b>Creation / Class Methods</b></p>
88 <p class="p2"><br></p>
89 <p class="p12"><b><span class="Apple-tab-span"> </span>*new(n, proto, parent, know = true)<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></p>
90 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>create an event with initial size <b>n</b>.</p>
91 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>proto</b> may be provided as another event which is used to <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><i>override</i> keys in the event.</p>
92 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>parent</b> may be provided as another event which is used to <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><i>provide default</i> keys for the event without modifying it.</p>
93 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>If <b>know</b> is set to true, the event will respond to appropriate message calls. See <a href="Environment.html"><span class="s3">Environment</span></a> for more details.</p>
94 <p class="p12"><b><span class="Apple-tab-span"> </span>*default<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></p>
95 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>returns an empty event with defaultParentEvent as parent</p>
96 <p class="p13"><b><span class="Apple-tab-span"> </span></b></p>
97 <p class="p12"><b><span class="Apple-tab-span"> </span>*silent (dur)<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></p>
98 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>returns an event that describes a pause of <b>dur</b> duration.</p>
99 <p class="p13"><b><span class="Apple-tab-span"> </span></b></p>
100 <p class="p12"><b><span class="Apple-tab-span"> </span>*addEventType(type, func)</b></p>
101 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>Event types define alternate play functions that are selected by the value of <b>~type</b></p>
102 <p class="p2"><br></p>
103 <p class="p2"><b><span class="Apple-tab-span"> </span></b></p>
104 <p class="p1"><b>Methods</b></p>
105 <p class="p2"><b><span class="Apple-tab-span"> </span></b></p>
106 <p class="p1"><b><span class="Apple-tab-span"> </span>play<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></p>
107 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>play the event. This evaluates the function at \play (see example above).</p>
108 <p class="p12"><b><span class="Apple-tab-span"> </span>delta<span class="Apple-tab-span"> </span></b></p>
109 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>Returns the inter onset time – the time delay until the next event in a sequence. This usually depends on \dur and \stretch, but may be overridden by specifying \delta directly.</p>
110 <p class="p14"><span class="s8"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span><span class="s3">Pn</span>((dur: 2, freq:8000)).play;</p>
111 <p class="p13"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
112 <p class="p12"><b><span class="Apple-tab-span"> </span>next(inval)<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></p>
113 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>Combines an event given in the argument with the current event. This is used to enable events to be composed.</p>
114 <p class="p14"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(a: 6, b: 7).next((c: 100));</p>
115 <p class="p2"><span class="Apple-tab-span"> </span></p>
116 <p class="p12"><span class="Apple-tab-span"> </span><b>playAndDelta(cleanup, mute)<span class="Apple-tab-span"> </span></b></p>
117 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>used by <a href="../Streams-Patterns-Events/EventStreamPlayer.html"><span class="s3">EventStreamPlayer</span></a> to play Events and obtain a time increment</p>
118 <p class="p13"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
119 <p class="p12"><span class="Apple-tab-span"> </span><b>asUGenInput</b></p>
120 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>calls asControlInput.</p>
121 <p class="p13"><br></p>
122 <p class="p12"><b><span class="Apple-tab-span"> </span>asControlInput</b></p>
123 <p class="p12"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>Enables events to represent the server resources they created in an Event</p>
124 <p class="p13"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
125 <p class="p2"><br></p>
126 <p class="p2"><b><span class="Apple-tab-span"> </span></b></p>
127 <p class="p1"><b>Methods that allow Events to provide user control for </b><a href="../ServerArchitecture/Synth.html"><span class="s3"><b>Synth</b></span></a><span class="s3"><b>s</b></span><b> on </b><a href="../ServerArchitecture/Group.html"><span class="s3"><b>Group</b></span></a><span class="s3"><b>s</b></span></p>
128 <p class="p13"><b><span class="Apple-tab-span"> </span></b></p>
129 <p class="p12"><b><span class="Apple-tab-span"> </span>synth<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>makes the event a control interface to the resultant synth when played</p>
130 <p class="p12"><b><span class="Apple-tab-span"> </span>group<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>makes the event a control interface to the resultant group when played.</p>
131 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>This is experimental, does not work consistently yet.</p>
132 <p class="p13"><b><span class="Apple-tab-span"> </span></b></p>
133 <p class="p12"><b><span class="Apple-tab-span"> </span>stop<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>free the synth or group</p>
134 <p class="p12"><b><span class="Apple-tab-span"> </span>pause<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>pause the synth or group</p>
135 <p class="p12"><b><span class="Apple-tab-span"> </span>resume<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>resume the synth or group</p>
136 <p class="p12"><b><span class="Apple-tab-span"> </span>release<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>release the synth or group</p>
137 <p class="p12"><b><span class="Apple-tab-span"> </span>set(key1, val1, ....)<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>set a control value in the synth or group</p>
138 <p class="p15"><br></p>
139 <p class="p16"><br></p>
140 <p class="p14"><span class="Apple-tab-span"> </span>a = (note: 2).play;</p>
141 <p class="p14"><span class="Apple-tab-span"> </span>a.set(<span class="s4">\freq</span>, 700);</p>
142 <p class="p14"><span class="Apple-tab-span"> </span>a.release;</p>
143 <p class="p2"><br></p>
144 <p class="p2"><br></p>
145 <p class="p5"><b>Events and SynthDefs</b></p>
146 <p class="p17"><br></p>
147 <p class="p1">The key used to select what synthdef is to be played is <b>\instrument</b>.<span class="Apple-converted-space">  </span>In order to use a <a href="../ServerArchitecture/SynthDef.html"><span class="s3">SynthDef</span></a> with an Event, send it an <b>add</b> message. This creates a description of the SynthDef that the event can consult to determine its control names. The values of these names in the event are used when the event is played. (See <a href="../ServerArchitecture/SynthDesc.html"><span class="s3">SynthDesc</span></a><b> </b>for details.)</p>
148 <p class="p2"><br></p>
149 <p class="p18">(</p>
150 <p class="p19">SynthDef<span class="s2">(</span><span class="s4">\pm</span><span class="s2">, { </span>|out=0, freq=440, amp=0.1, pan=0, gate=1, ratio = 1, index = 1, ar = 0.1, dr = 0.1|</p>
151 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">var</span> z;</p>
152 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>z = <span class="s3">LPF</span>.ar(</p>
153 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">PMOsc</span>.ar(freq, freq * ratio, <span class="s3">Linen</span>.kr(gate, ar,index, dr), 0, 0.3),</p>
154 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">XLine</span>.kr(<span class="s3">Rand</span>(4000, 5000), <span class="s3">Rand</span>(2500, 3200), 1)</p>
155 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>) * <span class="s3">Linen</span>.kr(gate, 0.01, 0.7, dr, 2);</p>
156 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">OffsetOut</span>.ar(out, <span class="s3">Pan2</span>.ar(z, pan, amp));</p>
157 <p class="p18">}).add</p>
158 <p class="p18">);</p>
159 <p class="p20"><br></p>
160 <p class="p18">(instrument: <span class="s4">\pm</span>).play;</p>
161 <p class="p20"><br></p>
162 <p class="p18">(instrument: <span class="s4">\pm</span>, ratio: 3.42, index: 12, freq: 150, ar: 8, dr: 3, sustain: 10).play;</p>
163 <p class="p6"><br></p>
164 <p class="p6"><span class="Apple-tab-span"> </span></p>
165 <p class="p1"><b>note</b>: The use of <a href="../UGens/InOut/OffsetOut.html"><span class="s3">OffsetOut</span></a> in the SynthDef prevents irregularities that can result from the interaction of the timing of a sequence of notes and the control rate of the Server.</p>
166 <p class="p2"><br></p>
167 <p class="p2"><br></p>
168 <p class="p2"><br></p>
169 <p class="p5"><b>Multi-channel Expansion</b><span class="s9"><span class="Apple-tab-span"> </span></span></p>
170 <p class="p20"><br></p>
171 <p class="p1">If a key relevant to the action is assigned an <a href="Array.html"><span class="s3">Array</span></a>, the action is repeated on each element of the array:</p>
172 <p class="p20"><span class="Apple-tab-span"> </span></p>
173 <p class="p18">(degree: (0..12)).play<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">// a diatonic cluster</span></p>
174 <p class="p2"><br></p>
175 <p class="p1">If several keys are assigned arrays, the action is repeated for each element of the largest array.</p>
176 <p class="p1">Smaller arrays are rotated through repeatedly.<span class="Apple-converted-space">  </span>Here are some examples:</p>
177 <p class="p2"><br></p>
178 <p class="p21">// every other note of the diatonic cluster: stacked thirds</p>
179 <p class="p18">(degree: (0..12), amp: [0, 0.1]).play</p>
180 <p class="p2"><br></p>
181 <p class="p21">// every other note of the semitone cluster: a wholetone cluster again</p>
182 <p class="p18">(note: (0..12), amp: [0, 0.1]).play</p>
183 <p class="p2"><br></p>
184 <p class="p21">// every third note of the semitone cluster: a diminished chord</p>
185 <p class="p18">(note: (0..12), amp: [0, 0, 0.1]).play</p>
186 <p class="p20"><br></p>
187 <p class="p21">// the same with different sustain times</p>
188 <p class="p18">(note: (0..12), amp: [0, 0, 0.1], sustain:[0.1, 0.3, 1.3, 2.5]).play</p>
189 <p class="p20"><br></p>
190 <p class="p21">// timingOffset gives a tempo-relative offset time to each synth</p>
191 <p class="p18">(instrument: <span class="s4">\pm</span>, ratio: [2.3, 4.5, 1.7], timingOffset: [0, 1.2, 3], sustain: [0.2, 2, 1]).play;</p>
192 <p class="p20"><br></p>
193 <p class="p20"><br></p>
194 <p class="p2"><br></p>
195 <p class="p5"><b>Arrayed Arguments</b><span class="s9"><span class="Apple-tab-span"> </span></span></p>
196 <p class="p20"><br></p>
197 <p class="p1">It is possible to assign an array to one of a <a href="../ServerArchitecture/SynthDef.html"><span class="s3">SynthDef</span></a>'s control names. For example:</p>
198 <p class="p2"><br></p>
199 <p class="p19">(</p>
200 <p class="p19">SynthDef<span class="s2">(</span><span class="s4">\test</span><span class="s2">, { </span>| out = 0, amp = 0.01, freq = #[300,400,400], pan, gate = 1 |</p>
201 <p class="p18"><span class="Apple-tab-span"> </span><span class="s3">var</span> audio, env;</p>
202 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>audio = </span><span class="s3">Mix</span><span class="s2">.ar(</span><span class="s3">Pulse</span><span class="s2">.ar(freq, 0.5));<span class="Apple-tab-span"> </span></span>// this is a mixture of three oscillators</p>
203 <p class="p18"><span class="Apple-tab-span"> </span>env = <span class="s3">Linen</span>.kr(gate, susLevel: amp , doneAction: 2);<span class="Apple-converted-space">  </span><span class="s6">// envelope deletes the synt when done</span></p>
204 <p class="p18"><span class="Apple-tab-span"> </span>audio = audio * env;</p>
205 <p class="p18"><span class="Apple-tab-span"> </span><span class="s3">OffsetOut</span>.ar(0, audio );</p>
206 <p class="p18">}).add</p>
207 <p class="p18">);</p>
208 <p class="p20"><span class="Apple-tab-span"> </span></p>
209 <p class="p1">Within an event, arrayed arguments of this sort must be enclosed within an additional array to distinguish them from arguments intended for multi-channel expansion.</p>
210 <p class="p20"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
211 <p class="p21">// one synth, use enclosing array to prevent multi-channel expansion</p>
212 <p class="p18">(instrument: <span class="s4">\test</span>, note: [[0, 2, 4]]).play</p>
213 <p class="p20"><br></p>
214 <p class="p21">// two synths</p>
215 <p class="p18">(instrument: <span class="s4">\test</span>, note: [[0, 2, 4], [6, 8, 10]]).play</p>
216 <p class="p2"><br></p>
217 <p class="p2"><br></p>
218 <p class="p5"><b>Events and Patterns</b></p>
219 <p class="p2"><br></p>
220 <p class="p1">Events are closely integrated with the Patterns library.<span class="Apple-converted-space">  </span>Different patterns can be bound to different keys (or collections of keys) to specify the resultant music.<span class="Apple-converted-space">  </span>See the help<span class="Apple-converted-space">  </span>files <a href="../Streams-Patterns-Events/Patterns/Pattern.html"><span class="s10">Pattern</span></a> and <a href="../Streams-Patterns-Events/Patterns/Pbind.html"><span class="s10">Pbind</span></a> and the tutorials<span class="Apple-converted-space">  </span><a href="../Streams-Patterns-Events/Streams-Patterns-Events4.html"><span class="s10">Streams-Patterns-Events4</span></a> and <a href="../Streams-Patterns-Events/Streams-Patterns-Events5.html"><span class="s10">Streams-Patterns-Events5</span></a> for more details on Patterns.</p>
221 <p class="p2"><br></p>
222 <p class="p1">Patterns that return events may be played on a clock: dur specifies the time between two subsequent events.</p>
223 <p class="p2"><br></p>
224 <p class="p21">// Pseq returns one item in the list after the other</p>
225 <p class="p18">(</p>
226 <p class="p19">Pseq<span class="s2">([</span></p>
227 <p class="p18"><span class="Apple-tab-span"> </span>(note: 2, sustain: 1, dur: 1.5),<span class="Apple-converted-space"> </span></p>
228 <p class="p18"><span class="Apple-tab-span"> </span>(note: [5, 7], sustain: 0.5, dur: 0.8),<span class="Apple-converted-space"> </span></p>
229 <p class="p18"><span class="Apple-tab-span"> </span>(note: [2, 6], sustain: 1, dur: 0.8)</p>
230 <p class="p18">]).play</p>
231 <p class="p18">);</p>
232 <p class="p20"><br></p>
233 <p class="p21">// Pbind binds parameters to events:</p>
234 <p class="p18">(</p>
235 <p class="p19">Pbind<span class="s2">(</span></p>
236 <p class="p18"><span class="Apple-tab-span"> </span><span class="s4">\note</span>, <span class="s3">Pseq</span>([2, [5, 7], [2, 6]]),</p>
237 <p class="p18"><span class="Apple-tab-span"> </span><span class="s4">\sustain</span>, <span class="s3">Pseq</span>([1, 0.5, 1]),</p>
238 <p class="p18"><span class="Apple-tab-span"> </span><span class="s4">\dur</span>, <span class="s3">Pseq</span>([1.5, 0.8, 0.8])</p>
239 <p class="p18">).play</p>
240 <p class="p18">)</p>
241 <p class="p20"><br></p>
242 <p class="p21">// per-event timing may be specified:</p>
243 <p class="p18">(</p>
244 <p class="p19">Pbind<span class="s2">(</span></p>
245 <p class="p18"><span class="Apple-tab-span"> </span><span class="s4">\note</span>, <span class="s3">Pseq</span>([[0, 9], [5, 7], [2, 6]], <span class="s3">inf</span>),</p>
246 <p class="p18"><span class="Apple-tab-span"> </span><span class="s4">\sustain</span>, <span class="s3">Pseq</span>([1, 0.5, 1], <span class="s3">inf</span>),</p>
247 <p class="p18"><span class="Apple-tab-span"> </span><span class="s4">\dur</span>, <span class="s3">Pseq</span>([1.5, 0.8, 0.8], <span class="s3">inf</span>),</p>
248 <p class="p18"><span class="Apple-tab-span"> </span><span class="s4">\timingOffset</span>, <span class="s3">Pseq</span>([[0, 0.3], [0, 0.01]], <span class="s3">inf</span>)</p>
249 <p class="p18">).play</p>
250 <p class="p18">)</p>
251 <p class="p2"><br></p>
252 <p class="p2"><br></p>
253 <p class="p1">Here is an example that illustrates some more of the keys defined by the defaultParentEvent.</p>
254 <p class="p1">Note that it is equivalent to write Pbind(\key, val, ...) and Pbind(*[key: val, ...]).</p>
255 <p class="p2"><br></p>
256 <p class="p18">(</p>
257 <p class="p19">Pbind<span class="s2">(*[</span></p>
258 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>stepsPerOctave:<span class="Apple-tab-span"> </span><span class="s3">Pstep</span>(<span class="s3">Pseq</span>((2..12).mirror, <span class="s3">inf</span>),12), <span class="s6">// 3 - 12 tone e.t. scales</span></p>
259 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>note:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">Pseq</span>((0..12).mirror, <span class="s3">inf</span>),<span class="Apple-tab-span"> </span><span class="s6">// play full notes up and down</span></p>
260 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>ctranspose:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">Pwhite</span>(-0.2, 0.2),<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">// detune up to +-20 cents</span></p>
261 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>detune:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">Pwhite</span>(-1.0, 1.0),<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">// detune up to 1 Hz<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span></p>
262 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>sustain:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">Prand</span>([0.2, 0.2, 0.2, 4], <span class="s3">inf</span>), <span class="Apple-tab-span"> </span><span class="s6">// notes last 0.2 or 4 seconds</span></p>
263 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// 1 in 6 chance waits 0.8 seconds:</p>
264 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>dur:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">Prand</span>([0.2, 0.2, 0.2, 0.2, 0.2, 0.8], <span class="s3">inf</span>),</p>
265 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>db:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">Pstep</span>(<span class="s3">Pseq</span>([-15, -25, -20, -25], <span class="s3">inf</span>), 0.8)<span class="s6">// 4 beat accent structure</span></p>
266 <p class="p18"><span class="Apple-tab-span"> </span>]).play<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
267 <p class="p18">)</p>
268 <p class="p4"><br></p>
269 <p class="p5"><b>Event's play method</b></p>
270 <p class="p2"><br></p>
271 <p class="p1">When an Event<span class="Apple-converted-space">  </span>(or any other <a href="Environment.html"><span class="s3">Environment</span></a>) receives a <span class="s5">use(function)</span> message, it sets itself to be currentEnvironment, evaluates the function, and restores the original value of currentEnvironment. This allows the function to access and alter the contents of the event using the following shortcuts:</p>
272 <p class="p2"><br></p>
273 <p class="p18"><span class="s8"><span class="Apple-tab-span"> </span></span>~keyName<span class="s5"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span><span class="s8">which is equivalent to<span class="Apple-tab-span"> </span></span>currentEnvironment.at(keyName)</p>
274 <p class="p1">and</p>
275 <p class="p18"><span class="s8"><span class="Apple-tab-span"> </span></span>~keyName = value<span class="s5"><span class="Apple-tab-span"> </span></span><span class="s8">which is equivalent to<span class="Apple-tab-span"> </span></span>currentEnvironment.put(keyName, value)</p>
276 <p class="p6"><br></p>
277 <p class="p1">We will write ~keyName whenever referring to the value stored at the key keyName in the event. <span class="Apple-converted-space"> </span></p>
278 <p class="p2"><br></p>
279 <p class="p1">Here is the definition of Event's play method:</p>
280 <p class="p2"><br></p>
281 <p class="p18"><span class="Apple-tab-span"> </span>play {</p>
282 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>if (parent.isNil) { parent = defaultParentEvent };</p>
283 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s3">this</span>.use { ~play.value };</p>
284 <p class="p18"><span class="Apple-tab-span"> </span>}</p>
285 <p class="p2"><br></p>
286 <p class="p1">Thus we can see that the defaultParentEvent is used unless otherwise specified and the function stored in <span class="s5">~play </span>is executed in the context of the Event. It can be replaced in a given event for different behavior:</p>
287 <p class="p4"><br></p>
288 <p class="p18">(a: 6, b: 7, play: { (~a * ~b).postln }).play;</p>
289 <p class="p4"><br></p>
290 <p class="p4"><br></p>
291 <p class="p5"><b>Timing control with Event's delta method</b></p>
292 <p class="p2"><br></p>
293 <p class="p1">Events also specify timing within a <a href="../Streams-Patterns-Events/Patterns/Pattern.html"><span class="s3">Pattern</span></a>.<span class="Apple-converted-space">  </span>Event's <span class="s5">delta </span>method returns the<span class="Apple-converted-space">  </span>value of <span class="s5">~delta </span>or, if that is nil,<span class="Apple-converted-space">  </span><span class="s5">~dur * ~stretch.<span class="Apple-converted-space"> </span></span></p>
294 <p class="p6"><br></p>
295 <p class="p1">Patterns are played by<b> </b><a href="../Scheduling/TempoClock.html"><span class="s3">TempoClock</span></a>s, which have their own tempo controls.<span class="Apple-converted-space">  </span>This tempo which can be controlled through <span class="s5">~tempo </span>in the event. Changes to the tempo affect everything else scheduled by the TempoClock, so <span class="s5">tempo </span>provides a global tempo control while <span class="s5">stretch </span>provides a control limited to the one pattern.</p>
296 <p class="p4"><br></p>
297 <p class="p4"><br></p>
298 <p class="p5"><b>The structure of defaultParentEvent</b></p>
299 <p class="p4"><br></p>
300 <p class="p1">The default parent event provides the collection of default values and functions needed for the different uses of an Event. These<span class="Apple-converted-space">  </span>defaults are defined in partialEvents that specify distinct aspects of default parent Event:<span class="Apple-converted-space"> </span></p>
301 <p class="p2"><br></p>
302 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>playerEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// defines ~play, ~type and ~eventTypes</p>
303 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>serverEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// server, group, addAction</p>
304 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>durEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// duration, tempo and articulation</p>
305 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>ampEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// volume, pan, MIDI velocity</p>
306 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>pitchEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// pitch specified in many different ways</p>
307 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>bufferEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// buffers on the server</p>
308 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>midiEvent<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// defines the sending of midi messages</p>
309 <p class="p2"><br></p>
310 <p class="p2"><br></p>
311 <p class="p5"><b>Useful keys for notes</b></p>
312 <p class="p2"><br></p>
313 <p class="p1">Using Events is largely a matter of overwriting keys.<span class="Apple-converted-space">  </span>Here is a list of keys useful for defining notes with their default values, grouped by the partialEvent within which they are defined.</p>
314 <p class="p2"><br></p>
315 <p class="p1">The keys in serverEvent provide the values needed to identify the server to be used and where in the tree</p>
316 <p class="p1">of nodes to place the group. <span class="Apple-converted-space"> </span></p>
317 <p class="p2"><br></p>
318 <p class="p1"><b>serverEvent keys</b>:</p>
319 <p class="p20"><span class="Apple-tab-span"> </span></p>
320 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>server: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span><span class="s3">nil</span><span class="s2">,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// if nil, Server.default is used</p>
321 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>instrument: <span class="Apple-tab-span"> </span></span><span class="s4">\default</span><span class="s2">,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// this is the name of a SynthDef</p>
322 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>group: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>1,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// nodeID of group on the server</p>
323 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// whening adding before or after a node</p>
324 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// this could be the nodeID of a synth instead of a group</p>
325 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>addAction:<span class="Apple-tab-span"> </span>0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// 0, 1, 2, 3 or \addToHead, \addToTail, \addBefore, \addAfter</p>
326 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>out: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// usually an output bus number, but depends on the SynthDef<span class="Apple-tab-span"> </span></p>
327 <p class="p20"><br></p>
328 <p class="p20"><br></p>
329 <p class="p1">The ampEvent determines volume.<span class="Apple-converted-space">  </span>Notice that <span class="s5">~amp</span> is a function that determines its value from <span class="s5">~db</span>. The user can choose to specify the amplitude directly by overwriting ~amp or to use a decibel specification by overwriting <span class="s5">~db</span>.</p>
330 <p class="p2"><br></p>
331 <p class="p20"><br></p>
332 <p class="p1"><b>ampEvent keys</b>:</p>
333 <p class="p20"><span class="Apple-tab-span"> </span></p>
334 <p class="p18"><span class="Apple-tab-span"> </span>amp: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>#{ ~db.dbamp },<span class="Apple-tab-span"> </span><span class="s6">// the amplitude</span></p>
335 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>db: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>-20.0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// the above described in decibel</p>
336 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>pan: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0.0, <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// pan position: -1 left 1 right</p>
337 <p class="p18"><span class="Apple-tab-span"> </span>velocity: <span class="Apple-tab-span"> </span>64<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">// midi velocity</span></p>
338 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>trig:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0.5<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// trigger value</p>
339 <p class="p2"><br></p>
340 <p class="p1">The durEvent has keys that determine the timing of a note. Notice that <span class="s5">~sustain </span>is a function that uses ~legato to determine the sustain. Like <span class="s5">~amp </span>this can be overwritten to set the sustain directly.</p>
341 <p class="p2"><br></p>
342 <p class="p2"><br></p>
343 <p class="p1"><b>durEvent keys</b>:</p>
344 <p class="p20"><span class="Apple-tab-span"> </span></p>
345 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>tempo:<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span><span class="s3">nil</span><span class="s2">,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// changes tempo of a TempoClock</p>
346 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>dur: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>1.0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// time until next note (inter-onset time)</p>
347 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>stretch: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>1.0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// inverse of tempo control, specific to the Event's stream</p>
348 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>legato: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0.8,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// ratio of sustain to duration</p>
349 <p class="p18"><span class="Apple-tab-span"> </span>sustain: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>#{ ~dur * ~legato * ~stretch },<span class="Apple-tab-span"> </span></p>
350 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>lag: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0.0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// delay (in seconds) relative to current time position of Stream</p>
351 <p class="p21"><span class="Apple-tab-span"> </span><span class="s2">timingOffset: 0.0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// delay (in beats) relative to current time position of Stream</p>
352 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>strum: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// "breaks" a chord. May be negative, playing the chord backward</p>
353 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>strumEndsTogether: </span><span class="s3">false</span><span class="s2"><span class="Apple-tab-span"> </span></span>// if true, the strummed notes end together (with gated synths)</p>
354 <p class="p10"><br></p>
355 <p class="p2"><br></p>
356 <p class="p2"><br></p>
357 <p class="p1"><b>pitchEvent keys:</b></p>
358 <p class="p2"><br></p>
359 <p class="p1">The pitchEvent has the most complex system of functions that provide a variety of useful ways to determine</p>
360 <p class="p1">pitch:</p>
361 <p class="p20"><span class="Apple-tab-span"> </span></p>
362 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>freq (-&gt;440)<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// determines the pitch directly as a frequency in Hertz</p>
363 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>midinote<span class="Apple-tab-span"> </span>(-&gt; 60)<span class="Apple-tab-span"> </span></span>// determines pitch as a fractional MIDI note (69 -&gt; 440)</p>
364 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>note<span class="Apple-tab-span"> </span>(-&gt; 0)<span class="Apple-tab-span"> </span></span>// determines pitch as a scale degree in an ~stepsPerOctave equal tempered scale</p>
365 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>degree: 0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// determines pitch as a scale degree within the scale ~scale</p>
366 <p class="p2"><br></p>
367 <p class="p1">The event also provides a set of transposition keys:</p>
368 <p class="p20"><br></p>
369 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>mtranspose: 0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// modal transposition of degree within a scale</p>
370 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>root: 0.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// transposes root of the scale<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
371 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>gtranspose: 0.0<span class="Apple-tab-span"> </span></span>// gamut transposition within the ~stepsPerOctave equal tempered scale</p>
372 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>ctranspose: 0.0<span class="Apple-tab-span"> </span></span>// chromatic transposition within the 12 tone equal tempered scale</p>
373 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>harmonic: 1.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// multiplies the frequency determined by ~midinote, typically to an overtone</p>
374 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>detune: 0.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// directly offsets frequency by adding this value</p>
375 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>midiToCps<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// a function taking a MIDI note number and turning it into frequency</p>
376 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// Normally this is _.midicps, but you can override it for non-ET tunings</p>
377 <p class="p2"><br></p>
378 <p class="p20"><br></p>
379 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>mtranspose: <span class="Apple-tab-span"> </span>0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// modal transposition of degree</p>
380 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>gtranspose: <span class="Apple-tab-span"> </span>0.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// gamut transposition of note within a ~stepsPerOctave e.t. scale</p>
381 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>ctranspose: <span class="Apple-tab-span"> </span>0.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// chromatic transposition of midinote within 12 tone e.t. scale</p>
382 <p class="p20"><span class="Apple-tab-span"> </span></p>
383 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>octave: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>5.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// octave offest of note</p>
384 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>root: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// root of the scale</p>
385 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>degree: <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// degree in scale</p>
386 <p class="p18"><span class="Apple-tab-span"> </span>scale: #[0, 2, 4, 5, 7, 9, 11] <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">// diatonic major scale</span></p>
387 <p class="p18"><span class="Apple-tab-span"> </span>stepsPerOctave: 12.0</p>
388 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>detune: 0.0,<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// detune in Hertz</p>
389 <p class="p18"><span class="Apple-tab-span"> </span>harmonic: 1.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s6">// harmonic ratio</span></p>
390 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>octaveRatio: 2.0<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// size of the octave (can be used with the <a href="Scale.html"><span class="s3">Scale</span></a> class)</p>
391 <p class="p20"><br></p>
392 <p class="p20"><br></p>
393 <p class="p1">The event calculates with these keys to derive parameters needed for the synth:</p>
394 <p class="p20"><span class="Apple-tab-span"> </span></p>
395 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>note: #{<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// note is the note in halftone steps from the root</p>
396 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(~degree + ~mtranspose).degreeToKey(~scale, ~stepsPerOctave);</p>
397 <p class="p18"><span class="Apple-tab-span"> </span>}</p>
398 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>midinote: #{<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// midinote is the midinote (continuous intermediate values)</p>
399 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>((~note.value + ~gtranspose + ~root) / ~stepsPerOctave + ~octave) * 12.0;<span class="Apple-converted-space"> </span></p>
400 <p class="p18"><span class="Apple-tab-span"> </span>}</p>
401 <p class="p18"><span class="Apple-tab-span"> </span>freq: #{<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
402 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(~midinote.value + ~ctranspose).midicps * ~harmonic;</p>
403 <p class="p18"><span class="Apple-tab-span"> </span>}</p>
404 <p class="p21"><span class="s2"><span class="Apple-tab-span"> </span>detunedFreq: #{<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// finally sent as "freq" to the synth as a parameter, if given</p>
405 <p class="p18"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>~freq.value + ~detune</p>
406 <p class="p18"><span class="Apple-tab-span"> </span>}</p>
407 <p class="p20"><br></p>
408 <p class="p2"><br></p>
409 <p class="p5"><b>Event types</b></p>
410 <p class="p2"><br></p>
411 <p class="p1">An Event responds to a play message by evaluating ~play in the event, which by default uses the event's type to define the action to be performed. See <a href="Event_types.html"><span class="s3">Event_types</span></a>.</p>
412 <p class="p2"><br></p>
413 </body>
414 </html>