Merge pull request #506 from andrewcsmith/patch-2

[supercollider.git] / HelpSource / Classes / Synth.schelp

class:: Synth
summary:: Client-side representation of a synth node on the server
categories:: Server>Nodes, Server>Abstractions
related:: Classes/Node, Classes/SynthDef

description::

A Synth is the client-side representation of a synth node on the server. A Synth represents a single sound producing unit.  What it does is defined in a link::Classes/SynthDef::, which specifies what link::Classes/UGen::s are used and how they are patched together.
It also specifies what inputs and outputs the Synth will have. A SynthDef is thus a kind of fixed pattern, upon which Synths are be based. (Despite this, a given SynthDef can provide a surprising amount of variation.) For more detail on SynthDefs, their construction, and how to send them to a server, see the link::Classes/SynthDef:: help file.

For more on the important distinction between client objects and server nodes, see link::Guides/ClientVsServer::. For information on creating nodes without using objects, see link::Guides/NodeMessaging::.

subsection:: Order of Execution
Order of execution is a crucial issue when creating Synths which interact with each other.
code::
        sound ->  filter
::
If a sound is to be passed through a filter, the synth that does the filtering must be later in the order of execution than the synth which is its input.  The computer must calculate a buffer's worth of sound, and then the computer moves on to calculate a buffer's worth of the filtered version of that sound.

The actual interconnection between synth nodes is accomplished with buses. See link::Classes/Bus:: and link::Reference/Server-Architecture:: for details.

See the link::Guides/Order-of-execution:: help file for a more detailed discussion of this important topic.

subsection:: Bundling

Some 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 link::Classes/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 link::Classes/Server:: and link::Guides/Bundled-Messages:: for more details.

classmethods::
Synth is a subclass of Node, and thus many of its most useful and important methods are documented in the link::Classes/Node:: help file.

private:: stop, play, sampleRate

subsection:: Creation with Immediate Instantiation on the Server
method:: new
Create and return a new Synth object, and immediately start the corresponding synth node on the server.

argument:: defName
A String or Symbol specifying the name of the SynthDef to use in creating the Synth.

argument:: args
An optional link::Classes/Array:: specifying initial values for the link::Classes/SynthDef::'s arguments (controls). These are specified in pairs of control name or index and value. If names are used they can be specified with either link::Classes/String::s or link::Classes/Symbol::s. e.g. code:: [\frequency, 440, \amplitude, 1, ...] ::.
Values that are arrays are sent using OSC array type-tags ($[ and $]).  These values will be assigned to subsequent controls.

argument:: target
A target for this Synth. If target is not a link::Classes/Group:: or Synth, it will be converted as follows: If it is a link::Classes/Server::, it will be converted to the link::Reference/default_group:: of that server. If it is nil, to the default_group of the default Server. If it is an integer, it is created relative to a group with that id.

argument:: addAction
one of the following Symbols:
definitionlist::
## \addToHead || (the default) add at the head of the group specified by target
## \addToTail || add at the tail of the group specified by target
## \addAfter || add immediately after target in its server's node order
## \addBefore || add immediately before target in its server's node order
## \addReplace || replace target and take its place in its server's node order
::
Note: A Synth is not a valid target for \addToHead and \addToTail.

discussion::
code::
s.boot;
// create a Synth at the head of the default Server's default group
// based on the SynthDef "default"
x = Synth.new("default");
s.queryAllNodes; // note the default group (ID 1)
x.free;

// Using an arrayed control
// run this block first to make the SynthDef
(
SynthDef("help-synth", {| freq = #[440, 450, 460], out = 0 |
        Out.ar(out, Mix(SinOsc.ar(freq, 0, 0.1)));
}).add;
)

// then this a short while later
x = Synth("help-synth", [freq: [500,501,510] ]);

x = Synth("help-synth", [freq: [500,501,510] ]);
x.set(\freq, [1,2,3] * 400 + [1,2,3], \out, 1);
x.set(\freq, [3] * 400 + [1,2,3], \out, 1);
x.free;
::

method:: newPaused
As code::new:: above, but creates a node which is paused. This can be started by calling code::run:: on it.
code::
s.boot;
x = Synth.newPaused("default");
s.queryAllNodes; // see I'm here
x.run; // true is the default
x.run(false); // pause me again
x.free;
::

method:: grain
A convenience method which will create a synth node with an node ID of -1. Such a node cannot be messaged after creation. As such this method does not create an object, and returns nil. For details of its arguments see code::new:: above.
returns:: nil

subsection:: Convenience methods for add actions
The following convenience methods correspond to the add actions of code::Synth.new:: :

method:: after
Create and return a Synth and add it immediately after aNode.

method:: before
Create and return a Synth and add it immediately before aNode.

