0.70.0 • Published 1 week ago

supersonic-scsynth

Licence

MIT

Version

0.70.0

Deps

Size

467 kB

Vulns

Weekly

Stars

206

Summary Dependency Versions

SuperSonic 0.70.0

SuperCollider's scsynth in the browser as an AudioWorklet.

Auto-generated from project docs — see GitHub for full documentation.

Quick Start
API Overview
Patterns
Constructor Options
Server Options
scsynth Command Quick Reference
Full Method Reference
Support + License

User Interaction

Web browsers have an autoplay policy that prevents websites from making sound without user consent. Audio can only start after a user interaction like a click, tap, or keypress.

This is why we use a boot button - calling init() from a button handler satisfies the browser's autoplay policy and allows audio to begin.

Creating a SuperSonic Instance

const supersonic = new SuperSonic({
  baseURL: "https://unpkg.com/supersonic-scsynth@latest/dist/",
  synthdefBaseURL: "https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/",
});

This creates a new SuperSonic instance configured to load assets from CDN. The baseURL tells SuperSonic where to find the WASM engine and workers. The synthdefBaseURL tells it where to find synthdef files when you call loadSynthDef(). The instance doesn't start the audio engine yet - it just sets up the configuration. You can pass additional options to configure transport mode, debug output, and scsynth engine settings (see API Reference).

Booting the Engine

await supersonic.init();

Calling init() boots the scsynth audio engine. Behind the scenes this:

Creates an AudioContext and AudioWorklet
Loads the WebAssembly module containing scsynth
Starts scsynth running in a dedicated high-priority audio thread

This is an async operation - the await ensures we don't proceed until the engine is ready.

Loading a Synth Definition

await supersonic.loadSynthDef("sonic-pi-prophet");

Before you can play a synth, you need to send its design to scsynth. This design is called a synth definition (or "synthdef") and is a recipe that describes a synth's audio graph - what oscillators, filters, and effects it uses and how they're connected.

SuperSonic comes with 127 ready-to-use synthdefs from Sonic Pi. Here we're loading sonic-pi-prophet, a warm polyphonic synth inspired by the Prophet-5.

Note: you can also use SuperCollider's Desktop app to design your own synthdefs and directly import them live at runtime into your SuperSonic session.

Triggering a Synth

supersonic.send("/s_new", "sonic-pi-prophet", -1, 0, 0, "note", 28, "release", 8, "cutoff", 70);

Now for the fun part - making sound! The send() method sends OSC (Open Sound Control) messages to scsynth. The /s_new command creates a new synth instance.

The arguments are:


synthdef name	`"sonic-pi-prophet"`	Which synth to create
node ID	`-1`	Let scsynth assign an ID automatically
add action	`0`	Add to the head of the target group
target	`0`	The root group
params...	`"note", 28, ...`	Name/value pairs for synth parameters

The synth parameters control the sound. Here we set note to 28 (a low E), release to 8 seconds, and cutoff to 70 (filter brightness). Each synthdef has its own parameters - see the synthdef documentation for available options.

We used -1 for the node ID here to let scsynth pick one for us. That's fine for fire-and-forget sounds, but if you need to control a synth after creating it - change its parameters, stop it, query it - you need to know its ID. That's where nextNodeId() comes in:

const id = supersonic.nextNodeId();
supersonic.send("/s_new", "sonic-pi-prophet", id, 0, 0, "note", 28, "release", 8, "cutoff", 70);

// Later — change the cutoff while it's playing
supersonic.send("/n_set", id, "cutoff", 100);

nextNodeId() is thread-safe - if you have multiple Web Workers sending OSC (see the Workers Guide), each one can allocate IDs independently, guaranteed unique with no clashes.

Working Example

See example/simple.html for a complete working example you can run locally, or example/simple_metrics.html for the same example with a live metrics dashboard.

Adding a Metrics Dashboard

SuperSonic includes a web component that renders a full metrics dashboard from the schema:

<link rel="stylesheet" href="https://unpkg.com/supersonic-scsynth@latest/dist/metrics-dark.css" />
<script type="module" src="https://unpkg.com/supersonic-scsynth@latest/dist/metrics_component.js"></script>

<supersonic-metrics id="metrics"></supersonic-metrics>

Connect it after boot to start live updates:

