Help/Tutorials/UGens-and-Synths.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.42">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #a71e12}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #0019b7; min-height: 12.0px}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Monaco; min-height: 16.0px}
  19 p.p10 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
  20 span.s1 {color: #0019b7}
  21 span.s2 {color: #000000}
  22 span.s3 {color: #606060}
  23 span.s4 {color: #a71e12}
  24 span.s5 {font: 9.0px Helvetica; color: #000000}
  25 </style>
  26 </head>
  27 <body>
  28 <p class="p1"><b>Unit Generators and Synths</b></p>
  29 <p class="p2"><br></p>
  30 <p class="p3">A unit generator is an object that processes or generates sound. There are many classes of unit generators, all of which derive from the class <b>UGen</b>.</p>
  31 <p class="p2"><br></p>
  32 <p class="p3">Unit generators in SuperCollider can have many inputs, but always have a single output. Unit generator classes which would naturally have several outputs such as a panner, return an array of unit generators when instantiated. The convention of having only a single output per unit generator allows the implementation of multiple channels by using arrays of unit generators. (See <b>MultiChannel </b>for more details.)</p>
  33 <p class="p2"><br></p>
  34 <p class="p4"><b>Instantiation. Audio Rate, Control Rate</b></p>
  35 <p class="p2"><br></p>
  36 <p class="p3">A unit generator is created by sending the 'ar' or 'kr' message to the unit generator's class object. The 'ar' message creates a unit generator that runs at audio rate. The 'kr' message creates a unit generator that runs<span class="Apple-converted-space"> </span></p>
  37 <p class="p3">at control rate. Control rate unit generators are used for low frequency or slowly changing control signals. Control rate unit generators produce only a single sample per control cycle and therefore use less processing power than audio rate unit generators.</p>
  38 <p class="p2"><br></p>
  39 <p class="p3">The input parameters for a unit generator are given in the documentation for that class.<span class="Apple-converted-space"> </span></p>
  40 <p class="p2"><br></p>
  41 <p class="p5"><span class="s1">FSinOsc</span><span class="s2">.ar(800, 0.0, 0.2); </span>// create a sine oscillator at 800 Hz, phase 0.0, amplitude 0.2</p>
  42 <p class="p2"><br></p>
  43 <p class="p3">A unit generator's signal inputs can be other unit generators, scalars, or arrays of unit generators and scalars.</p>
  44 <p class="p2"><br></p>
  45 <p class="p4"><b>SynthDefs and Synths</b></p>
  46 <p class="p2"><br></p>
  47 <p class="p3">In order to play a unit generator one needs to compile it in a <b>SynthDef</b> and play it on the server in a <b>Synth</b>. A synth node is a container for one or more unit generators that execute together. A SynthDef is like a kind of pattern for creating synth nodes on the server.</p>
  48 <p class="p6"><br></p>
  49 <p class="p5"><span class="s2">s.boot; </span>// boot the local server</p>
  50 <p class="p7"><br></p>
  51 <p class="p5">// compile and send this def</p>
  52 <p class="p8"><span class="s1">SynthDef</span>.new(<span class="s3">"FSinOsc-test"</span>, { <span class="s1">Out</span>.ar(0, <span class="s1">FSinOsc</span>.ar(800, 0, 0.2)) }).send(s); <span class="s4">// out channel 0</span></p>
  53 <p class="p9"><br></p>
  54 <p class="p5">// now create a Synth object which represents a synth node on the server</p>
  55 <p class="p10"><span class="s2">x = </span><span class="s1">Synth</span><span class="s2">.new(</span>"FSinOsc-test"<span class="s2">);</span></p>
  56 <p class="p7"><br></p>
  57 <p class="p5">// free the synth</p>
  58 <p class="p8">x.free;</p>
  59 <p class="p9"><br></p>
  60 <p class="p3">The synth node created above could also be created using 'messaging style', thus saving the overhead of a clientside Synth object:</p>
  61 <p class="p9"><br></p>
  62 <p class="p8">n = s.nextNodeID;</p>
  63 <p class="p10"><span class="s2">s.sendMsg(</span>"/s_new"<span class="s2">, </span>"FSinOsc-test"<span class="s2">, n);</span></p>
  64 <p class="p8">s.sendMsg(<span class="s3">"/n_free"</span>, n);</p>
  65 <p class="p2"><br></p>
  66 <p class="p3">Because any expression returns its value, we can nest the first two lines above for convenience. (See <b>Expression-Sequence</b> for more detail.)</p>
  67 <p class="p2"><br></p>
  68 <p class="p8">s.sendMsg(<span class="s3">"/s_new"</span>, <span class="s3">"FSinOsc-test"</span>, n = s.nextNodeID;);</p>
  69 <p class="p8">s.sendMsg(<span class="s3">"/n_free"</span>, n);</p>
  70 <p class="p2"><br></p>
  71 <p class="p3">It is VERY important and useful to understand the messaging structure which underlies the clientside Synth, Group, Buffer, and Bus objects. See <b>NodeMessaging</b>,<b> Tutorial</b>, and <b>ClientVsServer</b> for more detail.</p>
  72 <p class="p2"><br></p>
  73 <p class="p3">As a convenience the 'play' method of class <b>Function</b> will compile a SynthDef and create and play a synth using the function for you. With this method an <b>Out</b> ugen will be created for you if you do not do so explicitly.</p>
  74 <p class="p2"><br></p>
  75 <p class="p5"><span class="s5">{ </span><span class="s1">FSinOsc</span><span class="s2">.ar(800, 0, 0.2) }.play; </span>// create and play a sine oscillator at 800 Hz</p>
  76 <p class="p9"><br></p>
  77 <p class="p4"><b>Building Patches</b></p>
  78 <p class="p2"><br></p>
  79 <p class="p3">You can do math operations on unit generators and the result will be another unit generator. Doing math on unit generators is not doing any signal calculation itself - it is building the network of unit generators that will execute once they are played in a Synth. This is the essential thing to understand: Synthesis networks, or in other words signal flow graphs are created by executing expressions of unit generators. The following expression creates a flow graph whose root is an instance of <b>BinaryOpUGen</b> which performs the '+' operation. Its inputs are the <b>FSinOsc</b> and <b>BrownNoise</b> unit generators.</p>
  80 <p class="p2"><br></p>
  81 <p class="p5"><span class="s1">FSinOsc</span><span class="s2">.ar(800, 0.0, 0.2) + </span><span class="s1">BrownNoise</span><span class="s2">.ar(0.2); </span>// press enter and look at the post window</p>
  82 <p class="p9"><br></p>
  83 <p class="p8">{<span class="s1">FSinOsc</span>.ar(800, 0.0, 0.2) + <span class="s1">BrownNoise</span>.ar(0.2)}.play; <span class="s4">// play it</span></p>
  84 </body>
  85 </html>