sc3nb.sc_objects.node

Implements Node and subclasses Synth and Group.

Module Contents

Class List

GroupReply	Replies of Group Commands
GroupCommand	OSC Commands for Groups
SynthCommand	OSC Commands for Synths
NodeReply	Replies of Node Commands
NodeCommand	OSC Commands for Nodes
AddAction	AddAction of SuperCollider nodes.
SynthInfo	Information about the Synth from /n_info
GroupInfo	Information about the Group from /n_info
Node	Representation of a Node on SuperCollider.
Synth	Representation of a Synth on SuperCollider.
Group	Representation of a Group on SuperCollider.
NodeTree	Node Tree is a class for parsing /g_queryTree.reply

Content

sc3nb.sc_objects.node._LOGGER

class sc3nb.sc_objects.node.GroupReply

Bases: str, enum.Enum

Replies of Group Commands

Initialize self. See help(type(self)) for accurate signature.

QUERY_TREE_REPLY = '/g_queryTree.reply'

class sc3nb.sc_objects.node.GroupCommand

Bases: str, enum.Enum

OSC Commands for Groups

Initialize self. See help(type(self)) for accurate signature.

QUERY_TREE = '/g_queryTree'

DUMP_TREE = '/g_dumpTree'

DEEP_FREE = '/g_deepFree'

FREE_ALL = '/g_freeAll'

TAIL = '/g_tail'

HEAD = '/g_head'

G_NEW = '/g_new'

P_NEW = '/p_new'

class sc3nb.sc_objects.node.SynthCommand

Bases: str, enum.Enum

OSC Commands for Synths

Initialize self. See help(type(self)) for accurate signature.

NEW = '/s_new'

S_GET = '/s_get'

S_GETN = '/s_getn'

class sc3nb.sc_objects.node.NodeReply

Bases: str, enum.Enum

Replies of Node Commands

Initialize self. See help(type(self)) for accurate signature.

INFO = '/n_info'

class sc3nb.sc_objects.node.NodeCommand

Bases: str, enum.Enum

OSC Commands for Nodes

Initialize self. See help(type(self)) for accurate signature.

ORDER = '/n_order'

TRACE = '/n_trace'

QUERY = '/n_query'

MAP = '/n_map'

MAPN = '/n_mapn'

MAPA = '/n_mapa'

MAPAN = '/n_mapan'

FILL = '/n_fill'

SET = '/n_set'

SETN = '/n_setn'

RUN = '/n_run'

FREE = '/n_free'

class sc3nb.sc_objects.node.AddAction(*args, **kwds)

Bases: enum.Enum

AddAction of SuperCollider nodes.

This Enum contains the codes for the different ways to add a node.

TO_HEAD = 0

TO_TAIL = 1

BEFORE = 2

AFTER = 3

REPLACE = 4

class sc3nb.sc_objects.node.SynthInfo

Bases: NamedTuple

Information about the Synth from /n_info

nodeid: int

group: int

prev_nodeid: int

next_nodeid: int

class sc3nb.sc_objects.node.GroupInfo

Bases: NamedTuple

Information about the Group from /n_info

nodeid: int

group: int

prev_nodeid: int

next_nodeid: int

head: int

tail: int

class sc3nb.sc_objects.node.Node(*, nodeid: int | None = None, add_action: AddAction | int | None = None, target: Node | int | None = None, server: sc3nb.sc_objects.server.SCServer | None = None)

Bases: abc.ABC

Representation of a Node on SuperCollider.

Create a new Node

Parameters:

nodeidint or None

This Nodes node id or None

add_actionAddAction or corresponding int, optional

This Nodes AddAction when created in Server, by default None

targetNode or int or None, optional

This Nodes AddActions target, by default None

serverSCServer, optional

The Server for this Node, by default use the SC default server

_server

_state_lock

_free_event

_on_free_callback = None

_started = False

_freed = False

_nodeid

_group = None

_target_id

