AlgaNode | SuperCollider 3.13.0 Help

Description

An AlgaNode is the fundamental element of Alga. Conceptually, it is very similar to a single module of a modular synthesizer, which, however, can be dynamically created, replaced and patched on the fly.

There are 4 important features that make AlgaNodes different from other forms of patching already present in SuperCollider.

Connecting AlgaNodes together will trigger a process of interpolation between the current state of the receiver and the future one where the new connection will take place. This feature applies to any operation: from creation, to connection and replacement of nodes.
NOTE: Interpolation is a property that belongs to the receiver of the connection, not the sender. It is in fact possible to specify different interpolation times for each parameter of a receiver. Any sender that connects to those parameters will respect the relative interpolation times.
Whenever a new connection is made, Alga takes care of running any necessary conversions of rate and number of channels: Alga takes a patch anything into anything approach.
Whenever a new connection is made, Alga takes care of ordering the groups of the AlgaNodes on the server so that they respect the order of connections, preventing the introduction of blockSize delays in the signal chain. This feature is only limited by feedback connections. In such cases, there will obviously be an blockSize delay introduced between the last node in the chain and the first one.
AlgaNodes do not only specify connections via their parameter names, as it is usual in SuperCollider, but also by output names. In fact, thanks to the AlgaSynthDef class it is possible to define specific symbol to channel(s) mappings to address a specific output - or outputs - of a node. An AlgaNode, then, is not only described by its inputs, but, like in modular synthesizers, also by its outputs.

By going through the help files and the Examples folder, hopefully all these notions will be clearer.

Class Methods

.new

Create a new AlgaNode.

Arguments:

def	Mandatory argument. It accepts either a UGen function or a symbol to lookup a defined AlgaSynthDef.
args	Define default arguments for the parameters of the function or AlgaSynthDef. These can be Numbers, Arrays, AlgaNodes, AlgaTemps or AlgaArgs.
interpTime	Specify the interpolation time it takes whenever making a new connection to any parameter of this AlgaNode.
interpShape	Specify the interpolation shape that is to be used to perform new connections. This must be defined with an Env that always starts at 0 and ends at 1. If not specified, a single ramp `Env([0, 1], 1)` is used by default.
playTime	Specify the fading in / fading out time that it takes for this AlgaNode to play through speakers. These values are applied when calling the play or stop functions.
playSafety	Specify a different safety method to use to scale the output of a node when using the play method. Accepted values are: `'clip', 'tanh', 'softclip', 'limiter', 'none'`.
sched	Just like any other AlgaNode method, the current function can be scheduled at specific times in the future, according to the clock that the Alga instance booted on the server is using.
schedInSeconds	Specify if all sched actions should be scheduled in seconds, opposing to beats. Default is `false`.
tempoScaling	Specify if all timed actions should be scaled by the clock's tempo. Default is `false`.
outsMapping	It works just like AlgaSynthDef's outsMapping argument, but for the case of using an UGen function as the obj argument. Specify new mappings by an array that maps symbols to specific output channels. If not specified, the default `\out1, \out2, etc..` symbols can be used to address specific channels.
server	Specify a Server to instantiated the AlgaNode on. This Server must have had Alga booted on it. It defaults to `Server.default`.

Instance Methods

.play