method:: head
Create and return a Synth. If code::aGroup:: is a link::Classes/Group:: add it at the head of that group. If it is a link::Classes/Server::, add it at the head of the link::Reference/default_group:: of that server. If it is nil, add it at the head of the default_group of the default server. If it is an integer, it is created relative to a group with that id.

method:: tail
Create and return a Synth. If code::aGroup:: is a link::Classes/Group:: add it at the tail of that group. If it is a link::Classes/Server::, add it at the tail of the link::Reference/default_group:: of that server. If it is nil, add it at the tail of the default_group of the the default server. If it is an integer, it is created relative to a group with that id.

method:: replace
Create and return a Synth and use it to replace code::nodeToReplace::, taking its place in its server's node order.

subsection:: Creation without Instantiation on the Server

For use in message bundles it is also possible to create a Synth object in the client app without immediately creating a synth node on the server. Once done one can call methods which create messages to add to a bundle, which when sent to the server will instantiate the synth.

method:: basicNew
Create and return a Synth object without creating a synth node on the server.
argument:: defName
A String or Symbol specifying the name of the SynthDef to use in creating the Synth.
argument:: server
An optional instance of Server. If nil this will default to the default Server.
argument:: nodeID
An optional node ID number. If not supplied one will be generated by the Server's NodeIDAllocator. Normally you should not need to supply an ID.
discussion::
code::
s.boot;
x = Synth.basicNew("default", s); // Create without sending
s.sendBundle(nil, x.newMsg;); // Now send a message; create at the head of s' default group
s.queryAllNodes;
x.free;
::

After creation, use instance methods code::newMsg, addToHeadMsg, addToTailMsg, addBeforeMsg, addAfterMsg, addReplaceMsg:: to instantiate this synth on the server. See link::#instancemethods#Instance Methods:: below.



instancemethods::
Synth is a subclass of Node, and thus many of its most useful and important methods are documented in the link::Classes/Node:: help file.

private:: prepareForProxySynthDef, play

method:: defName
Returns:: the name of this Synth's SynthDef.

subsection:: Creation without Instantiation on the Server
Use class method code::basicNew:: to create a Synth without instantiating it on the server. Then use the following instance methods:
method:: newMsg
See *new above for details of addActions and args.
Returns:: a message of the type s_new which can be bundled. When sent to the server this message will instantiate this synth. If target is nil, it will default to the default_group of the Server specified in *basicNew when this Synth was created. The default addAction is \addToHead.

method:: addToHeadMsg
See *new above for details on args.
Returns:: a message of the type s_new which can be bundled. When sent to the server this message will instantiate this synth. If aGroup is a Group it will be added at the head of that group. If it is nil, it will be added at the head of the default_group of this Synth's server (as specified when *basicNew was called).

method:: addToTailMsg
See *new above for details on args.
Returns:: a message of the type s_new which can be bundled. When sent to the server this message will instantiate this synth. If aGroup is a Group it will be added at the tail of that group. If it is nil, it will be added at the tail of the default_group of this Synth's server (as specified when *basicNew was called).

method:: addBeforeMsg
See *new above for details on args.
Returns:: a message of the type s_new which can be bundled. When sent to the server this message will instantiate this synth, immediately before aNode.

method:: addAfterMsg
See *new above for details on args.
Returns:: a message of the type s_new which can be bundled. When sent to the server this message will instantiate this synth, immediately after aNode.

method:: addReplaceMsg
See *new above for details on args.
Returns:: a message of the type s_new which can be bundled. When sent to the server this message will instantiate this synth, replacing nodeToReplace in the server's node order.

subsection:: Control
For further methods of controlling Synths (set, map, etc.), see the link::Classes/Node:: helpfile.

method:: get, getMsg
Query the server for the current value of a link::Classes/Control:: (argument).
argument:: index
a control name or index
argument:: action
a Function which will be evaluated with the value passed as an argument when the reply is received.
discussion::
code::
s.boot;
(
SynthDef("help-Synth-get", { arg freq = 440;
        Out.ar(0, SinOsc.ar(freq, 0, 0.1));
}).add;
)
x = Synth("help-Synth-get");
x.set(\freq, 220 + 440.rand);
x.get(\freq, { arg value; ("freq is now:" + value + "Hz").postln; });
x.free;
::

method:: getn, getnMsg
Query the server for the current values of a sequential range of link::Classes/Control::s (arguments).
argument:: index
a control name or index
argument:: count
the number of sequential controls to query, starting at index.
argument:: action
a Function which will be evaluated with an link::Classes/Array:: containing the values passed as an argument when the reply is received.

method:: set
Set the values of one or more link::Classes/Control::s.
discussion::
Example:
code::
x.set(\freq, 440, \amp, 0.5)
::

