supersonic-scsynth 0.1.2 → 0.1.3

package/README.md

@@ -1,134 +1,117 @@
 # SuperSonic
 
-> **Warning - Super Alpha Status**: SuperSonic is currently in active development (v0.1.1). The API is likely to change between releases. Feedback welcome!
+> **Warning - Super Alpha Status**: SuperSonic is currently in active development. The API is likely to change between releases. Feedback welcome!
 
-This is a WebAssembly port of SuperCollider's highly flexible and powerful synthesis engine scsynth.
+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.
 
-SuperSonic's scsynth engine runs within a web AudioWorklet giving it access to a high-priority audio thread for real-time browser-based audio synthesis.
-
-The main API for SuperSonic is scsynth's OSC API with support for immediate and scheduled execution of OSC messages and bundles. It's also possible to register a handler to receive OSC replies from scsynth in addition to debug messages that would normally have been printed to stdout.
-
-Note: SuperSonic uses a SharedBuffer to send and receive OSC messages from scsynth which requires specific COOP/COEP headers to be set in your web browser (see below).
-
-
-## Installation
-
-### Option 1: npm Package (Recommended)
-
-```bash
-# Core engine only (~450KB)
-npm install supersonic-scsynth
-
-# Or install everything (engine + synthdefs + samples)
-npm install supersonic-scsynth-bundle
-```
-
-### Option 2: CDN (No build required)
+## Quick Start
 
 ```html
 <script type="module">
   import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';
 
   const sonic = new SuperSonic({
-    audioBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/'
+    sampleBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/',
+    synthdefBaseURL: 'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
   });
 
   await sonic.init();
 
-  // Load synthdefs from CDN
-  await sonic.loadSynthDefs(
-    ['sonic-pi-beep'],
-    'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
-  );
-</script>
-```
-
-### Option 3: Pre-built Distribution
+  // Load a synthdef
+  await sonic.loadSynthDefs(['sonic-pi-beep']);
 
-The 'nightly' (i.e. for every new commit) pre-built distribution files are published here:
-
-https://samaaron.github.io/supersonic/supersonic-dist.zip
+  // Trigger the synth
+  sonic.send('/s_new', 'sonic-pi-beep', -1, 0, 1, 'note', 60);
 
-This includes:
-- Core engine (WASM + JS)
-- All 120 synthdefs
-- All 206 samples
-- Size: ~35MB
-
-## Package Structure
-
-SuperSonic is published as multiple npm packages to keep the core engine small:
+  // Load and play a sample
+  sonic.send('/b_allocRead', 0, 'bd_haus.flac');
+  sonic.send('/s_new', 'sonic-pi-basic_mono_player', -1, 0, 1, 'buf', 0);
+</script>
+```
 
-### Core Package
-- **`supersonic-scsynth`** (~450KB) - The WebAssembly scsynth engine
-  - GPL-3.0-or-later license
+**Note:** Requires specific HTTP headers (COOP/COEP) for SharedArrayBuffer support. See [Browser Requirements](#browser-requirements) below.
 
-### Resource Packages
-- **`supersonic-scsynth-synthdefs`** (~67KB) - All 120 Sonic Pi synthdefs
-  - MIT license
-  - From [Sonic Pi](https://github.com/sonic-pi-net/sonic-pi)
+## Installation
 
-- **`supersonic-scsynth-samples`** (~34MB) - All 206 Sonic Pi samples
-  - CC0-1.0 license (public domain)
-  - Categories: ambient, bass, drums, electronic, glitch, guitar, hi-hats, loops, percussion, snares, tabla, vinyl, and more
-  - From [Sonic Pi](https://github.com/sonic-pi-net/sonic-pi)
+**Via npm:**
+```bash
+# Core engine only (~450KB)
+npm install supersonic-scsynth
 
