supersonic-scsynth 0.23.1 → 0.23.4

package/README.md

@@ -1,4 +1,4 @@
-> **Note: Alpha Status**: SuperSonic is in active development. The API may evolve, but the core synthesis engine is solid and ready for experimentation. Feedback and ideas are most welcome.
+> **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._
 
 ```
 ░█▀▀░█░█░█▀█░█▀▀░█▀▄░█▀▀░█▀█░█▀█░▀█▀░█▀▀
@@ -6,90 +6,64 @@
 ░▀▀▀░▀▀▀░▀░░░▀▀▀░▀░▀░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀▀
 ```
 
-**SuperSonic** - [SuperCollider](https://supercollider.github.io/)'s powerful audio synthesis engine scsynth running in the browser as an [AudioWorklet](https://developer.mozilla.org/en-US/docs/Web/API/AudioWorklet).
+Back in the late 90s James McCartney designed a series of live audio programming environments called [SuperCollider](https://en.wikipedia.org/wiki/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.
 
-- _AudioWorklet_ - runs in a dedicated high priority audio thread
-- _WebAssembly_ - scsynth's C++ code compiled for the web
-- _OSC API_ - talk to the scsynth server through its native OSC API
-- _Zero Config CDN_ - works directly from unpkg with no server setup
+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_.
 
-**[Try the live demo](https://sonic-pi.net/supersonic/demo.html)**
+This split made it possible to combine **scsynth**'s powerful audio synthesis capabilities with any existing - or yet to exist - programming language.
 
-## Getting Started
+This then led to a suite of powerful new live coding languages using **scsynth** for audio synthesis.
 
-### CDN (Zero Config)
+_What if you didn't just bring your language to scsynth? What if you brought scsynth to your environment?_
 
-The simplest way to use SuperSonic - no server setup required:
+This is SuperSonic. All the synthesis power of **scsynth** - modified and augmented to run in your web browser.
 
-```html
-<script type="module">
-  import { SuperSonic } from "https://unpkg.com/supersonic-scsynth@latest";
+# Welcome to SuperSonic
 
-  const supersonic = new SuperSonic();
-  await supersonic.init();
-  await supersonic.loadSynthDef("sonic-pi-prophet");
-  supersonic.send("/s_new", "sonic-pi-prophet", -1, 0, 0, "note", 60);
-</script>
-```
+**SuperSonic** is [SuperCollider](https://supercollider.github.io/)'s powerful audio synthesis engine **scsynth** running in the browser as an [AudioWorklet](https://developer.mozilla.org/en-US/docs/Web/API/AudioWorklet).
 
-All URLs are auto-detected from the import path. See `example/cdn.html` for a working example.
+Highlights:
 
-### Self-Hosted
+- **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
 
-You can also host the files yourself:
 
-```javascript
-import { SuperSonic } from "./supersonic/supersonic.js";
+## Demo
 
-const supersonic = new SuperSonic();  // URLs auto-detected from import path
-await supersonic.init();
-```
-
-Or with explicit configuration:
-
-```javascript
-const supersonic = new SuperSonic({
-  baseURL: "/supersonic/"
-});
-await supersonic.init();
-```
+Try the live demo: [**sonic-pi.net/supersonic/demo.html**](https://sonic-pi.net/supersonic/demo.html)
 
-### Playing Sounds
 
-Load and play a synth:
+## Documentation
 
-```javascript
-await supersonic.loadSynthDef("sonic-pi-prophet");
-supersonic.send("/s_new", "sonic-pi-prophet", -1, 0, 0, "note", 60);
-```
+- [API Reference](docs/API.md) - Methods, callbacks, and configuration
+- [Server Command Reference](docs/SERVER_COMMAND_REFERENCE.md) - OSC commands for controlling scsynth
+- [Deployment](docs/DEPLOYMENT.md) - CDN, self-hosting, browser requirements
+- [Metrics](docs/METRICS.md) - Performance monitoring and debugging
+- [Building from Source](docs/BUILDING.md) - Compiling the WASM yourself
 
-Load and play a sample:
 
-```javascript
-await supersonic.loadSynthDef("sonic-pi-basic_stereo_player");
-await supersonic.loadSample(0, "loop_amen.flac");
-supersonic.send("/s_new", "sonic-pi-basic_stereo_player", -1, 0, 0, "buf", 0);
-```
+## Getting Started
 
-See `example/simple.html` for a minimal working example.
+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:
 
-## Installation
+1. Install
+2. Configure
+3. Boot & Play
 
-### Option 1: CDN (Recommended for Getting Started)
+### 1. Install [Easy - CDN]
 
-No installation needed - just import directly:
+Import SuperSonic directly from a CDN such as unpkg for the simplest way to get started:
 
 ```javascript
 import { SuperSonic } from "https://unpkg.com/supersonic-scsynth@latest";
 ```
 
-### Option 2: npm
-
-```bash
-npm install supersonic-scsynth
-```
+### 1. Install [Advanced - Self-Hosted]
 
-### Option 3: Self-Hosted Bundle
+You can also host the source yourself:
 
 Download the pre-built distribution from [GitHub Releases](https://github.com/samaaron/supersonic/releases):
 
@@ -105,18 +79,101 @@ supersonic/
 ├── supersonic.js      # Main library
 ├── wasm/              # WebAssembly binaries
 ├── workers/           # Web Workers
-├── synthdefs/         # 127 synth definitions
-└── samples/           # 206 audio samples
+├── synthdefs/         # 127 (optional) synth definitions
+└── samples/           # 206 (optional) audio samples
 ```
 
-## Documentation
+Then import from this directory:
+
+```javascript
+import { SuperSonic } from "./supersonic/supersonic.js";
+```
+
+### 2. Configure [Easy - Use Defaults]
+
+If you're using SuperSonic's bundled samples and synthdefs, then no config is necessary:
+
+```javascript
+const supersonic = new SuperSonic();
+```
+
+### 2. Configure [Advanced - In Constructor]
+
+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)
+```javascript
+const supersonic = new SuperSonic({
+  baseURL: "/audio/supersonic/"
+  // Derives: /audio/supersonic/workers/, /audio/supersonic/wasm/, etc.
+});
+```
+
+B. Override individual paths
+```javascript
+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)
+```javascript
+const supersonic = new SuperSonic({
+  mode: "sab"  // default is "postMessage"
+});
+```
+
+D. Enable debug logging
+```javascript
+const supersonic = new SuperSonic({
+  debug: true  // logs scsynth output, OSC in/out to console
+});
+```
+
+E. Configure scsynth server options
+```javascript
+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](docs/API.md) for all available options.
+
+### 3. Boot & Play
+
+**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:
+
+```html
+<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:
+
+```javascript
+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.
 
-- [API Reference](docs/API.md) - Methods, callbacks, and configuration
-- [Server Command Reference](docs/SERVER_COMMAND_REFERENCE.md) - OSC commands for controlling scsynth
-- [Metrics](docs/METRICS.md) - Performance monitoring and debugging
-- [Browser Setup](docs/BROWSER_SETUP.md) - Required headers and browser requirements
-- [CDN and Self-Hosting](docs/CDN.md) - Why self-hosting is required
-- [Building from Source](docs/BUILDING.md) - Compiling the WASM yourself
 
 ## Support
 
@@ -125,10 +182,12 @@ SuperSonic is brought to you by Sam Aaron. Please consider joining the community
 - [Patreon](https://patreon.com/samaaron)
 - [GitHub Sponsors](https://github.com/sponsors/samaaron)
 
+
 ## License
 
 GPL v3 - This is a derivative work of SuperCollider
 
+
 ## Credits
 
 Based on [SuperCollider](https://supercollider.github.io/) 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!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supersonic-scsynth",
-  "version": "0.23.1",
+  "version": "0.23.4",
   "description": "SuperCollider scsynth WebAssembly port for AudioWorklet - Run SuperCollider synthesis in the browser",
   "main": "dist/supersonic.js",
   "unpkg": "dist/supersonic.js",