supercolliderjs

server

Boot a server with options and connect

Arguments

options Object = {}

command line options for server

store Store = null

optional external Store to hold Server state

Server

Server - boots the SuperCollider synthesis server

SuperCollider comes with an executable called scsynth which can be communicated with via OSC.

The primary way to send raw OSC messages is with:

server.send.msg('/s_new', ['defName', 440])

and the responses can be subscribed to:

server.receive.subscribe(function(msg) function(msg) {  ...  });
instance

Supports server.send.msg() and server.send.bundle()

You can also subscribe to it and get the OSC messages and bundles that are being sent echoed to you for debugging purposes.

A subscribeable stream of OSC events received.

A subscribeable stream of STDOUT printed by the scsynth process.

A subscribeable stream of events related to the scsynth process. Used internally.

Holds the mutable server state including allocators and the node state watcher. If a parent stateStore is supplied then it will store within that.

The logger used to print messages to the console.

Arguments

options Object = undefined

command line options for scsynth

stateStore  = undefined

optional parent Store for allocators and node watchers

emit signals are deprecated and will be removed in 1.0 use instead server.{channel}.subscribe((event) => { })

Event Emitter emits: 'out' - stdout text from the server 'error' - stderr text from the server or OSC error messages 'exit' - when server exits 'close' - when server closes the UDP connection 'OSC' - OSC responses from the server

Format command line args for scsynth

not yet fully implemented

Boot the server

Start scsynth and establish a pipe connection to receive stdout and stderr.

Does not connect, so UDP is not yet ready for OSC communication.

listen for system events and emit: exit out error

quit

kill scsynth process TODO: should send /quit first for shutting files

Establish connection to scsynth via OSC socket

Send OSC message to server

Arguments

address String

OSC command string eg. /s_new which is referred to in OSC as the address

args Array

Wait for a single OSC response from server matching the supplied args.

This is for getting responses async from the server. The first part of the message matches the expected args, and the rest of the message contains the response.

The Promise fullfills with any remaining payload including in the message.

Arguments

matchArgs Array

osc message to match as a single array: [/done, /notify]

timeout int = 4000

in milliseconds before the Promise is rejected

Send an OSC command that expects a reply from the server, returning a Promise that resolves with the response.

This is for getting responses async from the server. The first part of the message matches the expected args, and the rest of the message contains the response.

Arguments