-### Convenience Package
-- **`supersonic-scsynth-bundle`** - Includes core + synthdefs + all samples
-  - Install this to get everything in one command
+# Everything (engine + synthdefs + samples)
+npm install supersonic-scsynth-bundle
+```
 
-## Building from Source
+**Via CDN:**
+```javascript
+import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';
+```
 
-If you are familiar with Docker, you can build and run the example using the following commands:
+**Pre-built distribution:**
+Download the 'nightly' build (~35MB with all synthdefs and samples):
+https://samaaron.github.io/supersonic/supersonic-dist.zip
 
-```bash
-docker build -t supersonic .
-docker run --rm -it -p 8002:8002 supersonic
-```
+## Packages
 
-Or to build and run locally follow the instructions below.
+SuperSonic is split into multiple packages:
 
-### 1. Build
+| Package | Size | License | Contents |
+|---------|------|---------|----------|
+| `supersonic-scsynth` | ~450KB | GPL-3.0-or-later | Core WASM engine |
+| `supersonic-scsynth-synthdefs` | ~67KB | MIT | 120 Sonic Pi synthdefs |
+| `supersonic-scsynth-samples` | ~34MB | CC0-1.0 | 206 Sonic Pi samples |
+| `supersonic-scsynth-bundle` | - | - | All of the above |
 
-**Prerequisites:**
-- [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html)
-- [esbuild](https://esbuild.github.io/)
+All synthdefs and samples are from [Sonic Pi](https://github.com/sonic-pi-net/sonic-pi).
 
-```bash
-# Activate Emscripten
-source ~/path/to/emsdk_env.sh
+## API Reference
 
-# Build (compiles C++ to WASM and bundles JavaScript)
-./build.sh
+**Creating an instance:**
+```javascript
+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 */ }
+});
 ```
 
-Outputs to `dist/` directory (~1.5MB WASM + ~76KB JS + symlinks to synthdefs/samples).
-
-### 2. Serve Demo
+**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
 
-Start the basic Ruby webserver with the correct headers:
+**Callbacks:**
+- `sonic.onInitialized` - Called when ready
+- `sonic.onError(error)` - Error handling
+- `sonic.onMessageReceived(msg)` - Incoming OSC messages
+- `sonic.onMessageSent(oscData)` - Outgoing OSC messages
 
-```bash
-ruby example/server.rb
+**Common OSC commands:**
+```javascript
+sonic.send('/notify', 1);                              // Enable notifications
+sonic.send('/s_new', 'synth-name', -1, 0, 1);         // 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
 ```
 
-Open: http://localhost:8002/demo.html
+See [SuperCollider Server Command Reference](https://doc.sccode.org/Reference/Server-Command-Reference.html) for the full OSC API.
 
 ## Browser Requirements
 
-**Minimum Versions:**
+**Minimum browser versions:**
 - Chrome/Edge 92+
 - Firefox 79+
 - Safari 15.2+
 
-**Required Features:**
-- SharedArrayBuffer (requires COOP/COEP headers - see below)
+**Required features:**
+- SharedArrayBuffer (requires COOP/COEP headers)
 - AudioWorklet
-- WebAssembly with threads support
+- WebAssembly with threads
 
-**Required HTTP Headers:**
-
-Important: your server must send these headers for SharedArrayBuffer to work:
+**Required HTTP headers:**
+Your server must send these headers for SharedArrayBuffer support:
 
 ```
 Cross-Origin-Opener-Policy: same-origin
@@ -138,121 +121,39 @@ Cross-Origin-Resource-Policy: cross-origin
 
 See `example/server.rb` for a reference implementation.
 