method:: seti
Set part of an arrayed control.
argument:: ... args
A sequence of strong:: name, index, value :: triplets.

definitionlist::
## name || The name of the arrayed control
## index || The index into the array
## value || The new value to set, can be an array to set a range of elements.
::

discussion::
note::
The synthdef has to be .add'ed, so that it is stored in the link::Classes/SynthDescLib::.
::
Example:
code::
(
s.waitForBoot {
    SynthDef(\helpSeti, { |freqs = #[100,150,200,250]|
        Out.ar(0, SinOsc.ar(freqs.poll,0,0.1).sum ! 2)
    }).add;
    s.sync;
    x = Synth(\helpSeti);
}
)
x.seti(\freqs,2,600); // set only the third element
x.seti(\freqs,1,[400,410]); // set second and third element
x.free;
::

Examples::
code::
// boot the default server
s = Server.default; // just to be sure
s.boot;


(
// send a synth def to server
SynthDef("tpulse", { arg out = 0,freq = 700, sawFreq = 440.0;
        Out.ar(out, SyncSaw.ar(freq, sawFreq, 0.1));
}).add;
)

// Here the defaults for *new will result in a Synth at the head of the default group
// of the default Server. This will use the SynthDef's default arguments;
y = Synth.new("tpulse");
y.free;

// The same done explicitly
y = Synth.new("tpulse", nil, s, \addToHead);
y.free;

// With some arguments
y = Synth.new("tpulse", [\freq, 350, \sawFreq, 220]);
y.free;

// make a new synth
y = Synth("tpulse");

// pause
y.run(false);

y.run(true);

// set a control by argument name
y.set("freq", 200);

// or by index
y.set(2, 100.0);

// modulate out to bus number 1 (the right speaker)
y.set(0, 1);

//  multiple set commands in one message
y.set("out", 0, "freq",300);

// free the synth from the server
y.free;
::

subsection:: Filtering
code::
(
// first collect some things to play with
SynthDef("moto-rev", { arg out=0;
        var x;
        x = RLPF.ar(LFPulse.ar(SinOsc.kr(0.2, 0, 10, 21), [0,0.1], 0.1),
                100, 0.1).clip2(0.4);
        Out.ar(out, x);
}).add;

SynthDef("bubbles", { arg out=0;
        var f, zout;
        f = LFSaw.kr(0.4, 0, 24, LFSaw.kr([8,7.23], 0, 3, 80)).midicps;
        zout = CombN.ar(SinOsc.ar(f, 0, 0.04), 0.2, 0.2, 4); // echoing sine wave
        Out.ar(out, zout);
}).add;


SynthDef("rlpf",{ arg out=0,ffreq=600,rq=0.1;
        ReplaceOut.ar( out, RLPF.ar( In.ar(out), ffreq,rq) )
}).add;


SynthDef("wah", { arg out, rate = 1.5, cfreq = 1400, mfreq = 1200, rq=0.1;
        var zin, zout;

        zin = In.ar(out, 2);
        cfreq = Lag3.kr(cfreq, 0.1);
        mfreq = Lag3.kr(mfreq, 0.1);
        rq   = Ramp.kr(rq, 0.1);
        zout = RLPF.ar(zin, LFNoise1.kr(rate, mfreq, cfreq), rq, 10).distort
                                        * 0.15;

        // replace the incoming bus with the effected version
        ReplaceOut.ar( out , zout );

}).add;

SynthDef("modulate",{ arg out = 0, freq = 1, center = 440, plusMinus = 110;
        Out.kr(out, SinOsc.kr(freq, 0, plusMinus, center));
}).add;
)

// execute these one at a time

// y is playing on bus 0
y = Synth("moto-rev",["out",0]);

// z is reading from bus 0 and replacing that; It must be *after* y
z = Synth.after(y,"wah",["out",0]);

// stop the wah-ing
z.run(false);

// resume the wah-ing
z.run(true);

// add a rlpf after that, reading and writing to the same buss
x = Synth.after(z,"rlpf",["out",0]);

// create another rlpf after x
t = Synth.after(x,"rlpf",["out",0]);

x.set("ffreq", 400);

x.set(\ffreq, 800); // Symbols work for control names too

// Now let's modulate x's ffreq arg
// First get a control Bus
b = Bus.control(s, 1);

// now the modulator, *before* x
m = Synth.before(x, "modulate", [\out, b]);

// now map x's ffreq to b
x.map("ffreq", b);

m.set("freq", 4, "plusMinus", 20);

x.free;
z.free;
m.free;

// now place another synth after y, on the same bus
// they both write to the buss, adding their outputs
r = Synth.after(y,"bubbles",["out",0]);

y.free;

r.free;

// look at the Server window
// still see 4 Ugens and 1 synth?
// you can't hear me, but don't forget to free me
t.free;
::