Play the AlgaNode to SuperCollider's output. Note that this method also ensures that no dangerous audio signals are forwarded to your speaker's output, with an implementation inspired by the SafetyNet quark ( https://github.com/adcxyz/SafetyNet ).

Arguments:

chans	Specify an Array of output channels to play, which can contain outsMapping symbols. It's also possible to just specify a number, in which case it determines how many channels will be played.
time	Define a temporary connection time that the method takes to complete, applying the necessary interpolations. If not specified, playTime will be used.
scale	Specify a Number to scale the output by.
out	Specify a Bus index to play the node to.
sched	Just like any other AlgaNode method, the current function can be scheduled at specific times in the future, according to the clock that the Alga instance booted on the server is using.

Discussion:

.stop

Stop the output to speakers.

.clear

Clear the AlgaNode, dropping all connections in place (with appropriate interpolation) as well as the output to speakers.

.replace

Replace the current content of the AlgaNode. This method also takes care of restoring all running connections, applying the correct connection times and rate / channels conversions.

Arguments:

def	Mandatory argument. It accepts either a UGen function or a symbol to lookup a defined AlgaSynthDef.
args	Define default arguments for the parameters of the function or AlgaSynthDef. Note that these will be applied in regards to interpTime.
time	Define a temporary connection time that the method takes to complete, applying the necessary interpolations.
sched	Just like any other AlgaNode method, the current function can be scheduled at specific times in the future, according to the clock that the Alga instance booted on the server is using.
outsMapping	It works just like AlgaSynthDef's outsMapping argument, but for the case of using an UGen function as the obj argument. Specify new mappings by an array that maps symbols to specific output channels.
reset	Specify whether the parameters should keep their old connections or they should be reset to the default values. This argument either takes a boolean value (true / false) or an Array specifying the individual names of the parameters to reset, via Symbols (e.g. `[\freq, \amp]`. A true boolean value will reset all parameters, while the Array only some of them.
keepOutsMappingIn	Specify whether the current output channels mapping of the AlgaNodes connected to the inputs of this one should be maintained.
keepOutsMappingOut	Specify whether the current output channels mapping of the AlgaNodes connected to the outputs of this one should be maintained.
keepScalesIn	Specify whether the scales of all the AlgaNodes connected to the inputs of this one should be maintained.
keepScalesOut	Specify whether the scales of all the AlgaNodes connected to the outputs of this one should be maintained.

.from

Connect the specific input parameter of this AlgaNode to the output of an AlgaNode, Number, Array, AlgaTemp or AlgaArg.

Arguments:

sender	An AlgaNode, Number, Array, AlgaTemp or AlgaArg.
param	Which parameter to connect to.
chans	An optional Symbol or Array to specify which of the output channels mapping to take from the output of the sender. If not specified, all channels will be used.( a = AlgaNode( { SinOsc.ar([220, 440, 880, 1760])}, outsMapping: [\one, [0, 1], \two, [2, 3], \three, 2, \four, 3] ) ) b = AlgaNode({ \in.ar([0, 0]) }).play //a simple 2 channel bypass b.from(a, chans: \one) //connects \one == [0, 1] b.from(a, chans: \two) //connects \two == [2, 3] b.from(a, chans: [0, 3]) //connects [0, 3], a custom channels mapping
scale	An optional Number or Array. If it is a number, the value works as a multiplier of the output of the sender. If it is an array, it can be specified in two different ways: 4 elements, specify a linlin connection: `[-1, 1, 0, 10]`. 2 elements, specify a linlin connection but assume that the input range is -1 to 1: `[0, 10]`. Note that all the values can be specified as arrays, in which case they map for specific channels. For example, `[-1, [1, 2], 0, [10, 20]]` will scale the first channel to `[-1, 1, 0, 10]`, and the second one to `[-1, 2, 0, 20]`.
time	Define a temporary connection time that the method takes to complete, applying the necessary interpolations.
shape	Define a temporary shape to be used in the interpolation process. This must be defined with an Env starting at 0 and ending at 1.
forceReplace	Force a `replace` call instead of interpolating the values.
sched	Just like any other AlgaNode method, the current function can be scheduled at specific times in the future, according to the clock that the Alga instance booted on the server is using.

<<

Shortcut for from, where, due to syntax restrictions, only sender and param can be specified. Connect the specific input parameter of this AlgaNode to the output of an AlgaNode, Number, Array, AlgaTemp or AlgaArg.

Arguments:

sender	An AlgaNode, Number, Array, AlgaTemp or AlgaArg.
param	Which parameter to connect to.

.to

Same as from, where the receiver argument is the AlgaNode that the connection is applied to.

>>

Shortcut for to, where, due to syntax restrictions, only receiver and param can be specified.

.mixFrom

Same as from, but all active connections to the parameter are maintained. Essentially, this adds another connection to the specific parameter, adding the values of all the connections together.

<<+

Shortcut for mixFrom, where, due to syntax restrictions, only sender and param can be specified.

.mixTo

Same as mixFrom, where the receiver argument is the AlgaNode that the connection is applied to.

>>+

Shortcut for mixTo, where, due to syntax restrictions, only receiver and param can be specified.

.mixSwap

Replace a connection in the mix of a specific parameter: newSender replaces oldSender. All the other arguments work the same as the other connection methods.

.disconnect

If oldSender is specified, disconnect that specific entry in the mix of a specific parameter. Otherwise, reset the entire parameter to its default value.

.reset

Same as disconnect where no oldSender is specified: reset the parameter to its default value, disconnecting all mix entries.

<|

Shortcut for reset.

.addAction

Execute a Function on the scheduler of this node.

Arguments:

condition	A Function that must return `true` or `false`. If not specified, the condition is always considered `true`.
func	The Function to execute.
sched	When should the function be executed. In the case of AlgaPatterns, this can also be an AlgaStep.
topPriority	Specify if the function should be put at the top of the prioroty queue.
preCheck	Specify if the function should be executed right away in the case of a `true` condition.

.interpTime

Specify a new time that the connections to any of the parameters will use to perform interpolations.

.it

Shortcut for interpTime.

.paramInterpTime

Specify a new time that the connections to the specific param will use to perform interpolations.

.pit

Shortcut for paramInterpTime.

.interpShape

Specify a new interpolation shape that the connections to any of the parameters will use to perform interpolations. This must be defined with an Env that always starts at 0 and ends at 1. If not specified, a single ramp Env([0, 1], 1) is used by default.

.paramInterpShape

Specify a new interpolation shape that the connections to the specific param will use to perform interpolations.

.pis

Shortcut for paramInterpShape.

.playTime

Specify fade in / fade out times when calling play and stop.

.pt

Shortcut for playTime.

.replacePlayTime

Specify a boolean to determine whether to use playTime as the time parameter when calling replace on a node that was playing.

.rpt

Shortcut for replacePlayTime.

.playSafety

Specify a different safety method to use to scale the output of a node when using the play method. Accepted values are: 'clip', 'tanh', 'softclip', 'limiter', 'none'.

.sched

Specify a sched value to use for new actions. This will be used if sched is not provided in the arguments of the called function.

.schedInSeconds

Specify if all sched actions should be scheduled in seconds, opposing to beats. Default is false.

.tempoScaling

Specify if all timed actions should be scaled by the clock's tempo. Default is false.

Examples

//Boot Alga
(
Alga.boot({
    //Declare an AlgaSynthDef
    AlgaSynthDef(\sine, {
        SinOsc.ar(\freq.ar(440));
    }).add;

//Wait
    s.sync;

//Declare a node and play to stereo output
    a = AlgaNode(\sine, interpTime:2).play(chans:2);
});
)

//Change \freq parameter. Note how it interpolates to new value over 2 seconds
a <<.freq 220;

//Declare a square oscillator with variable frequency 1 to 100
b = AlgaNode({ Pulse.ar(LFNoise1.kr(1).range(1, 100)) });

//Map the b node to a's \freq parameter, scaling the -1 to 1 range to 100 to 1000.
//The interpolation will take 5 seconds to complete
a.from(b, \freq, scale: [100, 1000], time:5);

//Declare a new Sine oscillator to use as LFO
c = AlgaNode(\sine, [\freq, 2]);

//Also connect c to a's \freq, mixing with what was already there.
//This will use a's interpTime, 2
a.mixFrom(c, \freq, scale:[-100, 100]);

//Clear over 3 seconds. Note how the interpolation will bring us back
//to just having b modulating a's frequency parameter
c.clear(time:3);

//Clear over 5 seconds. No more connections:
//now we'll interpolate back to a's \freq default value, 440
b.clear(time:5);

//Bye bye
a.clear(time:3);

Simple feedback

(
Alga.boot({
    a = AlgaNode({ SinOsc.ar(\freq.kr(220) + \fm.ar(0)) }, interpTime:5, playTime:2);
    b = AlgaNode({ SinOsc.ar(\freq.kr(134) + \fm.ar(0)) }, interpTime:3);
    a.from(b, \fm, scale:[-100, 100]);
    b.from(a, \fm, scale:[-50, 50]); //Feedback connection!
    a.play(chans:2); //play stereo
})
)

(
//Randomly change a's fm scale every 3 seconds
fork {
    loop {
        a.from(b, \fm, scale:[rrand(-200, -30), rrand(10, 250)]);
        3.wait;
    }
};

//Randomly change b's fm scale every 2 seconds
fork {
    loop {
        b.from(a, \fm, scale:[rrand(-150, -10), rrand(3, 30)]);
        2.wait;
    }
}
)

//Change root frequencies
(
b <<.freq 25;
a <<.freq 103;
)

//Replace b's definition with a sawtooth wave.
//Make sure to have the same parameter names so they keep the mappings
b.replace({ Saw.ar(\freq.kr + \fm.ar) })

//Bye bye
(
b.clear(time:2);
a.clear(time:2);
)

//The errors on console are the routines (fork)
//that are still trying to make connections.
//Ctrl + . to stop them

helpfile source: HelpSource/Classes/AlgaNode.schelp
link::AlgaLib/Classes/AlgaNode::

AlgaNodeExtension

.new

Arguments:

.play

Arguments:

Discussion:

.stop

.clear

.replace

Arguments:

.from

Arguments:

Arguments:

.to

.mixFrom

.mixTo

.mixSwap

.disconnect

.reset

.addAction

Arguments:

.interpTime

.it

.paramInterpTime

.pit

.interpShape

.paramInterpShape

.pis

.playTime

.pt

.replacePlayTime

.rpt

.playSafety

.sched

.schedInSeconds

.tempoScaling

AlgaNode
Extension