Synth:
Filter:
Classes | Server > Nodes | Server > Abstractions

Synth : Node : Object

Client-side representation of a synth node on the server
Source: Node.sc

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 SynthDef, which specifies what UGens 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 SynthDef help file.

For more on the important distinction between client objects and server nodes, see Client vs Server. For information on creating nodes without using objects, see Node Messaging.

Order of Execution

Order of execution is a crucial issue when creating Synths which interact with each other.

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 Bus and Server Architecture for details.

See the Order of execution help file for a more detailed discussion of this important topic.

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 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 Bundled Server Messages for more details.

Class Methods

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

Creation with Immediate Instantiation on the Server

Synth.new(defName, args, target, addAction: 'addToHead')

Create and return a new Synth object, and immediately start the corresponding synth node on the server.

Arguments:

defName

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

args

An optional Array specifying initial values for the 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 Strings or Symbols. e.g. [\frequency, 440, \amplitude, 1, ...]. Values that are arrays are sent using OSC array type-tags ($[ and $]). These values will be assigned to subsequent controls.

target

A target for this Synth. If target is not a Group or Synth, it will be converted as follows: If it is a Server, it will be converted to the 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.

addAction

one of the following Symbols:

\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:

Synth.newPaused(defName, args, target, addAction: 'addToHead')

As new above, but creates a node which is paused. This can be started by calling run on it.

Synth.grain(defName, args, target, addAction: 'addToHead')

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 new above.

Returns:

nil

Convenience methods for add actions

The following convenience methods correspond to the add actions of Synth.new :

Synth.after(aNode, defName, args)

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

Synth.before(aNode, defName, args)

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

Synth.head(aGroup, defName, args)

Create and return a Synth. If aGroup is a Group add it at the head of that group. If it is a Server, add it at the head of the 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.

Synth.tail(aGroup, defName, args)

Create and return a Synth. If aGroup is a Group add it at the tail of that group. If it is a Server, add it at the tail of the 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.

Synth.replace(nodeToReplace, defName, args, sameID: false)

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

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.

Synth.basicNew(defName, server, nodeID)

Create and return a Synth object without creating a synth node on the server.

Arguments:

defName

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

server

An optional instance of Server. If nil this will default to the default Server.

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:

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

Inherited class methods

Instance Methods

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

.defName

.defName = value

Returns:

the name of this Synth's SynthDef.

Creation without Instantiation on the Server

Use class method basicNew to create a Synth without instantiating it on the server. Then use the following instance methods:

.newMsg(target, args, addAction: 'addToHead')

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.

.addToHeadMsg(aGroup, args)

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).

.addToTailMsg(aGroup, args)

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).

.addBeforeMsg(aNode, args)

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.

.addAfterMsg(aNode, args)

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.

.addReplaceMsg(nodeToReplace, args)

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.

Control

For further methods of controlling Synths (set, map, etc.), see the Node helpfile.

.get(index, action)

.getMsg(index)

Query the server for the current value of a Control (argument).

Arguments:

index

a control name or index

(action)

a Function which will be evaluated with the value passed as an argument when the reply is received.

Discussion:

.getn(index, count, action)

.getnMsg(index, count)

Query the server for the current values of a sequential range of Controls (arguments).

Arguments:

index

a control name or index

count

the number of sequential controls to query, starting at index.

(action)

a Function which will be evaluated with an Array containing the values passed as an argument when the reply is received.

.set( ... args)

From superclass: Node

Set the values of one or more Controls.

Discussion:

Example:

.seti( ... args)

Set part of an arrayed control.

Arguments:

... args

A sequence of name, index, value triplets.

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 SynthDescLib.

Example:

Inherited instance methods

Undocumented instance methods

.asGroup

From extension in /usr/local/share/SuperCollider/SCClassLibrary/Common/Control/asGroup.sc

.replace(defName, args, sameID)

Examples

Filtering