-## Basic Usage
-
-### Minimal Example (Core Only)
-
-```javascript
-import { SuperSonic } from './dist/supersonic.js';
-
-const sonic = new SuperSonic();
-await sonic.init();
-
-sonic.send('/notify', 1);
-```
-
-### With Synthdefs and Samples (npm/CDN)
-
-```javascript
-import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';
-
-// Configure sample path (required for buffer loading)
-const sonic = new SuperSonic({
-  audioBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/'
-});
-
-await sonic.init();
-
-// Load synthdefs (baseUrl is required)
-await sonic.loadSynthDefs(
-  ['sonic-pi-beep', 'sonic-pi-tb303'],
-  'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
-);
+## Building from Source
 
-// Play a synth
-sonic.send('/s_new', 'sonic-pi-beep', -1, 0, 1, 'note', 60);
+**Prerequisites:**
+- [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html)
+- [esbuild](https://esbuild.github.io/)
 
-// Load and play a sample
-await sonic.allocReadBuffer(0, 'bd_haus.flac');
-sonic.send('/s_new', 'sonic-pi-basic_mono_player', -1, 0, 1, 'buf', 0);
-```
+**Build:**
+```bash
+# Activate Emscripten
+source ~/path/to/emsdk_env.sh
 
-See `example/demo.html` for a complete working example.
-
-### API Reference
-
-**SuperSonic Class:**
-- `new SuperSonic(options)` - Create instance
-  - `options.audioBaseURL` - Base URL for sample files (required for buffer loading)
-  - `options.audioPathMap` - Custom mapping of sample names to URLs
-- `async init()` - Initialize audio engine
-- `async loadSynthDefs(names, baseUrl)` - Load synth definitions (baseUrl required)
-- `async allocReadBuffer(bufnum, filename)` - Load audio file into buffer
-- `send(address, ...args)` - Send OSC message (auto-detects types)
-- `sendOSC(oscBytes, options)` - Send pre-encoded OSC bytes
-- `onInitialized` - Callback when ready
-- `onError(error)` - Error callback
-- `onMessageReceived(msg)` - Incoming OSC message callback
-- `onMessageSent(oscData)` - Outgoing OSC message callback
-
-**Sending OSC Messages:**
-```javascript
-// Types are auto-detected: strings → 's', integers → 'i', floats → 'f'
-sonic.send('/notify', 1);
-sonic.send('/s_new', 'sonic-pi-beep', -1, 0, 0);
-sonic.send('/n_set', 1000, 'freq', 440.0, 'amp', 0.5);
+# Compile and bundle
+./build.sh
 ```
 
-**Common OSC Commands:**
-- `/d_recv` - Load synth definition
-- `/s_new` - Create synth
-- `/n_free` - Free node
-- `/n_set` - Set node parameters
-- `/notify` - Enable server notifications
-
-See [SuperCollider Server Command Reference](https://doc.sccode.org/Reference/Server-Command-Reference.html) for full OSC API.
-
-## Integration Guide
-
-### Recommended: npm Packages
-
-Install the core package and any resources you need:
+Output goes to `dist/` directory (~1.5MB WASM + ~76KB JS + workers).
 
+**Run demo:**
 ```bash
-# Core engine
-npm install supersonic-scsynth
-
-# Synthdefs (optional)
-npm install supersonic-scsynth-synthdefs
-
-# Samples (optional)
-npm install supersonic-scsynth-samples
-
-# Or everything at once
-npm install supersonic-scsynth-bundle
+ruby example/server.rb
 ```
 
-Then use via CDN in your HTML:
-
-```html
-<script type="module">
-  import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';
-
-  const sonic = new SuperSonic({
-    audioBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/'
-  });
+Open http://localhost:8002/demo.html
 
-  await sonic.init();
-  await sonic.loadSynthDefs(
-    ['sonic-pi-beep'],
-    'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
-  );
-</script>
+**Docker:**
+```bash
+docker build -t supersonic .
+docker run --rm -it -p 8002:8002 supersonic
 ```
 
-### Alternative: Manual File Integration
+## File Structure
 
-If you're building from source or need local files, copy these from `dist/`:
+When building from source or using local files:
 
 ```
 dist/
@@ -260,40 +161,13 @@ dist/
 ├── wasm/
 │   └── scsynth-nrt.wasm          # Audio engine (~1.5MB)
 └── workers/
-    ├── osc_in_worker.js          # OSC input handling
-    ├── osc_out_worker.js         # OSC output handling
-    ├── debug_worker.js           # Debug logging
-    └── scsynth_audio_worklet.js  # AudioWorklet processor
-```
-
-Resources (synthdefs/samples) are available separately via npm packages.
-
-### Path Configuration
-
-**Required Configuration:**
-
-Sample and synthdef paths must be explicitly configured:
-
-```javascript
-const sonic = new SuperSonic({
-  audioBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/'
-});
-
-await sonic.loadSynthDefs(
-  ['sonic-pi-beep'],
-  'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
-);
+    ├── scsynth_audio_worklet.js  # AudioWorklet processor
+    ├── osc_in_worker.js          # OSC input handler
+    ├── osc_out_worker.js         # OSC output handler
+    └── debug_worker.js           # Debug logger
 ```
 