_is_playing = None

_is_running = None

_current_controls

Overview:

new	Create a new Node
_get_status_repr
_set_node_attrs	Derive Node group from addaction and target
free	Free the node with /n_free.
run	Turn node on or off with /n_run.
set	Set a control value(s) of the node with n_set.
_update_control
_update_controls
fill	Fill ranges of control values with n_fill.
map	Map a node's control to read from a bus using /n_map or /n_mapa.
release	Set gate as specified.
query	Sends an n_query message to the server.
trace	Trace a node.
move	Move this node
register	Register to be watched.
unregister	Unregister to stop being watched.
on_free	Callback that is executed when this Synth is freed
wait	Wait until this Node is freed
_parse_info
_handle_notification
__eq__
_get_nodeid	Get the corresponding node id

abstract new(*args, add_action: AddAction | int | None = None, target: Node | int | None = None, return_msg: bool = False, **kwargs) → Node | sc3nb.osc.osc_communication.OSCMessage

Create a new Node

Parameters:

add_actionAddAction or int, optional

Where the Node should be added, by default AddAction.TO_HEAD (0)

targetNode or int, optional

AddAction target, if None it will be the default group of the server

_get_status_repr() → str

_set_node_attrs(target: Node | int | None = None, add_action: AddAction | int | None = None) → None

Derive Node group from addaction and target

Parameters:

targetint or Node

Target nodeid or Target Node of this Node’s AddAction

add_actionAddAction

AddAction of this Node, default AddAction.TO_HEAD (0)

