Node abstract superclass of Synth and Group

superclass: Object

See also: Server-Architecture, Synth, Group, RootNode

This class is the abstract super class of Synth and Group, which represent synth and group nodes on the server. Node objects are not made explicitly, but Synth and Group are subclasses, and inherit the methods documented below.

Freed Nodes and Node Status

Nodes which you explicitly free using the methods free or release will have their group instance variable set to nil. However Nodes which are automatically freed after a certain time (for instance by an EnvGen with a doneAction of 2) will not. This keeps the implementation of the classes simple and lightweight. To have the current state of a Node tracked you can register it with an instance of NodeWatcher. This will enable two variables, isPlaying and isRunning, which you can use for checking purposes.

Bundling

Many of the methods below have two versions: a regular one which sends its corresponding message to the server immediately, and one which returns the message in an Array so that it can be added to a bundle. It is also possible to capture the messages generated by the regular methods using Server's automated bundling capabilities. See Server and bundledCommands for more details.

Accessing Instance Variables

The following getter methods also have corresponding setters, but they should be used with extreme care and only if you are sure you know what you're doing.

nodeID - Returns the Node's node ID number. Normally you should not need to access this since instances of Node can be passed directly as UGen inputs or Synth args.

group - Returns an instance of Group or RootNode corresponding to this Node's group on the server.

server - Returns an instance of Server corresponding to this Node's server app.

isPlaying - Returns a boolean indicating if this node is currently on the server, providing this Node has been registered with a NodeWatcher. N.B. If this Node has not been registered this will likely be false in any case.

isRunning - Returns a boolean indicating if this node is currently on the server, providing this Node has been registered with a NodeWatcher. N.B. If this Node has not been registered this will likely be false in any case.

Node Commands

See the Node Commands section in Server-Command-Reference for the OSC equivalents of the methods outlined below.

free(sendFlag)

freeMsg

Stop this Node and free it from it's parent group on the server. Once a Node has been freed, you cannot restart it. sendFlag is a boolean indicating whether the free message should be sent. If false an n_free message will not be sent to this Node's server, but its isPlaying and isRunning variables will be set to false. The default for sendFlag is true. If this Node is a Group this will free all Nodes within the Group.

s.boot;

x = Synth("default");

x.free;

run(boolean)

runMsg(boolean)

Set the running state of this Node according to a boolean. False will pause the node without freeing it. The default is true. If this Node is a Group this will set the running state of all Nodes within the Group.

s.boot;

(

x = SynthDef("help-node-set", {arg freq = 440, out = 0;

Out.ar(out, SinOsc.ar(freq, 0, 0.1));}).play(s);

)

x.run(false);

x.run; // default is true

x.free;

set(controlName, value ... moreArgs)

setMsg(controlName, value ... moreArgs)

Set controls in this Node to values. Controls are defined in a SynthDef as args or instances of Control. They are specified here using symbols, strings, or indices, and are listed in pairs with values. If this Node is a Group this will set all Nodes within the Group.

s.boot;

(

x = SynthDef("help-node-set", {arg freq = 440, out = 0;

Out.ar(out, SinOsc.ar(freq, 0, 0.1));}).play(s);

)

x.set(\freq, 880, \out, 1); // two pairs

x.set(0, 660, 1, 0); // freq is the first argument, so it's index is 0. out is index 1.

x.free;

setn(controlName, values ... moreArgs)

setnMsg(controlName, values ... moreArgs)

Set sequential ranges of controls in this Node to values. Controls are defined in a SynthDef as args or instances of Control. They are specified here using symbols, strings, or indices, and are listed in pairs with arrays of values. If this Node is a Group this will setn all Nodes within the Group.

s.boot;

(

x = SynthDef("help-node-setn", {

arg freq1 = 440, freq2 = 440, freq3 = 440, amp1 = 0.05, amp2 = 0.05, amp3 = 0.05;

Out.ar(0, Mix(SinOsc.ar([freq1, freq2, freq3], 0, [amp1, amp2, amp3])));}).play(s);

)

// set 3 controls starting from \freq1, and 3 controls starting from \amp1

x.setn(\freq1, [440, 880, 441], \amp1, [0.3, 0.1, 0.3]);

x.free;

fill(controlName, numControls, value ... moreArgs)

fillMsg(controlName, numControls, value ... moreArgs)

Set sequential ranges of controls in this Node to a single value. Controls are defined in a SynthDef as args or instances of Control. They are specified here using symbols, strings, or indices, and are listed in groups of three along with an integer indicating the number of controls to set, and the value to set them to. If this Node is a Group this will fill all Nodes within the Group.

busMap(firstControl, aBus ... moreArgs)

busMapMsg(firstControl, aBus ... moreArgs)

Map sequential ranges of controls in this Node to read from control rate Buses. Controls are defined in a SynthDef as args or instances of Control. They are specified here using symbols, strings, or indices, and are listed in pairs with Bus objects. The number of sequential controls mapped corresponds to the Bus' number of channels. If this Node is a Group this will busMap all Nodes within the Group.

