?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
supernova: fixes for boost-1.49 and gcc-4.7
[supercollider.git] / Help / ServerArchitecture / Server.html
blobd6d34c20e887e8fca97c7d586420759b2bbbd5eb
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 0.0px; font: 9.0px Monaco; color: #a31917}
14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 13.0px Helvetica}
16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 15.0px Helvetica; min-height: 18.0px}
17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 15.0px Helvetica}
18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #6e3533; min-height: 12.0px}
20 p.p11 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
21 p.p12 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000}
22 p.p13 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
23 p.p14 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000; min-height: 12.0px}
24 p.p15 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0000bf}
25 p.p16 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #1534aa; min-height: 12.0px}
26 p.p17 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #000000; min-height: 14.0px}
27 p.p18 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #007300}
28 span.s1 {font: 18.0px Helvetica}
29 span.s2 {color: #1739a8}
30 span.s3 {color: #000000}
31 span.s4 {color: #0017b3}
32 span.s5 {color: #a31917}
33 span.s6 {font: 12.0px Helvetica}
34 span.s7 {color: #606060}
35 span.s8 {color: #595959}
36 span.s9 {font: 9.0px Monaco}
37 span.s10 {color: #35701d}
38 span.s11 {color: #0000bf}
39 span.s12 {color: #007300}
40 span.s13 {color: #bf0000}
41 span.s14 {color: #1c46e4}
42 span.s15 {text-decoration: underline ; color: #001de0}
43 span.s16 {color: #1534aa}
44 span.Apple-tab-span {white-space:pre}
45 </style>
46 </head>
47 <body>
48 <p class="p1"><span class="s1"><b>Server</b></span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><b>object representing an sc-server application</b></p>
49 <p class="p2"><br></p>
50 <p class="p1"><b>superclass: Model</b></p>
51 <p class="p2"><br></p>
52 <p class="p1">A Server object is the client-side representation of a server app and is used to control the app from the SuperCollider language application. (See <a href="ClientVsServer.html"><span class="s2">ClientVsServer</span></a> for more details on the distinction.) It forwards osc-messages and has a number of allocators that keep track of IDs for nodes, buses and buffers. The server application is a commandline program, so all commands apart from osc-messages are unix commands. The server application represented by a Server object might be running on the same machine as the client (in the same address space as the language application or separately; see below), or it may be running on a remote machine.<span class="Apple-converted-space"> </span></p>
53 <p class="p2"><br></p>
54 <p class="p1">Most of a Server's options are contolled through its instance of <b>ServerOptions</b>. See the <a href="ServerOptions.html"><span class="s2">ServerOptions</span></a> helpfile for more detail.</p>
55 <p class="p2"><br></p>
56 <p class="p3"><b>Paths</b></p>
57 <p class="p2"><br></p>
58 <p class="p1">Server apps running on the local machine have two unix environment variables: SC_SYNTHDEF_PATH and SC_PLUGIN_PATH. These indicate directories of synthdefs and ugen plugins that will be loaded at startup. These are in addition to the default synthdef/ and plugin/ directories which are hard-coded. These can be set within SC using the getenv and setenv methods of class <a href="../Collections/String.html"><span class="s2">String</span></a>.</p>
59 <p class="p2"><br></p>
60 <p class="p4">// all defs in this directory will be loaded when a local server boots</p>
61 <p class="p5">"SC_SYNTHDEF_PATH"<span class="s3">.setenv(</span>"~/scwork/"<span class="s3">.standardizePath);<span class="Apple-converted-space"> </span></span></p>
62 <p class="p5">"echo $SC_SYNTHDEF_PATH"<span class="s3">.unixCmd;</span></p>
63 <p class="p2"><br></p>
64 <p class="p6"><b>The default group</b></p>
65 <p class="p2"><br></p>
66 <p class="p1">When a Server is booted there is a top level group with an ID of 0 that defines the root of the node tree. (This is represented by a subclass of Group: <b>RootNode</b>.) If the server app was booted from within SCLang (as opposed to from the command line) the method initTree will be called automatically after booting. This will also create a <b>default_group</b> with an ID of 1, which is the default group for all Nodes when using object style. This provides a predictable basic node tree so that methods such as Server-scope, Server-record, etc. can function without running into order of execution problems. The default group is persistent, i.e. it is recreated after a reboot, pressing cmd-., etc. See <a href="RootNode.html"><span class="s2">RootNode</span></a> and <a href="default_group.html"><span class="s2">default_group</span></a> for more information. Note that if a Server has been booted from the command line you must call initTree manually in order to initialize the default group, if you want it. See <b>initTree</b> below.</p>
67 <p class="p2"><br></p>
68 <p class="p6"><b>Local vs. Internal</b></p>
69 <p class="p2"><br></p>
70 <p class="p1">In general, when working with a single machine one will probably be using one of two Server objects which are created at startup and stored in the class variables <b>local</b> and <b>internal</b>. By default two GUI windows are created to control these. The difference between the two is that the local server runs as a separate application with its own address space, and the internal server runs within the same space as the language/client app. The internal server has the advantage of being able to access shared memory, thus allowing for things like scope windows (see below) and <a href="../UGens/InOut/SharedIn.html"><span class="s2">SharedIn</span></a>/<a href="../UGens/InOut/SharedOut.html"><span class="s2">SharedOut</span></a>. It also minimizes messaging latency. The local server, and any other server apps running on your local machine, have the advantage that if the language app crashes, it (and thus possibly your piece) will continue to run. It is thus an inherently more robust arrangement.</p>
71 <p class="p2"><br></p>
72 <p class="p6"><b>The default Server</b></p>
73 <p class="p7"><br></p>
74 <p class="p1">There is always a default Server, which is stored in the class variable <b>default</b>. Any Synths or Groups created without a target will be created on the default server. At startup this is set to be the <b>local</b> server (see above), but can be set to be any Server.</p>
75 <p class="p2"><br></p>
76 <p class="p8"><b>Class Methods</b></p>
77 <p class="p2"><br></p>
78 <p class="p1"><b>*new(name, addr, options, clientID)</b></p>
79 <p class="p2"><span class="Apple-tab-span"> </span></p>
80 <p class="p1"><b><span class="Apple-tab-span"> </span>name</b> <b>- </b>a symbol;<span class="Apple-converted-space">  </span>each Server object is stored in one global classvariable under its name.</p>
81 <p class="p1"><b><span class="Apple-tab-span"> </span>addr - </b>an optional instance of <a href="../Control/NetAddr.html"><span class="s2">NetAddr</span></a>, providing host and port. The default is the localhost address <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>using port 57110; the same as the local server.</p>
82 <p class="p1"><b><span class="Apple-tab-span"> </span>options</b> <b>- </b>an optional instance of <b>ServerOptions</b>. If nil, an instance of ServerOptions will be created, using <span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>the default values.</p>
83 <p class="p1"><b><span class="Apple-tab-span"> </span>clientID - </b>an integer. In multi client situations, every client can be given a separate nodeID range.<span class="Apple-converted-space"> </span></p>
84 <p class="p1"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>The default is 0.</p>
85 <p class="p2"><br></p>
86 <p class="p2"><br></p>
87 <p class="p1"><b>*local - </b>returns the local server, stored in classvar local (created already on initClass)</p>
88 <p class="p2"><br></p>
89 <p class="p1"><b>*internal - </b>returns the internal server, stored in classvar local (created already on initClass)</p>
90 <p class="p2"><br></p>
91 <p class="p1"><b>*default - </b>returns the default server. By default this is the local server (see above)</p>
92 <p class="p2"><br></p>
93 <p class="p1"><b>*default_(aServer) - </b>sets the default Server to be aServer. This will also assign <b>aServer</b> to the interpreter variable 's'.</p>
94 <p class="p2"><span class="Apple-tab-span"> </span></p>
95 <p class="p4"><span class="s3"><span class="Apple-tab-span"> </span></span><span class="s4">Server</span><span class="s3">.default = </span><span class="s4">Server</span><span class="s3">.internal; </span>// set the internal Server to be the default Server</p>
96 <p class="p9"><span class="Apple-tab-span"> </span>s.postln; <span class="s5">// internal</span></p>
97 <p class="p2"><br></p>
98 <p class="p1"><b>*all</b> - the set of all servers.<span class="Apple-tab-span"> </span></p>
99 <p class="p2"><br></p>
100 <p class="p1"><b>*allRunningServers</b> - the set of all running servers.<span class="Apple-tab-span"> </span></p>
101 <p class="p2"><br></p>
102 <p class="p1"><b>*quitAll - </b>quit all registered servers</p>
103 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
104 <p class="p1"><b>*killAll - </b>query the system for any sc-server apps and hard quit them</p>
105 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
106 <p class="p1"><b>*freeAll - </b>free all nodes in all registered servers<span class="Apple-tab-span"> </span></p>
107 <p class="p2"><br></p>
108 <p class="p3"><b>Instance Methods</b></p>
109 <p class="p2"><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></p>
110 <p class="p1"><b>sendMsg(arg1, arg2, arg3, ... argN) - </b>send an osc message to the server.</p>
111 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
112 <p class="p9"><span class="s6"><span class="Apple-tab-span"> </span></span>s.sendMsg(<span class="s7">"/s_new"</span>, <span class="s7">"default"</span>, s.nextNodeID, 0, 1);</p>
113 <p class="p2"><br></p>
114 <p class="p1"><b>sendBundle(time, array1, array1, array1, ... arrayN) - </b>send an osc bundle to the server. Since the network may have irregular performance, <b>time</b> allows for the bundle to be evaluated at a specified point in the future. Thus all messages are synchronous relative to each other, but delayed by a constant offset. If such a bundle arrives late, the server replies with a late message but still evaluates it.<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>
115 <p class="p2"><span class="Apple-tab-span"> </span></p>
116 <p class="p9"><span class="s6"><span class="Apple-tab-span"> </span></span>s.sendBundle(0.2, [<span class="s7">"/s_new"</span>, <span class="s7">"default"</span>, x = s.nextNodeID, 0, 1], [<span class="s7">"/n_set"</span>, x, <span class="s7">"freq"</span>, 500]);</p>
117 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
118 <p class="p1"><b>sendRaw(aRawArray)</b></p>
119 <p class="p2"><br></p>
120 <p class="p1"><b>listSendMsg([arg1, arg2, arg3, ... argN]) - </b>as sendMsg, but takes an array as argument.</p>
121 <p class="p2"><br></p>
122 <p class="p1"><b>listSendBundle(time, [array1, array1, array1, ... arrayN]) - </b>as sendBundle, but takes an array as argument. This allows you to collect messages in an array and then send them.</p>
123 <p class="p2"><br></p>
124 <p class="p9"><span class="s6"><span class="Apple-tab-span"> </span></span>s.listSendBundle(0.2, [[<span class="s8">"/s_new"</span>, <span class="s8">"default"</span>, x = s.nextNodeID, 0, 1],<span class="Apple-converted-space"> </span></p>
125 <p class="p9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>[<span class="s8">"/n_set"</span>, x, <span class="s8">"freq"</span>, 600]]);</p>
126 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
127 <p class="p1"><b>sendSynthDef(name, dir) - </b>send a synthDef to the server that was written in a local directory</p>
128 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
129 <p class="p1"><b>loadSynthDef(name, completionMsg, dir) - </b>load a synthDef that resides in the remote directory</p>
130 <p class="p2"><br></p>
131 <p class="p1"><b>loadDirectory(dir, completionMsg) - </b>load all the SynthDefs in the directory <b>dir</b>. <b>dir</b> is a String which is a valid path.</p>
132 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
133 <p class="p1"><b>nextNodeID - </b>get a unique nodeID.<span class="Apple-converted-space"> </span></p>
134 <p class="p2"><br></p>
135 <p class="p1"><b>nextPermNodeID</b> - get a permanent node ID. This node ID is in a reserved range and will be held until you explicitly free it.</p>
136 <p class="p2"><br></p>
137 <p class="p1"><b>freePermNodeID</b> - free a permanent node ID for later reuse.</p>
138 <p class="p2"><span class="Apple-tab-span"> </span></p>
139 <p class="p1"><b>wait(responseName) - </b>this can be used within a Routine to wait for a server reply</p>
140 <p class="p2"><br></p>
141 <p class="p1"><b>waitForBoot(func, limit) - </b>evaluate the function <b>func </b>as soon as the server has booted. If it is running, it is evaluated immediately. If it is not running, boot the server and evaluate the function. <b>limit</b> indicates the maximum times to try. (5 times/sec)</p>
142 <p class="p2"><br></p>
143 <p class="p1"><b>doWhenBooted(func, limit) - </b>evaluate the function as soon as the server has booted. If it is running, it is evaluated immediately. <b>limit </b>is the maximum number of times to try. (5 times/sec)</p>
144 <p class="p2"><br></p>
145 <p class="p1"><b>boot(startAliveThread) -</b> boot the remote server, create new allocators. <b>startAliveThread</b>: if set to false, the server is not queried to give information for the window. <b>N.B. </b>You cannot locally boot a server app on a remote machine.</p>
146 <p class="p2"><br></p>
147 <p class="p1"><b>quit - </b>quit the server application</p>
148 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
149 <p class="p1"><b>reboot - </b>quit and restart the server application</p>
150 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
151 <p class="p1"><b>freeAll - </b>free all nodes in this server<span class="Apple-converted-space"> </span></p>
152 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
153 <p class="p1"><b>status - </b>query the server status</p>
154 <p class="p2"><br></p>
155 <p class="p1"><b>notify(flag) - </b>server sends notifications, for example if a node was created, a 'tr' message from a SendTrig, or a /done action. if flag is set to false, these messages are not sent. The default is true.</p>
156 <p class="p2"><br></p>
157 <p class="p1"><b>dumpOSC(code)</b></p>
158 <p class="p1"><b><span class="Apple-tab-span"> </span>code</b>:</p>
159 <p class="p1"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>0 - turn dumping OFF.</p>
160 <p class="p1"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>1 - print the parsed contents of the message.</p>
161 <p class="p1"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>2 - print the contents in hexadecimal.</p>
162 <p class="p1"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>3 - print both the parsed and hexadecimal representations of the contents.</p>
163 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
164 <p class="p1"><b>queryAllNodes - </b>Post a representation of this Server's current node tree to the post window. Very helpful for debugging. For local servers this uses g_dumpTree and for remote g_queryTree. See <a href="Group.html"><span class="s2">Group</span></a> and <a href="Server-Command-Reference.html"><span class="s2">Server-Command-Reference</span></a> for more info.</p>
165 <p class="p10"><span class="Apple-tab-span"> </span></p>
166 <p class="p9"><span class="Apple-tab-span"> </span>s.boot;</p>
167 <p class="p4"><span class="s3"><span class="Apple-tab-span"> </span>s.queryAllNodes; </span>// note the root node (ID 0) and the default group (ID 1)</p>
168 <p class="p9"><span class="Apple-tab-span"> </span>s.quit;</p>
169 <p class="p11"><span class="Apple-tab-span"> </span></p>
170 <p class="p1"><b>ping(numberOfTimes, waitBewteen, completionFunction)</b></p>
171 <p class="p1"><span class="s9"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></span>measure the time between server and client, which may vary. the completionFunction is</p>
172 <p class="p1"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>evaluated after numberOfTimes and is passed the resulting maximum.<span class="Apple-converted-space"> </span></p>
173 <p class="p11"><br></p>
174 <p class="p11"><br></p>
175 <p class="p1"><b>options - </b>returns this Server's <a href="ServerOptions.html"><span class="s2">ServerOptions</span></a> object. Changes take effect when the server is rebooted.</p>
176 <p class="p2"><br></p>
177 <p class="p1"><b>options_(aServerOptions) - </b>sets this Server's <a href="ServerOptions.html"><span class="s2">ServerOptions</span></a> object. Changes take effect when the server is rebooted.</p>
178 <p class="p11"><br></p>
179 <p class="p1"><b>defaultGroup - </b>returns this Server's default group.</p>
180 <p class="p11"><span class="Apple-tab-span"> </span></p>
181 <p class="p1"><b>volume -</b> an instance of Volume that runs after the defualt group.</p>
182 <p class="p2"><br></p>
183 <p class="p1"><b>volume_(level) -</b> sets the Volume of the Server's output to level. Level is in db.</p>
184 <p class="p11"><br></p>
185 <p class="p1"><b>mute - </b>mute the server's output. This can also be toggled from the Server window with the 'm' key.</p>
186 <p class="p11"><br></p>
187 <p class="p1"><b>unmute - </b>unmute the server. This can also be toggled from the Server window with the 'm' key.</p>
188 <p class="p2"><br></p>
189 <p class="p1"><b>reorder(nodeList, target, addAction)</b> - Move the nodes in <b>nodeList</b> to the location specified by <b>target</b> and <b>addAction</b>, placing them there in the order indicated by <b>nodeList</b>. Any nodes which have already been freed will be skipped. Passing nil for target and addAction will result in the location being the head of the default group.</p>
190 <p class="p2"><span class="Apple-tab-span"> </span></p>
191 <p class="p9"><span class="s6"><span class="Apple-tab-span"> </span></span>g = <span class="s4">Group</span>.new;</p>
192 <p class="p9"><span class="Apple-tab-span"> </span>x = <span class="s4">Array</span>.fill(5, {<span class="s4">Synth</span>(<span class="s10">\default</span>)});</p>
193 <p class="p9"><span class="Apple-tab-span"> </span>s.queryAllNodes;</p>
194 <p class="p9"><span class="Apple-tab-span"> </span>s.reorder(x, g, <span class="s10">\addToTail</span>);</p>
195 <p class="p9"><span class="Apple-tab-span"> </span>s.queryAllNodes;</p>
196 <p class="p11"><br></p>
197 <p class="p8"><b>Automatic Message Bundling</b></p>
198 <p class="p7"><br></p>
199 <p class="p1">Server provides support for automatically bundling messages. This is quite convenient in object style, and ensures synchronous execution. See also <b>bundledCommands</b>.</p>
200 <p class="p2"><br></p>
201 <p class="p1"><b>makeBundle(time, func, bundle) </b>- The Function <b>func </b>is evaluated, and all OSC messages generated by it are deferred and added to a bundle. This method returns the bundle so that it can be further used if needed. If <b>time</b> is set to nil or a number the bundle will be automatically sent and executed after the corresponding delay in seconds<i>. </i>If <b>time </b>is set to false the bundle will not be sent.<span class="Apple-converted-space"> </span><i> </i><b>bundle </b>allows you to pass in a preexisting bundle and continue adding to it. If an error is encountered while evaluating <b>func</b> this method will throw an <b>Error</b> and stop message deferral. Calling <b>sync</b> inside <b>func</b> will split the bundle and wait for asynchronous actions to complete before continuing.</p>
202 <p class="p2"><br></p>
203 <p class="p12"><span class="Apple-tab-span"> </span>s.boot;</p>
204 <p class="p12"><span class="Apple-tab-span"> </span>(</p>
205 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// send a synth def to server</p>
206 <p class="p12"><span class="Apple-tab-span"> </span><span class="s11">SynthDef</span>(<span class="s7">"tpulse"</span>, { <span class="s11">arg</span> out=0,freq=700,sawFreq=440.0;</p>
207 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="s11">Out</span>.ar(out, <span class="s11">SyncSaw</span>.ar(freq,<span class="Apple-converted-space">  </span>sawFreq,0.1) )</p>
208 <p class="p12"><span class="Apple-tab-span"> </span>}).add;</p>
209 <p class="p12"><span class="Apple-tab-span"> </span>)</p>
210 <p class="p14"><span class="Apple-tab-span"> </span></p>
211 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// all OSC commands generated in the function contained below will be added to a bundle</p>
212 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// and executed simultaneously after 2 seconds.</p>
213 <p class="p12"><span class="Apple-tab-span"> </span>(</p>
214 <p class="p12"><span class="Apple-tab-span"> </span>s.makeBundle(2.0, {</p>
215 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>x = <span class="s11">Synth</span>.new(<span class="s7">"tpulse"</span>);</p>
216 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a = <span class="s11">Bus</span>.control.set(440);</p>
217 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>x.map(<span class="s12">\freq</span>, a);</p>
218 <p class="p12"><span class="Apple-tab-span"> </span>});</p>
219 <p class="p12"><span class="Apple-tab-span"> </span>)</p>
220 <p class="p12"><span class="Apple-tab-span"> </span>x.free;</p>
221 <p class="p14"><span class="Apple-tab-span"> </span></p>
222 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// don't send</p>
223 <p class="p12"><span class="Apple-tab-span"> </span>(</p>
224 <p class="p12"><span class="Apple-tab-span"> </span>b = s.makeBundle(<span class="s11">false</span>, {<span class="Apple-converted-space"> <span class="Apple-tab-span"> </span></span></p>
225 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>x = { <span class="s11">PinkNoise</span>.ar(0.1) * <span class="s11">In</span>.kr(0, 1); }.play;</p>
226 <p class="p12"><span class="Apple-tab-span"> </span>});</p>
227 <p class="p12"><span class="Apple-tab-span"> </span>)</p>
228 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// now pass b as a pre-existing bundle, and start both synths synchronously</p>
229 <p class="p12"><span class="Apple-tab-span"> </span>(</p>
230 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span>s.makeBundle(</span><span class="s11">nil</span><span class="s3">, { </span>// nil executes ASAP</p>
231 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>y = { <span class="s11">SinOsc</span>.kr(0.2).abs }.play(x, 0, 0, <span class="s12">\addBefore</span>); <span class="s13">// sine envelope</span></p>
232 <p class="p12"><span class="Apple-tab-span"> </span>}, b);</p>
233 <p class="p12"><span class="Apple-tab-span"> </span>)</p>
234 <p class="p12"><span class="Apple-tab-span"> </span>x.free; y.free;</p>
235 <p class="p14"><span class="Apple-tab-span"> </span></p>
236 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// Throw an Error</p>
237 <p class="p12"><span class="Apple-tab-span"> </span>(</p>
238 <p class="p12"><span class="Apple-tab-span"> </span>try {</p>
239 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>s.makeBundle(<span class="s11">nil</span>, {</p>
240 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>s.farkermartin;</p>
241 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>});</p>
242 <p class="p15"><span class="s3"><span class="Apple-tab-span"> </span>} { </span>|error|</p>
243 <p class="p5"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>(</span>"Look Ma, normal operations resume even though:\n"<span class="s3"> + error.errorString).postln;<span class="Apple-converted-space"> </span></span></p>
244 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>x = { <span class="s11">FSinOsc</span>.ar(440, 0, 0.2) }.play; <span class="s13">// This works fine</span></p>
245 <p class="p12"><span class="Apple-tab-span"> </span>}</p>
246 <p class="p12"><span class="Apple-tab-span"> </span>)</p>
247 <p class="p12"><span class="Apple-tab-span"> </span>x.free;</p>
248 <p class="p14"><span class="Apple-tab-span"> </span></p>
249 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// use sync</p>
250 <p class="p12"><span class="Apple-tab-span"> </span>(</p>
251 <p class="p12"><span class="Apple-tab-span"> </span>s.makeBundle(<span class="s11">nil</span>, {</p>
252 <p class="p5"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>b = </span><span class="s11">Buffer</span><span class="s3">.read(s, </span>"sounds/a11wlk01.wav"<span class="s3">);</span></p>
253 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>s.sync; </span>// wait until load is done and then send the rest of the bundle</p>
254 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>x = { <span class="s11">PlayBuf</span>.ar(1, b) * 0.5 }.play;</p>
255 <p class="p12"><span class="Apple-tab-span"> </span>});</p>
256 <p class="p12"><span class="Apple-tab-span"> </span>)</p>
257 <p class="p12"><span class="Apple-tab-span"> </span>x.free; b.free;</p>
258 <p class="p2"><br></p>
259 <p class="p1"><b>bind(func) </b>- Just as in <b>makeBundle</b>, the Function <b>func </b>is evaluated, and all OSC messages generated by it are deferred and added to a bundle, which is sent to the server, using the server default latency.</p>
260 <p class="p11"><br></p>
261 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// example</p>
262 <p class="p12"><span class="Apple-tab-span"> </span>(</p>
263 <p class="p12"><span class="Apple-tab-span"> </span>s.bind {</p>
264 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a = { <span class="s11">|freq=100|</span> <span class="s11">SinOsc</span>.ar(freq, <span class="s11">LFTri</span>.ar(freq)) * 0.2 }.play;</p>
265 <p class="p12"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>a.set(<span class="s12">\freq</span>, 400);</p>
266 <p class="p12"><span class="Apple-tab-span"> </span>}</p>
267 <p class="p12"><span class="Apple-tab-span"> </span>)</p>
268 <p class="p7"><br></p>
269 <p class="p8"><b>Shared Controls</b></p>
270 <p class="p2"><br></p>
271 <p class="p1">The internal server has a number of shared control buses. Their values can be set or polled using the methods below.</p>
272 <p class="p2"><br></p>
273 <p class="p1"><b>getSharedControl(num)</b> - get the current value of a shared control bus. <b>num</b> is the index of the bus to poll. This command is synchronous and only works with the internal server.</p>
274 <p class="p2"><br></p>
275 <p class="p1"><b>setSharedControl(num, value)</b> - set the current value of a shared control bus to <b>value</b>. <b>num</b> is the index of the bus to set. This command is synchronous and only works with the internal server.</p>
276 <p class="p2"><br></p>
277 <p class="p1"><b>allocSharedControls(numControls)</b> - set the number of shared control buses. Must be done before the internal server is booted. The default is 1024.</p>
278 <p class="p2"><br></p>
279 <p class="p8"><b>Persistent Node Trees</b></p>
280 <p class="p2"><br></p>
281 <p class="p1">The class <a href="../Control/ServerTree.html"><span class="s14">ServerTree</span></a> can be used to store functions which will be evaluated after the server is booted, after all nodes are freed, and after cmd-. is pressed. This allows, for example, for one to create a persistent basic node structure. ServerTree is evaluated in the method <b>initTree</b> after the default group is created, so its existence can be relied upon.</p>
282 <p class="p2"><br></p>
283 <p class="p1"><b>initTree</b> - This method initializes the <a href="default_group.html"><span class="s2">default_group</span></a> and runs ServerTree. This method is called automatically when you boot a Server from the language. <b>N.B.</b> If you started a server app from the command line you will have to call initTree manually if you need this functionality.</p>
284 <p class="p2"><br></p>
285 <p class="p12"><span class="s6"><span class="Apple-tab-span"> </span></span>s.quit;</p>
286 <p class="p12"><span class="Apple-tab-span"> </span>f = {<span class="s11">Group</span>.new(s.defaultGroup); <span class="s7">"Other code can be evaluated too"</span>.postln;};</p>
287 <p class="p15"><span class="s3"><span class="Apple-tab-span"> </span></span>ServerTree<span class="s3">.add(f);</span></p>
288 <p class="p12"><span class="Apple-tab-span"> </span>s.boot;</p>
289 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span>s.queryAllNodes; </span>// note the group within the default group</p>
290 <p class="p12"><span class="Apple-tab-span"> </span><span class="s11">ServerTree</span>.remove(f);</p>
291 <p class="p2"><br></p>
292 <p class="p1"><span class="s15"><a href="../Control/ServerBoot.html">ServerBoot</a></span> and <a href="../Control/ServerQuit.html"><span class="s14">ServerQuit</span></a> provide similar functionality at boot and quit times.</p>
293 <p class="p2"><br></p>
294 <p class="p8"><b>Keyboard Shortcuts</b></p>
295 <p class="p2"><br></p>
296 <p class="p1">when a server window is in focus, these shortcuts can be used:</p>
297 <p class="p2"><br></p>
298 <p class="p1"><b>space</b>:<span class="Apple-tab-span"> </span>start the server</p>
299 <p class="p1"><b>d</b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>toggle dumpOSC</p>
300 <p class="p1"><b>n</b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>post a representation of the node tree</p>
301 <p class="p1"><b>N<span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></b>post a representation of the node tree and the current control values of any synths</p>
302 <p class="p1"><b>s</b><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span>scope (internal server only)</p>
303 <p class="p2"><br></p>
304 <p class="p8"><b>Scope Support</b></p>
305 <p class="p2"><br></p>
306 <p class="p1">This only works with the internal server, and currently only on OSX.</p>
307 <p class="p1">see<b> </b><a href="../GUI/Main-GUI/Stethoscope.html"><span class="s2">Stethoscope</span></a><b> </b>for further details.</p>
308 <p class="p2"><br></p>
309 <p class="p1"><b>scope(numChannels, index, bufsize, zoom, rate) - </b>Open a scope window showing the output of the Server.<span class="Apple-converted-space"> </span></p>
310 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
311 <p class="p1"><b>numChannels </b>- the number of channels to be scoped out. The default is this server's options' numOutputBusChannels.</p>
312 <p class="p1"><b>index </b>- the first channel to be output. The default is 0.</p>
313 <p class="p1"><b>bufsize </b>- the size of the buffer for the ScopeView. The default is 4096.</p>
314 <p class="p1"><b>zoom</b> - a zoom value for the scope's X axis. Larger values show more. The default is 1.</p>
315 <p class="p1"><b>rate</b> - whether to display audio or control rate buses (either \audio or \control)</p>
316 <p class="p2"><br></p>
317 <p class="p8"><b>Recording Support</b></p>
318 <p class="p2"><br></p>
319 <p class="p1">The following methods are for convenience use. For recording with sample accurate start and stop times you should make your own nodes. See the <a href="../UGens/Playback and Recording/DiskOut.html"><span class="s16">DiskOut</span></a> helpfile for more info. For non-realtime recording, see the <a href="../Other Topics/Non-Realtime-Synthesis.html"><span class="s16">Non-Realtime-Synthesis</span></a> helpfile.<span class="Apple-converted-space"> </span></p>
320 <p class="p2"><br></p>
321 <p class="p1">This functionality is also available through the recording button on the server windows. Pressing it once calls <b>record</b>, and pressing it again calls <b>stopRecording</b> (see below). When doing so the file created will be in your recordings folder and be named for the current date and time. The default location of the recordings folder varies from platform to platform but is always stored in <b>thisProcess.platform.recordingsDir</b>. Setting this variable allows you to change the default.</p>
322 <p class="p2"><br></p>
323 <p class="p1"><b>NOTE:</b> <b>record</b> creates the recording synth after the Server's default group and uses <b>In.ar</b>. Thus if you add nodes after the recording synth their output will not be captured. To avoid this, either use <b>Node</b> objects (which use the default node as their target) or (when using messaging style) use a target nodeID of 1 .</p>
324 <p class="p16"><br></p>
325 <p class="p9">s.sendMsg(<span class="s8">"/s_new"</span>, <span class="s8">"default"</span>, s.nextNodeID, 1,1);</p>
326 <p class="p2"><br></p>
327 <p class="p1">For more detail on this subject see <a href="Order-of-execution.html"><span class="s16">Order-of-execution</span></a><b>,</b> <a href="default_group.html"><span class="s16">default_group</span></a>, and <a href="NodeMessaging.html"><span class="s16">NodeMessaging</span></a>.</p>
328 <p class="p2"><br></p>
329 <p class="p1"><b>prepareForRecord(path) - </b>Allocates the necessary buffer, etc. for recording the server's output. (See <b>record</b> below.) <b>path </b>is a String representing the path and name of the output file. If you do not specify a path than a file will be created in your recordings folder (see the note above on this) called SC_thisDateAndTime. Changes to the header or sample format, or to the number of channels must be made BEFORE calling this.</p>
330 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
331 <p class="p1"><b>record(path) - </b>Starts or resumes recording the output. If you have not called prepareForRecord first (see above) then it will be invoked for you (but that adds a slight delay before recording starts for real). The <b>path</b> argument is optional and is passed to <b>prepareForRecord</b> (above).</p>
332 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
333 <p class="p1"><b>pauseRecording - </b>Pauses recording. Can be resumed by executing record again.</p>
334 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
335 <p class="p1"><b>stopRecording - </b>Stops recording, closes the file, and frees the associated resources. You must call this when finished recording or the output file will be unusable. Cmd-. while recording has the same effect.</p>
336 <p class="p2"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
337 <p class="p1"><b>recordNode - </b>Returns the current recording synth so that it can be used as a target. This should only be necessary for nodes which are not created in the default group.</p>
338 <p class="p2"><br></p>
339 <p class="p2"><br></p>
340 <p class="p1">The following setter methods have corresponding getters. See <a href="../Files/SoundFile.html"><span class="s2">SoundFile</span></a> for information on the various sample and header formats.<span class="Apple-tab-span"> </span>Not all sample and header formats are compatible.</p>
341 <p class="p2"><br></p>
342 <p class="p1"><b>recChannels_(anInteger) - </b>Sets the number of channels to record. The default is two. Must be called BEFORE prepareForRecord.</p>
343 <p class="p2"><br></p>
344 <p class="p1"><b>recHeaderFormat_(aString) - </b>Sets the header format of the output file. The default is "aiff". Must be called BEFORE prepareForRecord.</p>
345 <p class="p2"><span class="Apple-tab-span"> </span></p>
346 <p class="p1"><b>recSampleFormat_(aString) - </b>Sets the sample format of the output file. The default is "float". Must be called BEFORE prepareForRecord.</p>
347 <p class="p2"><br></p>
348 <p class="p1">Note that the sampling rate of the ouput file will be the same as that of the server app. This can be set using the Server's <a href="ServerOptions.html"><span class="s2">ServerOptions</span></a>.</p>
349 <p class="p2"><br></p>
350 <p class="p17"><br></p>
351 <p class="p13"><span class="s3">s.boot; </span>// start the server</p>
352 <p class="p14"><br></p>
353 <p class="p13">// something to record</p>
354 <p class="p12">(</p>
355 <p class="p5"><span class="s11">SynthDef</span><span class="s3">(</span>"bubbles"<span class="s3">, {</span></p>
356 <p class="p12"><span class="Apple-tab-span"> </span><span class="s11">var</span> f, zout;</p>
357 <p class="p12"><span class="Apple-tab-span"> </span>f = <span class="s11">LFSaw</span>.kr(0.4, 0, 24, <span class="s11">LFSaw</span>.kr([8,7.23], 0, 3, 80)).midicps; <span class="s13">// glissando function</span></p>
358 <p class="p12"><span class="Apple-tab-span"> </span>zout = <span class="s11">CombN</span>.ar(<span class="s11">SinOsc</span>.ar(f, 0, 0.04), 0.2, 0.2, 4); <span class="s13">// echoing sine wave</span></p>
359 <p class="p12"><span class="Apple-tab-span"> </span><span class="s11">Out</span>.ar(0, zout);</p>
360 <p class="p12">}).add;</p>
361 <p class="p12"><span class="s11">SynthDef</span>(<span class="s7">"tpulse"</span>, { <span class="s11">arg</span> out=0,freq=700,sawFreq=440.0;<span class="Apple-converted-space"> </span></p>
362 <p class="p12"><span class="Apple-tab-span"> </span><span class="s11">Out</span>.ar(out, <span class="s11">SyncSaw</span>.ar(freq,<span class="Apple-converted-space">  </span>sawFreq,0.1) )<span class="Apple-converted-space"> </span></p>
363 <p class="p12">}).add;</p>
364 <p class="p14"><br></p>
365 <p class="p12">)</p>
366 <p class="p14"><br></p>
367 <p class="p12">x = <span class="s11">Synth</span>.new(<span class="s7">"bubbles"</span>);</p>
368 <p class="p14"><br></p>
369 <p class="p13"><span class="s3">s.prepareForRecord; </span>// you have to call this first</p>
370 <p class="p14"><br></p>
371 <p class="p12">s.record;</p>
372 <p class="p14"><br></p>
373 <p class="p12">s.pauseRecording; <span class="s13">// pausable</span></p>
374 <p class="p14"><br></p>
375 <p class="p13"><span class="s3">s.record </span>// start again</p>
376 <p class="p14"><br></p>
377 <p class="p13"><span class="s3">s.stopRecording; </span>// this closes the file and deallocates the buffer recording node, etc.</p>
378 <p class="p14"><br></p>
379 <p class="p13"><span class="s3">x.free; </span>// stop the synths</p>
380 <p class="p14"><br></p>
381 <p class="p13">// look in your recordings folder and you'll find a file named for this date and time</p>
382 <p class="p10"><br></p>
383 <p class="p8"><b>Asynchronous Commands</b></p>
384 <p class="p7"><br></p>
385 <p class="p1">Server provides support for waiting on the completion of asynchronous OSC commands such as reading or writing soundfiles. <b>N.B. </b>The following methods must be called from within a running <a href="../Core/Kernel/Routine.html"><span class="s2">Routine</span></a>. Explicitly passing in a <a href="../Scheduling/Condition.html"><span class="s2">Condition</span></a> allows multiple elements to depend on different conditions. The examples below should make clear how all this works.</p>
386 <p class="p2"><br></p>
387 <p class="p1"><b>bootSync(condition) - </b>Boot the Server and wait until it has completed before resuming the thread. <b>condition</b> is an optional instance of <b>Condition</b> used for evaluating this.</p>
388 <p class="p2"><br></p>
389 <p class="p1"><b>sendMsgSync(condition, args) - </b>Send the following message to the<span class="Apple-converted-space">  </span>wait until it has completed before resuming the thread. <b>condition</b> is an optional instance of <a href="../Scheduling/Condition.html"><span class="s2">Condition</span></a> used for evaluating this. <b>args </b>should be one or more valid OSC messages.</p>
390 <p class="p2"><br></p>
391 <p class="p1"><b>sync(condition, bundles, latency)</b> - Send a /sync message to the server, which will replie with the message /synced when all pending asynchronous commands have been completed. <b>condition</b> is an optional instance of <a href="../Scheduling/Condition.html"><span class="s2">Condition</span></a> used for evaluating this. This may be slightly less safe then <b>sendMsgSync</b> under UDP on a wide area network, as packets may arrive out of order, but on a local network should be okay. Under TCP this should always be safe. <b>bundles</b> is one or more OSC messages which will be bundled before the sync message (thus ensuring that they will arrive before the /sync message). <b>latency </b>allows for the message to be evaluated at a specific point in the future.</p>
392 <p class="p17"><br></p>
393 <p class="p12">(</p>
394 <p class="p15">Routine<span class="s3">.run {</span></p>
395 <p class="p12"><span class="Apple-tab-span"> </span><span class="s11">var</span> c;</p>
396 <p class="p14"><br></p>
397 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// create a condition variable to control execution of the Routine</p>
398 <p class="p12"><span class="Apple-tab-span"> </span>c = <span class="s11">Condition</span>.new;</p>
399 <p class="p14"><span class="Apple-tab-span"> </span></p>
400 <p class="p12"><span class="Apple-tab-span"> </span>s.bootSync(c);</p>
401 <p class="p12"><span class="Apple-tab-span"> </span><span class="s12">\BOOTED</span>.postln;</p>
402 <p class="p14"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
403 <p class="p12"><span class="Apple-tab-span"> </span>s.sendMsgSync(c, <span class="s7">"/b_alloc"</span>, 0, 44100, 2);</p>
404 <p class="p12"><span class="Apple-tab-span"> </span>s.sendMsgSync(c, <span class="s7">"/b_alloc"</span>, 1, 44100, 2);</p>
405 <p class="p12"><span class="Apple-tab-span"> </span>s.sendMsgSync(c, <span class="s7">"/b_alloc"</span>, 2, 44100, 2);</p>
406 <p class="p18"><span class="s3"><span class="Apple-tab-span"> </span></span>\b_alloc_DONE<span class="s3">.postln;</span></p>
407 <p class="p12">};</p>
408 <p class="p12">)</p>
409 <p class="p14"><br></p>
410 <p class="p12">(</p>
411 <p class="p15">Routine<span class="s3">.run {</span></p>
412 <p class="p12"><span class="Apple-tab-span"> </span><span class="s11">var</span> c;</p>
413 <p class="p14"><br></p>
414 <p class="p13"><span class="s3"><span class="Apple-tab-span"> </span></span>// create a condition variable to control execution of the Routine</p>
415 <p class="p12"><span class="Apple-tab-span"> </span>c = <span class="s11">Condition</span>.new;</p>
416 <p class="p14"><span class="Apple-tab-span"> </span></p>
417 <p class="p12"><span class="Apple-tab-span"> </span>s.bootSync(c);</p>
418 <p class="p12"><span class="Apple-tab-span"> </span><span class="s12">\BOOTED</span>.postln;</p>
419 <p class="p14"><span class="Apple-tab-span"> </span><span class="Apple-tab-span"> </span></p>
420 <p class="p12"><span class="Apple-tab-span"> </span>s.sendMsg(<span class="s7">"/b_alloc"</span>, 0, 44100, 2);</p>
421 <p class="p12"><span class="Apple-tab-span"> </span>s.sendMsg(<span class="s7">"/b_alloc"</span>, 1, 44100, 2);</p>
422 <p class="p12"><span class="Apple-tab-span"> </span>s.sendMsg(<span class="s7">"/b_alloc"</span>, 2, 44100, 2);</p>
423 <p class="p12"><span class="Apple-tab-span"> </span>s.sync(c);</p>
424 <p class="p18"><span class="s3"><span class="Apple-tab-span"> </span></span>\b_alloc_DONE<span class="s3">.postln;</span></p>
425 <p class="p12">};</p>
426 <p class="p12">)</p>
427 <p class="p17"><br></p>
428 <p class="p2"><br></p>
429 <p class="p7"><br></p>
430 <p class="p10"><br></p>
431 <p class="p10"><br></p>
432 <p class="p10"><br></p>
433 <p class="p10"><br></p>
434 </body>
435 </html>