bootBtn.onclick = async () => {
  await supersonic.init();
  await supersonic.loadSynthDef("sonic-pi-prophet");
  document.getElementById("metrics").connect(supersonic, { refreshRate: 10 });
};

See Metrics Component for theming, layout control, and customisation.

API Overview

Coordinates WASM, AudioWorklet, SharedArrayBuffer, and IO Workers to run scsynth with low latency inside a web page.

Core

Member	Description
`init()`	Initialise the engine.
`shutdown()`	Shut down the engine.
`destroy()`	Destroy the engine completely.
`recover()`	Smart recovery — tries a quick resume first, falls back to full reload.
`suspend()`	Suspend the AudioContext and stop the drift timer.
`resume()`	Quick resume — calls purge to flush stale messages, resumes AudioContext, and resyncs timing.
`reload()`	Full reload — destroys and recreates the worklet and WASM, then restores all previously loaded synthdefs and audio buffers.
`reset()`	Shutdown and immediately re-initialise.
`send()`	Send any OSC message.
`sendOSC()`	Send pre-encoded OSC bytes to scsynth.
`sync()`	Wait for scsynth to process all pending commands.
`purge()`	Flush all pending scheduled OSC: clears the WASM BundleScheduler and the IN ring so nothing already in-flight will fire.

Asset Loading

Member	Description
`loadSynthDef()`	Load a SynthDef into scsynth.
`loadSynthDefs()`	Load multiple SynthDefs by name in parallel.
`loadSample()`	Load an audio sample into a scsynth buffer slot.
`sampleInfo()`	Get sample metadata (including content hash) without allocating a buffer.

Events

Member	Description
`on()`	Subscribe to an event.
`off()`	Unsubscribe from an event.
`once()`	Subscribe to an event once.
`removeAllListeners()`	Remove all listeners for an event, or all listeners entirely.

Node Tree

Member	Description
`getTree()`	Get the node tree in hierarchical format.
`getRawTree()`	Get the node tree in flat format with linkage pointers.
`getSnapshot()`	Get a diagnostic snapshot with metrics, node tree, and memory info.

Metrics

Member	Description
`getMetrics()`	Get current metrics as a named object.
`getMetricsArray()`	Get metrics as a flat Uint32Array for zero-allocation reading.
`getMetricsSchema()`	Get the metrics schema describing all available metrics.

Properties

Member	Description
`initialized`	Whether the engine has completed initialisation.
`initializing`	Whether init is currently in progress.
`audioContext`	The underlying AudioContext.
`node`	AudioWorkletNode wrapper for custom audio routing.

Advanced

Member	Description
`getInfo()`	Get engine info: sample rate, memory layout, capabilities, and version.
`createOscChannel()`	Create an OscChannel for direct worker-to-worklet communication.
`startCapture()`	Start capturing audio output to a buffer.
`stopCapture()`	Stop capturing and return the captured audio data.
`getCaptureFrames()`	Get number of audio frames captured so far.
`isCaptureEnabled()`	Check if audio capture is currently enabled.
`getMaxCaptureDuration()`	Get maximum capture duration in seconds.
`setClockOffset()`	Set clock offset for multi-system sync (e.g. Ableton Link, NTP server).

Advanced

Member	Description
`bufferConstants`	Buffer layout constants from the WASM build.
`initTime`	NTP time (seconds since 1900) when the AudioContext started.
`mode`	Active transport mode ('sab' or 'postMessage').
`ringBufferBase`	Ring buffer base offset in SharedArrayBuffer.
`sharedBuffer`	The SharedArrayBuffer (SAB mode) or null (postMessage mode).
`superClock`	Session-timeline service: tempo, beat origin, transport, NTP "now." See SuperClock for the full API surface.
`getEngineState()`	Returns the current engine lifecycle state.
`getLoadedBuffers()`	Get info about all loaded audio buffers.
`getSystemReport()`	Get a comprehensive system performance report.
`isRunning()`	Returns true if the engine has finished booting and is ready to send and receive messages.
`nextNodeId()`	Get the next unique node ID.
`getRawTreeSchema()`	Get schema describing the raw flat node tree structure.
`getTreeSchema()`	Get schema describing the hierarchical node tree structure.

OscChannel

