supersonic-scsynth 0.69.0 → 0.70.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +19 -0
- package/README.md +82 -456
- package/README.npm.md +82 -456
- package/dist/metrics_component.js +1 -1
- package/dist/osc_channel.js +1 -1
- package/dist/supersonic.js +5 -5
- package/dist/workers/osc_in_worker.js +1 -1
- package/dist/workers/osc_out_log_sab_worker.js +1 -1
- package/package.json +2 -1
- package/supersonic.d.ts +36 -204
- package/dist/workers/debug_worker.js +0 -3
- package/dist/workers/osc_out_prescheduler_worker.js +0 -1
package/README.npm.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# SuperSonic 0.
|
|
1
|
+
# SuperSonic 0.70.0
|
|
2
2
|
|
|
3
3
|
> SuperCollider's scsynth in the browser as an AudioWorklet.
|
|
4
4
|
>
|
|
@@ -174,24 +174,20 @@ scsynth with low latency inside a web page.
|
|
|
174
174
|
|
|
175
175
|
**Core**
|
|
176
176
|
|
|
177
|
-
| Member
|
|
178
|
-
|
|
|
179
|
-
| [`init()`](#init)
|
|
180
|
-
| [`shutdown()`](#shutdown)
|
|
181
|
-
| [`destroy()`](#destroy)
|
|
182
|
-
| [`recover()`](#recover)
|
|
183
|
-
| [`suspend()`](#suspend)
|
|
184
|
-
| [`resume()`](#resume)
|
|
185
|
-
| [`reload()`](#reload)
|
|
186
|
-
| [`reset()`](#reset)
|
|
187
|
-
| [`send()`](#send)
|
|
188
|
-
| [`sendOSC()`](#sendosc)
|
|
189
|
-
| [`sync()`](#sync)
|
|
190
|
-
| [`purge()`](#purge)
|
|
191
|
-
| [`cancelAll()`](#cancelall) | Cancel all scheduled messages in the JS prescheduler. |
|
|
192
|
-
| [`cancelSession()`](#cancelsession) | Cancel all scheduled messages for a session. |
|
|
193
|
-
| [`cancelSessionTag()`](#cancelsessiontag) | Cancel scheduled messages matching both a session and run tag. |
|
|
194
|
-
| [`cancelTag()`](#canceltag) | Cancel all scheduled messages with the given run tag. |
|
|
177
|
+
| Member | Description |
|
|
178
|
+
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
179
|
+
| [`init()`](#init) | Initialise the engine. |
|
|
180
|
+
| [`shutdown()`](#shutdown) | Shut down the engine. |
|
|
181
|
+
| [`destroy()`](#destroy) | Destroy the engine completely. |
|
|
182
|
+
| [`recover()`](#recover) | Smart recovery — tries a quick resume first, falls back to full reload. |
|
|
183
|
+
| [`suspend()`](#suspend) | Suspend the AudioContext and stop the drift timer. |
|
|
184
|
+
| [`resume()`](#resume) | Quick resume — calls purge to flush stale messages, resumes AudioContext, and resyncs timing. |
|
|
185
|
+
| [`reload()`](#reload) | Full reload — destroys and recreates the worklet and WASM, then restores all previously loaded synthdefs and audio buffers. |
|
|
186
|
+
| [`reset()`](#reset) | Shutdown and immediately re-initialise. |
|
|
187
|
+
| [`send()`](#send) | Send any OSC message. |
|
|
188
|
+
| [`sendOSC()`](#sendosc) | Send pre-encoded OSC bytes to scsynth. |
|
|
189
|
+
| [`sync()`](#sync) | Wait for scsynth to process all pending commands. |
|
|
190
|
+
| [`purge()`](#purge) | Flush all pending scheduled OSC: clears the WASM BundleScheduler and the IN ring so nothing already in-flight will fire. |
|
|
195
191
|
|
|
196
192
|
**Asset Loading**
|
|
197
193
|
|
|
@@ -274,27 +270,19 @@ OscChannel — unified dispatch for sending OSC to the AudioWorklet.
|
|
|
274
270
|
Obtain a channel via [SuperSonic.createOscChannel](#createoscchannel) on the main thread,
|
|
275
271
|
then transfer it to a Web Worker for direct communication with the AudioWorklet.
|
|
276
272
|
|
|
277
|
-
| Member | Description
|
|
278
|
-
| --------------------------------------------- |
|
|
279
|
-
| [`getCurrentNTP`](#getcurrentntp) | Set the NTP time source for classification (used in AudioWorklet context).
|
|
280
|
-
| [`mode`](#mode) | Transport mode this channel is using.
|
|
281
|
-
| [`
|
|
282
|
-
| [`
|
|
283
|
-
| [`
|
|
284
|
-
| [`
|
|
285
|
-
| [`
|
|
286
|
-
| [`
|
|
287
|
-
| [`
|
|
288
|
-
| [`
|
|
289
|
-
| [`
|
|
290
|
-
| [`getMetrics()`](#getmetrics) | Get current metrics snapshot. |
|
|
291
|
-
| [`nextNodeId()`](#nextnodeid) | Get the next unique node ID. |
|
|
292
|
-
| [`pollReplies()`](#pollreplies) | Drain pending replies, calling the registered handler (or handler argument, if given) once per message. |
|
|
293
|
-
| [`send()`](#send) | Send an OSC message with automatic routing. |
|
|
294
|
-
| [`sendDirect()`](#senddirect) | Send directly to worklet without classification or metrics tracking. |
|
|
295
|
-
| [`sendToPrescheduler()`](#sendtoprescheduler) | Send to prescheduler without classification. |
|
|
296
|
-
| [`setReplyHandler()`](#setreplyhandler) | Register a handler for OSC replies from scsynth. |
|
|
297
|
-
| [`fromTransferable()`](#fromtransferable) | Reconstruct an OscChannel from data received via postMessage in a worker. |
|
|
273
|
+
| Member | Description |
|
|
274
|
+
| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
275
|
+
| [`getCurrentNTP`](#getcurrentntp) | Set the NTP time source for classification (used in AudioWorklet context). |
|
|
276
|
+
| [`mode`](#mode) | Transport mode this channel is using. |
|
|
277
|
+
| [`transferable`](#transferable) | Serializable config for transferring this channel to a worker via postMessage. |
|
|
278
|
+
| [`transferList`](#transferlist) | Array of transferable objects (MessagePorts) for the postMessage transfer list. |
|
|
279
|
+
| [`close()`](#close) | Close the channel and release its ports. |
|
|
280
|
+
| [`getAndResetMetrics()`](#getandresetmetrics) | Get and reset local metrics (for periodic reporting). |
|
|
281
|
+
| [`getMetrics()`](#getmetrics) | Get current metrics snapshot. |
|
|
282
|
+
| [`nextNodeId()`](#nextnodeid) | Get the next unique node ID. |
|
|
283
|
+
| [`send()`](#send) | Send an OSC message: frames it onto the IN ring (SAB) or postMessages it to the worklet (PM). |
|
|
284
|
+
| [`sendDirect()`](#senddirect) | Alias of send — kept for callers that used the explicit direct path. |
|
|
285
|
+
| [`fromTransferable()`](#fromtransferable) | Reconstruct an OscChannel from data received via postMessage in a worker. |
|
|
298
286
|
|
|
299
287
|
#### Example
|
|
300
288
|
|
|
@@ -358,20 +346,6 @@ Transport mode this channel is using.
|
|
|
358
346
|
|
|
359
347
|
[`TransportMode`](#transportmode)
|
|
360
348
|
|
|
361
|
-
##### replyDrops
|
|
362
|
-
|
|
363
|
-
###### Get Signature
|
|
364
|
-
|
|
365
|
-
> **get** **replyDrops**(): `number`
|
|
366
|
-
|
|
367
|
-
Number of reply messages dropped because the reply buffer was full.
|
|
368
|
-
SAB mode only — undefined in PM mode or before [activateReplies](#activatereplies).
|
|
369
|
-
Counter resets each time the slot is (re)claimed.
|
|
370
|
-
|
|
371
|
-
###### Returns
|
|
372
|
-
|
|
373
|
-
`number`
|
|
374
|
-
|
|
375
349
|
##### transferable
|
|
376
350
|
|
|
377
351
|
###### Get Signature
|
|
@@ -412,45 +386,6 @@ worker.postMessage({ ch: channel.transferable }, channel.transferList);
|
|
|
412
386
|
|
|
413
387
|
#### Methods
|
|
414
388
|
|
|
415
|
-
##### activateReplies()
|
|
416
|
-
|
|
417
|
-
> **activateReplies**(): `void`
|
|
418
|
-
|
|
419
|
-
Activate the reply slot without registering a handler. Usually called
|
|
420
|
-
for you by [setReplyHandler](#setreplyhandler); only call directly if you want to
|
|
421
|
-
claim the slot before installing a handler (or to use the optional
|
|
422
|
-
one-shot handler argument of [pollReplies](#pollreplies)).
|
|
423
|
-
|
|
424
|
-
###### Returns
|
|
425
|
-
|
|
426
|
-
`void`
|
|
427
|
-
|
|
428
|
-
##### classify()
|
|
429
|
-
|
|
430
|
-
> **classify**(`oscData`): [`OscCategory`](#osccategory)
|
|
431
|
-
|
|
432
|
-
Classify an OSC message to determine its routing.
|
|
433
|
-
|
|
434
|
-
###### Parameters
|
|
435
|
-
|
|
436
|
-
| Parameter | Type | Description |
|
|
437
|
-
| --------- | ------------ | ----------------- |
|
|
438
|
-
| `oscData` | `Uint8Array` | Encoded OSC bytes |
|
|
439
|
-
|
|
440
|
-
###### Returns
|
|
441
|
-
|
|
442
|
-
[`OscCategory`](#osccategory)
|
|
443
|
-
|
|
444
|
-
##### clearReplyHandler()
|
|
445
|
-
|
|
446
|
-
> **clearReplyHandler**(): `void`
|
|
447
|
-
|
|
448
|
-
Clear the reply handler and release the reply channel. Idempotent.
|
|
449
|
-
|
|
450
|
-
###### Returns
|
|
451
|
-
|
|
452
|
-
`void`
|
|
453
|
-
|
|
454
389
|
##### close()
|
|
455
390
|
|
|
456
391
|
> **close**(): `void`
|
|
@@ -461,16 +396,6 @@ Close the channel and release its ports.
|
|
|
461
396
|
|
|
462
397
|
`void`
|
|
463
398
|
|
|
464
|
-
##### deactivateReplies()
|
|
465
|
-
|
|
466
|
-
> **deactivateReplies**(): `void`
|
|
467
|
-
|
|
468
|
-
Release the reply slot. Usually called for you by [clearReplyHandler](#clearreplyhandler).
|
|
469
|
-
|
|
470
|
-
###### Returns
|
|
471
|
-
|
|
472
|
-
`void`
|
|
473
|
-
|
|
474
399
|
##### getAndResetMetrics()
|
|
475
400
|
|
|
476
401
|
> **getAndResetMetrics**(): [`OscChannelMetrics`](#oscchannelmetrics)
|
|
@@ -507,40 +432,13 @@ the root group, 1 is the default group, 2–999 are reserved for manual use).
|
|
|
507
432
|
|
|
508
433
|
A unique node ID (>= 1000)
|
|
509
434
|
|
|
510
|
-
##### pollReplies()
|
|
511
|
-
|
|
512
|
-
> **pollReplies**(`handler?`): `number`
|
|
513
|
-
|
|
514
|
-
Drain pending replies, calling the registered handler (or `handler`
|
|
515
|
-
argument, if given) once per message. Returns the number of messages
|
|
516
|
-
processed. Zero-allocation on the hot path.
|
|
517
|
-
|
|
518
|
-
Call from an AudioWorklet's `process()` method to receive replies on
|
|
519
|
-
the audio thread. In other contexts automatic delivery already calls
|
|
520
|
-
this for you.
|
|
521
|
-
|
|
522
|
-
###### Parameters
|
|
523
|
-
|
|
524
|
-
| Parameter | Type | Description |
|
|
525
|
-
| ---------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
|
|
526
|
-
| `handler?` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) | Optional override for this call only |
|
|
527
|
-
|
|
528
|
-
###### Returns
|
|
529
|
-
|
|
530
|
-
`number`
|
|
531
|
-
|
|
532
|
-
Number of messages drained
|
|
533
|
-
|
|
534
435
|
##### send()
|
|
535
436
|
|
|
536
437
|
> **send**(`oscData`): `boolean`
|
|
537
438
|
|
|
538
|
-
Send an OSC message
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
* bypass categories → sent directly to the AudioWorklet
|
|
543
|
-
* far-future bundles → routed to the prescheduler for timed dispatch
|
|
439
|
+
Send an OSC message: frames it onto the IN ring (SAB) or postMessages it to
|
|
440
|
+
the worklet (PM). Classification and scheduling happen on the audio thread
|
|
441
|
+
(the engine's OscIngress + BundleScheduler) — the producer never classifies.
|
|
544
442
|
|
|
545
443
|
###### Parameters
|
|
546
444
|
|
|
@@ -558,7 +456,7 @@ true if sent successfully
|
|
|
558
456
|
|
|
559
457
|
> **sendDirect**(`oscData`): `boolean`
|
|
560
458
|
|
|
561
|
-
|
|
459
|
+
Alias of [send](#send) — kept for callers that used the explicit direct path.
|
|
562
460
|
|
|
563
461
|
###### Parameters
|
|
564
462
|
|
|
@@ -572,58 +470,6 @@ Send directly to worklet without classification or metrics tracking.
|
|
|
572
470
|
|
|
573
471
|
true if sent successfully
|
|
574
472
|
|
|
575
|
-
##### sendToPrescheduler()
|
|
576
|
-
|
|
577
|
-
> **sendToPrescheduler**(`oscData`): `boolean`
|
|
578
|
-
|
|
579
|
-
Send to prescheduler without classification.
|
|
580
|
-
|
|
581
|
-
###### Parameters
|
|
582
|
-
|
|
583
|
-
| Parameter | Type | Description |
|
|
584
|
-
| --------- | ------------ | ----------------- |
|
|
585
|
-
| `oscData` | `Uint8Array` | Encoded OSC bytes |
|
|
586
|
-
|
|
587
|
-
###### Returns
|
|
588
|
-
|
|
589
|
-
`boolean`
|
|
590
|
-
|
|
591
|
-
true if sent successfully
|
|
592
|
-
|
|
593
|
-
##### setReplyHandler()
|
|
594
|
-
|
|
595
|
-
> **setReplyHandler**(`handler`): `void`
|
|
596
|
-
|
|
597
|
-
Register a handler for OSC replies from scsynth. Idempotent — replaces
|
|
598
|
-
any previously-registered handler. In AudioWorklet contexts the worklet
|
|
599
|
-
must call [pollReplies](#pollreplies) from `process()` to drain; in all other
|
|
600
|
-
contexts delivery is automatic. All registered channels receive all
|
|
601
|
-
replies (broadcast); filter locally if you only need specific addresses.
|
|
602
|
-
|
|
603
|
-
SAB mode: handler receives `(view, offset, length, sequence)` — zero-copy
|
|
604
|
-
into the shared buffer. Read bytes from `view[offset..offset+length]`.
|
|
605
|
-
Data is valid only for the duration of the handler call.
|
|
606
|
-
|
|
607
|
-
PM mode: handler receives `(oscData, sequence)` where `oscData` is a copy.
|
|
608
|
-
|
|
609
|
-
###### Parameters
|
|
610
|
-
|
|
611
|
-
| Parameter | Type |
|
|
612
|
-
| --------- | ------------------------------------------------------------------------------------------- |
|
|
613
|
-
| `handler` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) |
|
|
614
|
-
|
|
615
|
-
###### Returns
|
|
616
|
-
|
|
617
|
-
`void`
|
|
618
|
-
|
|
619
|
-
###### Example
|
|
620
|
-
|
|
621
|
-
```ts
|
|
622
|
-
channel.setReplyHandler((view, offset, length, sequence) => {
|
|
623
|
-
// SAB: read raw OSC bytes from view[offset..offset+length]
|
|
624
|
-
});
|
|
625
|
-
```
|
|
626
|
-
|
|
627
473
|
##### fromTransferable()
|
|
628
474
|
|
|
629
475
|
> `static` **fromTransferable**(`data`): [`OscChannel`](#oscchannel)
|
|
@@ -979,33 +825,31 @@ if (loaded.some(b => b.hash === info.hash)) {
|
|
|
979
825
|
|
|
980
826
|
## Constructor Options
|
|
981
827
|
|
|
982
|
-
| Property
|
|
983
|
-
|
|
|
984
|
-
| <a id="activityevent"></a> `activityEvent?`
|
|
985
|
-
| <a id="audiocontext-1"></a> `audioContext?`
|
|
986
|
-
| <a id="audiocontextoptions"></a> `audioContextOptions?`
|
|
987
|
-
| <a id="autoconnect"></a> `autoConnect?`
|
|
988
|
-
| <a id="baseurl"></a> `baseURL?`
|
|
989
|
-
| <a id="buffergrowincrement"></a> `bufferGrowIncrement?`
|
|
990
|
-
| <a id="
|
|
991
|
-
| <a id="
|
|
992
|
-
| <a id="
|
|
993
|
-
| <a id="
|
|
994
|
-
| <a id="
|
|
995
|
-
| <a id="
|
|
996
|
-
| <a id="
|
|
997
|
-
| <a id="
|
|
998
|
-
| <a id="
|
|
999
|
-
| <a id="
|
|
1000
|
-
| <a id="
|
|
1001
|
-
| <a id="
|
|
1002
|
-
| <a id="
|
|
1003
|
-
| <a id="
|
|
1004
|
-
| <a id="
|
|
1005
|
-
| <a id="
|
|
1006
|
-
| <a id="
|
|
1007
|
-
| <a id="workerbaseurl"></a> `workerBaseURL?` | `string` | Base URL for MIT worker scripts. Defaults to `baseURL + 'workers/'`. | |
|
|
1008
|
-
| <a id="workleturl"></a> `workletUrl?` | `string` | Full URL to the AudioWorklet script. Overrides `coreBaseURL`. | |
|
|
828
|
+
| Property | Type | Description | Required |
|
|
829
|
+
| ------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
|
|
830
|
+
| <a id="activityevent"></a> `activityEvent?` | [`ActivityLineConfig`](#activitylineconfig) | Line length limits for activity events emitted to listeners. | |
|
|
831
|
+
| <a id="audiocontext-1"></a> `audioContext?` | `AudioContext` | Provide your own AudioContext instead of letting SuperSonic create one. | |
|
|
832
|
+
| <a id="audiocontextoptions"></a> `audioContextOptions?` | `AudioContextOptions` | Options passed to `new AudioContext()`. Ignored if `audioContext` is provided. | |
|
|
833
|
+
| <a id="autoconnect"></a> `autoConnect?` | `boolean` | Auto-connect the AudioWorkletNode to the AudioContext destination. Default: true. | |
|
|
834
|
+
| <a id="baseurl"></a> `baseURL?` | `string` | Convenience shorthand when all assets (WASM, workers, synthdefs, samples) are co-located. | Yes\* |
|
|
835
|
+
| <a id="buffergrowincrement"></a> `bufferGrowIncrement?` | `number` | Bytes to grow the buffer pool per growth event. Default: 32MB. | |
|
|
836
|
+
| <a id="corebaseurl"></a> `coreBaseURL?` | `string` | Base URL for GPL assets: WASM and AudioWorklet (supersonic-scsynth-core package). Defaults to `baseURL`. | |
|
|
837
|
+
| <a id="debug-1"></a> `debug?` | `boolean` | Enable all debug console logging. Default: false. | |
|
|
838
|
+
| <a id="debugoscin"></a> `debugOscIn?` | `boolean` | Log incoming OSC messages to console. Default: false. | |
|
|
839
|
+
| <a id="debugoscout"></a> `debugOscOut?` | `boolean` | Log outgoing OSC messages to console. Default: false. | |
|
|
840
|
+
| <a id="debugscsynth"></a> `debugScsynth?` | `boolean` | Log scsynth debug output to console. Default: false. | |
|
|
841
|
+
| <a id="fetchmaxretries"></a> `fetchMaxRetries?` | `number` | Max fetch retries when loading assets. Default: 3. | |
|
|
842
|
+
| <a id="fetchretrydelay"></a> `fetchRetryDelay?` | `number` | Base delay between retries in ms (exponential backoff). Default: 1000. | |
|
|
843
|
+
| <a id="maxbuffermemory"></a> `maxBufferMemory?` | `number` | Maximum buffer pool capacity in bytes. Pool grows on demand up to this limit. Default: 256MB. | |
|
|
844
|
+
| <a id="mode-5"></a> `mode?` | [`TransportMode`](#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. | |
|
|
845
|
+
| <a id="samplebaseurl"></a> `sampleBaseURL?` | `string` | Base URL for audio sample files (used by [SuperSonic.loadSample](#loadsample)). | |
|
|
846
|
+
| <a id="scsynthoptions-1"></a> `scsynthOptions?` | [`ScsynthOptions`](#scsynthoptions) | Engine options passed to scsynth World\_New(). | |
|
|
847
|
+
| <a id="snapshotintervalms"></a> `snapshotIntervalMs?` | `number` | How often to snapshot metrics/tree in postMessage mode (ms). | |
|
|
848
|
+
| <a id="synthdefbaseurl"></a> `synthdefBaseURL?` | `string` | Base URL for synthdef files (used by [SuperSonic.loadSynthDef](#loadsynthdef)). | |
|
|
849
|
+
| <a id="wasmbaseurl"></a> `wasmBaseURL?` | `string` | Base URL for WASM files. Defaults to `coreBaseURL + 'wasm/'`. | |
|
|
850
|
+
| <a id="wasmurl"></a> `wasmUrl?` | `string` | Full URL to the WASM binary. Overrides wasmBaseURL. | |
|
|
851
|
+
| <a id="workerbaseurl"></a> `workerBaseURL?` | `string` | Base URL for MIT worker scripts. Defaults to `baseURL + 'workers/'`. | |
|
|
852
|
+
| <a id="workleturl"></a> `workletUrl?` | `string` | Full URL to the AudioWorklet script. Overrides `coreBaseURL`. | |
|
|
1009
853
|
|
|
1010
854
|
*Required unless both `coreBaseURL`/`workerBaseURL` and `wasmBaseURL` are provided.*
|
|
1011
855
|
|
|
@@ -1218,66 +1062,6 @@ For full details on every command (parameters, replies, examples), see the [scsy
|
|
|
1218
1062
|
|
|
1219
1063
|
#### Methods
|
|
1220
1064
|
|
|
1221
|
-
##### cancelAll()
|
|
1222
|
-
|
|
1223
|
-
> **cancelAll**(): `void`
|
|
1224
|
-
|
|
1225
|
-
Cancel all scheduled messages in the JS prescheduler.
|
|
1226
|
-
|
|
1227
|
-
###### Returns
|
|
1228
|
-
|
|
1229
|
-
`void`
|
|
1230
|
-
|
|
1231
|
-
##### cancelSession()
|
|
1232
|
-
|
|
1233
|
-
> **cancelSession**(`sessionId`): `void`
|
|
1234
|
-
|
|
1235
|
-
Cancel all scheduled messages for a session.
|
|
1236
|
-
|
|
1237
|
-
###### Parameters
|
|
1238
|
-
|
|
1239
|
-
| Parameter | Type | Description |
|
|
1240
|
-
| ----------- | -------- | ----------------- |
|
|
1241
|
-
| `sessionId` | `string` | Session to cancel |
|
|
1242
|
-
|
|
1243
|
-
###### Returns
|
|
1244
|
-
|
|
1245
|
-
`void`
|
|
1246
|
-
|
|
1247
|
-
##### cancelSessionTag()
|
|
1248
|
-
|
|
1249
|
-
> **cancelSessionTag**(`sessionId`, `runTag`): `void`
|
|
1250
|
-
|
|
1251
|
-
Cancel scheduled messages matching both a session and run tag.
|
|
1252
|
-
|
|
1253
|
-
###### Parameters
|
|
1254
|
-
|
|
1255
|
-
| Parameter | Type | Description |
|
|
1256
|
-
| ----------- | -------- | -------------------------------- |
|
|
1257
|
-
| `sessionId` | `string` | Session to match |
|
|
1258
|
-
| `runTag` | `string` | Tag to match within that session |
|
|
1259
|
-
|
|
1260
|
-
###### Returns
|
|
1261
|
-
|
|
1262
|
-
`void`
|
|
1263
|
-
|
|
1264
|
-
##### cancelTag()
|
|
1265
|
-
|
|
1266
|
-
> **cancelTag**(`runTag`): `void`
|
|
1267
|
-
|
|
1268
|
-
Cancel all scheduled messages with the given run tag.
|
|
1269
|
-
Only affects messages in the JS prescheduler (not yet dispatched to WASM).
|
|
1270
|
-
|
|
1271
|
-
###### Parameters
|
|
1272
|
-
|
|
1273
|
-
| Parameter | Type | Description |
|
|
1274
|
-
| --------- | -------- | ------------- |
|
|
1275
|
-
| `runTag` | `string` | Tag to cancel |
|
|
1276
|
-
|
|
1277
|
-
###### Returns
|
|
1278
|
-
|
|
1279
|
-
`void`
|
|
1280
|
-
|
|
1281
1065
|
##### createOscChannel()
|
|
1282
1066
|
|
|
1283
1067
|
> **createOscChannel**(`options?`): [`OscChannel`](#oscchannel)
|
|
@@ -1805,11 +1589,8 @@ Unsubscribe function — call it to remove the listener before it fires
|
|
|
1805
1589
|
|
|
1806
1590
|
> **purge**(): `Promise`<`void`>
|
|
1807
1591
|
|
|
1808
|
-
|
|
1809
|
-
|
|
1810
|
-
Unlike [cancelAll](#cancelall) which only clears messages still waiting in JS,
|
|
1811
|
-
`purge()` guarantees that nothing already in-flight will fire either.
|
|
1812
|
-
Resolves when the flush is confirmed complete.
|
|
1592
|
+
Flush all pending scheduled OSC: clears the WASM BundleScheduler and the IN
|
|
1593
|
+
ring so nothing already in-flight will fire. Resolves when confirmed.
|
|
1813
1594
|
|
|
1814
1595
|
###### Returns
|
|
1815
1596
|
|
|
@@ -2100,7 +1881,7 @@ File writing is not available in the browser.
|
|
|
2100
1881
|
|
|
2101
1882
|
###### Deprecated
|
|
2102
1883
|
|
|
2103
|
-
Use purge() to clear
|
|
1884
|
+
Use purge() to clear the WASM BundleScheduler + IN ring.
|
|
2104
1885
|
|
|
2105
1886
|
###### Call Signature
|
|
2106
1887
|
|
|
@@ -3155,7 +2936,7 @@ For 64-bit or timetag types, use the tagged object form:
|
|
|
3155
2936
|
|
|
3156
2937
|
##### sendOSC()
|
|
3157
2938
|
|
|
3158
|
-
> **sendOSC**(`oscData
|
|
2939
|
+
> **sendOSC**(`oscData`): `void`
|
|
3159
2940
|
|
|
3160
2941
|
Send pre-encoded OSC bytes to scsynth.
|
|
3161
2942
|
|
|
@@ -3166,10 +2947,9 @@ Use [send](#send-1) for buffer commands so they are handled correctly.
|
|
|
3166
2947
|
|
|
3167
2948
|
###### Parameters
|
|
3168
2949
|
|
|
3169
|
-
| Parameter
|
|
3170
|
-
|
|
|
3171
|
-
| `oscData`
|
|
3172
|
-
| `options?` | [`SendOSCOptions`](#sendoscoptions) | Optional session/tag for cancellation |
|
|
2950
|
+
| Parameter | Type | Description |
|
|
2951
|
+
| --------- | ------------------------------------------------ | ----------------------------------- |
|
|
2952
|
+
| `oscData` | `ArrayBuffer` \| `Uint8Array`<`ArrayBufferLike`> | Encoded OSC message or bundle bytes |
|
|
3173
2953
|
|
|
3174
2954
|
###### Returns
|
|
3175
2955
|
|
|
@@ -3177,17 +2957,13 @@ Use [send](#send-1) for buffer commands so they are handled correctly.
|
|
|
3177
2957
|
|
|
3178
2958
|
###### Throws
|
|
3179
2959
|
|
|
3180
|
-
If the
|
|
2960
|
+
If the message exceeds the IN ring size
|
|
3181
2961
|
|
|
3182
2962
|
###### Example
|
|
3183
2963
|
|
|
3184
2964
|
```ts
|
|
3185
2965
|
const msg = SuperSonic.osc.encodeMessage('/n_set', [1001, 'freq', 880]);
|
|
3186
2966
|
sonic.sendOSC(msg);
|
|
3187
|
-
|
|
3188
|
-
// With cancellation tags:
|
|
3189
|
-
const bundle = SuperSonic.osc.encodeBundle(futureTime, packets);
|
|
3190
|
-
sonic.sendOSC(bundle, { sessionId: 'song1', runTag: 'verse' });
|
|
3191
2967
|
```
|
|
3192
2968
|
|
|
3193
2969
|
##### setClockOffset()
|
|
@@ -3340,27 +3116,19 @@ OscChannel — unified dispatch for sending OSC to the AudioWorklet.
|
|
|
3340
3116
|
Obtain a channel via [SuperSonic.createOscChannel](#createoscchannel) on the main thread,
|
|
3341
3117
|
then transfer it to a Web Worker for direct communication with the AudioWorklet.
|
|
3342
3118
|
|
|
3343
|
-
| Member | Description
|
|
3344
|
-
| --------------------------------------------- |
|
|
3345
|
-
| [`getCurrentNTP`](#getcurrentntp) | Set the NTP time source for classification (used in AudioWorklet context).
|
|
3346
|
-
| [`mode`](#mode) | Transport mode this channel is using.
|
|
3347
|
-
| [`
|
|
3348
|
-
| [`
|
|
3349
|
-
| [`
|
|
3350
|
-
| [`
|
|
3351
|
-
| [`
|
|
3352
|
-
| [`
|
|
3353
|
-
| [`
|
|
3354
|
-
| [`
|
|
3355
|
-
| [`
|
|
3356
|
-
| [`getMetrics()`](#getmetrics) | Get current metrics snapshot. |
|
|
3357
|
-
| [`nextNodeId()`](#nextnodeid) | Get the next unique node ID. |
|
|
3358
|
-
| [`pollReplies()`](#pollreplies) | Drain pending replies, calling the registered handler (or handler argument, if given) once per message. |
|
|
3359
|
-
| [`send()`](#send) | Send an OSC message with automatic routing. |
|
|
3360
|
-
| [`sendDirect()`](#senddirect) | Send directly to worklet without classification or metrics tracking. |
|
|
3361
|
-
| [`sendToPrescheduler()`](#sendtoprescheduler) | Send to prescheduler without classification. |
|
|
3362
|
-
| [`setReplyHandler()`](#setreplyhandler) | Register a handler for OSC replies from scsynth. |
|
|
3363
|
-
| [`fromTransferable()`](#fromtransferable) | Reconstruct an OscChannel from data received via postMessage in a worker. |
|
|
3119
|
+
| Member | Description |
|
|
3120
|
+
| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
3121
|
+
| [`getCurrentNTP`](#getcurrentntp) | Set the NTP time source for classification (used in AudioWorklet context). |
|
|
3122
|
+
| [`mode`](#mode) | Transport mode this channel is using. |
|
|
3123
|
+
| [`transferable`](#transferable) | Serializable config for transferring this channel to a worker via postMessage. |
|
|
3124
|
+
| [`transferList`](#transferlist) | Array of transferable objects (MessagePorts) for the postMessage transfer list. |
|
|
3125
|
+
| [`close()`](#close) | Close the channel and release its ports. |
|
|
3126
|
+
| [`getAndResetMetrics()`](#getandresetmetrics) | Get and reset local metrics (for periodic reporting). |
|
|
3127
|
+
| [`getMetrics()`](#getmetrics) | Get current metrics snapshot. |
|
|
3128
|
+
| [`nextNodeId()`](#nextnodeid) | Get the next unique node ID. |
|
|
3129
|
+
| [`send()`](#send) | Send an OSC message: frames it onto the IN ring (SAB) or postMessages it to the worklet (PM). |
|
|
3130
|
+
| [`sendDirect()`](#senddirect) | Alias of send — kept for callers that used the explicit direct path. |
|
|
3131
|
+
| [`fromTransferable()`](#fromtransferable) | Reconstruct an OscChannel from data received via postMessage in a worker. |
|
|
3364
3132
|
|
|
3365
3133
|
#### Example
|
|
3366
3134
|
|
|
@@ -3424,20 +3192,6 @@ Transport mode this channel is using.
|
|
|
3424
3192
|
|
|
3425
3193
|
[`TransportMode`](#transportmode)
|
|
3426
3194
|
|
|
3427
|
-
##### replyDrops
|
|
3428
|
-
|
|
3429
|
-
###### Get Signature
|
|
3430
|
-
|
|
3431
|
-
> **get** **replyDrops**(): `number`
|
|
3432
|
-
|
|
3433
|
-
Number of reply messages dropped because the reply buffer was full.
|
|
3434
|
-
SAB mode only — undefined in PM mode or before [activateReplies](#activatereplies).
|
|
3435
|
-
Counter resets each time the slot is (re)claimed.
|
|
3436
|
-
|
|
3437
|
-
###### Returns
|
|
3438
|
-
|
|
3439
|
-
`number`
|
|
3440
|
-
|
|
3441
3195
|
##### transferable
|
|
3442
3196
|
|
|
3443
3197
|
###### Get Signature
|
|
@@ -3478,45 +3232,6 @@ worker.postMessage({ ch: channel.transferable }, channel.transferList);
|
|
|
3478
3232
|
|
|
3479
3233
|
#### Methods
|
|
3480
3234
|
|
|
3481
|
-
##### activateReplies()
|
|
3482
|
-
|
|
3483
|
-
> **activateReplies**(): `void`
|
|
3484
|
-
|
|
3485
|
-
Activate the reply slot without registering a handler. Usually called
|
|
3486
|
-
for you by [setReplyHandler](#setreplyhandler); only call directly if you want to
|
|
3487
|
-
claim the slot before installing a handler (or to use the optional
|
|
3488
|
-
one-shot handler argument of [pollReplies](#pollreplies)).
|
|
3489
|
-
|
|
3490
|
-
###### Returns
|
|
3491
|
-
|
|
3492
|
-
`void`
|
|
3493
|
-
|
|
3494
|
-
##### classify()
|
|
3495
|
-
|
|
3496
|
-
> **classify**(`oscData`): [`OscCategory`](#osccategory)
|
|
3497
|
-
|
|
3498
|
-
Classify an OSC message to determine its routing.
|
|
3499
|
-
|
|
3500
|
-
###### Parameters
|
|
3501
|
-
|
|
3502
|
-
| Parameter | Type | Description |
|
|
3503
|
-
| --------- | ------------ | ----------------- |
|
|
3504
|
-
| `oscData` | `Uint8Array` | Encoded OSC bytes |
|
|
3505
|
-
|
|
3506
|
-
###### Returns
|
|
3507
|
-
|
|
3508
|
-
[`OscCategory`](#osccategory)
|
|
3509
|
-
|
|
3510
|
-
##### clearReplyHandler()
|
|
3511
|
-
|
|
3512
|
-
> **clearReplyHandler**(): `void`
|
|
3513
|
-
|
|
3514
|
-
Clear the reply handler and release the reply channel. Idempotent.
|
|
3515
|
-
|
|
3516
|
-
###### Returns
|
|
3517
|
-
|
|
3518
|
-
`void`
|
|
3519
|
-
|
|
3520
3235
|
##### close()
|
|
3521
3236
|
|
|
3522
3237
|
> **close**(): `void`
|
|
@@ -3527,16 +3242,6 @@ Close the channel and release its ports.
|
|
|
3527
3242
|
|
|
3528
3243
|
`void`
|
|
3529
3244
|
|
|
3530
|
-
##### deactivateReplies()
|
|
3531
|
-
|
|
3532
|
-
> **deactivateReplies**(): `void`
|
|
3533
|
-
|
|
3534
|
-
Release the reply slot. Usually called for you by [clearReplyHandler](#clearreplyhandler).
|
|
3535
|
-
|
|
3536
|
-
###### Returns
|
|
3537
|
-
|
|
3538
|
-
`void`
|
|
3539
|
-
|
|
3540
3245
|
##### getAndResetMetrics()
|
|
3541
3246
|
|
|
3542
3247
|
> **getAndResetMetrics**(): [`OscChannelMetrics`](#oscchannelmetrics)
|
|
@@ -3573,40 +3278,13 @@ the root group, 1 is the default group, 2–999 are reserved for manual use).
|
|
|
3573
3278
|
|
|
3574
3279
|
A unique node ID (>= 1000)
|
|
3575
3280
|
|
|
3576
|
-
##### pollReplies()
|
|
3577
|
-
|
|
3578
|
-
> **pollReplies**(`handler?`): `number`
|
|
3579
|
-
|
|
3580
|
-
Drain pending replies, calling the registered handler (or `handler`
|
|
3581
|
-
argument, if given) once per message. Returns the number of messages
|
|
3582
|
-
processed. Zero-allocation on the hot path.
|
|
3583
|
-
|
|
3584
|
-
Call from an AudioWorklet's `process()` method to receive replies on
|
|
3585
|
-
the audio thread. In other contexts automatic delivery already calls
|
|
3586
|
-
this for you.
|
|
3587
|
-
|
|
3588
|
-
###### Parameters
|
|
3589
|
-
|
|
3590
|
-
| Parameter | Type | Description |
|
|
3591
|
-
| ---------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
|
|
3592
|
-
| `handler?` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) | Optional override for this call only |
|
|
3593
|
-
|
|
3594
|
-
###### Returns
|
|
3595
|
-
|
|
3596
|
-
`number`
|
|
3597
|
-
|
|
3598
|
-
Number of messages drained
|
|
3599
|
-
|
|
3600
3281
|
##### send()
|
|
3601
3282
|
|
|
3602
3283
|
> **send**(`oscData`): `boolean`
|
|
3603
3284
|
|
|
3604
|
-
Send an OSC message
|
|
3605
|
-
|
|
3606
|
-
|
|
3607
|
-
|
|
3608
|
-
* bypass categories → sent directly to the AudioWorklet
|
|
3609
|
-
* far-future bundles → routed to the prescheduler for timed dispatch
|
|
3285
|
+
Send an OSC message: frames it onto the IN ring (SAB) or postMessages it to
|
|
3286
|
+
the worklet (PM). Classification and scheduling happen on the audio thread
|
|
3287
|
+
(the engine's OscIngress + BundleScheduler) — the producer never classifies.
|
|
3610
3288
|
|
|
3611
3289
|
###### Parameters
|
|
3612
3290
|
|
|
@@ -3624,25 +3302,7 @@ true if sent successfully
|
|
|
3624
3302
|
|
|
3625
3303
|
> **sendDirect**(`oscData`): `boolean`
|
|
3626
3304
|
|
|
3627
|
-
|
|
3628
|
-
|
|
3629
|
-
###### Parameters
|
|
3630
|
-
|
|
3631
|
-
| Parameter | Type | Description |
|
|
3632
|
-
| --------- | ------------ | ----------------- |
|
|
3633
|
-
| `oscData` | `Uint8Array` | Encoded OSC bytes |
|
|
3634
|
-
|
|
3635
|
-
###### Returns
|
|
3636
|
-
|
|
3637
|
-
`boolean`
|
|
3638
|
-
|
|
3639
|
-
true if sent successfully
|
|
3640
|
-
|
|
3641
|
-
##### sendToPrescheduler()
|
|
3642
|
-
|
|
3643
|
-
> **sendToPrescheduler**(`oscData`): `boolean`
|
|
3644
|
-
|
|
3645
|
-
Send to prescheduler without classification.
|
|
3305
|
+
Alias of [send](#send) — kept for callers that used the explicit direct path.
|
|
3646
3306
|
|
|
3647
3307
|
###### Parameters
|
|
3648
3308
|
|
|
@@ -3656,40 +3316,6 @@ Send to prescheduler without classification.
|
|
|
3656
3316
|
|
|
3657
3317
|
true if sent successfully
|
|
3658
3318
|
|
|
3659
|
-
##### setReplyHandler()
|
|
3660
|
-
|
|
3661
|
-
> **setReplyHandler**(`handler`): `void`
|
|
3662
|
-
|
|
3663
|
-
Register a handler for OSC replies from scsynth. Idempotent — replaces
|
|
3664
|
-
any previously-registered handler. In AudioWorklet contexts the worklet
|
|
3665
|
-
must call [pollReplies](#pollreplies) from `process()` to drain; in all other
|
|
3666
|
-
contexts delivery is automatic. All registered channels receive all
|
|
3667
|
-
replies (broadcast); filter locally if you only need specific addresses.
|
|
3668
|
-
|
|
3669
|
-
SAB mode: handler receives `(view, offset, length, sequence)` — zero-copy
|
|
3670
|
-
into the shared buffer. Read bytes from `view[offset..offset+length]`.
|
|
3671
|
-
Data is valid only for the duration of the handler call.
|
|
3672
|
-
|
|
3673
|
-
PM mode: handler receives `(oscData, sequence)` where `oscData` is a copy.
|
|
3674
|
-
|
|
3675
|
-
###### Parameters
|
|
3676
|
-
|
|
3677
|
-
| Parameter | Type |
|
|
3678
|
-
| --------- | ------------------------------------------------------------------------------------------- |
|
|
3679
|
-
| `handler` | ((`view`, `offset`, `length`, `sequence`) => `void`) \| ((`oscData`, `sequence`) => `void`) |
|
|
3680
|
-
|
|
3681
|
-
###### Returns
|
|
3682
|
-
|
|
3683
|
-
`void`
|
|
3684
|
-
|
|
3685
|
-
###### Example
|
|
3686
|
-
|
|
3687
|
-
```ts
|
|
3688
|
-
channel.setReplyHandler((view, offset, length, sequence) => {
|
|
3689
|
-
// SAB: read raw OSC bytes from view[offset..offset+length]
|
|
3690
|
-
});
|
|
3691
|
-
```
|
|
3692
|
-
|
|
3693
3319
|
##### fromTransferable()
|
|
3694
3320
|
|
|
3695
3321
|
> `static` **fromTransferable**(`data`): [`OscChannel`](#oscchannel)
|