Note: Still Alpha Status: SuperSonic is in active development. The API may continue to evolve, but the core synthesis engine is solid and ready for experimentation. Feedback and ideas are most welcome.
░█▀▀░█░█░█▀█░█▀▀░█▀▄░█▀▀░█▀█░█▀█░▀█▀░█▀▀
░▀▀█░█░█░█▀▀░█▀▀░█▀▄░▀▀█░█░█░█░█░░█░░█░░
░▀▀▀░▀▀▀░▀░░░▀▀▀░▀░▀░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀▀
Back in the late 90s James McCartney designed a series of live audio programming environments called SuperCollider. These were systems with both programming languages and audio runtimes carefully designed for live realtime modification at every level - from high sweeping programming language abstractions all the way down to the fine control of the low-level synthesis components of the audio chain.
One of the many gifts from this work is scsynth - the core synthesis engine James created for version 3 of SuperCollider. It was at this point when he formally separated the language from the synth engine.
This split made it possible to combine scsynth's powerful audio synthesis capabilities with any existing - or yet to exist - programming language.
This then led to a suite of powerful new live coding languages using scsynth for audio synthesis.
What if you didn't just bring your language to scsynth? What if you brought scsynth to your environment?
This is SuperSonic. All the synthesis power of scsynth - modified and augmented to run in your web browser.
SuperSonic is SuperCollider's powerful audio synthesis engine scsynth running in the browser as an AudioWorklet.
Highlights:
- AudioWorklet - runs in a dedicated high priority audio thread
- WebAssembly - scsynth's original C++ code compiled for the web
- OSC API - talk to the scsynth server through its native OSC API
- Zero Config via CDN - no installation necessary - works directly from CDNs such as unpkg.
- Optional SAB mode - can use a SharedArrayBuffer (SAB) for lower latency and reduced jitter with internal comms. Requires COOP/COEP headers to enable browsers to use the SAB
Try the live demo: sonic-pi.net/supersonic/demo.html
- API Reference - Methods, callbacks, and configuration
- Server Command Reference - OSC commands for controlling scsynth
- Deployment - CDN, self-hosting, browser requirements
- Metrics - Performance monitoring and debugging
- Building from Source - Compiling the WASM yourself
In order to use SuperSonic, you need to first install it, configure it, boot it then play. Luckily these are all really easy. We'll go through each in turn:
- Install
- Configure
- Boot & Play
Import SuperSonic directly from a CDN such as unpkg for the simplest way to get started:
import { SuperSonic } from "https://unpkg.com/supersonic-scsynth@latest";You can also host the source yourself:
Download the pre-built distribution from GitHub Releases:
curl -LO https://github.com/samaaron/supersonic/releases/latest/download/supersonic.zip
unzip supersonic.zipThis gives you:
supersonic/
├── supersonic.js # Main library
├── wasm/ # WebAssembly binaries
├── workers/ # Web Workers
├── synthdefs/ # 127 (optional) synth definitions
└── samples/ # 206 (optional) audio samples
Then import from this directory:
import { SuperSonic } from "./supersonic/supersonic.js";If you're using SuperSonic's bundled samples and synthdefs, then no config is necessary:
const supersonic = new SuperSonic();If you want to point to your own assets, you can configure this when you create your SuperSonic instance:
A. Set a base URL (derives subdirectories automatically)
const supersonic = new SuperSonic({
baseURL: "/audio/supersonic/"
// Derives: /audio/supersonic/workers/, /audio/supersonic/wasm/, etc.
});B. Override individual paths
const supersonic = new SuperSonic({
workerBaseURL: "/my-workers/",
wasmBaseURL: "/my-wasm/",
synthdefBaseURL: "/my-synthdefs/",
sampleBaseURL: "/my-samples/"
});C. Enable SAB mode for lower latency (requires COOP/COEP headers)
const supersonic = new SuperSonic({
mode: "sab" // default is "postMessage"
});D. Enable debug logging
const supersonic = new SuperSonic({
debug: true // logs scsynth output, OSC in/out to console
});E. Configure scsynth server options
const supersonic = new SuperSonic({
scsynthOptions: {
numBuffers: 4096, // max audio buffers (default: 1024)
numAudioBusChannels: 256, // audio buses (default: 128)
realTimeMemorySize: 16384 // RT memory in KB (default: 8192)
}
});See API Reference for all available options.
Web browsers require you to press a button or make an explicit action before audio can start.
The easiest way to boot SuperSonic is from a boot button handler. Consider we have the following HTML buttons:
<button id="boot-btn">boot</button>
<button id="trig-btn">trigger</button>We can then use the boot button for booting SuperSonic and the trigger button to trigger a synth:
const bootBtn = document.getElementById("boot-btn");
const trigBtn = document.getElementById("trig-btn");
bootBtn.onclick = async () => {
await supersonic.init();
await supersonic.loadSynthDefs(["sonic-pi-prophet"]);
};
trigBtn.onclick = async () => {
supersonic.send("/s_new", "sonic-pi-prophet", -1, 0, 0, "note", 28, "release", 8, "cutoff", 70);
};See example/simple.html for a minimal working example.
SuperSonic is brought to you by Sam Aaron. Please consider joining the community of supporters enabling Sam's work on creative coding projects like this, Sonic Pi and Tau5.
SuperSonic uses a tiered licensing model - see LICENSE for details.
| Package | License | Contains |
|---|---|---|
supersonic-scsynth |
MIT | Client API |
supersonic-scsynth-core |
GPL-3.0-or-later | WASM engine + workers |
supersonic-scsynth-synthdefs |
MIT | Synth definitions |
supersonic-scsynth-samples |
CC0 | Audio samples |
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!