OscChannel — unified dispatch for sending OSC to the AudioWorklet.

Obtain a channel via SuperSonic.createOscChannel on the main thread, then transfer it to a Web Worker for direct communication with the AudioWorklet.

Member	Description
`getCurrentNTP`	Set the NTP time source for classification (used in AudioWorklet context).
`mode`	Transport mode this channel is using.
`transferable`	Serializable config for transferring this channel to a worker via postMessage.
`transferList`	Array of transferable objects (MessagePorts) for the postMessage transfer list.
`close()`	Close the channel and release its ports.
`getAndResetMetrics()`	Get and reset local metrics (for periodic reporting).
`getMetrics()`	Get current metrics snapshot.
`nextNodeId()`	Get the next unique node ID.
`send()`	Send an OSC message: frames it onto the IN ring (SAB) or postMessages it to the worklet (PM).
`sendDirect()`	Alias of send — kept for callers that used the explicit direct path.
`fromTransferable()`	Reconstruct an OscChannel from data received via postMessage in a worker.

Example

// Main thread: create and transfer to worker
const channel = sonic.createOscChannel();
myWorker.postMessage(
  { channel: channel.transferable },
  channel.transferList,
);

// Inside worker: reconstruct and send
import { OscChannel } from 'supersonic-scsynth/osc-channel';
const channel = OscChannel.fromTransferable(event.data.channel);
channel.send(oscBytes);

Constructors

Constructor

new OscChannel(): OscChannel

Value	Meaning
`1`, `null`, `undefined`	Execute immediately
`[seconds, fraction]`	NTP uint32 pair — preserves full 64-bit precision
Number (e.g. `3913056000.5`)	NTP float — seconds since 1900 (fractional part encoded)

Message Type	Where It Goes	Why
Regular messages (not bundles)	Direct to AudioWorklet	No timing requirements
Immediate bundles (timetag 0 or 1)	Direct to AudioWorklet	Execute now
Near-future bundles (within 500ms)	Direct to AudioWorklet	Close enough to buffer
Late bundles (in the past)	Direct to AudioWorklet	Execute immediately
Far-future bundles (>500ms ahead)	Prescheduler	Hold until closer to execution time

Method	Description
`send(oscBytes)`	Send with automatic routing
`sendDirect(oscBytes)`	Force direct send (bypass prescheduler)
`classify(oscBytes)`	Get routing classification without sending
`close()`	Release resources

Property	Description
`mode`	`'sab'` or `'postMessage'`
`transferable`	Data for `postMessage` transfer
`transferList`	Transferable objects array
`getCurrentNTP`	(setter) Set NTP time source function for timestamp classification

Property	Type	Description	Required
`activityEvent?`	`ActivityLineConfig`	Line length limits for activity events emitted to listeners.
`audioContext?`	`AudioContext`	Provide your own AudioContext instead of letting SuperSonic create one.
`audioContextOptions?`	`AudioContextOptions`	Options passed to `new AudioContext()`. Ignored if `audioContext` is provided.
`autoConnect?`	`boolean`	Auto-connect the AudioWorkletNode to the AudioContext destination. Default: true.
`baseURL?`	`string`	Convenience shorthand when all assets (WASM, workers, synthdefs, samples) are co-located.	Yes*
`bufferGrowIncrement?`	`number`	Bytes to grow the buffer pool per growth event. Default: 32MB.
`coreBaseURL?`	`string`	Base URL for GPL assets: WASM and AudioWorklet (supersonic-scsynth-core package). Defaults to `baseURL`.
`debug?`	`boolean`	Enable all debug console logging. Default: false.
`debugOscIn?`	`boolean`	Log incoming OSC messages to console. Default: false.
`debugOscOut?`	`boolean`	Log outgoing OSC messages to console. Default: false.
`debugScsynth?`	`boolean`	Log scsynth debug output to console. Default: false.
`fetchMaxRetries?`	`number`	Max fetch retries when loading assets. Default: 3.
`fetchRetryDelay?`	`number`	Base delay between retries in ms (exponential backoff). Default: 1000.
`maxBufferMemory?`	`number`	Maximum buffer pool capacity in bytes. Pool grows on demand up to this limit. Default: 256MB.
`mode?`	`TransportMode`	Transport mode. - `'postMessage'` (default) — works everywhere, no special headers needed - `'sab'` — lowest latency, requires Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers See docs/MODES.md for a full comparison of communication modes.
`sampleBaseURL?`	`string`	Base URL for audio sample files (used by SuperSonic.loadSample).
`scsynthOptions?`	`ScsynthOptions`	Engine options passed to scsynth World_New().
`snapshotIntervalMs?`	`number`	How often to snapshot metrics/tree in postMessage mode (ms).
`synthdefBaseURL?`	`string`	Base URL for synthdef files (used by SuperSonic.loadSynthDef).
`wasmBaseURL?`	`string`	Base URL for WASM files. Defaults to `coreBaseURL + 'wasm/'`.
`wasmUrl?`	`string`	Full URL to the WASM binary. Overrides wasmBaseURL.
`workerBaseURL?`	`string`	Base URL for MIT worker scripts. Defaults to `baseURL + 'workers/'`.
`workletUrl?`	`string`	Full URL to the AudioWorklet script. Overrides `coreBaseURL`.

