sc3.synth.node module¶

Node.sc

class Node¶

Bases: sc3.synth._graphparam.NodeParameter

Base class for Group and Synth.

This class is not used directly but though its subclasses, Synth and Group (or ParGroup), which represent synth or group nodes on the server.

Node objects which you explicitly free using the methods free or release will have their group instance variable set to None. However, objects which are automatically freed after a certain time (for instance by an EnvGen with a done action 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, either by calling register on the Node instance or on the NodeWatcher singleton. This will enable two variables, is_playing and is_running, which you can use for checking purposes.

add_actions = {'addToHead': 0, 'addToTail': 1, 'addBefore': 2, 'addAfter': 3, 'addReplace': 4, 'head': 0, 'tail': 1, 'before': 2, 'after': 3, 'replace': 4, 'h': 0, 't': 1, 'b': 2, 'a': 3, 'r': 4, 0: 0, 1: 1, 2: 2, 3: 3, 4: 4}¶

property is_playing¶

Return True if the node is in the server.

The node must have been registered for this property to be active.

Type: bool

property is_running¶

Return True if the node is running, i.e. not paused.

Nodes can be paused by sending a ‘/n_run’ message using the method run. The node must have been registered for this property to be active.

Type: bool

classmethod basic_new(server=None, node_id=None)¶

Instantiate a node object without creating it on the server.

Parameters

server (Server) – The target server. If None default server will be used.
node_id (int) – ID of the node. If not supplied one will be generated by the server’s NodeIDAllocator. Normally there is no need to supply an ID. Default is None.

free(send_flag=True)¶

Stop this node and free it from its parent group on the server.

Once a node has been freed, is not possible to restart it.

Parameters: send_flag (bool) – Indicate whether the free message should be sent. If False an ‘/n_free’ message will not be sent to this node’s server, but its is_playing and is_running properties will be set to false. Default is True.

run(flag=True)¶

Set the running state of this node.

Parameters: flagprBootInProcessServer (bool) – False will pause the node without freeing it. Default is True.

map(*args)¶

Map controls in this node to read from control rate buses.

Parameters: *args (tuple(str | int, ControlBus | int, )) – A sequence alternating controls and buses to map to each control.

Notes

Controls are defined in a SynthDef as parameters or instances of Control ugens or its subclasses. They are specified here using either strings (names) or indices (position), and are listed in pairs with control bus indices or objects.

To unmap a control set the bus value to -1.

If the node is a group, mapping propagates recursively to the controls of all nodes within the group.

mapa(*args)¶

Map controls in this node to read from audio rate buses.

Parameters: *args (tuple(str | int, ControlBus | int, )) – A sequence alternating controls and buses to map to each control.

Notes

Controls are defined in a SynthDef as parameters or instances of Control ugens or its subclasses. They are specified here using either strings (names) or indices (position), and are listed in pairs with audio bus indices or objects.

To unmap a control set the bus value to -1.

If the node is a group, mapping propagates recursively to the controls of all nodes within the group.

mapn(*args)¶

Map adjacent controls in this node to read from control rate buses.

Warning

This message only maps adjacent controls from multichannel buses if controls are set by position (as int). Setting controls by name (as str) has the same effect as map.

Parameters: *args (tuple(str | int, ControlBus | int, )) – A sequence alternating controls and buses to map to each control.

Notes

Multichannel buses will sequentially map to adjacent controls if the control is specified by index (position). See also map.

mapan(*args)¶

Map adjacent controls in this node to read from audio rate buses.

Warning

This message only maps adjacent controls from multichannel buses if controls are set by position (as int). Setting controls by name (as str) has the same effect as mapa.

Parameters: *args (tuple(str | int, AudioBus | int, )) – A sequence alternating controls and buses to map to each control.

Notes

Multichannel buses will sequentially map to adjacent controls if the control is specified by index (position). See also mapa.

set(*args)¶

Set controls’ values for this node.

Warning

This message only maps adjacent controls if they are set by position (as int).

Parameters: *args (tuple(str | int, float | int, )) – A sequence alternating controls’ names or positions and values.

Notes

Values that are lists or tuples are sent using the OSC array type-tags. These values will be assigned to subsequent controls in the manner of setn if the control are specified by position (as int).

If the node is a group, mapping propagates recursively to the controls of all nodes within the group.

setn(*args)¶

Set ranges of adjacent controls in this node to values.

See the``set`` method.

fill(cname, num_controls, value, *args)¶

Set sequential ranges of controls in this node to a single value.

Parameters

cname (str | int) – Control’s name or position.
num_controls (int) – Number of adjacent controls to set.
value (float | int) – Value of the controls.
*args (tuple(cname, num_controls, value)) – More control.

release(time=None)¶

Free the node using the ‘gate’ control.

Parameters

time (None | float | int) –

The amount of time in seconds during which the node will release. If set to a value <= 0, the synth will release immediately. A None value will cause the synth to release using its envelope’s normal release stage(s).

Providing a releaseTime != None doesn’t trigger a normal release, but a different behavior called forced release. This difference is particularly important for envelopes with a multi-node release stage, i.e. whose releaseNode is not their last node. See EnvGen forced release.

Notes

This method causes the receiver to be freed after the specified amount of time. This is a convenience method which assumes tha the synth contains an envelope generator (an EnvGen, Linen, or similar ugen) running a sustaining envelope and that this envelope’s gate argument is set to a control called 'gate'.

If the receiver is a group, all nodes within the group will be released.

trace()¶

Dump internal synth or group information to stdout.

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.

query(action=None)¶

Retrieve information about this node within the server tree.

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.

Parameters: action (callable) – An optional function. If the node is a synth, the function will take the arguments server_cmd, node_id, parent, prev, next and is_group. If the node is a group, the function will take the arguments server_cmd, node_id, parent, prev, next, is_group, head, tail. Providing a function here will bypass query’s normal behaviour, i.e., the usual node information will not be posted.

Notes

By default this information will be printed to stdout with the following format: ‘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.

See also the query_tree method of Server.

register(playing=True, running=True)¶

Registers the node at the NodeWatcher object.

Parameters

playing (bool) – Enable is_playing property.
running (bool) – Enable is_running property.

Notes

This will enable is_playing and is_running, which you can use for checking purposes. These properties can also be enabled at instantiation time setting the register` parameter to True.

unregister()¶: Unregisters the node at the NodeWatcher object.

on_free(action)¶

Evaluate a function when this node is freed.

Parameters: action (callable) – A function that optionaly receives this node as argument.

wait_for_free()¶

Wait until this Node is freed.

Should be yield from inside a routine.

move_before(target)¶

Move this node to be directly before target.

Parameters: target (Node) – Reference node.

Notes

This method sends a ‘/n_before’ command that 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.

move_after(target)¶

Move this node to be directly after target.

Parameters: target (Node) – Reference node.

Notes

This method sends a ‘/n_after’ command that 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.

move_to_head(target=None)¶

Move this node to head of the target group.

Parameters: target (Group | None) – Reference group.

Notes

If target is a group then this method will move this node to the head of that group. If it is None this will move this node to the head of the default group of this node’s server.

move_to_tail(target=None)¶

Move this node to tail of the target group.

Parameters: target (Group | None) – Reference group.

Notes

If target is a group then this method will move this node to the tail of that group. If it is None this will move this node to the tail of the default group of this node’s server.

class AbstractGroup(target=None, add_action='addToHead', register=False)¶

Bases: sc3.synth.node.Node

Base class for Group and ParGroup.

Create a group node in the server.

Parameters

target (Server | Node) – Reference node for add actions. …
add_action (str | int) –
…
register (bool) – Register the node at the NodeWatcher object. Default is False.

classmethod after(target)¶: Create a group after target. Convenience constructor.

classmethod before(target)¶: Create a group before target. Convenience constructor.

classmethod head(target)¶: Create a group at the head of target. Convenience constructor.

classmethod tail(target)¶: Create a group at the tail of target. Convenience constructor.

classmethod replace(target)¶: Create a group and replace target. Convenience constructor.

free_all()¶: Free all children nodes.

deep_free()¶

Free all synth nodes in this group and all its sub groups.

Traverses all groups below this group and frees all the synths. Sub groups are not freed.

dump_tree(controls=False)¶

Ask the server to dump this node tree to stdout.

Parameters: controls (bool) – If True also print synth controls with current values.

query_tree(controls=False, action=None, timeout=3)¶

Query the groups’s node tree.

Parameters

controls (bool) – If True also request synth controls values.
action (function) – A responder function that receives the data in JSON format.
timeout (int | float) – Request timeout in seconds.

static creation_cmd()¶

class Group(target=None, add_action='addToHead', register=False)¶

Bases: sc3.synth.node.AbstractGroup

Client-side representation of a group node on the server.

Create a group node in the server.

Parameters

target (Server | Node) – Reference node for add actions. …
add_action (str | int) –
…
register (bool) – Register the node at the NodeWatcher object. Default is False.

static creation_cmd()¶

class ParGroup(target=None, add_action='addToHead', register=False)¶

Bases: sc3.synth.node.AbstractGroup

Client-side representation of a parallel group node on the server.

Parallel groups are only supported by supernova.

Create a group node in the server.

Parameters

target (Server | Node) – Reference node for add actions. …
add_action (str | int) –
…
register (bool) – Register the node at the NodeWatcher object. Default is False.

static creation_cmd()¶

class RootNode(server=None)¶

Bases: sc3.synth.node.Group

Persistent root node group on the server.

For each booted server the node tree structure is initialized with a root node of ID 0. This is intended for internal use only and should not be confused with the default group. Root nodes are always playing, always running, cannot be freed, or moved anywhere. Caching is used so that there is always one root node per server.:

s = Server.default
a = RootNode(s)
b = RootNode(s)
assert a is b

Notes

In general user nodes should not be added to the root node unless there is a specific reason to do so. Instead one should add nodes to the default group. This provides a known basic node order and protects functionality like Server.recorder, or other special objects.

The default group is the default target for all new nodes, so when using object style nodes will normally not be added to the root node unless that is explicitly specified. See default group for more information.

Create a group node in the server.

Parameters

target (Server | Node) – Reference node for add actions. …
add_action (str | int) –
…
register (bool) – Register the node at the NodeWatcher object. Default is False.

roots = {}¶

run()¶

Set the running state of this node.

Parameters: flagprBootInProcessServer (bool) – False will pause the node without freeing it. Default is True.

free()¶

Stop this node and free it from its parent group on the server.

Once a node has been freed, is not possible to restart it.

Parameters: send_flag (bool) – Indicate whether the free message should be sent. If False an ‘/n_free’ message will not be sent to this node’s server, but its is_playing and is_running properties will be set to false. Default is True.

move_before()¶

Move this node to be directly before target.

Parameters: target (Node) – Reference node.

Notes

This method sends a ‘/n_before’ command that 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.

move_after()¶

Move this node to be directly after target.

Parameters: target (Node) – Reference node.

Notes

This method sends a ‘/n_after’ command that 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.

move_to_head()¶

Move this node to head of the target group.

Parameters: target (Group | None) – Reference group.

Notes

If target is a group then this method will move this node to the head of that group. If it is None this will move this node to the head of the default group of this node’s server.

move_to_tail()¶

Move this node to tail of the target group.

Parameters: target (Group | None) – Reference group.

Notes

If target is a group then this method will move this node to the tail of that group. If it is None this will move this node to the tail of the default group of this node’s server.

classmethod free_all_roots()¶: Free all root nodes of all servers.

class Synth(def_name, args=None, target=None, add_action='addToHead', register=False)¶

Bases: sc3.synth.node.Node

Client-side representation of a synth node on the server.

Create a synth node in the server.

Parameters

def_name (str) – The name of the synthesis definition used by the server to create synth nodes.
args (...) –
…
target (Server | Node) – The target server or node. If None default node of the default server will be used. …
add_action (str | int) –
…
register (bool) – Register the node at the NodeWatcher object. Default is False.

classmethod basic_new(def_name, server=None, node_id=None)¶

Instantiate a synth object without creating it on the server.

Parameters

def_name (str) – The name of the synthesis definition used by the server to create synth nodes.
server (Server) – The target server. If None default server will be used.
node_id (int) – ID of the node. If not supplied one will be generated by the server’s NodeIDAllocator. Normally there is no need to supply an ID. Default is None.

classmethod new_paused(def_name, args=None, target=None, add_action='addToHead', register=False)¶

Create a node which is paused.

A paused synth can be started by calling run on it. All parameters are the same as __init__.

classmethod grain(def_name, args=None, target=None, add_action='addToHead')¶

Create a transitory synth node.

Create a synth node with a node ID of -1. Such a node cannot be messaged after creation. As such this method does not create an object, and returns None. Parameters are the same as __init__.

classmethod after(target, def_name, args=None)¶: Create a synth after target. Convenience constructor.

classmethod before(target, def_name, args=None)¶: Create a synth before target. Convenience constructor.

classmethod head(target, def_name, args=None)¶: Create a synth at the head of target. Convenience constructor.

classmethod tail(target, def_name, args=None)¶: Create a synth at the tail of target. Convenience constructor.

classmethod replace(target, def_name, args=None, same_id=False)¶: Create a synth and replace target. Convenience constructor.

get(index, action)¶

Query the current value of a control for this node.

Parameters

index (int | str) – A control name or index.
action (callable) – A function which will be evaluated with the value passed as an argument when the reply is received.

getn(index, count, action)¶

Query the current values of a range of controls for this node.

Parameters

index (int | str) – A control name or index.
count (int) – The number of sequential controls to query, starting at index.
action (callable) – A function which will be evaluated with a list containing the values passed as an argument when the reply is received.

seti(*args)¶

Set part of an arrayed control.

Parameters

*args (tuple(str, int, float | int | list, )) – A sequence of name, index and value representing the name of an arrayed control, the index within the array and the value for that control position. The value can be a list to set a range of elements for one arrayed control.
note:: (.) – The synthdef has to be .add’ed, so that it is stored in the SynthDescLib to check the control names and set the values.