Warning - Super Alpha Status: SuperSonic is currently in active development. The API is likely to change between releases. Feedback welcome!

A WebAssembly port of SuperCollider's scsynth audio synthesis engine for the browser. Runs in an AudioWorklet for real-time, high-priority audio processing with full OSC API support.

<script type="module">
  import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';

  const sonic = new SuperSonic({
    sampleBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/',
    synthdefBaseURL: 'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
  });

  await sonic.init();

  // Load a synthdef
  await sonic.loadSynthDefs(['sonic-pi-beep']);

  // Trigger the synth
  sonic.send('/s_new', 'sonic-pi-beep', -1, 0, 0, 'note', 60);

  // Load and play a sample
  sonic.send('/b_allocRead', 0, 'bd_haus.flac');
  sonic.send('/s_new', 'sonic-pi-basic_mono_player', -1, 0, 0, 'buf', 0);
</script>

Note: Requires specific HTTP headers (COOP/COEP) for SharedArrayBuffer support. See Browser Requirements below.

Via npm:

# Core engine only (~450KB)
npm install supersonic-scsynth

# Everything (engine + synthdefs + samples)
npm install supersonic-scsynth-bundle

Via CDN:

import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';

Pre-built distribution: Download the 'nightly' build (~35MB with all synthdefs and samples): https://samaaron.github.io/supersonic/supersonic-dist.zip

SuperSonic is split into multiple packages:

All synthdefs and samples are from Sonic Pi.

Creating an instance:

const sonic = new SuperSonic({
  sampleBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/',
  synthdefBaseURL: 'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/',
  audioPathMap: { /* optional custom path mappings */ }
});

Core methods:

• await sonic.init() - Initialize the audio engine
• await sonic.loadSynthDefs(names) - Load synth definitions
• sonic.send(address, ...args) - Send OSC message (types auto-detected)
• sonic.sendOSC(oscBytes, options) - Send pre-encoded OSC bytes

Callbacks:

• sonic.onInitialized - Called when ready
• sonic.onError(error) - Error handling
• sonic.onMessageReceived(msg) - Incoming OSC messages
• sonic.onMessageSent(oscData) - Outgoing OSC messages

Common OSC commands:

sonic.send('/notify', 1);                              // Enable notifications
sonic.send('/s_new', 'synth-name', -1, 0, 0);         // Create synth
sonic.send('/n_set', 1000, 'freq', 440.0, 'amp', 0.5); // Set parameters
sonic.send('/n_free', 1000);                            // Free node
sonic.send('/b_allocRead', 0, 'sample.flac');          // Load audio buffer

See SuperCollider Server Command Reference for the full OSC API.

Minimum browser versions:

• Chrome/Edge 92+
• Firefox 79+
• Safari 15.2+

Required features:

• SharedArrayBuffer (requires COOP/COEP headers)
• AudioWorklet
• WebAssembly with threads

Required HTTP headers: Your server must send these headers for SharedArrayBuffer support:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Resource-Policy: cross-origin

See example/server.rb for a reference implementation.

Prerequisites:

• Emscripten SDK
• esbuild

Build:

# Activate Emscripten
source ~/path/to/emsdk_env.sh

# Compile and bundle
./build.sh

Output goes to dist/ directory (~1.5MB WASM + ~76KB JS + workers).

Run demo:

ruby example/server.rb

Open http://localhost:8002/demo.html

Docker:

docker build -t supersonic .
docker run --rm -it -p 8002:8002 supersonic

When building from source or using local files:

dist/
├── supersonic.js                 # Main entry point (ES module)
├── wasm/
│   └── scsynth-nrt.wasm          # Audio engine (~1.5MB)
└── workers/
    ├── scsynth_audio_worklet.js  # AudioWorklet processor
    ├── osc_in_worker.js          # OSC input handler
    ├── osc_out_prescheduler_worker.js # OSC pre-scheduler (timers & tag cancellation)
    └── debug_worker.js           # Debug logger

The engine expects these files at ./dist/ relative to your HTML. Paths are currently not configurable.

GPL v3 - This is a derivative work of SuperCollider

Based on SuperCollider by James McCartney and the SuperCollider community. This AudioWorklet port was inspired by Hanns Holger Rutz who started the first port of scsynth to WASM and Dennis Scheiba who continued this work. Thank you to everyone in the SuperCollider community!