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 ranges of control value(s). Get contiguous ranges of controls. Replies to sender with the corresponding /n_setn command.

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

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.

Get a representation of this group's node subtree.

Adds the node to the tail (last to be executed) of the group.

Link to this section OSC communication

Link to this function

dump_osc(soundserver, code)

View Source

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.
Link to this function

encode_osc(address, arguments \\ [])

View Source

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.

Link to this function

send_osc(soundserver, address, arguments \\ [])

View Source

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.

Link to this function

send_to_sc(soundserver, osc_message)

View Source

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

Link to this function

clear_sched(soundserver)

View Source

Clear all scheduled bundles. Removes all bundles from the scheduling queue.

Link to this function

cmd(soundserver, command_name, arguments \\ [])

View Source

Send a plug-in defined command. Commands are defined by plug-ins.

This function takes:

  • command name (String)
  • any arguments (As a list []).
Link to this function

error(soundserver, mode)

View Source

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.

Link to this function

notify(soundserver, flag \\ 1, client_id \\ nil)

View Source

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 processing
  • float peak percent CPU usage for signal processing
  • double nominal sample rate
  • double actual sample rate
Link to this function

sync(soundserver, command_code)

View Source

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

Link to this function

d_free(soundserver, synth_def_name)

View Source

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.

Link to this function

d_load(soundserver, path, completion_message \\ nil)

View Source

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.

Link to this function

d_load_dir(soundserver, path, completion_message \\ nil)

View Source

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.

Link to this function

d_recv(soundserver, data, completion_message \\ nil)

View Source

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.

Link to this function

s_get(soundserver, synth_id, control_name)

View Source

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.

Link to this function

s_getn(soundserver, synth_id, control_name)

View Source

Get ranges of control value(s). Get contiguous ranges of controls. Replies to sender with the corresponding /n_setn command.

Link to this function

s_new(soundserver, synth_def_name, synth_id, add_action_code, add_target_id, control_args \\ [])

View Source

Create 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

Link to this function

s_noid(soundserver, synth_ids)

View Source

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

Link to this function

n_after(soundserver, node_a_id, node_b_id)

View Source

Place a node after another.

Places node A in the same group as node B, to execute immediately after node B.

Link to this function

n_before(soundserver, node_a_id, node_b_id)

View Source

Place a node before another.

Places node A in the same group as node B, to execute immediately before node B.

Link to this function

n_fill(soundserver, node_id, args \\ [])

View Source

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.

Link to this function

n_free(soundserver, node_id)

View Source

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.

Link to this function

n_map(soundserver, node_id, args \\ [])

View Source

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.

Link to this function

n_mapa(soundserver, node_id, args \\ [])

View Source

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.

Link to this function

n_mapan(soundserver, node_id, args \\ [])

View Source

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.

Link to this function

n_mapn(soundserver, node_id, args \\ [])

View Source

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.

Link to this function

n_order(soundserver, add_action_code, add_target_id, node_ids \\ [])

View Source

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.

The second, third and fourth parameters are:

  • int add action (0,1,2 or 3 see below)
  • int add target ID
  • N * 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.
Link to this function

n_query(soundserver, node_id)

View Source

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.

Link to this function

n_run(soundserver, node_id, run_flag)

View Source

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.

Link to this function

n_set(soundserver, node_id, args \\ [])

View Source

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

Link to this function

n_setn(soundserver, node_id, args \\ [])

View Source

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.

Link to this function

n_trace(soundserver, node_id)

View Source

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

Link to this function

g_deep_free(soundserver, group_id)

View Source

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.

Link to this function

g_dump_tree(soundserver, group_id, flag_code \\ 1)

View Source

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.

Link to this function

g_free_all(soundserver, group_id)

View Source

Frees all nodes in the group. A list of groups may be specified.

Link to this function

g_head(soundserver, node_id, group_id, node_id)

View Source

Adds the node to the head (first to be executed) of the group.

Link to this function

g_new(soundserver, node_id, add_action_id, target_node_id)

View Source

Create a new group.

Link to this function

g_query_tree(soundserver, group_id, flag_code \\ 1)

View Source

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

Link to this function

g_tail(soundserver, node_id, group_id, node_id)

View Source

Adds the node to the tail (last to be executed) of the group.

Link to this function

p_new(soundserver, node_id, add_action_id, target_node_id)

View Source

Create a new parallel group.

Link to this section Unit generator commands

Link to this function

u_cmd(soundserver, node_id, ug_index, command_name, args \\ [])

View Source

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.

Link to this section Functions

Link to this function

dump_OSC(soundserver, code)

View Source
Link to this function

free_node(soundserver, node_id)

View Source
Link to this function

synth(soundserver, attr \\ [])

View Source