#lang scribble/manual
@(require (for-label racket))

@title{Synth}
 Client-side representation of a synth node on the server@section{categories}
  Server>Nodes, Server>Abstractions
@section{related}
  Classes/Node, Classes/SynthDef

@section{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::.

@section{subsection}
  Order of Execution
Order of execution is a crucial issue when creating Synths which interact with each other.

@racketblock[
	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.

]
@section{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.

@section{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.

@section{private}
  stop, play, sampleRate

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

@section{argument}
  defName
A String or Symbol specifying the name of the SynthDef to use in creating the Synth.

@section{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. 
@racketblock[ [\frequency, 440, \amplitude, 1, ...] ::.
Values that are arrays are sent using OSC array type-tags ($[ and $]).  These values will be assigned to subsequent controls.

]
@section{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.

@section{argument}
  addAction
one of the following Symbols:
@section{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.

@section{discussion}
 

@racketblock[
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;
::

]
@section{method}
  newPaused
As 
@racketblock[new:: above, but creates a node which is paused. This can be started by calling ]

@racketblock[run:: on it.
]

@racketblock[
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;
::

]
@section{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 
@racketblock[new:: above.
]
@section{returns}
  nil

@section{subsection}
  Convenience methods for add actions
The following convenience methods correspond to the add actions of 
@racketblock[Synth.new:: :

]
@section{method}
  after
Create and return a Synth and add it immediately after aNode.

@section{method}
  before
Create and return a Synth and add it immediately before aNode.

@section{method}
  head
Create and return a Synth. If 
@racketblock[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.

]
@section{method}
  tail
Create and return a Synth. If 
@racketblock[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.

]
@section{method}
  replace
Create and return a Synth and use it to replace 
@racketblock[nodeToReplace::, taking its place in its server's node order.

]
@section{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.

@section{method}
  basicNew
Create and return a Synth object without creating a synth node on the server.
@section{argument}
  defName
A String or Symbol specifying the name of the SynthDef to use in creating the Synth.
@section{argument}
  server
An optional instance of Server. If nil this will default to the default Server.
@section{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.
@section{discussion}
 

@racketblock[
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 ]

@racketblock[newMsg, addToHeadMsg, addToTailMsg, addBeforeMsg, addAfterMsg, addReplaceMsg:: to instantiate this synth on the server. See link::#instancemethods#Instance Methods:: below.



]
@section{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.

@section{private}
  prepareForProxySynthDef, play

@section{method}
  defName
@section{Returns}
  the name of this Synth's SynthDef.

@section{subsection}
  Creation without Instantiation on the Server
Use class method 
@racketblock[basicNew:: to create a Synth without instantiating it on the server. Then use the following instance methods:
]
@section{method}
  newMsg
See *new above for details of addActions and args.
@section{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.

@section{method}
  addToHeadMsg
See *new above for details on args.
@section{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).

@section{method}
  addToTailMsg
See *new above for details on args.
@section{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).

@section{method}
  addBeforeMsg
See *new above for details on args.
@section{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.

@section{method}
  addAfterMsg
See *new above for details on args.
@section{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.

@section{method}
  addReplaceMsg
See *new above for details on args.
@section{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.

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

@section{method}
  get, getMsg
Query the server for the current value of a link::Classes/Control:: (argument).
@section{argument}
  index
a control name or index
@section{argument}
  action
a Function which will be evaluated with the value passed as an argument when the reply is received.
@section{discussion}
 

@racketblock[
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;
::

]
@section{method}
  getn, getnMsg
Query the server for the current values of a sequential range of link::Classes/Control::s (arguments).
@section{argument}
  index
a control name or index
@section{argument}
  count
the number of sequential controls to query, starting at index.
@section{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.

@section{method}
  set
Set the values of one or more link::Classes/Control::s.
@section{discussion}
 
Example:

@racketblock[
x.set(\freq, 440, \amp, 0.5)
::

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

@section{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.
::

@section{discussion}
 
@section{note}
 
The synthdef has to be .add'ed, so that it is stored in the link::Classes/SynthDescLib::.
::
Example:

@racketblock[
(
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;
::

]
@section{Examples}
 

@racketblock[
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;
::

]
@section{subsection}
  Filtering

@racketblock[
(
// 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;
::

]