-**Engine Paths:**
-
-The core engine expects these files relative to your HTML:
-- WASM: `./dist/wasm/scsynth-nrt.wasm`
-- AudioWorklet: `./dist/workers/scsynth_audio_worklet.js`
-- Workers: `./dist/workers/osc_out_worker.js`, `osc_in_worker.js`, `debug_worker.js`
-
-These paths are currently not configurable.
-
+The engine expects these files at `./dist/` relative to your HTML. Paths are currently not configurable.
 
 ## License
 
@@ -301,5 +175,4 @@ 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 massively inspired and motivated by
-Hanns Holger Rutz who started the first port of scsynth to WASM and Dennis Scheiba who took the baton and continued this great work. Thank-you also to everyone in the SuperCollider community, you're all beautiful people.
+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/dist/supersonic.js

@@ -1616,7 +1616,8 @@ var SuperSonic = class {
         sampleRate: 48e3
       }
     };
-    this.audioBaseURL = options.audioBaseURL || null;
+    this.sampleBaseURL = options.sampleBaseURL || null;
+    this.synthdefBaseURL = options.synthdefBaseURL || null;
     this.audioPathMap = options.audioPathMap || {};
     this.allocatedBuffers = /* @__PURE__ */ new Map();
     this.stats = {
@@ -2099,12 +2100,12 @@ var SuperSonic = class {
     if (this.audioPathMap[scPath]) {
       return this.audioPathMap[scPath];
     }
-    if (!this.audioBaseURL) {
+    if (!this.sampleBaseURL) {
       throw new Error(
-        'audioBaseURL not configured. Please set it in SuperSonic constructor options.\nExample: new SuperSonic({ audioBaseURL: "https://unpkg.com/supersonic-scsynth-samples@latest/samples/" })\nOr install sample packages: npm install supersonic-scsynth-samples'
+        'sampleBaseURL not configured. Please set it in SuperSonic constructor options.\nExample: new SuperSonic({ sampleBaseURL: "https://unpkg.com/supersonic-scsynth-samples@latest/samples/" })\nOr install sample packages: npm install supersonic-scsynth-samples'
       );
     }
-    return this.audioBaseURL + scPath;
+    return this.sampleBaseURL + scPath;
   }
   /**
    * Handle /buffer/freed message from WASM
@@ -2311,28 +2312,24 @@ var SuperSonic = class {
   /**
    * Load multiple synthdefs from a directory
    * @param {string[]} names - Array of synthdef names (without .scsyndef extension)
-   * @param {string} baseUrl - Base URL for synthdef files (required)
    * @returns {Promise<Object>} Map of name -> success/error
    * @example
-   * const results = await sonic.loadSynthDefs(
-   *   ['sonic-pi-beep', 'sonic-pi-tb303'],
-   *   'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
-   * );
+   * const results = await sonic.loadSynthDefs(['sonic-pi-beep', 'sonic-pi-tb303']);
    */
-  async loadSynthDefs(names, baseUrl) {
+  async loadSynthDefs(names) {
     if (!this.initialized) {
       throw new Error("SuperSonic not initialized. Call init() first.");
     }
-    if (!baseUrl) {
+    if (!this.synthdefBaseURL) {
       throw new Error(
-        'baseUrl is required. Please specify the URL to your synthdefs.\nExample: await sonic.loadSynthDefs(["sonic-pi-beep"], "https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/")\nOr install: npm install supersonic-scsynth-synthdefs'
+        'synthdefBaseURL not configured. Please set it in SuperSonic constructor options.\nExample: new SuperSonic({ synthdefBaseURL: "https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/" })\nOr install: npm install supersonic-scsynth-synthdefs'
       );
     }
     const results = {};
     await Promise.all(
       names.map(async (name) => {
         try {
-          const path = `${baseUrl}${name}.scsyndef`;
+          const path = `${this.synthdefBaseURL}${name}.scsyndef`;
           await this.loadSynthDef(path);
           results[name] = { success: true };
         } catch (error) {

package/dist/wasm/manifest.json

@@ -1,6 +1,6 @@
 {
   "wasmFile": "scsynth-nrt.wasm",
-  "buildId": "20251104-122135",
-  "buildTime": "2025-11-04T12:21:35Z",
-  "gitHash": "261e158"
+  "buildId": "20251104-125406",
+  "buildTime": "2025-11-04T12:54:06Z",
+  "gitHash": "003a9a0"
 }

package/package.json

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