s.boot;

(

b = Bus.control(s, 2); b.set(440, 660); // a two channel bus

c = Bus.control(s, 1); c.set(441); // a one channel bus

x = SynthDef("help-Node-busMap", { arg freq1 = 440, freq2 = 440, freq3 = 440;

Out.ar(0, Mix(SinOsc.ar([freq1, freq2, freq3], 0, 0.1)));

}).play(s);)

// b has two channels, so both freq2 and freq3 are mapped to its first and second channels

// respectively; c has one channel, so it maps only freq1

x.busMap(\freq1, c, \freq2, b);

b.set(440, 880);

c.set(1200);

x.free; b.free; c.free;

map(controlName, index ... moreArgs)

mapMsg(controlName, index ... moreArgs)

Map controls in this Node to read from control rate Buses. Controls are defined in a SynthDef as args or instances of Control. They are specified here using symbols, strings, or indices, and are listed in pairs with bus indices. If this Node is a Group this will map all Nodes within the Group.

s.boot;

(

b = Bus.control(s, 1); b.set(880);

c = Bus.control(s, 1); c.set(884);

x = SynthDef("help-Node-busMap", { arg freq1 = 440, freq2 = 440;

Out.ar(0, SinOsc.ar([freq1, freq2], 0, 0.1));

}).play(s);)

x.map(\freq1, b, \freq2, c);

x.free; b.free; c.free;

mapn(controlName, index, numControls ... moreArgs)

mapnMsg(controlName, index, numControls ... moreArgs)

Map sequential ranges of controls in this Node to read from control rate Buses. This is similar to busMap above, but instead of passing in Bus objects you specify the index, and the number of sequential Controls to map. If this Node is a Group this will mapn all Nodes within the Group.

release(releaseTime)

releaseMsg(releaseTime)

This is a convenience method which assumes that the synth contains an envelope generator (an EnvGen, Linen, or similar UGen) running a sustaining envelope (see Env) and that it's gate argument is set to a control called \gate. This method will cause the envelope to release. If releaseTime is not nil, it will override the envelope's decay or release time. If this Node is a Group this will release all Nodes within the Group.

x = { arg gate=1; BrownNoise.ar(0.5) * EnvGen.kr(Env.cutoff(1), gate, doneAction:2) }.play;

x.release(5); // overide the Env's specified 1 second release time

query

Sends an n_query message to the server, which will reply with a message containing information about this node and its place in the server's node tree. This information will be printed to the post window. (See also the queryAllNodes method of Server.) "parent" indicates the Node's enclosing group. If "prev" or "next" are equal to -1 that indicates that there are no other nodes in the enclosing group before or after this one, respectively.

g = Group.new;

x = Synth.head(g, "default");

x.query;

g.query;

s.queryAllNodes; // Note the RootNode (ID 0) and the default Group (ID 1)

x.free; g.free;

trace

Causes a synth to print out the values of the inputs and outputs of its unit generators for one control period to the post window. Causes a group to print the node IDs and names of each node in the group for one control period.

g = Group.new;

x = Synth.head(g, "default");

x.trace;

g.trace;

x.free; g.free;

Changing the order of execution

The following methods can be used to change the Node's place in the order of execution. See the Order-of-execution help file for more information on this important topic. See Server-Command-Reference for the OSC equivalents of these methods.

moveAfter(aNode)

moveAfterMsg(aNode)

Move this Node to be directly after aNode. N.B. n_after, the OSC message which this method encapsulates, allows already freed nodes as targets. This is so that one may attempt a series of moves, with the last successful one taking effect. For this reason this method will fail silently if either the target or this node have already been freed. If you will need to check, you may register the relevant nodes with a NodeWatcher.

moveBefore(aNode)

moveBeforeMsg(aNode)

Move this Node to be directly before aNode. N.B. n_before, the OSC message which this method encapsulates, allows already freed nodes as targets. This is so that one may attempt a series of moves, with the last successful one taking effect. For this reason this method will fail silently if either the target or this node have already been freed. If you will need to check, you may register the relevant nodes with a NodeWatcher.

moveToHead(aGroup)

moveToHeadMsg(aGroup)

If aGroup is a Group then this method will move this Node to the head of that Group. If it is nil this will move this Node to the head of the default_group of this Node's Server.

moveToTail(aGroup)

moveToTailMsg(aGroup)

If aGroup is a Group then this method will move this Node to the tail of that Group. If it is nil this will move this Node to the tail of the default_group of this Node's Server.

Other Methods

asTarget - Returns this Node. See the asTarget help file for more details.

printOn(stream) - Prints this Node's Class (Synth or Group) and nodeID on stream.

hash - Returns server.hash bitXor: nodeID.hash

== aNode - Returns true if this Node and aNode have the same nodeID and the same Server object, otherwise returns false. Under certain circumstances this Node and aNode might not be the same object, even though this returns true.

g = Group.basicNew(s, 1); // the default group of s

h = Group.basicNew(s, 1); // and again

g == h; // true

g === h; // false