@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
-
// 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
-
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.
Documentation
Compatibility
Works on Node 10+
Source code is written in TypeScript and is usable in JavaScript es2018 or TypeScript projects.
Contribute
- Issue Tracker: https://github.com/crucialfelix/supercolliderjs/issues
- Source Code: https://github.com/crucialfelix/supercolliderjs
License
MIT license