HelpSource/Guides/NodeMessaging.schelp

   1 title:: Node Messaging
   2 summary:: Messaging Nodes with OSC
   3 categories:: Server>Nodes, External Control>OSC
   4
   5 section:: Introduction
   6 The most direct and fast way to send commands to the server is to send messages to the link::Classes/Server:: object, if you are within sc-lang.  If you are in a shell you can use sendOSC (available from CNMAT).
   7
   8 this messaging scheme is explained in detail in:
   9 list::
  10 ## link::Reference/Server-Architecture::
  11 ## link::Reference/Server-Command-Reference::
  12 ## link::Tutorials/Tutorial::
  13 ::
  14
  15 section:: Messaging nodes
  16 When creating nodes on the server (synths and groups) the only things we need to know are the nodeID and the server (its address to be precise).
  17
  18 In order to communicate with a synth, one sends messages with its nodeID. If you do not intend to communicate with the node after its creation (and the node will cause itself to end without external messaging), the node id can be set to -1, which is the server's equivalent to nil.
  19
  20 As soon as you want to pass around the reference to a certain node, assuming that you might not have only one server, it can be useful to create a link::Classes/Synth:: or link::Classes/Group:: object. These objects also respond to messages, and when needed can be used to obtain the state of the server side node.
  21
  22 see link::Classes/Node::, link::Classes/Synth::, and link::Classes/Group:: help for more detailed helpfiles on node objects.
  23
  24 the equivalent of
  25 code::
  26 n = s.nextNodeID;
  27 s.sendMsg("/s_new", "default", n);
  28 s.sendMsg("/n_free", n);
  29 ::
  30 is
  31 code::
  32 n = Synth("default");
  33 n.free;
  34 ::
  35
  36 when passing arguments:
  37 code::
  38 n = s.nextNodeID;
  39 s.sendMsg("/s_new", "default", n, 0, 0, "freq", 850);
  40 s.sendMsg("/n_set", n, "freq", 500);
  41 s.sendMsg("/n_free", n);
  42 ::
  43
  44 it is
  45 code::
  46 n = Synth("default", [\freq, 850]);
  47 n.set(\freq, 500)
  48 n.free;
  49 ::
  50
  51 note that Symbols may be used instead of Strings:
  52 code::
  53 n = s.nextNodeID;
  54 s.sendMsg(\s_new, \default, n, 0, 0, \freq, 850);
  55 s.sendMsg(\n_set, n, \freq, 500);
  56 s.sendMsg(\n_free, n);
  57 ::
  58 and:
  59 code::
  60 n = Synth(\default, [\freq, 850]);
  61 n.set(\freq, 500)
  62 n.free;
  63 ::
  64
  65 The answer to the question of whether one should work with node objects or directly with messages depends to some extent on context, and to some extent is a matter of personal taste.
  66
  67 The encapsulation of node objects results in a certain generalization, meaning that other compound objects can respond to the same messages and thus exploit polymorphism. They also provide a certain level of convienence, keeping track of indexes and IDs, etc.
  68
  69 In certain cases, such as for granular synthesis it is recommended to use messages directly, because there is no benefit to be gained from the node objects (i.e. no need to message them) and they add cpu load to the client side.
  70 code::
  71 (
  72 SynthDef("grain", {
  73         Out.ar(0, Line.kr(0.1, 0, 0.01, doneAction:2) * FSinOsc.ar(12000))
  74 }).send(s);
  75 )
  76
  77 (
  78 Routine({
  79         20.do({
  80                 s.sendMsg("/s_new", "grain", -1);
  81                 0.01.wait;
  82         })
  83 }).play;
  84 )
  85 ::
  86
  87 In cases where you need to keep track of the synth's state, it is advisable to use node objects and register them with a link::Classes/NodeWatcher::. (see helpfile)
  88
  89 Apart from such cases it is a matter of taste whether you want to use the combination of message and a numerical global representation or an object representation. The two can be mixed, and certain advantages of the object style can be accessed when using messaging style. For instance code::Server.nextNodeID:: allows one to use dynamically assigned IDs in messaging style. As a gross generalization, it is probably fair to say that object style is more convienent, but messaging style is more efficient, due to reduce client-side CPU load.
  90
  91 note::
  92 IMPORTANT: If you wish to have the functionality of the default_group (e.g. problem free use of Server's record and scope functionality) you should treat ID 1 (the default_group) as the root of your node tree rather than ID 0 (the RootNode). See default_group for more details.
  93 ::
  94
  95 Note that link::Classes/Function#play#Function-play:: and link::Classes/SynthDef#play#SynthDef-play:: return a synth object that can be used to send messages to.
  96 code::
  97 x = { arg freq=1000; Ringz.ar(Crackle.ar(1.95, 0.1), freq, 0.05) }.play(s);
  98 x.set(\freq, 1500);
  99 x.free;
 100 ::
 101
 102 section:: Argument lists in node messages
 103
 104 Several node messages accept lists of values to map onto the controls of Synth nodes, as in some of the examples already given:
 105 code::
 106 s.sendMsg(\s_new, \default, n, 0, 0, \freq, 850);
 107 n = Synth(\default, [\freq, 850]);
 108 ::
 109 Argument lists generally appear as alternating pairs, with the control identifier preceding the value. Usually the control identifier is a name, as above, but it could also be an integer index. (Using integers is slightly faster for the server, but it makes the code harder to read and can introduce bugs if the SynthDef structure changes.)
 110 One way to find out control indices is to .add the SynthDef into a link::Classes/SynthDescLib::, then get the list of all controls out of the link::Classes/SynthDesc::.
 111 code::
 112 (
 113 SynthDef(\controlList, { |freq = 440, amp = 0.1, detune = #[0.999, 1.001], gate = 1, out = 0|
 114         var     sig = Mix(Saw.ar(freq * (detune ++ [1]), amp)),
 115                 env = EnvGen.kr(Env.adsr, gate, doneAction: 2);
 116         Out.ar(0, (sig * env) ! 2);
 117 }).add;
 118
 119 SynthDescLib.global[\controlList]
 120 )
 121 ::
 122 Prints:
 123 code::
 124 SynthDesc 'controlList'
 125 Controls:
 126 ControlName  P 0 freq control 440
 127 ControlName  P 1 amp control 0.10000000149012
 128 ControlName  P 2 detune control 0.9990000128746
 129 ControlName  P 3 ? control 1.00100004673
 130 ControlName  P 4 gate control 1
 131 ControlName  P 5 out control 0
 132    O audio 0 2
 133 ::
 134 The list shows that the 'freq' control has index 0, 'amp' is 1 and so on. Detune is defined as an "array argument," occupying indices 2-3.
 135
 136 SynthDefs with a large number of controls may need a little extra code to print the entire list.
 137 code::
 138 SynthDescLib.global[\controlList].controls.do(_.postln); ""
 139 ::
 140
 141 Prior to SuperCollider 3.3, the only way to set array arguments by name was using n_setn (or Node's setn method). Beginning in version 3.3, array arguments can be included in s_new or n_set messages transparently.
 142
 143 subsection::Messaging style
 144 note the characters $[ and $] delimiting the array in the list:
 145 code::
 146 n = s.nextNodeID;
 147 s.sendMsg(\s_new, \controlList, n, 0, 0, \detune, $[, 0.95, 1.005, $], \freq, 220);
 148 s.sendMsg(\n_set, n, \gate, 0);
 149 ::
 150
 151 subsection::Object style
 152 the Node object automatically inserts $[ and $] for you:
 153 code::
 154 n = Synth(\controlList, [\detune, [0.95, 1.005], \freq, 220]);
 155 n.set(\detune, [0.99, 1.01]);
 156 n.release;
 157 ::
 158
 159 subsection::Event style
 160 Supplying an array for an argument in an event already has another meaning: multichannel expansion, in which a separate node is created for each array item. If all items of the array should be sent to the same node, then the array argument should be enclosed in another array level:
 161 code::
 162 (instrument: \controlList, freq: 220, detune: [[0.95, 1.005]], sustain: 2).play;
 163 ::
 164