Help/ServerArchitecture/Server-Architecture.html

   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="824.48">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica; min-height: 22.0px}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 10.0px Helvetica; min-height: 12.0px}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 10.0px Helvetica}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  16 span.Apple-tab-span {white-space:pre}
  17 </style>
  18 </head>
  19 <body>
  20 <p class="p1"><br></p>
  21 <p class="p2">SuperCollider 3 Synth Server Architecture</p>
  22 <p class="p3"><br></p>
  23 <p class="p4">copyright © 2002 James McCartney</p>
  24 <p class="p1"><br></p>
  25 <p class="p2">Introduction</p>
  26 <p class="p5"><br></p>
  27 <p class="p6">The SuperCollider 3 Synth Server is a simple but powerful synthesis engine. While synthesis is running, new modules can be created, destroyed and repatched, sample buffers can be created and reallocated. Effects processes can be created and patched into a signal flow dynamically at scheduled times.<span class="Apple-converted-space">  </span>All running modules are ordered in a tree of nodes that define an order of execution. Patching between modules is done through global audio and control buses.<span class="Apple-converted-space"> </span></p>
  28 <p class="p5"><br></p>
  29 <p class="p6">All commands are received via TCP or UDP using a simplified version of Open Sound Control (OSC). The synth server and its client(s) may be on the same machine or across a network. The synth server does not send or receive MIDI. It is expected that the client will send all control commands. If MIDI is desired, it is up to the client to receive it and convert it to appropriate OSC commands for the synth engine.</p>
  30 <p class="p5"><br></p>
  31 <p class="p6">Synth definitions are stored in files generated by the SuperCollider language application. Unit generator definitions are Mach-O bundles (not to be confused with CFBundles). The Unit generator API is a simple C interface.</p>
  32 <p class="p1"><br></p>
  33 <p class="p1"><br></p>
  34 <p class="p1"><br></p>
  35 <p class="p2">Main Design Concepts</p>
  36 <p class="p5"><br></p>
  37 <p class="p6"><b>Node</b></p>
  38 <p class="p6">A Node is an addressable node in a tree of nodes run by the synth engine. There are two types, Synths and Groups. The tree defines the order of execution of all Synths. All nodes have an integer ID.</p>
  39 <p class="p5"><br></p>
  40 <p class="p6"><b>Group</b></p>
  41 <p class="p6">A Group is a collection of Nodes represented as a linked list. A new Node may be added to the head or tail of the group. The Nodes within a Group may be controlled together. The Nodes in a Group may be both Synths and other Groups. At startup there is a top level group with an ID of zero that defines the root of the tree. If the server was booted from within SCLang (as opposed to from the command line) there will also be a 'default group' with an ID of 1 which is the default target for all new Nodes. See <b>RootNode</b> and <b>default_group</b> for more info.</p>
  42 <p class="p5"><br></p>
  43 <p class="p6"><b>Synth</b></p>
  44 <p class="p6">A Synth is a collection of unit generators that run together. They can be addressed and controlled by commands to the synthesis engine. They read input and write output to global audio and control buses. Synths can have their own local controls that are set via commands to the server.</p>
  45 <p class="p5"><br></p>
  46 <p class="p6"><b>Synth Definition</b></p>
  47 <p class="p6">Synths are created from Synth Definitions. Synth Definition files are created by the SuperCollider language application and are loaded into the synth server. Synth Definitions are referred to by name.</p>
  48 <p class="p5"><br></p>
  49 <p class="p6"><b>Audio Buses</b></p>
  50 <p class="p6">Synths send audio signals to each other via a single global array of audio buses.<span class="Apple-converted-space">  </span>Audio buses are indexed by integers beginning with zero. Using buses rather than connecting synths to each other directly allows synths to connect themselves to the community of other synths without having to know anything about them specifically. The lowest numbered buses get written to the audio hardware outputs. Immediately following the output buses are the input buses, read from the audio hardware inputs. The number of bus channels defined as inputs and outputs do not have to match that of the hardware.</p>
  51 <p class="p5"><br></p>
  52 <p class="p6"><b>Control Buses</b></p>
  53 <p class="p6">Synths can send control signals to each other via a single global array of control buses.<span class="Apple-converted-space">  </span>Buses are indexed by integers beginning with zero.</p>
  54 <p class="p5"><br></p>
  55 <p class="p6"><b>Shared Control Buses</b></p>
  56 <p class="p6">The internal server (which runs within the same address space as the client app) also has a number of shared control buses to which the client app has synchronous read/write access.<span class="Apple-converted-space">  </span>These buses are indexed by integers beginning with zero.</p>
  57 <p class="p5"><br></p>
  58 <p class="p6"><b>Buffers</b></p>
  59 <p class="p6">Buffers are arrays of 32 bit floating point values with a small descriptive header. Buffers are stored in a single global array indexed by integers beginning with zero. Buffers may be safely allocated, loaded and freed while synthesis is running, even while unit generators are using them. Buffers are used for wave tables, sample buffers, delay lines, envelopes, or for any other need which can use an array of floating point values. Sound files may be loaded into or written from buffers.</p>
  60 <p class="p5"><br></p>
  61 <p class="p6"><b>Unit Generator Definitions</b></p>
  62 <p class="p6">Unit Generator Definitions are plug-ins loaded automatically when the program starts. They are binary code libraries that are used as building blocks by Synths to build synthesis algorithms. Unit Generator Definitions have names that match the names of SuperCollider language classes used in building Synth Definitions.<span class="Apple-converted-space"> </span></p>
  63 <p class="p5"><br></p>
  64 <p class="p1"><br></p>
  65 <p class="p1"><br></p>
  66 <p class="p2">Command Line Arguments</p>
  67 <p class="p1"><br></p>
  68 <p class="p6">One of -u or -t must be supplied. Both may be supplied.</p>
  69 <p class="p6">-u <i>udp-port-number</i></p>
  70 <p class="p6"><span class="Apple-tab-span">     </span>a port number 0-65535.<span class="Apple-converted-space"> </span></p>
  71 <p class="p6">-t <i>tcp-port-number</i></p>
  72 <p class="p6"><span class="Apple-tab-span">     </span>a port number 0-65535</p>
  73 <p class="p5"><span class="Apple-tab-span">     </span></p>
  74 <p class="p6">-v <i>verbosity</i></p>
  75 <p class="p6"><span class="Apple-tab-span">     </span>Controls the verbosity of server messages. A value of 0 is normal behaviour, -1 suppresses informational</p>
  76 <p class="p6"><span class="Apple-tab-span">     </span>messages, and -2 suppresses informational and many error messages.</p>
  77 <p class="p5"><span class="Apple-tab-span">     </span></p>
  78 <p class="p6">-a <i>num-audio-bus-channels</i></p>
  79 <p class="p6"><span class="Apple-tab-span">     </span>number of audio bus channels (default = 128).</p>
  80 <p class="p6"><span class="Apple-tab-span">     </span>The space allocated for audio buses is: (numchannels * (blocksize + 1) * 4)</p>
  81 <p class="p6">-i <i>num-input-bus-channels</i></p>
  82 <p class="p6"><span class="Apple-tab-span">     </span>number of audio input bus channels (default = 8)</p>
  83 <p class="p6">-o <i>num-output-bus-channels</i></p>
  84 <p class="p6"><span class="Apple-tab-span">     </span>number of audio output bus channels (default = 8)</p>
  85 <p class="p6">-c <i>num-control-bus-channels</i></p>
  86 <p class="p6"><span class="Apple-tab-span">     </span>number of control bus channels (default = 4096)</p>
  87 <p class="p6"><span class="Apple-tab-span">     </span>The space allocated for control buses is: (numchannels * 8)</p>
  88 <p class="p6">-b <i>num-buffers</i></p>
  89 <p class="p6"><span class="Apple-tab-span">     </span>number of sample buffers (default = 1024)</p>
  90 <p class="p6">-n <i>max-nodes</i></p>
  91 <p class="p6"><span class="Apple-tab-span">     </span>maximum number of nodes (default = 1024)</p>
  92 <p class="p6">-d <i>max-synth-defs</i></p>
  93 <p class="p6"><span class="Apple-tab-span">     </span>maximum number of synth definitions (default = 1024)</p>
  94 <p class="p6">-D <i>1 or 0</i></p>
  95 <p class="p6"><span class="Apple-tab-span">     </span>if zero, then synth definitions will not be loaded on start up. (default = 1)</p>
  96 <p class="p6">-z <i>block-size</i></p>
  97 <p class="p6"><span class="Apple-tab-span">     </span>The number of samples in one control period. (default = 64)</p>
  98 <p class="p6">-Z <i>preferred-hardware-buffer-size</i></p>
  99 <p class="p6"><span class="Apple-tab-span">     </span>If non-zero, it will attempt to set the hardware buffer frame size. (default = 0)</p>
 100 <p class="p6">-S <i>preferred-sample-rate</i></p>
 101 <p class="p6"><span class="Apple-tab-span">     </span>If non-zero, it will attempt to set the hardware sample rate. (default = 0)</p>
 102 <p class="p6">-m <i>real-time-memory-size</i></p>
 103 <p class="p6"><span class="Apple-tab-span">     </span>The number of kilobytes of real time memory.<span class="Apple-converted-space"> </span></p>
 104 <p class="p6"><span class="Apple-tab-span">     </span>This memory is used to allocate synths and any memory that<span class="Apple-converted-space"> </span></p>
 105 <p class="p6"><span class="Apple-tab-span">     </span>unit generators themselves allocate. (default = 8192)</p>
 106 <p class="p6">-r <i>random-number-generators</i></p>
 107 <p class="p6"><span class="Apple-tab-span">     </span>The number of seedable random number generators. (default = 64)</p>
 108 <p class="p6">-w <i>max-interconnect-buffers</i></p>
 109 <p class="p6"><span class="Apple-tab-span">     </span>The maximum number of buffers that are allocated for buffers to interconnect<span class="Apple-converted-space"> </span></p>
 110 <p class="p6"><span class="Apple-tab-span">     </span>unit generators. Sets the limit of complexity of synth defs that can be loaded at<span class="Apple-converted-space"> </span></p>
 111 <p class="p6"><span class="Apple-tab-span">     </span>runtime. This value will be increased if a more complex synth-def is loaded at<span class="Apple-converted-space"> </span></p>
 112 <p class="p6"><span class="Apple-tab-span">     </span>start up time, but it cannot be increased once synthesis has begun. (default = 64)</p>
 113 <p class="p5"><span class="Apple-tab-span">     </span></p>
 114 <p class="p6">-l <i>max-logins</i></p>
 115 <p class="p6"><span class="Apple-tab-span">     </span>maximum number of named return addresses stored (default = 64)</p>
 116 <p class="p6"><span class="Apple-tab-span">     </span>also maximum number of tcp connections accepted</p>
 117 <p class="p6">-p <i>session-password</i></p>
 118 <p class="p6"><span class="Apple-tab-span">     </span>When using TCP, the session password must be the first command sent.</p>
 119 <p class="p6"><span class="Apple-tab-span">     </span>The default is no password.</p>
 120 <p class="p6"><span class="Apple-tab-span">     </span>UDP ports never require passwords, so if password protection is desired,<span class="Apple-converted-space"> </span></p>
 121 <p class="p6"><span class="Apple-tab-span">     </span>use TCP.</p>
 122 <p class="p5"><br></p>
 123 <p class="p6">-H <i>device-name</i></p>
 124 <p class="p6"><span class="Apple-tab-span">     </span>name of the hardware I/O device. If not provided, the default device is used.</p>
 125 <p class="p5"><span class="Apple-tab-span">     </span></p>
 126 <p class="p6">-I <i>input-streams-enable-string</i></p>
 127 <p class="p6"><span class="Apple-tab-span">     </span>Allows turning off input streams that you are not interested in on the device.</p>
 128 <p class="p6"><span class="Apple-tab-span">     </span>If the string is 01100, for example, then only the second and third input streams</p>
 129 <p class="p6"><span class="Apple-tab-span">     </span>on the device will be enabled. Turning off streams can reduce CPU load.</p>
 130 <p class="p5"><br></p>
 131 <p class="p6">-O <i>output-streams-enable-string</i></p>
 132 <p class="p6"><span class="Apple-tab-span">     </span>Allows turning off output streams that you are not interested in on the device.</p>
 133 <p class="p6"><span class="Apple-tab-span">     </span>If the string is 11000, for example, then only the first two output streams</p>
 134 <p class="p6"><span class="Apple-tab-span">     </span>on the device will be enabled. Turning off streams can reduce CPU load.</p>
 135 <p class="p5"><span class="Apple-tab-span">     </span></p>
 136 <p class="p6">-N <i>cmd-filename input-filename output-filename sample-rate header-format sample-format</i></p>
 137 <p class="p5"><br></p>
 138 <p class="p6"><span class="Apple-tab-span">     </span>Run in non-real-time mode.<span class="Apple-converted-space"> </span></p>
 139 <p class="p6"><span class="Apple-tab-span">     </span>The <i>cmd-filename</i> should be a file that contains OSC bundles sorted in<span class="Apple-converted-space"> </span></p>
 140 <p class="p6"><span class="Apple-tab-span">     </span>ascending time order. If <i>cmd-filename</i> is the underscore character _, then OSC<span class="Apple-converted-space"> </span></p>
 141 <p class="p6"><span class="Apple-tab-span">     </span>will be streamed from standard input.</p>
 142 <p class="p6"><span class="Apple-tab-span">     </span>The audio input will taken from <i>input-filename</i>.<span class="Apple-converted-space"> </span></p>
 143 <p class="p6"><span class="Apple-tab-span">     </span>If <i>input-filename</i> is the underscore character _, then no input file will be read.<span class="Apple-converted-space"> </span></p>
 144 <p class="p6"><span class="Apple-tab-span">     </span>Output will be written to <i>output-filename</i>.</p>
 145 <p class="p6"><span class="Apple-tab-span">     </span>The output file's sample rate is specified by <i>sample-rate</i>.</p>
 146 <p class="p6"><span class="Apple-tab-span">     </span>The output file <i>header-format</i> should be one of: AIFF, WAVE, NeXT.<span class="Apple-converted-space"> </span></p>
 147 <p class="p6"><span class="Apple-tab-span">     </span>The output file <i>sample-format</i> should be one of: int16, int24, int32, float, double.<span class="Apple-converted-space"> </span></p>
 148 <p class="p6"><span class="Apple-tab-span">     </span>The number of channels in the output file is specified with the -o argument.</p>
 149 <p class="p5"><br></p>
 150 <p class="p5"><br></p>
 151 <p class="p6">example:</p>
 152 <p class="p5"><br></p>
 153 <p class="p6">scscynth -u 57117 &gt;synth_log &amp;</p>
 154 <p class="p5"><span class="Apple-tab-span">     </span></p>
 155 <p class="p6"><span class="Apple-tab-span">     </span>Accept commands via UDP on port 57117.<span class="Apple-converted-space"> </span></p>
 156 <p class="p6"><span class="Apple-tab-span">     </span>Send output to file "synth_log"</p>
 157 <p class="p6"><span class="Apple-tab-span">     </span>Run asynchronously: &amp;.</p>
 158 <p class="p5"><br></p>
 159 <p class="p6">scsynth -N score.osc _ out.aiff 48000 AIFF int24<span class="Apple-converted-space"> </span></p>
 160 <p class="p5"><span class="Apple-tab-span">     </span></p>
 161 <p class="p6"><span class="Apple-tab-span">     </span>Run in non real time mode with command file score.osc, no input file, and output file named out.aiff. Sample rate is 48000. Output file header format is aiff, sample format is 24 bit integer.</p>
 162 <p class="p1"><br></p>
 163 <p class="p2">Binary Format of Messages</p>
 164 <p class="p1"><br></p>
 165 <p class="p6">Messages are similar in format to Open Sound Control messages, except that OSC #bundles may not be nested, and pattern matching of the command name is not performed. When streamed via TCP, Messages are each preceeded by a 32 bit integer giving the length in bytes of the message. UDP datagrams contain this length information already.</p>
 166 <p class="p5"><br></p>
 167 <p class="p6"><b>Types:</b></p>
 168 <p class="p6">All values are in network byte order.</p>
 169 <p class="p6"><span class="Apple-tab-span">     </span><b>long</b> - a 64 bit integer. Used for time stamps only.</p>
 170 <p class="p6"><span class="Apple-tab-span">     </span><b>int</b> - a 32 bit integer.</p>
 171 <p class="p6"><span class="Apple-tab-span">     </span><b>float</b> - a 32 bit single precision floating point number.</p>
 172 <p class="p6"><span class="Apple-tab-span">     </span><b>double</b> - a 64 bit double precision floating point number.</p>
 173 <p class="p6"><span class="Apple-tab-span">     </span><b>string</b> - a string of 8 bit ASCII characters, zero padded to a multiple of 4 bytes.</p>
 174 <p class="p6"><span class="Apple-tab-span">     </span><b>bytes</b> - a buffer of data preceeded by a 32 bit length field and padded to a multiple of 4 bytes.<span class="Apple-converted-space"> </span></p>
 175 <p class="p5"><br></p>
 176 <p class="p6"><b>Tags:</b></p>
 177 <p class="p6">Command arguments have single character tags which occur in a tag string to identify their types.</p>
 178 <p class="p6"><span class="Apple-tab-span">     </span>'i' - an int.</p>
 179 <p class="p6"><span class="Apple-tab-span">     </span>'f' - a float</p>
 180 <p class="p6"><span class="Apple-tab-span">     </span>'s' - a string</p>
 181 <p class="p6"><span class="Apple-tab-span">     </span>'b' - bytes</p>
 182 <p class="p5"><br></p>
 183 <p class="p6"><b>a Command consists of:</b></p>
 184 <p class="p6"><span class="Apple-tab-span">     </span>string - the command name. See the Command Reference below.</p>
 185 <p class="p6"><span class="Apple-tab-span">     </span>string - a string with tags defined by the types of the arguments to follow.<span class="Apple-converted-space"> </span></p>
 186 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>The tag string begins with a comma ',' character.</p>
 187 <p class="p6"><span class="Apple-tab-span">     </span>...any combination of arguments of types: int, float, string or bytes.</p>
 188 <p class="p5"><br></p>
 189 <p class="p6"><b>a Bundle consists of:</b></p>
 190 <p class="p6"><span class="Apple-tab-span">     </span>time stamp - long. Time stamps are in the same format as defined by Open Sound Control :<span class="Apple-converted-space">  </span>The top 32 bits are seconds since 1900 and the lower 32 bits represent the 32 bit fraction of one second.</p>
 191 <p class="p6"><span class="Apple-tab-span">     </span>...a series of Commands each preceded by a 32-bit integer byte length.</p>
 192 <p class="p5"><span class="Apple-tab-span">     </span></p>
 193 <p class="p6"><b>a Message consists of:</b></p>
 194 <p class="p6"><b><span class="Apple-tab-span">  </span>using UDP :<span class="Apple-converted-space"> </span></b></p>
 195 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>one Bundle or one Command.</p>
 196 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
 197 <p class="p6"><b><span class="Apple-tab-span">  </span>using TCP :<span class="Apple-converted-space"> </span></b></p>
 198 <p class="p6"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>int - the length in bytes of the following message.</p>
 199 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>one Bundle or one Command.</p>
 200 <p class="p5"><span class="Apple-tab-span">     </span></p>
 201 <p class="p5"><br></p>
 202 <p class="p5"><br></p>
 203 <p class="p5"><br></p>
 204 <p class="p2">Glossary</p>
 205 <p class="p5"><br></p>
 206 <p class="p6"><b>buffer</b> - a header and array of floating point sample data. Buffers are used for sound files, delay lines, arrays of global controls, and arrays of inter-synth patch points.</p>
 207 <p class="p5"><br></p>
 208 <p class="p6"><b>group</b> - a linked list of nodes. groups provide ways to control execution of many nodes at once. a group is a kind of node.</p>
 209 <p class="p5"><br></p>
 210 <p class="p6"><b>MIDI</b> - a protocol for sending music control data between synthesizers.</p>
 211 <p class="p5"><br></p>
 212 <p class="p6"><b>node</b> - an object in a tree of objects executed in a depth first traversal order by the synth engine. There are two types of nodes, synths and groups.</p>
 213 <p class="p5"><br></p>
 214 <p class="p6"><b>Open Sound Control</b> - a protocol defined by CNMAT at UCBerkeley for controlling synthesizers. See http://cnmat.cnmat.berkeley.edu/OSC/ .</p>
 215 <p class="p5"><br></p>
 216 <p class="p6"><b>OSC</b> - see Open Sound Control.</p>
 217 <p class="p5"><br></p>
 218 <p class="p6"><b>synth</b> - a sound processing module. Similar to "voice " in other systems. Synths are referred to by a number.</p>
 219 <p class="p5"><br></p>
 220 <p class="p6"><b>synth definition</b> - a definition for creating new synths. similar to "instrument" in other systems.</p>
 221 <p class="p5"><br></p>
 222 <p class="p6"><b>TCP</b> - a protocol for streaming data over a network.</p>
 223 <p class="p5"><br></p>
 224 <p class="p6"><b>UDP</b> - a protocol for sending datagrams over a network.</p>
 225 <p class="p5"><br></p>
 226 <p class="p4">copyright © 2002 James McCartney</p>
 227 <p class="p3"><br></p>
 228 <p class="p5"><br></p>
 229 </body>
 230 </html>