callAndResponse Object
 {
     call: ['/some_osc_msg', 1, 2],
     response: ['/expected_osc_response', 1, 2, 3]
 }```
timeout int = 4000

in milliseconds before rejecting the Promise

ServerPlus

Extends Server with methods for creating Synth, Group etc.

instance

Create a Synth on the server

Arguments

synthDef SynthDef
args Object = undefined
group ?Group
addAction number = undefined

Create a Group on the server

Arguments

group ?Group
addAction number = undefined

Compile multiple SynthDefs either from source or path. If you have more than one to compile then always use this as calling server.synthDef multiple times will start up multiple supercollider interpreters. This is harmless, but you do have a lot of icons bouncing in your dock.

Arguments

defs Object

An object with {defName: spec, ...} where spec is an object like {source: "SynthDef('noise', { ...})"} or {path: "./noise.scd"}

Load and compile a SynthDef from path and send it to the server.

Arguments

defName string
path string

Compile a SynthDef from supercollider source code and send it to the server.

Arguments

defName string
sourceCode string

Allocate a Buffer on the server.

Arguments

numFrames number
numChannels number = undefined

Allocate a Buffer on the server and load a sound file into it.

Problem: scsynth uses however many channels there are in the sound file, but the client (sclang or supercolliderjs) doesn't know how many there are.

Arguments

path string
numChannels number = undefined
startFrame number = undefined
numFramesToRead number = undefined

Allocate an audio bus.

Arguments

numChannels number = undefined

Allocate a control bus.

Arguments

numChannels number = undefined

Synth

scsynth Synth

See server.synth(...)

Group

scsynth Group

See server.group(...)

instance

Stop the Group and remove it from the play graph on the server.

Update control parameters on the Synth.

Arguments

settings Object

SynthDef

scsynth SynthDef

See server.synthDefs(...)

These are currently compiled using sclang, and the synthDefResult holds metadata about the compiled synthdef and the raw compiled bytes.

The SynthDef may have been compiled from a sourceCode string or compiled from a file at path.

Buffer

scsynth Buffer

See server.buffer(...) and server.readBuffer(...)

instance

Deallocate the Buffer, freeing memory on the server.

AudioBus

scsynth audio bus

See server.audioBus(...)

These bus numbers (ids) and numChannels are allocated here in the client. The server only gets bus ids for reading and writing to.

instance

Deallocate the AudioBus, freeing it for resuse.

ControlBus

scsynth control bus

See server.controlBus(...)

These bus numbers (ids) and numChannels are allocated here in the client. The server only gets bus ids for reading and writing to.

instance

Deallocate the ControlBus, freeing it for resuse.

node-watcher

Functions for watching scsynth's node lifecycle notifications.

Node states and metadata are stored in server.state, so most useful information can be retrieved from there.

These functions here are for registering callbacks.

Watch server OSC receive for any n_XXX messages:

  • n_go

  • n_end

  • n_on

  • n_off

  • n_move

  • n_info

Save all of the supplied info for the node and call any registered callbacks.

Initially there is no need to unwatch unless you are creating and discarding Server objects which can happen during testing.

TODO: add Server.destroy

Arguments

server Server

Call a function when the server sends an /n_go message One callback allowed per id and node The id is usually a context id but could be a random guid

Arguments

server Server
id String

unique id for this callback registration

nodeID int
handler Function

Returns a Promise that resolves when the server sends an /n_go message.

The id is usually a context id (dryadic) but could be any random guid. It can be anything you want to supply as long as it is unique.

Arguments

server Server
id String

unique id for this callback registration

nodeID int

Call a function when the server sends an /n_end message One callback allowed per id and node.

Arguments

server Server
id String

unique id for this callback registration

nodeID int
handler Function

Returns a Promise that resolves when the server sends an /n_end message.

The id is usually a context id but could be a random guid

Arguments

server Server
id string
nodeID number

Update values in the Server's node state registery.

This is for internal use.

Arguments

server Server
nodeID number
nodeState NodeStateType

map

Useful mapping functions from supercollider

Convert a MIDI note (1..127) to frequency.

Arguments

midiNote number

Convert frequency to MIDI note (1..127).

Arguments

freq number

Map a number from linear min/max to min/max.

Arguments

inMin number
inMax number
outMin number
outMax number
value number

Map a number from linear min/max to exponential min/max.

Arguments

inMin number
inMax number
outMin number
outMax number
value number

Map a number from exponential min/max to linear min/max.

Arguments

inMin number
inMax number
outMin number
outMax number
value number

Map an amplitude value (usually 0..1) to dB.

Arguments

amp number

Map dB to an amplitude value that can be used as a multiplier.

Arguments

db number

Returns a function that maps 0..1 input to the spec's minval..maxval with a linear curve.

Arguments

spec Object

Returns a function that maps 0..1 input to the spec's minval..maxval with an exponential curve. minval/maxval must not have oppositive signs -- ie. the output range must not cross zero.

Arguments

spec Object

Returns dB mapping function (DbFaderWarp)

Arguments

spec Object

Returns amp mapping function (FaderWarp)

Arguments

spec Object

Returns inverse of linear mapping function

Arguments

spec Object

Returns inverse of exponential mapping function

Arguments

spec Object

Returns inverse of dB mapping function (DbFaderWarp)

Arguments

spec Object

Returns inverse of amp mapping function (FaderWarp)

Arguments

spec Object

Returns the inverse mapping function for a spec, using the curve as defined by spec.warp

Arguments

value number
spec Object

Returns the mapping function for a spec, using the curve as defined by spec.warp

Arguments

value number
spec Object

msg

Functions that format OSC message arrays For OSC commands that have an asynchronous response the function returns a {call: response: } object to make it easy to map directly to a calling function.

Add actions for specifying relationship of newly adding node to its targetID

  • 0 add the new group to the the head of the group specified by the add target ID.

  • 1 add the new group to the the tail of the group specified by the add target ID.

  • 2 add the new group just before the node specified by the add target ID.

  • 3 add the new group 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.

Tell server to exit

Register to receive notifications from server

Asynchronous. Replies with /done /notify clientID. 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 in node IDs, bus indices, buffer numbers, etc.

Arguments

on int = 1

start or stop If argument is 1, server will remember your return address and send you notifications. 0 will stop sending notifications.

Query for server status.

Server replies with /status.reply

Execute a command defined by a UGen Plug-in

Arguments

command number
args MsgType = undefined

Dump incoming OSC messages to stdout

Arguments

code int = 1

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.

Notify when async commands have completed.

Replies with a /synced message when all asynchronous commands received before this one have completed. The reply will contain the sent unique ID.

Asynchronous. Replies with /synced ID .

Arguments

id int

a unique number identifying this command.

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

Enable/disable error message posting.

Arguments

on int = 1

Loads a file of synth definitions from a data buffer included in the message. Resident definitions with the same names are overwritten.

Asynchronous. Replies with /done.

Arguments

buffer Buffer

A node global datatype: new Buffer(array)

completionMsg Array = null

Load synth definition.

Loads a file of synth definitions. Resident definitions with the same names are overwritten. Asynchronous. Replies with /done.

Arguments

path String
completionMsg Array = null

Load a directory of synth definitions.

Asynchronous. Replies with /done.

Arguments

path String
completionMsg Array = null

Delete synth definition.

The definition is removed immediately, and does not wait for synth nodes based on that definition to end.

Arguments

defName String

Delete/free a node

Arguments

nodeID int

Stop/start a node from running

Save computation by turning a node (and its children) off but without removing it from the UGen graph

Arguments

nodeID int
on int = 1

binary boolean

Set a node's control value(s).

Takes a list of pairs of control indices and values and sets the controls to those values. If the node is a group, then it sets the controls of every node in the group.

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

I think this also takes [freq, 440]

Arguments

nodeID int
pairs Object|Array

[[key, value], ...] or {key: value, ...}

Set ranges of a node's control value(s).

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.

Arguments

nodeID int

-

valueSets Array = []

[[controlName|index, numValues, value1, ... valueN], ...]

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.

Arguments

nodeID int

-

triples Array = []

[[key, numValuesToFill, value], ...]

Map a node's controls to read from a bus.

Arguments

nodeID int

-

pairs  = []

[[controlName, busID], ...]

Map a node's controls to read from buses.

Takes a list of triples 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.

Arguments

nodeID int

-

triples Array = []

[[controlName|index, busID, numControlsToMap], ...]

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.

Arguments

nodeID int

-

pairs Array

[[controlName|index, audioBusID], ...]

Map a node's controls to read from audio buses.

Arguments

nodeID int

-

triples Array = []

[[controlName|index, audioBusID, numControlsToMap], ...]

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

Arguments

moveNodeID int

the node to move (A)

beforeNodeID int

the node to move A before

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

Arguments

moveNodeID int

the ID of the node to place (A)

afterNodeID int

the ID of the node after which the above is placed (B)

Get info about a node.

The server sends an /n_info message for each node to registered clients. See Node Notifications for the format of the /n_info message.

Arguments

nodeID int

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.

Arguments

nodeID int

Move and order a list of nodes.

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

Arguments

addAction int
targetID int
nodeIDs Array<int>

Create a new synth.

Create a new synth from a named, compiled and already loaded 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

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 /n_go, /n_end, /n_on, /n_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 linkGuides/NodeMessaging helpfile.

Arguments

args Object = []

key: a control index or name

  • value: 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.

defName string
nodeID number = undefined
addAction number = undefined
targetID number = undefined

Get control value(s).

Arguments

synthID int
controlNames Array<int|String>

index or names

Get ranges of control value(s).

Arguments

synthID int
controlName int|String

a control index or name

n int

number of sequential controls to get (M)

Auto-reassign synths' 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.

Arguments

synthIDs Array

Create a new group.

Create a new group and add it to the tree of nodes. There are four ways to add the group to the tree as determined by the add action argument

Arguments

nodeID int

new group ID

addAction int = AddActions.HEAD
targetID int = 0

Create a new parallel group. supernova only

Create a new parallel group and add it to the tree of nodes. Parallel groups are relaxed groups, their child nodes are evaluated in unspecified order. There are four ways to add the group to the tree as determined by the add action argument

Multiple groups may be created in one command by adding arguments. (not implemented here)

Arguments

groupID int

new group ID

addAction int = AddActions.HEAD

add action

targetID int = 0

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

Arguments

groupID int
nodeID int
rest ...int

more node IDs to also move to head

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

Arguments

groupID int
nodeID int
rest ...int

more node IDs to also move to tail

Frees all immediate children nodes in the group

Arguments

groupID int

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.

Arguments

groupID int

Post a representation of this group's node subtree to STDOUT

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.

Arguments

groupID int
dumpControlValues int = 0

if not 0 post current control (arg) values for synths to STDOUT

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:

param {int} - flag: if synth control values are included 1, else 0 param {int} nodeID - of the requested group param {int} - number of child nodes contained within the requested group then for each node in the subtree: param {int} nodeID - param {int} - number of child nodes contained within this node. If -1 this is a synth, if >=0 it's a group then, if this node is a synth: strongsymbol the SynthDef name for this node. then, if flag (see above) is true: param {int} - numControls for this synth (M) multiple: param {string|int} - control name or index param {float|String} value or control bus mapping symbol (e.g. 'c1')

N.B. The order of nodes corresponds to their execution order on the server. Thus child nodes (those contained within a group) are listed immediately following their parent. See the method Server:queryAllNodes for an example of how to process this reply.

Arguments

groupID int
dumpControlValues int = 0

if not 0 the current control (arg) values for synths will be included

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.

Arguments

nodeID int

-

uGenIndex int

unit generator index

command String

-

args Array = []

Allocates zero filled buffer to number of channels and samples.

Asynchronous. Replies with /done /b_alloc bufNum.

Arguments

bufferID int
numFrames int
numChannels int
completionMsg Array = null

(optional)

Allocate buffer space and read a sound file.

Allocates buffer to number of channels of file and number of samples requested, or fewer if sound file is smaller than requested. Reads sound file data from the given starting frame in the file. If the number of frames argument is less than or equal to zero, the entire file is read. Asynchronous. Replies with /done /b_allocRead bufNum.

Arguments

bufferID int
path String

name of a sound file.

startFrame int = 0

starting frame in file (optional. default = 0)

numFramesToRead int = -1

number of frames to read (optional. default = 0, see below)

completionMsg Array = null

(optional)

Allocate buffer space and read channels from a sound file.

As b_allocRead, but reads individual channels into the allocated buffer in the order specified. Asynchronous. Replies with /done /b_allocReadChannel bufNum.

Arguments

bufferID int

buffer number

path String

path name of a sound file

startFrame int

starting frame in file

numFramesToRead int

number of frames to read

channels Array<int>

source file channel indices

completionMsg Array = null

(optional)

Read sound file data into an existing buffer.

Reads sound file data from the given starting frame in the file and writes it to the given starting frame in the buffer. If number of frames is less than zero, the entire file is read.

If reading a file to be used by DiskIn ugen then you will want to set "leave file open" to one, otherwise set it to zero.

Asynchronous. Replies with /done /b_read bufNum.

Arguments

bufferID int
path String

path name of a sound file.

startFrame int = 0

starting frame in file (optional. default = 0)

numFramesToRead int = -1

number of frames to read (optional. default = -1, see below)

startFrameInBuffer int = 0

starting frame in buffer (optional. default = 0)

leaveFileOpen int = 0

leave file open (optional. default = 0)

completionMsg Array = null

(optional)

Read sound file channel data into an existing buffer.

As b_read, but reads individual channels in the order specified. The number of channels requested must match the number of channels in the buffer.

Asynchronous. Replies with /done /b_readChannel bufNum.

Arguments

bufferID int
path String

of a sound file

startFrame int = 0

starting frame in file

numFramesToRead int = -1

number of frames to read

startFrameInBuffer int = 0

starting frame in buffer

leaveFileOpen int = 0

leave file open

channels  = []

source file channel indexes

completionMsg Array = null

Write buffer contents to a sound file.

Not all combinations of header format and sample format are possible.

If number of frames is less than zero, all samples from the starting frame to the end of the buffer are written. If opening a file to be used by DiskOut ugen then you will want to set "leave file open" to one, otherwise set it to zero. If "leave file open" is set to one then the file is created, but no frames are written until the DiskOut ugen does so.

Asynchronous. Replies with /done /b_write bufNum.

Arguments

bufferID int
path String

path name of a sound file.

headerFormat String = 'aiff'

Header format is one of: "aiff", "next", "wav", "ircam"", "raw"

sampleFormat String = 'float'

Sample format is one of: "int8", "int16", "int24", "int32", "float", "double", "mulaw", "alaw"

numFramesToWrite int = -1

number of frames to write (optional. default = -1, see below)

startFrameInBuffer int = 0

starting frame in buffer (optional. default = 0)

leaveFileOpen int = 0

leave file open (optional. default = 0)

completionMsg Array = null

(optional)

Frees buffer space allocated for this buffer.

Asynchronous. Replies with /done /b_free bufNum.

Arguments

bufferID int
completionMsg Array = null

(optional)

Sets all samples in the buffer to zero.

Asynchronous. Replies with /done /b_zero bufNum.

Arguments

bufferID int
completionMsg Array = null

(optional)

Takes a list of pairs of sample indices and values and sets the samples to those values.

Arguments

bufferID int
pairs Array

[[frame, value], ...]

Set ranges of sample value(s).

Set contiguous ranges of sample indices to sets of values. For each range, the starting sample index is given followed by the number of samples to change, followed by the values.

Arguments

bufferID int
startFrame int
values  = []

Fill ranges of samples with a value

Set contiguous ranges of sample indices to single values. For each range, the starting sample index is given followed by the number of samples to change, followed by the value to fill. This is only meant for setting a few samples, not whole buffers or large sections.

Arguments

bufferID int
startFrame int
numFrames int
value float

Call a command to fill a buffer.

Plug-ins can define commands that operate on buffers. The arguments after the command name are defined by the command. The currently defined buffer fill commands are listed below in a separate section.

Asynchronous. Replies with /done /b_gen bufNum.

Arguments

bufferID int
command String
args Array = []

After using a buffer with DiskOut, close the soundfile and write header information.

Asynchronous. Replies with /done /b_close bufNum.

Arguments

bufferID int

Get buffer info.

Responds to the sender with a /b_info message with: multiple: param {int} bufferID param {int} - number of frames param {int} - number of channels param {float} sample rate

Arguments

bufferID int

Get sample value(s). Replies with the corresponding /b_set command.

Arguments

bufferID int

buffer number

framesArray Array

sample indices to return

Get ranges of sample value(s).

Get contiguous ranges of samples. Replies with the corresponding b_setn command. This is only meant for getting a few samples, not whole buffers or large sections.

Arguments

bufferID int
startFrame int

starting sample index

numFrames int

number of sequential samples to get (M)

Takes a list of pairs of bus indices and values and sets the buses to those values.

Arguments

pairs Array

[[busID, value], ...]

Set ranges of bus value(s).

Set contiguous ranges of buses to sets of values. For each range, the starting bus index is given followed by the number of channels to change, followed by the values.

Arguments

triples Array = []

[[firstBusID, numBussesToChange, value], ...]

Fill ranges of bus value(s).

Set contiguous ranges of buses to single values. For each range, the starting sample index is given followed by the number of buses to change, followed by the value to fill.

TODO: What is difference to c_setn ?

Arguments

triples Array = []

[[firstBusID, numBussesToChange, value], ...]

Get control bus values

Takes a bus ID and replies with the corresponding c_set command.

Arguments

busID Number

Get contiguous ranges of buses. Replies with the corresponding c_setn command.

Arguments

startBusIndex int

starting bus index

numBusses int

number of sequential buses to get (M)

End real time mode, close file. Not yet implemented on server

This message should be sent in a bundle in non real time mode. The bundle timestamp will establish the ending time of the file. This command will end non real time mode and close the sound file. Replies with /done.

lang

Boots an sclang interpreter, resolving options and connecting.

Arguments

commandLineOptions Object = {}

A dict of options to be merged into the loaded config. Command line options to be supplied to sclang --sclang=/some/path/to/sclang commandLineOptions.config - Explicit path to a yaml config file If undefined then it will look for config files in:

  • .supercollider.yaml

  • ~/.supercollider.yaml

SCLang

This class manages a supercollider language interpreter process and sends messages to and from it using STDIN / STDOUT.

SuperCollider comes with an executable called sclang which can be communicated with via stdin/stdout or via OSC.

instance

build args for sclang

  -d <path>                      Set runtime directory
  -D                             Enter daemon mode (no input)
  -g <memory-growth>[km]         Set heap growth (default 256k)
  -h                             Display this message and exit
  -l <path>                      Set library configuration file
  -m <memory-space>[km]          Set initial heap size (default 2m)
  -r                             Call Main.run on startup
  -s                             Call Main.stop on shutdown
  -u <network-port-number>       Set UDP listening port (default 57120)
  -i <ide-name>                  Specify IDE name (for enabling IDE-specific class code, default "none")
  -a                             Standalone mode

Arguments

options Object

makeSclangConfig

make sclang_config.yaml as a temporary file with the supplied values

This is the config file that sclang reads, specifying includePaths and excludePaths

Arguments

config Object

Start sclang executable as a subprocess.

sclang will compile it's class library, and this may result in syntax or compile errors. These errors are parsed and returned in a structured format.

Resolves with:

{dirs: [compiled directories]}

or rejects with:

{
  dirs: [],
  compileErrors: [],
  parseErrors: [],
  duplicateClasses: [],
  errors[],
  extensionErrors: [],
  stdout: 'compiling class library...etc.'
}

spawnProcess - starts the sclang executable

sets this.process adds state listeners

Arguments

execPath string

path to sclang

commandLineOptions object

options for the command line filtered with this.args so it will only include values that sclang uses.

sclangConfigOptions

Builds the options that will be written to the config file that is read by sclang If supercolliderjs-conf specifies a sclang_conf path then this is read and any includePaths and excludePaths are merged

throws error if config cannot be read

Arguments

options object = {}

supercolliderJs options

listen to events from process and pipe stdio to the stateWatcher

Arguments

subprocess ChildProcessType
listenToStdin boolean = undefined

write

Send a raw string to sclang to be interpreted callback is called after write is complete.

Arguments

chunk string
callback ?Function
noEcho boolean

storeSclangConf

Store the original configuration path so that it can be accessed by the modified Quarks methods to store into the correct conf file.

Interprets code in sclang and returns a Promise.

Arguments

code String

source code to evaluate

nowExecutingPath String

set thisProcess.nowExecutingPath for use in a REPL to evaluate text in a file and let sclang know what file it is executing.

asString Boolean

return result .asString for post window otherwise returns result as a JSON object

postErrors Boolean

call error.reportError on any errors which posts call stack, receiver, args, etc

getBacktrace Boolean

return full backtrace

executeFile

Arguments

filename string

SynthDefCompiler

Utility class to compile SynthDefs either from source code or by loading a path.

Stores metadata, watches path for changes and can resend on change. Can write compiled synthDefs to .scsyndef

instance

Returns an object with each compiled synthdef as a SynthDefResultType.

Arguments

defs Object

Compile SynthDefs and send them to the server.

Arguments

defs Object
server Server

Returns a Promise for a SynthDef result object: name, bytes, synthDesc

Arguments

sourceCode string
pathName ?string

Returns a Promise for a SynthDef result object: name, bytes, synthDesc

Arguments

sourcePath string

load configuration files and merge options into a final dict

Arguments

configPath String

explicit path to a yaml config file otherwise tries .supercollider.yaml ~/.supercollider.yaml

commandLineOptions Object
       a dict of options to be merged over the loaded config.
       eg. supplied command line options --sclang=/some/path/to/sclang

Boot a server with options and connect

Arguments

options Object = {}

command line options for server

store Store = null

optional external Store to hold Server state

SendOSC

Owned by the Server, this is an object that you call .msg or .bundle on to send OSC.

The Server subscribes to this and does the actual sending. You may also subscribe to this for debugging, logging or entertainment purposes.

instance

bundle

Note that in SuperCollider language a number is interpreted as relative seconds from 'now'; here is is interpreted as a unix timestamp. See deltaTimeTag

Arguments

time null|Number|Array|Date

null: now, immediately

  • Number: if less than 10000 then it is interpreted as number of seconds from now. It it is larger then it is interpreted as a unix timestamp in seconds

  • Array: [secondsSince1900Jan1, fractionalSeconds]

  • Date

packets Array

osc messages as [address, arg1, ...argN] or sub bundles as [{timeTag: , packets: }, ...]

Make NTP timetag array relative to the current time.

Arguments

delta Number
now Date

optional, default new Date

Subscribe to monitor OSC messages and bundles sent.

Events are: {type: msg|bundle: payload: Array}

Arguments

onNext Function
onError ?Function
onComplete ?Function

utils

OSC utilities

Convert full OSC message to a simple Array

Converts:

 {address: '/n_go',
   args:
    [ Object { type: 'integer', value: 1000 },
      Object { type: 'integer', value: 0 },
      Object { type: 'integer', value: -1 },
      Object { type: 'integer', value: 3 },
      Object { type: 'integer', value: 0 } ],
   oscType: 'message' }

to:

['/n_go', 1000, 0, -1, 3, 0]

Arguments

msg OSCMinMsgType

Format an object for osc-min message

Arguments

msg MsgType

Format an object for osc-min bundle

Arguments

time null|Number|Array|Date
  • null: now, immediately

  • number: unix timestamp in seconds

  • Array: [secondsSince1900Jan1, fractionalSeconds]

  • Date

packets Array

osc messages as [address, arg1, ...argN] or sub bundles as [{timeTag: , packets: }, ...]

Convert a timetag array to a JavaScript Date object in your local timezone.

Received OSC bundles that were converted with fromBuffer will have a timetag array: [secondsSince1970, fractionalSeconds]

That has an accuracy of 0.00000000023283 seconds or 2^32 per second or 4,294,979,169.35102864751106 per second.

Note that the sample rate for audio is usually only 44.1kHz.

timetagToDate reduces the accuracy but is useful for logging a human readable date.

Accuracy is reduced to milliseconds, but the returned Date object also has fractionalSecondsInt and fractionalSecondsFloat properties set.

Convert a JavaScript Date to a NTP timetag array [secondsSince1970, fractionalSeconds].

toBuffer already accepts Dates for timetags so you might not need this function. If you need to schedule bundles with sub-millisecond accuracy then you could use this to help assemble the NTP array.

Make NTP timetag array relative to the current time.

Arguments

seconds number

seconds relative to now

now ?number

JavaScript timestamp in milliseconds

ServerState

Holds state for a Server such as node/bus/buffer allocators, node status and SynthDefs compiled.

Server has this has as the property: server.state

Many of these functions are low-level accessors and allocators useful for building higher-level applications that are easier to use.

Each server is stored by its unique address, so multiple Servers can store state in the same global Store object.

instance

Arguments

server Server
store Store

optional parent Store to use.

Mutate a value or object in the server state.

Arguments

key String

top level key eg. nodeAllocator, controlBufAllocator

fn Function

will receive current state or an empty Map, returns the altered state.

Get current state value for the server using an array of keys.

Arguments

keys String

list of keys eg. ['NODE_WATCHER', 'n_go', 1000]

notSetValue any

default value to return if empty

Allocates a node ID to be used for making a synth or group

Allocate an audio bus.

Arguments

numChannels number = undefined

Allocate a control bus.

Arguments

numChannels number = undefined

Free a previously allocate audio bus

These require you to remember the channels and it messes it up if you free it wrong. will change to higher level storage.

Arguments

index int
numChannels int

Free a previously allocated control bus

These require you to remember the channels and it messes it up if you free it wrong. will change to higher level storage.

Arguments

index int
numChannels int

Allocate a buffer id.

Note that numChannels is specified when creating the buffer. This allocator makes sure that the neighboring buffers are empty.

Arguments

numConsecutive int = 1

consecutively numbered buffers are needed by VOsc and VOsc3.

Free a previously allocated buffer id.

Note that numChannels is specified when creating the buffer.

Arguments

index int
numConsecutive int

consecutively numbered buffers are needed by VOsc and VOsc3.

Store

A Store that holds a state tree. This is used by ServerState as its immutable memory storage.

Holds an Immutable.Map and offers functions to mutate sub-states in that tree, and stores the new state.

https://facebook.github.io/immutable-js/docs/#/Map

instance

Fetch the object at keys pass it to the function which mutates it and returns new sub state.

Arguments

keys Array<string>
fn Function

Fetch one part of the state, mutate it with the callback, which returns result, subState. Save the subState back into state and return the result.

Arguments

keys Array<string>
fn Function

allocators

A simple incrementing allocator used for nodeIds.

The return type is designed to be consistent with the block allocator and other mutating functions used by Server

Arguments

state int
initial int = 0

Create initial state for block allocator.

Arguments

initialSize int

eg. total numChannels

Allocates a contigious block of numbers.

Arguments

state Immutable.Map
blockSize int

number of numbers eg. numChannels

Return a previously allocated block back to the free list.

Defragments by merging with adjoining neighbors where possible

Arguments

state Immutable.Map
addr int
blockSize int

Reserve a block by re-writing the free list

Arguments

state Immutable.Map
addr int
blockSize int

Returns a list of the free blocks and their sizes.

Arguments

state Immutable.Map

Arguments

state Immutable.Map
addr int
blockSize int

Tests if a block encloses another block

Arguments

addr int

child block

size int
encBlock int

address of the potentially enclosing block being tested

encSize int

size of the potentially enclosing block being tested

Arguments

state Immutable.Map
addr int
blockSize int

Arguments

state Immutable.Map
addr int
blockSize int

Split a block into two or three parts.

addr/blockSize is the original block that is currently in state. splitAddr/splitSize is being removed from it (its being allocated) and the original free block will be resized

If splitAddr/splitSize is at the top or bottom edge then you get 2 parts. If in the middle then you get 3.

Arguments

state Immutable.Map
addr int
blockSize int
splitAddr int
splitSize int

Check that scsynth and sclang executables exist.

This can be called in a postInstall step for a package to inform the user if it can or cannot find scsynth and sclang.

Posts the options to console. Posts errors and any information it can find to help the user.

Arguments

checkSclang 
checkScsynth 

SCError

A custom error class that adds a data field for passing structured error data.

instance

Update message and data with additional information. Used when passing the error along but when you want to add additional contextual debugging information.

Arguments

message string
data Object

SCLangError

SCLangError - syntax errors while interpreting code, interpret code execution errors, and asynchronous errors.

Logger

A customized logging interface for supercollider.js

Has special colors for osc messages and for logging stdin/stdout traffic.

instance

Arguments

debug Boolean

Post all debugging calls to log. If false then only errors are posted.

echo Boolean

Echo stdin/stdout and osc traffic to console

log winston.Logger|undefined

Default is to use console.(log|error) but any object with a compatible API such as winston will work.

Log debugging information but only if this.debug is true

Arguments

text 

Log an error.

Arguments

text 

Log messages that were sent to stdin or sclang.

Arguments

text 

Log messages that were received from stdout of sclang/scsynth.

Arguments

text 

Log messages that were emitted from stderr of sclang/scsynth.

Arguments

text 

Log OSC messages sent to scsynth.

Arguments

text 

Log OSC messages received from scsynth.

Arguments

text