HelpSource/Guides/UGens-and-Synths.schelp

   1 title:: Unit Generators and Synths
   2 summary:: Introduction to some fundamental concepts
   3 categories:: Server>Nodes
   4
   5 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 link::Classes/UGen::.
   6
   7 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 link::Guides/Multichannel-Expansion:: for more details.)
   8
   9 section::Instantiation. Audio Rate, Control Rate
  10
  11 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
  12 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.
  13
  14 The input parameters for a unit generator are given in the documentation for that class.
  15
  16 code::
  17 FSinOsc.ar(800, 0.0, 0.2); // create a sine oscillator at 800 Hz, phase 0.0, amplitude 0.2
  18 ::
  19
  20 A unit generator's signal inputs can be other unit generators, scalars, or arrays of unit generators and scalars.
  21
  22 section::SynthDefs and Synths
  23
  24 In order to play a unit generator one needs to compile it in a link::Classes/SynthDef:: and play it on the server in a link::Classes/Synth::. 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.
  25
  26 code::
  27 s.boot; // boot the local server
  28
  29 // compile and send this def
  30 SynthDef.new("FSinOsc-test", { Out.ar(0, FSinOsc.ar(800, 0, 0.2)) }).send(s); // out channel 0
  31
  32 // now create a Synth object which represents a synth node on the server
  33 x = Synth.new("FSinOsc-test");
  34
  35 // free the synth
  36 x.free;
  37 ::
  38
  39 The synth node created above could also be created using 'messaging style', thus saving the overhead of a clientside Synth object:
  40
  41 code::
  42 n = s.nextNodeID;
  43 s.sendMsg("/s_new", "FSinOsc-test", n);
  44 s.sendMsg("/n_free", n);
  45 ::
  46
  47 Because any expression returns its value, we can nest the first two lines above for convenience. (See link::Reference/Expression-Sequence:: for more detail.)
  48
  49 code::
  50 s.sendMsg("/s_new", "FSinOsc-test", n = s.nextNodeID;);
  51 s.sendMsg("/n_free", n);
  52 ::
  53
  54 It is VERY important and useful to understand the messaging structure which underlies the clientside Synth, Group, Buffer, and Bus objects. See link::Guides/NodeMessaging::, link::Tutorials/Tutorial::, and link::Guides/ClientVsServer:: for more detail.
  55
  56 As a convenience the 'play' method of class link::Classes/Function:: will compile a SynthDef and create and play a synth using the function for you. With this method an link::Classes/Out:: ugen will be created for you if you do not do so explicitly.
  57
  58 code::
  59 { FSinOsc.ar(800, 0, 0.2) }.play; // create and play a sine oscillator at 800 Hz
  60 ::
  61
  62 section::Building Patches
  63
  64 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 link::Classes/BinaryOpUGen:: which performs the '+' operation. Its inputs are the link::Classes/FSinOsc:: and link::Classes/BrownNoise:: unit generators.
  65
  66 code::
  67 FSinOsc.ar(800, 0.0, 0.2) + BrownNoise.ar(0.2); // press enter and look at the post window
  68
  69 {FSinOsc.ar(800, 0.0, 0.2) + BrownNoise.ar(0.2)}.play; // play it
  70 ::