@supercollider/server NPM

@supercollider/server

Client library for the SuperCollider scsynth audio engine

scsynth features

scsynth is SuperCollider's synthesis server.

High quality accurate and efficient audio engine
Fully adjustable sample rate (192k+) and block size
32-bit float signal chain
Sampling buffers use 64-bit float
Fast and fluid control rate modulation
Communicates via Open Sound Control - TCP/UDP network communication
Hundreds of UGens (unit generators)
Simple ANSI C plugin API
Hundreds more community contributed UGens
Supports any number of input and output channels, ideal for large multichannel setups

@supercollider/server Features

This package supports all the core functionality for working with scsynth:

Spawns the synthesis server, scsynth as a subprocess
Send and receive OSC messages
Comprehensive support for constructing and sending all commands the server understands
Call async commands on the server and receive results as Promises
Synth/Group/Bus/Buffer allocators with clean immutable state implementation
Immutable server state and synth/group tracking
Just-in-time OSC scheduler

You can install this lib separately from supercolliderjs, but currently to compile SynthDefs you need to write them in SuperCollider code and use @supercollider/lang to compile those.

Examples

Server low level API

const sc = require('supercolliderjs');

sc.server.boot().then(async server => {

  // Really low level, using explicit hard coded node ids
  // and manually building the message.
  // You don't want to do this.
  server.send.msg('/g_new', [ 9999 ] );

  // Use node id allocator and OSC message constructors.
  // Still tedidous and error prone.
  // No notification of when the group is created on the server.
  const groupNodeID = server.state.nextNodeID();
  server.send.msg(sc.server.msg.groupNew(groupNodeID));

  // @supercollider/server-plus adds these methods:
  // Create a group and wait for confirmation. Nice and simple
  const group = await server.group();

});

The @supercollider/server-plus package extends the Server class, adding extra methods. It is one way of working. @supercollider/dryads are another higher level api for working.

You can also build your own way of working if you like—all the packages expose low level functions so you can reuse them in different projects.

API

boot Start the server process and connect to it.

  // options: ServerArgs
 sc.server.boot({device: 'Soundflower (2ch)'});

ServerArgs This is the union of ServerSettings and ScsynthArgs
Server
```
// options: ServerArgs
const server = new sc.server.Server(options);
```
- boot Starts the server process scsynth and establish a pipe connection to receive stdout and stderr. Does not connect, so UDP is not yet ready for OSC communication.
- connect Establish connection to scsynth via OSC socket
- send
```
server.send.msg('/s_new', ['defName', 440]);
server.send.bundle(0.05, [
  ['/s_new', 'defName', 440],
  ['/s_new', 'defName', 880],
]);
```
- receive A subscribeable stream of OSC events received.
```
server.receive.subscribe(function(msg) {
  console.log(msg);
});
```
- callAndResponse
  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.
```
  await server.callAndResponse(sc.server.msg.defLoadDir("./synthdefs/"));
```
- stdout A subscribeable stream of STDOUT printed by the scsynth process.
```
server.stdout.subscribe(function(msg) {
  console.log(msg);
});
```
- quit
```
await server.quit();
```

msg Functions for building all OSC messages for scsynth.
mapping Frequently used musical mapping functions ported from SuperCollider.
ServerState Holds internal state for a Server such as node/bus/buffer allocators, node status and SynthDefs that have been compiled and sent. 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.
This is where all state is stored for node, buffer and bus allocators, as well as node state tracking (is a Synth playing or not). The nice thing about this design is that the new state is only committed if no Exception is thrown.