View Source SuperCollider.SoundServer.Command (SuperCollider v0.1.5)
This module is used to send Open Sound Control (OSC) commands to SuperCollider's server (scsynth or supernova) via UDP.
These commands make use of the server configuration and state details in %SoundServer{}, and is most cases, a %SoundServer{} struct is passed as the first parameter in these funtions.
For an official list of these commands, see: https://doc.sccode.org/Reference/Server-Command-Reference.html
structure-of-this-module
Structure of this module
The functions of this module are grouped into the following categories:
- scserver communication helper functions, such as to encode OSC messages and to send them to a scserver insrtance
- scserver commands, following the SuperCollider Server Synth Engine Command Reference:
- General Commands - such as for getting status or version information or quitting scynth/supernova.
- Node Commands - for manipulating nodes including freeing them
- Synth Commands - such as for sending or loading synth defs, and creating a new synth
- Group Commands
- Unit Generator Commands
- Buffer Commands
- Control Bus Commands
- Non Real Time Mode Commands
- Replies to Commands
- Node Notifications from Server
- Trigger Notification
- Buffer Fill Commands.
Note that this library uses the OSC style string format to send commands, rather than command numbers.
Link to this section Summary
OSC communication
Displays incoming OSC messages.
Takes an address and a list of optional arguments and encodes them as an OSC message.
The primary way to send commands to a scynth sound server.
Sends an encoded OSC message to the specified %SoundServer{}
via UDP.
Mainly used by send_osc/3
as a helper function.
General commands
Clear all scheduled bundles. Removes all bundles from the scheduling queue.
Send a plug-in defined command. Commands are defined by plug-ins.
Enable/disable error message posting.
Register to receive notifications from scserver.
Instructs scsynth to quit. Before exiting, scserver will reply to the sender with '/done'.
Query the servers status.
Notify when async commands have completed.
Query the SuperCollider version. Replies to sender with the following message
Synth commands
Deleted (removes) a synth definition.
Loads a file of synth definitions.
Loads a directory of synth definitions files.
Instructs the sound server (scsynth or supernova) to receive a synth definition file.
Get control value(s).
Get ranges of control value(s). Get contiguous ranges of controls. Replies to sender with the corresponding /n_setn command.
Create a new synth.
Auto-reassign synth's ID to a reserved value.
Node commands
Place a node after another.
Place a node before another.
Fill ranges of a node's control value(s).
Deletes a node. There is is also an alias to this function called free_node/2.
Map a node's controls to read from a bus.
Map a node's controls to read from an audio bus.
Map a node's controls to read from audio buses.
Map a node's controls to read from buses.
Move and order a list of nodes. Moves the listed nodes to the location specified by the target and add action, and place them in the order specified. Nodes which have already been freed will be ignored.
Get info about a node.
Turns a node on or off.
Set a node's control value(s).
Set ranges of a node's control value(s).
Trace a node.
Group commands
Free all synths in this group and all its sub-groups.
Post a representation of this group's node subtree.
Frees all nodes in the group. A list of groups may be specified.
Adds the node to the head (first to be executed) of the group.
Create a new group.
Get a representation of this group's node subtree.
Adds the node to the tail (last to be executed) of the group.
Create a new parallel group.
Unit generator commands
Send a command to a unit generator.
Link to this section OSC communication
Displays incoming OSC messages.
Turns on and off printing of the contents of incoming Open Sound Control messages. This is useful when debugging your command stream.
Accepts one of the following integers as the second parameter:
- 0 turn dumping OFF.
- 1 print the parsed contents of the message.
- 2 print the contents in hexadecimal.
- 3 print both the parsed and hexadecimal representations of the contents.
Takes an address and a list of optional arguments and encodes them as an OSC message.
Mainly used by send_osc/3
as a helper function.
The primary way to send commands to a scynth sound server.
For a given %SoundServer{}
, takes an adress an optional arguments, encodes them as OSC and sends them to the sound server via UDP.
This function makes use of the encode_osc/3
and send_to_sc/2
helper functions.
Sends an encoded OSC message to the specified %SoundServer{}
via UDP.
Mainly used by send_osc/3
as a helper function.
Link to this section General commands
Clear all scheduled bundles. Removes all bundles from the scheduling queue.
Send a plug-in defined command. Commands are defined by plug-ins.
This function takes:
- command name (String)
- any arguments (As a list []).
Enable/disable error message posting.
Turn on or off error messages sent to the SuperCollider post window. Useful when sending a message, such as /n_free, whose failure does not necessarily indicate anything wrong.
Takes an integer as the second parameter:
- 0 turn off error posting until the next ['/error', 1] message.
- 1 turn on error posting.
For convenience of client-side methods, you can also suppress errors temporarily, for the scope of a single bundle. To do that use the following codes:
- -1 turn off locally in the bundle -- error posting reverts to the "permanent" setting for the next message or bundle.
- -2 turn on locally in the bundle.
These "temporary" states accumulate within a single bundle -- so if you have nested calls to methods that use bundle-local error suppression, error posting remains off until all the layers have been unwrapped. If you use ['/error', -1] within a self-bundling method, you should always close it with ['/error', -2] so that subsequent bundled messages will take the correct error posting status. However, even if this is not done, the next bundle or message received will begin with the standard error posting status, as set by modes 0 or 1.
Temporary error suppression may not affect asynchronous commands in every case.
Register to receive notifications from scserver.
Takes two optional parameters:
- flag: this is an integer with either:
- 1 to receive notifications (default): the server will remember your return address and send you notifications
- 0 to stop receiving them: scserver will stop sending notifications.
- client_id: an integer representing the client. This is optional.
From SuperCollider documentation:
Replies to sender with /done /notify clientID [maxLogins] when complete.
If this client has registered for notifications before, this may be the same ID. Otherwise it will be a new one.
Clients can use this ID in multi-client situations to avoid conflicts when allocating resources such as node IDs, bus indices, and buffer numbers.
maxLogins is only returned when the client ID argument is supplied in this command. maxLogins is not supported by supernova.
Instructs scsynth to quit. Before exiting, scserver will reply to the sender with '/done'.
Query the servers status.
Replies to sender with an '/status.reply' message with a list containing the following:
int
1. unused.int
number of unit generators.int
number of synths.int
number of groups.int
number of loaded synth definitions.float
average percent CPU usage for signal processingfloat
peak percent CPU usage for signal processingdouble
nominal sample ratedouble
actual sample rate
Notify when async commands have completed.
Takes an unique integer identifying this command as the second parameter.
Replies with a /synced message when all asynchronous commands received before this one have completed. The reply will contain the sent unique ID.
Query the SuperCollider version. Replies to sender with the following message:
string
Program name. May be "scsynth" or "supernova".int
Major version number. Equivalent to sclang's Main.scVersionMajor.int
Minor version number. Equivalent to sclang's Main.scVersionMinor.string
Patch version name. Equivalent to the sclang code "." ++ Main.scVersionPatch ++ Main.scVersionTweak.string
Git branch name.string
First seven hex digits of the commit hash.
Link to this section Synth commands
Deleted (removes) a synth definition.
The second parameter is a string representing the name of the synth.
The definition is removed immediately, and does not wait for synth nodes based on that definition to end.
Loads a file of synth definitions.
The second and third parameter are:
- pathname of the file (string). Can be a pattern like "synthdefs/perc-*"
- OSC message to execute upon completion. (optional)
Replies to sender with /done when complete.
Loads a directory of synth definitions files.
The second and third parameter are:
- pathname of the directory (string)
- OSC message to execute upon completion. (optional)
Replies to sender with /done when complete.
Instructs the sound server (scsynth or supernova) to receive a synth definition file.
This function takes as it's second and third parameter:
- bytes of data which contain the file of synth definition(s)
- OSC message to execute upon completion (optional).
Replies to sender with /done when complete.
Get control value(s).
Second parameter is the synth id (integer). The third parameter is the control identifier, which can either be an integer id or a string name.
Replies to sender with the corresponding /n_set command.
Get ranges of control value(s). Get contiguous ranges of controls. Replies to sender with the corresponding /n_setn command.
s_new(soundserver, synth_def_name, synth_id, add_action_code, add_target_id, control_args \\ [])
View SourceCreate a new synth.
Create a new synth from a synth definition, give it an ID, and add it to the tree of nodes. There are four ways to add the node to the tree as determined by the add action argument which is defined as follows:
Parameters:
- string synth definition name
- int synth ID
- int add action (0,1,2, 3 or 4 see below)
- int add target ID
- N *
- int or string a control index or name
- float or int or string floating point and integer arguments are interpreted as control value. a symbol argument consisting of the letter 'c' or 'a' (for control or audio) followed by the bus's index.
add actions:
- 0 add the new node to the head of the group specified by the add target ID.
- 1 add the new node to the tail of the group specified by the add target ID.
- 2 add the new node just before the node specified by the add target ID.
- 3 add the new node just after the node specified by the add target ID.
- 4 the new node replaces the node specified by the add target ID. The target node is freed.
Controls may be set when creating the synth. The control arguments are the same as for the n_set command.
If you send /s_new with a synth ID of -1, then the server will generate an ID for you. The server reserves all negative IDs. Since you don't know what the ID is, you cannot talk to this node directly later. So this is useful for nodes that are of finite duration and that get the control information they need from arguments and buses or messages directed to their group. In addition no notifications are sent when there are changes of state for this node, such as /go, /end, /on, /off.
If you use a node ID of -1 for any other command, such as /n_map, then it refers to the most recently created node by /s_new (auto generated ID or not). This is how you can map the controls of a node with an auto generated ID. In a multi-client situation, the only way you can be sure what node -1 refers to is to put the messages in a bundle.
This message now supports array type tags ($[ and $]) in the control/value component of the OSC message. Arrayed control values are applied in the manner of n_setn (i.e., sequentially starting at the indexed or named control). See the Node Messaging helpfile: https://doc.sccode.org/Guides/NodeMessaging.html
Auto-reassign synth's ID to a reserved value.
This command is used when the client no longer needs to communicate with the synth and wants to have the freedom to reuse the ID. The server will reassign this synth to a reserved negative number. This command is purely for bookkeeping convenience of the client. No notification is sent when this occurs.
Link to this section Node commands
Place a node after another.
Places node A in the same group as node B, to execute immediately after node B.
Place a node before another.
Places node A in the same group as node B, to execute immediately before node B.
Fill ranges of a node's control value(s).
Set contiguous ranges of control indices to single values. For each range, the starting control index is given followed by the number of controls to change, followed by the value to fill.
If the node is a group, then it sets the controls of every node in the group.
Deletes a node. There is is also an alias to this function called free_node/2.
From the SuperCollider docs:
Stops a node abruptly, removes it from its group, and frees its memory. A list of node IDs may be specified. Using this method can cause a click if the node is not silent at the time it is freed.
Takes the node id (integer) to delete as the second parameter.
Map a node's controls to read from a bus.
Takes a list of pairs of control names or indices and bus indices and causes those controls to be read continuously from a global control bus. If the node is a group, then it maps the controls of every node in the group. If the control bus index is -1 then any current mapping is undone.
Any n_set, n_setn and n_fill command will also unmap the control.
Map a node's controls to read from an audio bus.
Takes a list of pairs of control names or indices and audio bus indices and causes those controls to be read continuously from a global audio bus. If the node is a group, then it maps the controls of every node in the group. If the audio bus index is -1 then any current mapping is undone. Any n_set, n_setn and n_fill command will also unmap the control. For the full audio rate signal, the argument must have its rate set to \ar.
Map a node's controls to read from audio buses.
Takes a list of triplets of control names or indices, audio bus indices, and number of controls to map and causes those controls to be mapped sequentially to buses. If the node is a group, then it maps the controls of every node in the group. If the audio bus index is -1 then any current mapping is undone. Any n_set, n_setn and n_fill command will also unmap the control. For the full audio rate signal, the argument must have its rate set to \ar.
Map a node's controls to read from buses.
Takes a list of triplets of control names or indices, bus indices, and number of controls to map and causes those controls to be mapped sequentially to buses. If the node is a group, then it maps the controls of every node in the group. If the control bus index is -1 then any current mapping is undone. Any n_set, n_setn and n_fill command will also unmap the control.
n_order(soundserver, add_action_code, add_target_id, node_ids \\ [])
View SourceMove and order a list of nodes. Moves the listed nodes to the location specified by the target and add action, and place them in the order specified. Nodes which have already been freed will be ignored.
The second, third and fourth parameters are:
int
add action (0,1,2 or 3 see below)int
add target IDN * int
node IDs
add actions are as follows:
- 0 construct the node order at the head of the group specified by the add target ID.
- 1 construct the node order at the tail of the group specified by the add target ID.
- 2 construct the node order just before the node specified by the add target ID.
- 3 construct the node order just after the node specified by the add target ID.
Get info about a node.
The server sends an /n_info message for each node to registered clients. See Node Notifications below for the format of the /n_info message.
Turns a node on or off.
Takes a node id (integer) as the second parameter and a run flag (integer) as the third.
If the run flag set:
- to zero then the node will not be executed.
- back to one, then it will be executed.
Note that using this method to start and stop nodes can cause a click if the node is not silent at the time run flag is toggled.
Set a node's control value(s).
If the node is a group, then it sets the controls of every node in the group.
The second parameter is the node id (integer).
The third parameter takes a list of pairs of control indices and values and sets the controls to those values.
This message supports array type tags ($[ and $]) in the control/value component of the OSC message. Arrayed control values are applied in the manner of n_setn (i.e., sequentially starting at the indexed or named control).
Set ranges of a node's control value(s).
From the SuperCollider documentation: Set contiguous ranges of control indices to sets of values. For each range, the starting control index is given followed by the number of controls to change, followed by the values. If the node is a group, then it sets the controls of every node in the group.
Takes a node id (integer) as it's second parameter.
Trace a node.
Causes a synth to print out the values of the inputs and outputs of its unit generators for one control period. Causes a group to print the node IDs and names of each node in the group for one control period.
Link to this section Group commands
Free all synths in this group and all its sub-groups.
Traverses all groups below this group and frees all the synths. Sub-groups are not freed.
A list of groups may be specified.
Post a representation of this group's node subtree.
Posts a representation of this group's node subtree, i.e. all the groups and synths contained within it, optionally including the current control values for synths.
For the flag code: if not 0 the current control (arg) values for synths will be posted.
Frees all nodes in the group. A list of groups may be specified.
Adds the node to the head (first to be executed) of the group.
Create a new group.
Get a representation of this group's node subtree.
Request a representation of this group's node subtree, i.e. all the groups and synths contained within it. Replies to the sender with a /g_queryTree.reply message listing all of the nodes contained within the group in the following format: https://doc.sccode.org/Reference/Server-Command-Reference.html#/g_queryTree
Adds the node to the tail (last to be executed) of the group.
Create a new parallel group.
Link to this section Unit generator commands
Send a command to a unit generator.
Sends all arguments following the command name to the unit generator to be performed. Commands are defined by unit generator plug ins.