Property	Type	Description	Default	Range
`bufLength?`	`128`	Audio buffer length — must be 128 (WebAudio API constraint).	128	128 (fixed)
`loadGraphDefs?`	`0` \| `1`	Auto-load synthdefs from disk: 0 or 1. Default: 0.	0	0–1
`maxGraphDefs?`	`number`	Max synth definitions. Default: 1024.	1024	1+
`maxNodes?`	`number`	Max synthesis nodes — synths + groups. Default: 1024.	1024	1+
`maxWireBufs?`	`number`	Max wire buffers for internal UGen routing. Default: 64.	64	1+
`memoryLocking?`	`boolean`	Memory locking — not applicable in browser. Default: false.	false	—
`numAudioBusChannels?`	`number`	Audio bus channels for routing between synths. Default: 128.	128	1+
`numBuffers?`	`number`	Max audio buffers (1–65535). Default: 1024.	1024	1–65535
`numControlBusChannels?`	`number`	Control bus channels for control-rate data. Default: 4096.	4096	1+
`numInputBusChannels?`	`number`	Hardware input channels. Default: 2 (stereo).	2	0+
`numOutputBusChannels?`	`number`	Hardware output channels (1–128). Default: 2 (stereo).	2	1–128
`numRGens?`	`number`	Random number generators per synth. Default: 64.	64	1+
`preferredSampleRate?`	`number`	Preferred sample rate. 0 = use AudioContext default (typically 48000).	0	0, 8000–384000
`realTime?`	`boolean`	Clock source. Always false in SuperSonic (externally clocked by AudioWorklet).	false	—
`realTimeMemorySize?`	`number`	Real-time memory pool in KB for synthesis allocations. Default: 8192 (8MB).	8192	1+
`verbosity?`	`number`	Debug verbosity: 0 = quiet, 1 = errors, 2 = warnings, 3 = info, 4 = debug.	0	0–4

Command	Description
Top-Level
`/notify`	Register for node event notifications
`/status`	Query server status (UGens, synths, CPU)
`/sync`	Wait for async commands to complete
`/version`	Query server version info
`/rtMemoryStatus`	Query realtime memory usage
Synth Definitions
`/d_recv`	Load a synthdef from binary data
`/d_free`	Free loaded synthdefs by name
Nodes
`/n_free`	Delete nodes
`/n_run`	Turn nodes on or off
`/n_set`	Set node control values
`/n_setn`	Set sequential control values
`/n_fill`	Fill controls with a single value
`/n_map`	Map controls to control buses
`/n_mapn`	Map sequential controls to control buses
`/n_mapa`	Map controls to audio buses
`/n_mapan`	Map sequential controls to audio buses
`/n_before`	Move node before another
`/n_after`	Move node after another
`/n_query`	Query node info
`/n_trace`	Debug trace node execution
`/n_order`	Reorder nodes within a group
Synths
`/s_new`	Create a new synth
`/s_get`	Get synth control values
`/s_getn`	Get sequential synth control values
`/s_noid`	Remove synth ID tracking
Groups
`/g_new`	Create a new group
`/p_new`	Create a parallel group
`/g_head`	Move node to head of group
`/g_tail`	Move node to tail of group
`/g_freeAll`	Free all nodes in group
`/g_deepFree`	Recursively free all synths in group
`/g_dumpTree`	Print group tree (debug)
`/g_queryTree`	Query group tree structure
Buffers
`/b_alloc`	Allocate an empty buffer
`/b_allocRead`	Allocate buffer and load audio file
`/b_allocReadChannel`	Allocate buffer and load specific channels
`/b_free`	Free a buffer
`/b_zero`	Zero buffer contents
`/b_set`	Set individual samples
`/b_setn`	Set sequential samples
`/b_fill`	Fill samples with a value
`/b_gen`	Generate buffer contents (sine, cheby, etc.)
`/b_query`	Query buffer info
`/b_get`	Get sample values
`/b_getn`	Get sequential sample values
Control Buses
`/c_set`	Set control bus values
`/c_setn`	Set sequential bus values
`/c_fill`	Fill buses with a value
`/c_get`	Get bus values
`/c_getn`	Get sequential bus values
SuperSonic Extensions
`/b_allocFile`	Load audio from inline file data (SuperSonic only)

