?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
supernova: c++11 compile fix
[supercollider.git] / Help / ServerArchitecture / SynthDef.html
blobcc34f66303122a991c88426f13a86a2766820dab
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="949.54">
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: 14.0px Helvetica}
13 p.p4 {margin: 0.0px 0.0px 0.0px 28.0px; text-indent: -28.0px; font: 12.0px Helvetica}
14 p.p5 {margin: 0.0px 0.0px 0.0px 28.0px; text-indent: -28.0px; font: 12.0px Helvetica; min-height: 14.0px}
15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #526c33}
17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #792724}
18 p.p9 {margin: 0.0px 0.0px 0.0px 56.0px; text-indent: -56.0px; font: 12.0px Helvetica}
19 p.p10 {margin: 0.0px 0.0px 0.0px 56.0px; text-indent: -56.0px; font: 12.0px Helvetica; min-height: 14.0px}
20 p.p11 {margin: 0.0px 0.0px 0.0px 28.0px; font: 12.0px Helvetica; min-height: 14.0px}
21 p.p12 {margin: 0.0px 0.0px 0.0px 28.0px; font: 12.0px Helvetica}
22 p.p13 {margin: 0.0px 0.0px 0.0px 56.0px; text-indent: -56.0px; font: 9.0px Monaco; color: #526c33}
23 p.p14 {margin: 0.0px 0.0px 0.0px 56.0px; text-indent: -56.0px; font: 9.0px Monaco}
24 p.p15 {margin: 0.0px 0.0px 0.0px 56.0px; text-indent: -56.0px; font: 9.0px Monaco; min-height: 12.0px}
25 p.p16 {margin: 0.0px 0.0px 0.0px 28.0px; text-indent: -28.0px; font: 9.0px Monaco}
26 p.p17 {margin: 0.0px 0.0px 0.0px 28.0px; text-indent: -28.0px; font: 9.0px Monaco; color: #233aa6}
27 p.p18 {margin: 0.0px 0.0px 0.0px 0.0px; font: 16.0px Helvetica}
28 p.p19 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
29 p.p20 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #a31917}
30 p.p21 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #35701d}
31 p.p22 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0017b3}
32 span.s1 {font: 18.0px Helvetica}
33 span.s2 {color: #3e5ed3}
34 span.s3 {color: #3250d0}
35 span.s4 {color: #10289e}
36 span.s5 {color: #000000}
37 span.s6 {color: #526c33}
38 span.s7 {color: #2e4cd0}
39 span.s8 {color: #2e4bd2}
40 span.s9 {font: 12.0px Helvetica}
41 span.s10 {color: #5e7b40}
42 span.s11 {color: #233aa6}
43 span.s12 {color: #3f5ed3}
44 span.s13 {color: #304cd0}
45 span.s14 {font: 9.0px Monaco; color: #20359b}
46 span.s15 {font: 9.0px Monaco}
47 span.s16 {color: #335ade}
48 span.s17 {color: #007300}
49 span.s18 {color: #0017b3}
50 span.s19 {color: #35701d}
51 span.s20 {color: #a31917}
52 span.Apple-tab-span {white-space:pre}
53 </style>
54 </head>
55 <body>
56 <p class="p1"><span class="s1"><b>SynthDef<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></span><b>client-side representation of a synth definition</b></p>
57 <p class="p2"><br></p>
58 <p class="p1"><b>superclass: Object</b></p>
59 <p class="p2"><br></p>
60 <p class="p2"><br></p>
61 <p class="p1">The server application uses synth definitions as templates for creating <a href="Synth.html"><span class="s2">Synth</span></a> nodes. (Methods such as <b>Function-play</b>, etc. are simply conveniences which automatically create such a def.) The SynthDef class encapsulates the client-side representation of a given def, and provides methods for creating new defs, writing them to disk, and streaming them to a server.</p>
62 <p class="p2"><br></p>
63 <p class="p1">SynthDef is one of the more complicated classes in SC and an exhaustive explanation of it is beyond the scope of this document. As such, the examples at the bottom of this document and those found in the various tutorials accessible from <a href="../Help.html"><span class="s2">Help</span></a> may be necessary to make some aspects of its use clear.</p>
64 <p class="p2"><br></p>
65 <p class="p2"><br></p>
66 <p class="p3"><b>UGen Graph Functions and Special Argument Forms</b></p>
67 <p class="p2"><br></p>
68 <p class="p1">The core of a def is its <b>unit generator graph function</b>. This is an instance of <a href="../Core/Kernel/Function.html"><span class="s2">Function</span></a> which details how the def's unit generators are interconnected, its inputs and outputs, and what parameters are available for external control. In a synth based on the def, arguments to the function will become instances of <a href="../UGens/Synth control/Control.html"><span class="s3">Control</span></a>. These can have default values, or can be set at the time the synth is created. After creation they will be controllable through Node's <b>set</b> and <b>setn</b> methods, or the n_set and n_setn OSC messages.</p>
69 <p class="p2"><br></p>
70 <p class="p1">There are four special types of arguments, which are treated differently:</p>
71 <p class="p2"><br></p>
72 <p class="p4"><b>audio rate </b>-<b> </b>Arguments that begin with "a_" (e.g. a_input), or that are specified as <b>\ar</b> in the def's rates argument (see below), will be able to read and audio rate bus when mapped to it with /n_mapa.</p>
73 <p class="p5"><br></p>
74 <p class="p4"><b>initial rate </b>-<b> </b>Arguments that begin with "i_" (e.g. i_freq), or that are specified as <b>\ir</b> in the def's rates argument (see below), will be static and non-modulatable. They will not respond to /n_set or /n_map. This is slightly more efficient in terms of CPU than a regular arg.</p>
75 <p class="p5"><br></p>
76 <p class="p4"><b>trigger rate </b>-<b> </b>Arguments that begin with "t_" (e.g. t_trig), or that are specified as <b>\tr</b> in the def's rates argument (see below), will be made as a <b>TrigControl</b>. Setting the argument will create a control-rate impulse at the set value. This is useful for triggers.</p>
77 <p class="p5"><br></p>
78 <p class="p4"><b>literal arrays</b> -<b> </b>Arguments which have literal arrays as default values (see <a href="../Language/Literals.html"><span class="s2">Literals</span></a>) result in multichannel controls, which can be set as a group with <b>Node-setn</b> or n_setn. When setting such controls <i>no bounds checking is done</i>, so you are responsible for making sure that you set the correct number of arguments.</p>
79 <p class="p2"><br></p>
80 <p class="p1">See the examples below for more detail on how this works.</p>
81 <p class="p2"><br></p>
82 <p class="p1">Certain argument names (such as 'out' to specify an out bus) are in such common use that adopting them might be said to constitute 'good style'. One of these, '<b>gate</b>' when used to control the gate input of an <a href="../UGens/Synth control/Envelopes/EnvGen.html"><span class="s3">EnvGen</span></a>, deserves special mention, as it allows one to use Node's <b>release</b> method. See <a href="Node.html"><span class="s2">Node</span></a> for an example and more detail.</p>
83 <p class="p2"><br></p>
84 <p class="p3"><b>Static versus Dynamic Elements</b></p>
85 <p class="p2"><br></p>
86 <p class="p1">It is important to understand that although a single def can provide a great deal of flexibility through its arguments, etc., it is nevertheless a static entity. A def's UGen graph function (and the SC code within it) is evaluated <i>only</i> when the def is created. Thus 'if' statements, etc. will have no further effect at the time the def is used to create a Synth, and it is important to understand that a UGen graph function should not be designed in the same way as functions in the language, where multiple evaluations can yield different results. It will be evaluated <i>once and only once</i>.</p>
87 <p class="p2"><br></p>
88 <p class="p1">There are other ways of achieving similar results, however, often using UGens such as <a href="../UGens/Random/Rand.html"><span class="s2">Rand</span></a>. For example, the following def will have a single randomly generated frequency, which will be the same for every Synth based on it:</p>
89 <p class="p2"><br></p>
90 <p class="p6">(</p>
91 <p class="p7"><span class="s4">SynthDef</span><span class="s5">(</span>\help_notRand<span class="s5">, {<span class="Apple-converted-space"> </span></span></p>
92 <p class="p6"><span class="Apple-tab-span"> </span><span class="s4">Out</span>.ar(0,<span class="Apple-converted-space"> </span></p>
93 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s4">SinOsc</span>.ar(rrand(400, 800), 0, 0.2) * <span class="s4">Line</span>.kr(1, 0, 1, doneAction: 2)</p>
94 <p class="p6"><span class="Apple-tab-span"> </span>)</p>
95 <p class="p6">}).add;</p>
96 <p class="p6">)</p>
97 <p class="p7"><span class="s5">a = </span><span class="s4">Synth</span><span class="s5">(</span>\help_notRand<span class="s5">);</span></p>
98 <p class="p8"><span class="s5">b = </span><span class="s4">Synth</span><span class="s5">(</span><span class="s6">\help_notRand</span><span class="s5">); </span>// the same freq as a</p>
99 <p class="p2"><br></p>
100 <p class="p1">This one on the other hand will have a different random freq for each Synth created:</p>
101 <p class="p2"><br></p>
102 <p class="p6">(</p>
103 <p class="p7"><span class="s4">SynthDef</span><span class="s5">(</span>\help_isRand<span class="s5">, {<span class="Apple-converted-space"> </span></span></p>
104 <p class="p6"><span class="Apple-tab-span"> </span><span class="s4">Out</span>.ar(0,<span class="Apple-converted-space"> </span></p>
105 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s4">SinOsc</span>.ar(<span class="s4">Rand</span>(400, 800), 0, 0.2) * <span class="s4">Line</span>.kr(1, 0, 1, doneAction: 2)</p>
106 <p class="p6"><span class="Apple-tab-span"> </span>)<span class="Apple-converted-space"> </span></p>
107 <p class="p6">}).add;</p>
108 <p class="p6">)</p>
109 <p class="p7"><span class="s5">a = </span><span class="s4">Synth</span><span class="s5">(</span>\help_isRand<span class="s5">);</span></p>
110 <p class="p8"><span class="s5">b = </span><span class="s4">Synth</span><span class="s5">(</span><span class="s6">\help_isRand</span><span class="s5">); </span>// a different randomly selected freq</p>
111 <p class="p2"><br></p>
112 <p class="p2"><br></p>
113 <p class="p2"><br></p>
114 <p class="p2"><br></p>
115 <p class="p3"><b>Class Methods</b></p>
116 <p class="p2"><br></p>
117 <p class="p1"><b>*new(name, ugenGraphFunc, rates, prependArgs, variants, metadata)</b></p>
118 <p class="p2"><span class="Apple-tab-span"> </span></p>
119 <p class="p1"><span class="Apple-tab-span"> </span>Create a SynthDef instance, evaluate the ugenGraphFunc and build the ugenGraph.</p>
120 <p class="p2"><br></p>
121 <p class="p9"><span class="Apple-tab-span"> </span><b>name </b>- A <a href="../Collections/String.html"><span class="s2">String</span></a> or <a href="../Core/Symbol.html"><span class="s2">Symbol</span></a> (i.e. "name" or \name). This name will be used to refer to the SynthDef when creating a <a href="Synth.html"><span class="s2">Synth</span></a> based upon it, and should be unique.</p>
122 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
123 <p class="p9"><span class="Apple-tab-span"> </span><b>ugenGraphFunc</b> - An instance of <a href="../Core/Kernel/Function.html"><span class="s2">Function</span></a><b> </b>specifying how the def's UGens are interconnected. See the discussion above for information on how the Function's arguments are specified.</p>
124 <p class="p10"><span class="Apple-tab-span"> </span></p>
125 <p class="p9"><span class="Apple-tab-span"> </span><b>rates</b> - An optional Array of specifications for the ugenGraphFunc's arguments. The order corresponds to the order of arguments. See the examples below to see how these are used.</p>
126 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>A specification can be:</p>
127 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>nil/zero</b><span class="Apple-tab-span"> </span>A standard control rate <a href="../UGens/Synth control/Control.html"><span class="s3">Control</span></a> is created.</p>
128 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>\ar</b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>An audio rate AudioControl is created.</p>
129 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>a float</b><span class="Apple-tab-span"> </span>the Control will have a lag of the specified time. This can be used to create<span class="Apple-converted-space"> </span></p>
130 <p class="p9"><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>smooth transitions between different values. t_ and i_ args cannot be lagged.</p>
131 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>\ir</b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>The Control can be set only at creation ('initial rate'). See discussion above.</p>
132 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>\tr</b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>The Control is used as a trigger. See discussion above.</p>
133 <p class="p10"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
134 <p class="p9"><span class="Apple-tab-span"> </span><b>prependArgs </b>- An optional Array of objects which will be passed as the first arguments to the <b>ugenGraphFunc</b> when it is evaluated. Arguments which receive values in this way will not be converted to instances of <a href="../UGens/Synth control/Control.html"><span class="s3">Control</span></a>. See the *<b>wrap</b> example below for an example of how this can be used.</p>
135 <p class="p10"><span class="Apple-tab-span"> </span></p>
136 <p class="p9"><span class="Apple-tab-span"> </span><b>variants</b> - An optional <a href="../Collections/Event.html"><span class="s2">Event</span></a> containing default argument settings. These can override the defaults specified in the <b>ugenGraphFunc</b>. When creating a Synth a variant can be requested by appending the defName argument in the form<span class="Apple-converted-space">  </span>'name.variant' or "name.variant". See example below.</p>
137 <p class="p10"><span class="Apple-tab-span"> </span></p>
138 <p class="p9"><span class="Apple-tab-span"> </span><b>metadata</b> - An optional <a href="../Collections/Event.html"><span class="s7">Event</span></a> containing additional, user-defined information that is relevant to the use of the SynthDef in the client. The SynthDef itself is sent to the server for audio rendering; metadata are strictly client-side descriptive information. Currently the 'specs' key in the event is reserved for ControlSpecs to be associated with SynthDef arguments (this is useful for automatic GUI construction). Metadata can be persisted to disk and loaded automatically as part of a SynthDesc. See the <a href="SynthDesc.html"><span class="s7">SynthDesc</span></a> help file for more details.</p>
139 <p class="p10"><br></p>
140 <p class="p11"><br></p>
141 <p class="p10"><br></p>
142 <p class="p9"><b>*wrap(ugenGraphFunc, rates, prependArgs)</b></p>
143 <p class="p10"><br></p>
144 <p class="p12">Wraps a function within an enclosing synthdef. Arguments to the wrapped function are automatically promoted to be SynthDef controls, using the same rules applied to arguments of the main UGen function. For a very simple example:</p>
145 <p class="p11"><br></p>
146 <p class="p13"><span class="s5"><span class="Apple-tab-span"> </span>d = </span><span class="s4">SynthDef</span><span class="s5">(</span>\demoWrapping<span class="s5">, { </span><span class="s4">|out|</span></p>
147 <p class="p14"><span class="s6"><span class="Apple-tab-span"> </span></span><span class="Apple-tab-span"> </span><span class="s4">Out</span>.ar(out, <span class="s4">SynthDef</span>.wrap({ <span class="s4">|freq|</span> <span class="s4">SinOsc</span>.ar(freq) }))</p>
148 <p class="p14"><span class="Apple-tab-span"> </span>});</p>
149 <p class="p15"><span class="Apple-tab-span"> </span></p>
150 <p class="p14"><span class="Apple-tab-span"> </span>d.allControlNames;</p>
151 <p class="p10"><br></p>
152 <p class="p9">Prints: [ ControlName<span class="Apple-converted-space">  </span>P 0 <b>out</b> control 0, ControlName<span class="Apple-converted-space">  </span>P 1 <b>freq</b> control 0 ]</p>
153 <p class="p11"><br></p>
154 <p class="p12">The outer function declares the argument 'out', and the wrapped function has 'freq' as its argument. The resulting SynthDef has both arguments as controls, exactly as if the outer function included both as arguments.</p>
155 <p class="p11"><br></p>
156 <p class="p12">The <b>rates</b> array behaves as described earlier. <b>PrependArgs</b> allows values or unit generators to be passed into the inner function from the enclosing SynthDef context. Any inner function argument that receives a prependArg value (including nil) will use that value, suppressing creation of a control for that argument. The longer example below demonstrates this technique.</p>
157 <p class="p11"><br></p>
158 <p class="p12">This is very useful for mass-producing SynthDefs that have a common "shell" defining features such as enveloping or triggering mechanisms that apply to different subgraphs of unit generators. The common features need be written only once; the UGens that differ between the SynthDefs are plugged into the supporting architecture.</p>
159 <p class="p2"><br></p>
160 <p class="p2"><br></p>
161 <p class="p9"><b>*synthDefDir</b></p>
162 <p class="p9"><b>*synthDefDir_(dir)</b></p>
163 <p class="p10"><br></p>
164 <p class="p9"><b><span class="Apple-tab-span"> </span></b>Get or set the default directory to which defs are written.</p>
165 <p class="p10"><br></p>
166 <p class="p10"><span class="Apple-tab-span"> </span></p>
167 <p class="p10"><br></p>
168 <p class="p10"><br></p>
169 <p class="p3"><b>Instance Methods</b></p>
170 <p class="p2"><span class="Apple-tab-span"> </span></p>
171 <p class="p2"><br></p>
172 <p class="p1"><b>add(libname, completionMsg, keepDef)</b></p>
173 <p class="p2"><br></p>
174 <p class="p4"><span class="Apple-tab-span"> </span>Adds the synthdef to the <a href="SynthDescLib.html"><span class="s8">SynthDescLib</span></a> specified by <b>libname</b>, and sends it to the library's servers. No defFile is written; all operations take place in memory. After using this method, the synthdef can be used with event streams as in store(), but without the permanent artifact of a file on disk.</p>
175 <p class="p5"><span class="Apple-tab-span"> </span></p>
176 <p class="p4"><span class="Apple-tab-span"> </span>A server can be added by SynthDescLib.global.addServer(server)</p>
177 <p class="p5"><br></p>
178 <p class="p4"><span class="Apple-tab-span"> </span>Note that the "dir" and "mdPlugin" arguments do not exist for this method. Because no file is written, there is no need to specify a directory or write a metadata file.</p>
179 <p class="p5"><span class="Apple-tab-span"> </span></p>
180 <p class="p5"><span class="Apple-tab-span"> </span></p>
181 <p class="p16"><span class="s9"><span class="Apple-tab-span"> </span></span>(</p>
182 <p class="p17"><span class="s5"><span class="Apple-tab-span"> </span></span>SynthDef<span class="s5">(</span><span class="s10">\help_synth</span><span class="s5">, { </span>|out, freq = 800, sustain = 1, amp = 0.1|</p>
183 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s11">Out</span>.ar(out,<span class="Apple-converted-space"> </span></p>
184 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s11">SinOsc</span>.ar(freq, 0, 0.2) * <span class="s11">Line</span>.kr(amp, 0, sustain, doneAction: 2)</p>
185 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>)<span class="Apple-converted-space"> </span></p>
186 <p class="p6"><span class="Apple-tab-span"> </span>}).add;</p>
187 <p class="p6"><span class="Apple-tab-span"> </span>)</p>
188 <p class="p2"><br></p>
189 <p class="p4"><b>*removeAt(name, libname)</b></p>
190 <p class="p5"><br></p>
191 <p class="p4"><span class="Apple-tab-span"> </span>Remove the synthdef from the SynthDescLib and from its servers.</p>
192 <p class="p2"><br></p>
193 <p class="p1"><b>name</b></p>
194 <p class="p2"><span class="Apple-tab-span"> </span></p>
195 <p class="p1"><span class="Apple-tab-span"> </span>Return this def's name.</p>
196 <p class="p2"><span class="Apple-tab-span"> </span></p>
197 <p class="p1"><b>func</b></p>
198 <p class="p2"><br></p>
199 <p class="p1"><span class="Apple-tab-span"> </span>Return this def's ugenGraphFunc.</p>
200 <p class="p2"><span class="Apple-tab-span"> </span></p>
201 <p class="p1"><b>variants</b></p>
202 <p class="p2"><span class="Apple-tab-span"> </span></p>
203 <p class="p1"><span class="Apple-tab-span"> </span>Return an <a href="../Collections/Event.html"><span class="s2">Event</span></a> containing this def's variants.</p>
204 <p class="p2"><span class="Apple-tab-span"> </span></p>
205 <p class="p2"><br></p>
206 <p class="p2"><br></p>
207 <p class="p2"><span class="Apple-tab-span"> </span></p>
208 <p class="p3"><b>Special purpose methods</b></p>
209 <p class="p3">(for most purposes, the method <b><i>add</i></b> is recommended)</p>
210 <p class="p2"><span class="Apple-tab-span"> </span></p>
211 <p class="p1"><b>writeDefFile(dir)</b><span class="Apple-converted-space"> </span></p>
212 <p class="p2"><br></p>
213 <p class="p4"><span class="Apple-tab-span"> </span>Writes the def as a file called name.scsyndef in a form readable by a server. Default for <b>dir</b> is synthdefs/. Defs stored in the default directory will be automatically loaded by the local and internal Servers when they are booted.</p>
214 <p class="p2"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></p>
215 <p class="p4"><b>load(server, completionMessage, dir)</b></p>
216 <p class="p5"><b><span class="Apple-tab-span"> </span></b></p>
217 <p class="p4"><b><span class="Apple-tab-span"> </span></b>Write the defFile and send a message to <b>server</b> to load this file. When this asynchronous command is completed, the <b>completionMessage</b> (a valid OSC message) is immediately executed by the server. Default for <b>dir</b> is synthdefs/.</p>
218 <p class="p5"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
219 <p class="p4"><b>send(server, completionMessage)</b></p>
220 <p class="p5"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b><span class="Apple-tab-span"> </span></p>
221 <p class="p4"><span class="Apple-tab-span"> </span>Compile the def and send it to <b>server</b> without writing to disk (thus avoiding that annoying SynthDef buildup). When this asynchronous command is completed, the <b>completionMessage</b> (a valid OSC message) is immediately executed by the server.</p>
222 <p class="p2"><br></p>
223 <p class="p1"><b>store(libname, dir, completionMessage, mdPlugin)<span class="Apple-converted-space"> </span></b></p>
224 <p class="p2"><br></p>
225 <p class="p4"><span class="Apple-tab-span"> </span>Write the defFile and store it in the <b>SynthDescLib</b> specified by <b>libname</b>, and send a message to the library's server to load this file. When this asynchronous command is completed, the <b>completionMessage</b> (a valid OSC<span class="Apple-converted-space">  </span>message) is immediately executed by the server. Default for <b>libname</b> is \global, for <b>dir</b> is synthdefs/. This is needed to use defs with the event stream system. See <a href="../Streams-Patterns-Events/Streams.html"><span class="s12">Streams</span></a> and <a href="../Streams-Patterns-Events/Patterns/Pattern.html"><span class="s12">Pattern</span></a>.</p>
226 <p class="p5"><span class="Apple-tab-span"> </span></p>
227 <p class="p4"><span class="Apple-tab-span"> </span>mdPlugin (optional) is the metadata plug-in class that will be used to persist metadata. If not supplied, the default plug-in is used. See the <a href="SynthDesc.html"><span class="s13">SynthDesc</span></a> help file for details.</p>
228 <p class="p5"><br></p>
229 <p class="p5"><br></p>
230 <p class="p9"><b>*writeOnce(name, ugenGraphFunc, rates, prependArgs, dir, metadata)</b></p>
231 <p class="p10"><b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b></p>
232 <p class="p12">Create a new SynthDef and write it to disk, but only if a def file with this name does not already exist. This is useful in class definitions so that the def is not written every time the library is compiled. Note that this will not check for differences, so you will need to delete the defFile to get it to rebuild. Default for <b>dir</b> is to use the path specified by <span class="s14">SynthDef</span><span class="s15">.synthDefDir</span>.</p>
233 <p class="p11"><br></p>
234 <p class="p1"><b>memStore(libname, completionMsg)</b></p>
235 <p class="p2"><br></p>
236 <p class="p4"><span class="Apple-tab-span"> </span>This method has been deprecated, use <b>add</b> instead.</p>
237 <p class="p5"><br></p>
238 <p class="p4"><b>play(target, args, addAction)</b></p>
239 <p class="p5"><b><span class="Apple-tab-span"> </span></b></p>
240 <p class="p4"><b><span class="Apple-tab-span"> </span></b>A convenience method which compiles the def and sends it to <b>target's</b> server. When this asynchronous command is completed, it create one synth from this definition, using the argument values specified in the Array <b>args</b>. Returns a corresponding <b>Synth</b> object. For a list of valid <b>addActions</b> see <a href="../../../../../../../Applications/SuperCollider/Help/ServerArchitecture/Synth.html"><span class="s16">Synth</span></a>. The default is <span class="s17">\addToHead</span><span class="s5">.<b><span class="Apple-tab-span"> </span></b></span></p>
241 <p class="p2"><span class="Apple-tab-span"> </span></p>
242 <p class="p2"><span class="Apple-tab-span"> </span></p>
243 <p class="p2"><span class="Apple-tab-span"> </span></p>
244 <p class="p18"><b>Examples</b></p>
245 <p class="p19"><br></p>
246 <p class="p1"><b>Basic</b></p>
247 <p class="p19"><br></p>
248 <p class="p20">// Note that constructions like SynthDef(...) and Synth(...) are short for SynthDef.new(...), etc.</p>
249 <p class="p20">// With SynthDef it is common to chain this with calls on the resulting instance,</p>
250 <p class="p20">// e.g. SynthDef(...).add or SynthDef(...).play</p>
251 <p class="p19"><br></p>
252 <p class="p20">// make a simple def and send it to the server</p>
253 <p class="p19"><br></p>
254 <p class="p6">s.boot;</p>
255 <p class="p6"><span class="s18">SynthDef</span>(<span class="s19">\SimpleSine</span>, {<span class="s18">|freq = 440|</span> <span class="s18">Out</span>.ar(0, <span class="s18">SinOsc</span>.ar(freq, 0, 0.2)) }).add;</p>
256 <p class="p19"><br></p>
257 <p class="p20">// the above is essentially the same as the following:</p>
258 <p class="p6">d = <span class="s18">SynthDef</span>.new(<span class="s19">\SimpleSine</span>, {<span class="s18">|freq = 440|</span> <span class="s18">Out</span>.ar(0, <span class="s18">SinOsc</span>.ar(freq, 0, 0.2)) });</p>
259 <p class="p6">d.add;</p>
260 <p class="p19"><br></p>
261 <p class="p20">// now make a synth from it, using the default value for freq, then another with a different value</p>
262 <p class="p21"><span class="s5">x = </span><span class="s18">Synth</span><span class="s5">(</span>\SimpleSine<span class="s5">);</span></p>
263 <p class="p6">y = <span class="s18">Synth</span>(<span class="s19">\SimpleSine</span>, [<span class="s19">\freq</span>, 660]);</p>
264 <p class="p19"><br></p>
265 <p class="p20">// now change the freq value for x</p>
266 <p class="p6">x.set(<span class="s19">\freq</span>, 880);</p>
267 <p class="p19"><br></p>
268 <p class="p6">x.free; y.free;</p>
269 <p class="p19"><br></p>
270 <p class="p20">// using the play convenience method</p>
271 <p class="p6">x = <span class="s18">SynthDef</span>(<span class="s19">\SimpleSine</span>, {<span class="s18">|freq = 440|</span> <span class="s18">Out</span>.ar(0, <span class="s18">SinOsc</span>.ar(freq, 0, 0.2)) }).play</p>
272 <p class="p6">x.free;</p>
273 <p class="p19"><br></p>
274 <p class="p19"><br></p>
275 <p class="p1"><b>Argument Rates</b></p>
276 <p class="p19"><br></p>
277 <p class="p20">// the following two defs are equivalent. The first uses a 't_' arg:</p>
278 <p class="p6">(</p>
279 <p class="p20"><span class="s18">SynthDef</span><span class="s5">(</span><span class="s19">\trigTest</span><span class="s5">, {</span><span class="s18">|t_trig=0, freq=440|</span><span class="s5"> </span>// t_trig creates a TrigControl</p>
280 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">Out</span>.ar(0, <span class="s18">SinOsc</span>.ar(freq+[0,1], 0, <span class="s18">Decay2</span>.kr(t_trig, 0.005, 1.0)));</p>
281 <p class="p20"><span class="s5">}, [0, 4]<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// lag the freq by 4 seconds (the second arg), but not t_trig (won't work anyway)</p>
282 <p class="p6">);</p>
283 <p class="p6">)</p>
284 <p class="p19"><br></p>
285 <p class="p20">// This second version makes trig a \tr arg by specifying it in the rates array.</p>
286 <p class="p6">(</p>
287 <p class="p22">SynthDef<span class="s5">(</span><span class="s19">\trigTest2</span><span class="s5">, {</span>|trig=0, freq=440|<span class="s5"><span class="Apple-converted-space"> </span></span></p>
288 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">Out</span>.ar(0, <span class="s18">SinOsc</span>.ar(freq+[0,1], 0, <span class="s18">Decay2</span>.kr(trig, 0.005, 1.0)));</p>
289 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span>}, [</span><span class="s19">\tr</span><span class="s5">, 4]<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// lag the freq (lagtime: 4s), \tr creates a TrigControl for trig</p>
290 <p class="p6">).add;<span class="Apple-converted-space"> <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span></p>
291 <p class="p6">)</p>
292 <p class="p19"><br></p>
293 <p class="p20">// Different way of writing the same thing</p>
294 <p class="p6">(</p>
295 <p class="p21"><span class="s18">SynthDef</span><span class="s5">(</span>\trigTest2<span class="s5">, {</span></p>
296 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">Out</span>.ar(0, <span class="s18">SinOsc</span>.ar(<span class="s19">\freq</span>.kr(440, 4) + [0,1], 0, <span class="s18">Decay2</span>.kr(<span class="s19">\trig</span>.tr, 0.005, 1.0)));</p>
297 <p class="p6">}).add;<span class="Apple-converted-space"> <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span></p>
298 <p class="p6">)</p>
299 <p class="p19"><br></p>
300 <p class="p19"><br></p>
301 <p class="p20">// Using the second version create a synth</p>
302 <p class="p6">z = <span class="s18">Synth</span>.head(s, <span class="s19">\trigTest2</span>);</p>
303 <p class="p19"><br></p>
304 <p class="p20">// now trigger the decay envelope</p>
305 <p class="p20"><span class="s5">z.set(</span><span class="s19">\trig</span><span class="s5">, 1); <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>// you can do this multiple times<span class="Apple-converted-space"> </span></p>
306 <p class="p20"><span class="s5">z.set(</span><span class="s19">\trig</span><span class="s5">, 1, </span><span class="s19">\freq</span><span class="s5">, 220); <span class="Apple-tab-span"> </span></span>// hear how the freq lags</p>
307 <p class="p6">z.set(<span class="s19">\trig</span>, 1, <span class="s19">\freq</span>, 880);</p>
308 <p class="p19"><br></p>
309 <p class="p20"><span class="s5">z.free; </span>//free the synth</p>
310 <p class="p19"><br></p>
311 <p class="p19"><br></p>
312 <p class="p1"><b>Variants</b></p>
313 <p class="p19"><br></p>
314 <p class="p20">// create a def with some variants</p>
315 <p class="p6">(</p>
316 <p class="p22">SynthDef<span class="s5">(</span><span class="s19">\vartest</span><span class="s5">, {</span>|out=0, freq=440, amp=0.2, a = 0.01, r = 1|</p>
317 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span></span>// the EnvGen with doneAction: 2 frees the synth automatically when done</p>
318 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">Out</span>.ar(out, <span class="s18">SinOsc</span>.ar(freq, 0, <span class="s18">EnvGen</span>.kr(<span class="s18">Env</span>.perc(a, r, amp), doneAction: 2)));</p>
319 <p class="p6">}, variants: (alpha: [a: 0.5, r: 0.5], beta: [a: 3, r: 0.01], gamma: [a: 0.01, r: 4])</p>
320 <p class="p6">).add;</p>
321 <p class="p6">)</p>
322 <p class="p19"><br></p>
323 <p class="p20">// now make some synths. First using the arg defaults</p>
324 <p class="p21"><span class="s18">Synth</span><span class="s5">(</span>\vartest<span class="s5">);</span></p>
325 <p class="p19"><br></p>
326 <p class="p20">// now the variant defaults</p>
327 <p class="p21"><span class="s18">Synth</span><span class="s5">(</span>'vartest.alpha'<span class="s5">);</span></p>
328 <p class="p21"><span class="s18">Synth</span><span class="s5">(</span>'vartest.beta'<span class="s5">);</span></p>
329 <p class="p21"><span class="s18">Synth</span><span class="s5">(</span>'vartest.gamma'<span class="s5">);</span></p>
330 <p class="p19"><br></p>
331 <p class="p20">// override a variant</p>
332 <p class="p21"><span class="s18">Synth</span><span class="s5">(</span>'vartest.alpha'<span class="s5">, [</span>\release<span class="s5">, 3, </span>\freq<span class="s5">, 660]);</span></p>
333 <p class="p19"><br></p>
334 <p class="p19"><br></p>
335 <p class="p1"><b>Literal Array Arguments</b></p>
336 <p class="p2"><br></p>
337 <p class="p20">// freqs has a literal array of defaults. This makes a multichannel Control of the same size.</p>
338 <p class="p6">(</p>
339 <p class="p22">SynthDef<span class="s5">(</span><span class="s19">\arrayarg</span><span class="s5">, { </span>| amp = 0.1, freqs = #[300, 400, 500, 600], gate = 1 |</p>
340 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">var</span> env, sines;</p>
341 <p class="p6"><span class="Apple-tab-span"> </span>env = <span class="s18">Linen</span>.kr(gate, 0.1, 1, 1, 2) * amp;</p>
342 <p class="p6"><span class="Apple-tab-span"> </span>sines = <span class="s18">SinOsc</span>.ar(freqs +.t [0,0.5]).cubed.sum; <span class="s20">// A mix of 4 oscillators</span></p>
343 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">Out</span>.ar(0, sines * env);<span class="Apple-converted-space"> </span></p>
344 <p class="p6">}, [0, 0.1, 0]).add;</p>
345 <p class="p6">)</p>
346 <p class="p19"><br></p>
347 <p class="p21"><span class="s5">x = </span><span class="s18">Synth</span><span class="s5">(</span>\arrayarg<span class="s5">);</span></p>
348 <p class="p6">x.setn(<span class="s19">\freqs</span>, [440, 441, 442, 443]);</p>
349 <p class="p19"><br></p>
350 <p class="p20">// Don't accidentally set too many values, or you may have unexpected side effects</p>
351 <p class="p20">// The code below inadvertantly sets the gate arg, and frees the synth</p>
352 <p class="p6">x.setn(<span class="s19">\freqs</span>, [300, 400, 500, 600, 0]);</p>
353 <p class="p19"><br></p>
354 <p class="p20">// Mr. McCartney's more complex example</p>
355 <p class="p6">(</p>
356 <p class="p6">fork {<span class="Apple-converted-space"> <span class="Apple-tab-span"> </span></span></p>
357 <p class="p21"><span class="s5"><span class="Apple-tab-span"> </span>z = </span><span class="s18">Synth</span><span class="s5">(</span>\arrayarg<span class="s5">);</span></p>
358 <p class="p19"><span class="Apple-tab-span"> </span></p>
359 <p class="p6"><span class="Apple-tab-span"> </span>2.wait;</p>
360 <p class="p6"><span class="Apple-tab-span"> </span>10.do {</p>
361 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>z.setn(<span class="s19">\freqs</span>, {exprand(200,800.0)} ! 4);</p>
362 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(2 ** (0..3).choose * 0.2).wait;</p>
363 <p class="p6"><span class="Apple-tab-span"> </span>};</p>
364 <p class="p19"><br></p>
365 <p class="p6"><span class="Apple-tab-span"> </span>z.set(<span class="s19">\amp</span>, -40.dbamp);</p>
366 <p class="p19"><br></p>
367 <p class="p6"><span class="Apple-tab-span"> </span>10.do {</p>
368 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>z.setn(<span class="s19">\freqs</span>, {exprand(200,800.0)} ! 4);</p>
369 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(2 ** (0..3).choose * 0.2).wait;</p>
370 <p class="p6"><span class="Apple-tab-span"> </span>};</p>
371 <p class="p6"><span class="Apple-tab-span"> </span>2.wait;</p>
372 <p class="p19"><span class="Apple-tab-span"> </span></p>
373 <p class="p6"><span class="Apple-tab-span"> </span>z.release;</p>
374 <p class="p6">};</p>
375 <p class="p6">)</p>
376 <p class="p19"><br></p>
377 <p class="p19"><br></p>
378 <p class="p1"><b>Wrapping Example: 'factory' production of effects defs</b></p>
379 <p class="p19"><br></p>
380 <p class="p20">// The makeEffect function below wraps a simpler function within itself and provides</p>
381 <p class="p20">// a crossfade into the effect (so you can add it without clicks), control over wet</p>
382 <p class="p20">// and dry mix, etc.</p>
383 <p class="p20">// Such functionality is useful for a variety of effects, and SynthDef-wrap</p>
384 <p class="p20">// lets you reuse the common code.</p>
385 <p class="p6">(</p>
386 <p class="p20">// the basic wrapper</p>
387 <p class="p22"><span class="s5">~makeEffect = {</span>| name, func, lags, numChannels = 2 |</p>
388 <p class="p19"><br></p>
389 <p class="p22"><span class="s5"><span class="Apple-tab-span"> </span></span>SynthDef<span class="s5">(name, {</span>| i_bus = 0, gate = 1, wet = 1|</p>
390 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s18">var</span> in, out, env, lfo;</p>
391 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>in = <span class="s18">In</span>.ar(i_bus, numChannels);</p>
392 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>env = <span class="s18">Linen</span>.kr(gate, 2, 1, 2, 2); <span class="s20">// fade in the effect</span></p>
393 <p class="p19"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
394 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// call the wrapped function. The in and env arguments are passed to the function</p>
395 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// as the first two arguments (prependArgs).<span class="Apple-converted-space"> </span></p>
396 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>// Any other arguments of the wrapped function will be Controls.</p>
397 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>out = <span class="s18">SynthDef</span>.wrap(func, lags, [in, env]);</p>
398 <p class="p19"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
399 <p class="p6"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s18">XOut</span>.ar(i_bus, wet * env, out);</p>
400 <p class="p6"><span class="Apple-tab-span"> </span>}, [0, 0, 0.1] ).add;</p>
401 <p class="p19"><br></p>
402 <p class="p6">};</p>
403 <p class="p6">)</p>
404 <p class="p19"><br></p>
405 <p class="p20">// now make a wah</p>
406 <p class="p6">(</p>
407 <p class="p22"><span class="s5">~makeEffect.value(</span><span class="s19">\wah</span><span class="s5">, {</span>|in, env, rate = 0.7, ffreq = 1200, depth = 0.8, rq = 0.1|</p>
408 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span></span>// in and env come from the wrapper. The rest are controls</p>
409 <p class="p6"><span class="Apple-converted-space"> <span class="Apple-tab-span"> </span></span><span class="s18">var</span> lfo;</p>
410 <p class="p6"><span class="Apple-tab-span"> </span>lfo = <span class="s18">LFNoise1</span>.kr(rate, depth * ffreq, ffreq);</p>
411 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">RLPF</span>.ar(in, lfo, rq, 10).distort * 0.15; },</p>
412 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span>[0.1, 0.1, 0.1, 0.1],<span class="Apple-converted-space">  </span></span>// lags for rate ffreq, depth and rq</p>
413 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span>2<span class="Apple-tab-span"> </span></span>// numChannels</p>
414 <p class="p6">);</p>
415 <p class="p6">)</p>
416 <p class="p19"><br></p>
417 <p class="p20">// now make a simple reverb</p>
418 <p class="p6">(</p>
419 <p class="p6">~makeEffect.value(<span class="s19">\reverb</span>, {<span class="s18">|in, env|</span></p>
420 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span></span>// in and env come from the wrapper.</p>
421 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">var</span> input;</p>
422 <p class="p6"><span class="Apple-tab-span"> </span>input = in;</p>
423 <p class="p6"><span class="Apple-tab-span"> </span>16.do({ input = <span class="s18">AllpassC</span>.ar(input, 0.04, <span class="s18">Rand</span>(0.001,0.04), 3)});</p>
424 <p class="p6"><span class="Apple-tab-span"> </span>input; },</p>
425 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span></span><span class="s18">nil</span><span class="s5">,<span class="Apple-converted-space">  </span></span>// no lags</p>
426 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span>2<span class="Apple-tab-span"> </span></span>// numChannels</p>
427 <p class="p6">);</p>
428 <p class="p6">)</p>
429 <p class="p19"><br></p>
430 <p class="p20">// something to process</p>
431 <p class="p6">x = { {<span class="s18">Decay2</span>.ar(<span class="s18">Dust2</span>.ar(3), mul: <span class="s18">PinkNoise</span>.ar(0.2))} ! 2}.play;</p>
432 <p class="p19"><br></p>
433 <p class="p6">y = <span class="s18">Synth</span>.tail(s, <span class="s19">\wah</span>);</p>
434 <p class="p6">z = <span class="s18">Synth</span>.tail(s, <span class="s19">\reverb</span>, [<span class="s19">\wet</span>, 0.5]);</p>
435 <p class="p19"><br></p>
436 <p class="p20">// we used an arg named gate, so Node-release can crossfade out the effects</p>
437 <p class="p6">y.release;<span class="Apple-converted-space"> </span></p>
438 <p class="p19"><br></p>
439 <p class="p20">// setting gate to zero has the same result</p>
440 <p class="p6">z.set(<span class="s19">\gate</span>, 0);</p>
441 <p class="p19"><br></p>
442 <p class="p6">x.free;</p>
443 <p class="p19"><br></p>
444 <p class="p19"><br></p>
445 <p class="p1"><b>common argument names: <i>out</i> </b>and<b> <i>gate</i></b></p>
446 <p class="p2"><br></p>
447 <p class="p20">// arguments named 'out' and 'gate' are commonly used to specify an output bus and</p>
448 <p class="p20">// EnvGen gate respectively. Although not required, using them can help with consistency</p>
449 <p class="p20">// and interchangeability. 'gate' is particularly useful, as it allows for Node's release</p>
450 <p class="p20">// method.</p>
451 <p class="p6">(</p>
452 <p class="p22">SynthDef<span class="s5">(</span><span class="s19">\synthDefTest</span><span class="s5">, {</span>|out, gate=1, freq=440|</p>
453 <p class="p20"><span class="s5"><span class="Apple-tab-span"> </span></span>// doneAction: 2 frees the synth when EnvGen is done</p>
454 <p class="p6"><span class="Apple-tab-span"> </span><span class="s18">Out</span>.ar(out, <span class="s18">SinOsc</span>.ar(freq) * <span class="s18">EnvGen</span>.kr(<span class="s18">Env</span>.asr(0.1, 0.3, 1.3), gate, doneAction:2));</p>
455 <p class="p20"><span class="s5">}).store; </span>// use store for compatibility with pattern example below</p>
456 <p class="p6">)</p>
457 <p class="p19"><br></p>
458 <p class="p20"><span class="s5">x = </span><span class="s18">Synth</span><span class="s5">(</span><span class="s19">\synthDefTest</span><span class="s5">, [</span><span class="s19">\out</span><span class="s5">, 0]); </span>// play out through hardware output bus 0 (see Out.help)</p>
459 <p class="p20"><span class="s5">x.release; </span>// releases and frees the synth (if doneAction is &gt; 2; see EnvGen)</p>
460 <p class="p19"><br></p>
461 <p class="p20">//equivalent:</p>
462 <p class="p19"><br></p>
463 <p class="p20"><span class="s5">x = </span><span class="s18">Synth</span><span class="s5">(</span><span class="s19">\synthDefTest</span><span class="s5">); </span>// out defaults to zero, if no default arg is given.</p>
464 <p class="p6">x.set(<span class="s19">\gate</span>, 0);</p>
465 <p class="p19"><br></p>
466 <p class="p20">// if value is negative, it overrides the release time, to -1 - gate</p>
467 <p class="p21"><span class="s5">x = </span><span class="s18">Synth</span><span class="s5">(</span>\synthDefTest<span class="s5">);</span></p>
468 <p class="p20"><span class="s5">x.set(</span><span class="s19">\gate</span><span class="s5">, -5); </span>// 4 second release</p>
469 <p class="p19"><br></p>
470 <p class="p20">//equivalent:</p>
471 <p class="p21"><span class="s5">x = </span><span class="s18">Synth</span><span class="s5">(</span>\synthDefTest<span class="s5">);</span></p>
472 <p class="p6">x.release(4);</p>
473 <p class="p19"><br></p>
474 <p class="p20">// if the out arg is used in a standard way, it can always be changed without knowing the synth def</p>
475 <p class="p21"><span class="s5">x = </span><span class="s18">Synth</span><span class="s5">(</span>\synthDefTest<span class="s5">, [</span>\out<span class="s5">, 0]);</span></p>
476 <p class="p20"><span class="s5">x.set(</span><span class="s19">\out</span><span class="s5">, 1); </span>//play through channel 1</p>
477 <p class="p6">x.release;</p>
478 <p class="p19"><br></p>
479 <p class="p20">// Another good example of this is with patterns, which can use gate to release notes</p>
480 <p class="p6">(</p>
481 <p class="p22">Pbind<span class="s5">(</span></p>
482 <p class="p21"><span class="s5"><span class="Apple-tab-span"> </span></span>\instrument<span class="s5">, </span>\synthDefTest<span class="s5">,</span></p>
483 <p class="p6"><span class="Apple-tab-span"> </span><span class="s19">\freq</span>, <span class="s18">Pseq</span>([500, 600, <span class="s18">Prand</span>([200, 456, 345],1)], <span class="s18">inf</span>),</p>
484 <p class="p6"><span class="Apple-tab-span"> </span><span class="s19">\legato</span>, <span class="s18">Pseq</span>([1.5, 0.2], <span class="s18">inf</span>),</p>
485 <p class="p6"><span class="Apple-tab-span"> </span><span class="s19">\dur</span>, 0.4,</p>
486 <p class="p6"><span class="Apple-tab-span"> </span><span class="s19">\out</span>, <span class="s18">Pseq</span>([0, 1], <span class="s18">inf</span>)</p>
487 <p class="p6">).play;</p>
488 <p class="p6">)</p>
489 </body>
490 </html>