free(return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Free the node with /n_free.

This will set is_running and is_playing to false. Even when the message is returned to mimic the behavior of the SuperCollider Node See https://doc.sccode.org/Classes/Node.html#-freeMsg

Returns:

Node or OSCMessage

self for chaining or OSCMessage when return_msg=True

run(on: bool = True, return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Turn node on or off with /n_run.

Parameters:

onbool

True for on, False for off, by default True

Returns:

Node or OSCMessage

self for chaining or OSCMessage when return_msg=True

set(argument: str | Dict | List, *values: Any, return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Set a control value(s) of the node with n_set.

Parameters:

argumentstr | dict | list

if string: name of control argument if dict: dict with argument, value pairs if list: use list as message content

valueany, optional

only used if argument is string, by default None

Examples

>>> synth.set("freq", 400)
>>> synth.set({"dur": 1, "freq": 400})
>>> synth.set(["dur", 1, "freq", 400])

_update_control(control: str, value: Any) → None

_update_controls(controls: Dict[str, Any] | None = None) → None

fill(control: str | int, num_controls: int, value: Any, return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Fill ranges of control values with n_fill.

Parameters:

controlint or string

control index or name

num_controlsint

number of control values to fill

valuefloat or int

value to set

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

OSCMessage

if return_msg else self

map(control: str | int, bus: sc3nb.sc_objects.bus.Bus, return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Map a node’s control to read from a bus using /n_map or /n_mapa.

Parameters:

controlint or string

control index or name

busBus

control/audio bus

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

OSCMessage

if return_msg else self

release(release_time: float | None = None, return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Set gate as specified.

https://doc.sccode.org/Classes/Node.html#-release

Parameters:

release_timefloat, optional

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

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

OSCMessage

if return_msg else self

query() → SynthInfo | GroupInfo

Sends an n_query message to the server.

The answer is send to all clients who have registered via the /notify command. Content of answer:

node ID the node’s parent group ID previous node ID, -1 if no previous node. next node ID, -1 if no next node. 1 if the node is a group, 0 if it is a synth

if the node is a group:

ID of the head node, -1 if there is no head node. ID of the tail node, -1 if there is no tail node.

Returns:

SynthInfo or GroupInfo

n_info answer. See above for content description

trace(return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Trace a node.

Print out values of the inputs and outputs for one control period. If node is a group then print the node IDs and names of each node.

Parameters:

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

Node or OSCMessage

if return_msg else self

move(add_action: AddAction, another_node: Node, return_msg: bool = False) → Node | sc3nb.osc.osc_communication.OSCMessage

Move this node

Parameters:

add_actionAddAction [TO_HEAD, TO_TAIL, AFTER, BEFORE]

What add action should be done.

another_nodeNode

The node which is the target of the add action

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

Node or OSCMessage

if return_msg this will be the OSCMessage, else self

Raises:

ValueError

If a wrong AddAction was provided

abstract register()

Register to be watched.

abstract unregister()

Unregister to stop being watched.

on_free(func)

Callback that is executed when this Synth is freed

wait(timeout: float | None = None) → None

Wait until this Node is freed

Raises:

TimeoutError

If timeout was provided and wait timed out.

_parse_info(nodeid: int, group: int, prev_nodeid: int, next_nodeid: int, *rest: Sequence[int]) → SynthInfo | GroupInfo

_handle_notification(kind: str, info) → None

__eq__(other)

static _get_nodeid(value: Node | int) → int

Get the corresponding node id

Parameters:

valueNode or int

If a Node is provided it will get its nodeid If a int is provided it will be returned

Returns:

int

nodeid

Raises:

ValueError

When neither Node or int was provided

class sc3nb.sc_objects.node.Synth(name: str | None = None, controls: Dict[str, Any] = None, *, nodeid: int | None = None, new: bool = True, add_action: AddAction | int | None = None, target: Node | int | None = None, server: sc3nb.sc_objects.server.SCServer | None = None)

Bases: Node

Representation of a Synth on SuperCollider.

Create a Python representation of a SuperCollider synth.

Parameters:

namestr, optional

name of the synth to be created, by default “default”

controlsdict, optional

synth control arguments, by default None

nodeidint, optional

ID of the node in SuperCollider, by default sc3nb will create one. Can be set to an existing id to create a Python instance of a running Node.

newbool, optional

True if synth should be created on the server, by default True Should be False if creating an instance of a running Node.

add_actionAddAction or int, optional

Where the Synth should be added, by default AddAction.TO_HEAD (0)

targetNode or int, optional

AddAction target, if None it will be the default group of the server

serverSCServer

sc3nb SCServer instance

Raises:

ValueError

Raised when synth can’t be found via SynthDescLib.global

Examples

>>> scn.Synth(sc, "s1", {"dur": 1, "freq": 400})

_server

_initialized = False

Overview:

_update_synth_state
new	Creates the synth on the server with s_new.
get	Get a Synth argument
seti	Set part of an arrayed control.
__getattr__
__setattr__
__repr__

_update_synth_state(name: str | None, controls: dict | None)

new(controls: dict | None = None, add_action: AddAction | int | None = None, target: Node | int | None = None, *, return_msg: bool = False) → Synth | sc3nb.osc.osc_communication.OSCMessage

Creates the synth on the server with s_new.

Attention: Here you create an identical synth! Same nodeID etc. - This will fail if there is already this nodeID on the SuperCollider server!

get(control: str) → Any

Get a Synth argument

This will request the value from scsynth with /s_get(n).

Parameters:

controlstr

name of the Synth control argument

abstract seti(*args)

Set part of an arrayed control.

__getattr__(name)

__setattr__(name, value)

__repr__() → str

class sc3nb.sc_objects.node.Group(*, nodeid: int | None = None, new: bool = True, parallel: bool = False, add_action: AddAction = AddAction.TO_HEAD, target: Node | int | None = None, server: sc3nb.sc_objects.server.SCServer | None = None)

Bases: Node

Representation of a Group on SuperCollider.

Create a Python representation of a SuperCollider group.

Parameters:

nodeidint, optional

ID of the node in SuperCollider, by default sc3nb will create one. Can be set to an existing id to create a Python instance of a running Node.

newbool, optional

True if synth should be created on the server, by default True Should be False if creating an instance of a running Node.

parallelbool, optional

If True create a parallel group, by default False

add_actionAddAction or int, optional

Where the Group should be added, by default AddAction.TO_HEAD (0)

targetNode or int, optional

AddAction target, if None it will be the default group of the server

serverSCServer, optional

Server instance where this Group is located, by default use the SC default server

_server

Overview:

_update_group_state
new	Creates the synth on the server with g_new / p_new.
move_node_to_head	Move node to this groups head with g_head.
move_node_to_tail	Move node to this groups tail with g_tail.
free_all	Frees all nodes in the group with g_freeAll.
deep_free	Free all synths in this group and its sub-groups with g_deepFree.
dump_tree	Posts a representation of this group's node subtree with g_dumpTree.
query_tree	Send a g_queryTree message for this group.
_repr_pretty_
__repr__

_update_group_state(children: Sequence[Node] | None = None) → None

new(add_action=AddAction.TO_HEAD, target=None, *, parallel=None, return_msg=False) → Group | sc3nb.osc.osc_communication.OSCMessage

Creates the synth on the server with g_new / p_new.

Attention: Here you create an identical group! Same nodeID etc. - This will fail if there is already this nodeID on the SuperCollider server!

Parameters:

add_actionAddAction or int, optional

where the group should be added, by default AddAction.TO_HEAD (0)

targetNode or int, optional

add action target, by default 1

parallelbool, optional

If True use p_new, by default False

return_msgbool, optional

If ture return the OSCMessage instead of sending it, by default False

Returns:

Group

self

move_node_to_head(node, return_msg=False)

Move node to this groups head with g_head.

Parameters:

nodeNode

node to move

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

Group

self

move_node_to_tail(node, return_msg=False)

Move node to this groups tail with g_tail.

Parameters:

nodeNode

node to move

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

Group

self

free_all(return_msg=False)

Frees all nodes in the group with g_freeAll.

Parameters:

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

OSCMessage

if return_msg else self

deep_free(return_msg=False)

Free all synths in this group and its sub-groups with g_deepFree.

Sub-groups are not freed.

Parameters:

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

OSCMessage

if return_msg else self

dump_tree(post_controls=True, return_msg=False)

Posts a representation of this group’s node subtree with g_dumpTree.

Parameters:

post_controlsbool, optional

True for control values, by default False

return_msgbool, optional

If True return msg else send it directly, by default False

Returns:

OSCMessage

if return_msg else self

query_tree(include_controls=False) → Group

Send a g_queryTree message for this group.

See https://doc.sccode.org/Reference/Server-Command-Reference.html#/g_queryTree for details.

Parameters:

include_controlsbool, optional

True for control values, by default False

Returns:

tuple

/g_queryTree.reply

_repr_pretty_(printer, cylce)

__repr__() → str

class sc3nb.sc_objects.node.NodeTree(info: Sequence[Any], root_nodeid: int, controls_included: bool, start: int = 0, server: sc3nb.sc_objects.server.SCServer | None = None)

Node Tree is a class for parsing /g_queryTree.reply

controls_included

root_nodeid

Overview:

parse_nodes	Parse Nodes from reply of the /g_queryTree cmd of scsynth.
_repr_pretty_

static parse_nodes(info: Sequence[Any], controls_included: bool = True, start: int = 0, server: sc3nb.sc_objects.server.SCServer | None = None) → Tuple[int, Node]

Parse Nodes from reply of the /g_queryTree cmd of scsynth. This reads the /g_queryTree.reply and creates the corresponding Nodes in Python. See https://doc.sccode.org/Reference/Server-Command-Reference.html#/g_queryTree

Parameters:

controls_includedbool

If True the current control (arg) values for synths will be included

startint

starting position of the parsing, used for recursion, default 0

infoSequence[Any]

/g_queryTree.reply to be parsed.

Returns:

Tuple[int, Node]

postion where the parsing ended, resulting Node

_repr_pretty_(printer, cylce)