Notation	Type	Description
`int`	Integer	32-bit signed integer
`float`	Float	32-bit floating point
`double`	Double	64-bit floating point
`string`	String	Null-terminated string
`bytes`	Blob	Binary data (byte array)

Value	Action	Description
0	head	Add to head of target group
1	tail	Add to tail of target group
2	before	Add before target node
3	after	Add after target node
4	replace	Replace target node

Command	Reason
`/clearSched`	Use `cancelAll()` or the fine-grained `cancelTag()`, `cancelSession()`, `cancelSessionTag()` methods instead
`/error`	SuperSonic always enables error notifications so you never miss a `/fail` message
`/quit`	Use `destroy()` to shut down the SuperSonic instance

Command	Status
`/cmd`	No commands currently registered
`/u_cmd`	No UGens currently define commands

Parameter	Type	Description
`bufnum`	`number`	Buffer slot number (0 to numBuffers-1)
`source`	`string` \| `ArrayBuffer` \| `ArrayBufferView`<`ArrayBufferLike`> \| `Blob`	Sample path/URL, raw bytes, or File/Blob
`startFrame?`	`number`	First frame to read (default: 0)
`numFrames?`	`number`	Number of frames to read (default: 0 = all)

Parameter	Type	Description
`event`	`E`	Event name
`callback`	`SuperSonicEventMap`[`E`]	The same function reference passed to on

Parameter	Type	Description
`event`	`E`	Event name
`callback`	`SuperSonicEventMap`[`E`]	Handler function (type-checked per event)

Command	Alternative
`/d_load`	`loadSynthDef()` or `/d_recv` with bytes
`/d_loadDir`	`loadSynthDefs()`
`/b_read`	`loadSample()`
`/b_readChannel`	`loadSample()`
`/b_write`	Not available
`/b_close`	Not available

Parameter	Type	Description
`options?`	{ `blocking?`: `boolean`; `sourceId?`: `number`; }	Channel options
`options.blocking?`	`boolean`	Whether sends block until the worklet reads the message
`options.sourceId?`	`number`	Numeric source ID (0 = main thread, 1+ = workers)

Event	Description
`audiocontext:interrupted`	AudioContext was interrupted (iOS-specific). Another app or system event took audio focus. Similar to suspended but triggered externally.
`audiocontext:resumed`	AudioContext resumed to 'running' state.
`audiocontext:statechange`	AudioContext state changed. State is one of: `'running'`, `'suspended'`, `'closed'`, or `'interrupted'`.
`audiocontext:suspended`	AudioContext was suspended (e.g. tab backgrounded, autoplay policy, iOS audio interruption). Show a restart UI and call `recover()` when the user interacts.
`buffer:pool:grown`	Buffer pool grew on demand. Fired when the initial pool was exhausted and a new segment was added.
`debug`	Debug text output from scsynth (e.g. synthdef compilation messages). Includes NTP timestamp and sequence number.
`destroy`	Engine has been destroyed. Only fired by `destroy()`, not by `shutdown()` or `reset()`. Last chance to clean up before all listeners are cleared.
`error`	Error from any component (worklet, transport, workers).
`in`	Decoded OSC message received from scsynth. Messages are plain arrays: `[address, ...args]`.
`in:html`	Pre-formatted HTML representation of an incoming OSC message with CSS classes for colorization. Only emitted when listeners are attached.
`in:osc`	Raw OSC bytes received from scsynth (before decoding). Includes NTP timestamps for timing analysis.
`in:text`	Pre-formatted text representation of an incoming OSC message. Only emitted when listeners are attached or debug logging is enabled.
`loading:complete`	An asset finished loading. Size is in bytes.
`loading:start`	An asset started loading. Type is `'wasm'`, `'synthdef'`, or `'sample'`.
`out`	Decoded OSC message sent to scsynth. Messages are plain arrays: `[address, ...args]`. Mirrors the `'in'` event for outgoing messages.
`out:html`	Pre-formatted HTML representation of an outgoing OSC message with CSS classes for colorization. Only emitted when listeners are attached.
`out:osc`	Raw OSC bytes sent to scsynth. Includes source worker ID, sequence number, and NTP timestamps.
`out:text`	Pre-formatted text representation of an outgoing OSC message. Only emitted when listeners are attached or debug logging is enabled.
`ready`	Fired when the engine is fully booted and ready to receive messages. Payload includes browser capabilities and boot timing.
`reload:complete`	Full reload completed.
`reload:start`	Full reload started (worklet and WASM will be recreated).
`resumed`	Audio resumed after a suspend (AudioContext was re-started). Emitted after `resume()` succeeds.
`setup`	Fired after init completes, before `'ready'`. Use for setting up groups, FX chains, and bus routing. Can be async — init waits for all setup handlers to resolve. Also fires after `recover()` triggers a `reload()`.
`shutdown`	Engine is shutting down. Fired by `shutdown()`, `reset()`, and `destroy()`.

Parameter	Type
`address`	`"/d_recv"`
`bytes`	`ArrayBuffer` \| `Uint8Array`<`ArrayBufferLike`>
`completionMessage?`	`ArrayBuffer` \| `Uint8Array`<`ArrayBufferLike`>

Parameter	Type
`address`	`"/s_new"`
`defName`	`string`
`nodeID`	`number`
`addAction`	`AddAction`
`targetID`	`number`
...`controls`	(`string` \| `number`)[]

Parameter	Type
`address`	`"/s_get"`
`nodeID`	`number`
...`controls`	(`string` \| `number`)[]

Parameter	Type
`address`	`"/s_getn"`
`nodeID`	`number`
`control`	`string` \| `number`
`count`	`number`

Parameter	Type
`address`	`"/n_set"`
`nodeID`	`number`
...`controls`	(`string` \| `number`)[]

Parameter	Type
`address`	`"/n_setn"`
`nodeID`	`number`
`control`	`string` \| `number`
`count`	`number`
...`values`	`number`[]

Parameter	Type
`address`	`"/n_fill"`
`nodeID`	`number`
`control`	`string` \| `number`
`count`	`number`
`value`	`number`

Parameter	Type
`address`	`"/n_run"`
...`pairs`	[`number`, `0` \| `1`, `...number[]`]

Parameter	Type
`address`	`"/n_before"`
...`pairs`	[`number`, `number`, `...number[]`]

Parameter	Type
`address`	`"/n_after"`
...`pairs`	[`number`, `number`, `...number[]`]

Parameter	Type
`address`	`"/n_order"`
`addAction`	`0` \| `1` \| `2` \| `3`
`targetID`	`number`
...`nodeIDs`	[`number`, `...number[]`]

Parameter	Type
`address`	`"/n_map"`
`nodeID`	`number`
...`mappings`	(`string` \| `number`)[]

Parameter	Type
`address`	`"/n_mapn"`
`nodeID`	`number`
...`mappings`	(`string` \| `number`)[]

Parameter	Type
`address`	`"/n_mapa"`
`nodeID`	`number`
...`mappings`	(`string` \| `number`)[]

Parameter	Type
`address`	`"/n_mapan"`
`nodeID`	`number`
...`mappings`	(`string` \| `number`)[]

Parameter	Type
`address`	`"/g_new"`
...`args`	[`number`, `AddAction`, `number`, `...number[]`]

Parameter	Type
`address`	`"/p_new"`
...`args`	[`number`, `AddAction`, `number`, `...number[]`]