@effetune/dsp 0.0.0

package/dist/worklet-processor.js

@@ -0,0 +1,175 @@
+import { createEngineSession } from './engine.js';
+import { errorMessage } from './errors.js';
+import { countTelemetryFrames, TELEMETRY_RING_BYTES } from './telemetry.js';
+
+class EffeTuneDspProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.session = null;
+    this.ready = false;
+    this.closed = false;
+    this.channels = 0;
+    this.pendingCommands = [];
+    this.sourceChannels = [];
+    this.targetChannels = [];
+    this.telemetryEnabled = false;
+    this.telemetryPackets = Array.from(
+      { length: 4 },
+      () => new ArrayBuffer(TELEMETRY_RING_BYTES)
+    );
+    this.telemetryDiscardPacket = new Uint8Array(TELEMETRY_RING_BYTES);
+    this.telemetryDropped = 0;
+    this.port.onmessage = event => this.handleMessage(event.data);
+  }
+
+  handleMessage(message) {
+    if (message?.type === 'initialize') {
+      this.initialize(message);
+      return;
+    }
+    if (message?.type === 'close') {
+      this.closed = true;
+      this.session?.close();
+      this.session = null;
+      return;
+    }
+    if (message?.type === 'telemetryReturn') {
+      if (message.packet instanceof ArrayBuffer &&
+          message.packet.byteLength === TELEMETRY_RING_BYTES) {
+        this.telemetryPackets.push(message.packet);
+      }
+      return;
+    }
+    if (message?.type === 'setParam' || message?.type === 'reset' ||
+        message?.type === 'setTelemetryEnabled') {
+      this.pendingCommands.push(message);
+    }
+  }
+
+  async initialize(message) {
+    try {
+      this.channels = message.channels;
+      this.sourceChannels = new Array(this.channels);
+      this.targetChannels = new Array(this.channels);
+      const active = message.document.chain.some(effect => effect.enabled);
+      if (active) {
+        this.session = await createEngineSession(
+          { bytes: message.wasmBytes },
+          message.document.chain,
+          message.resolvedAssets,
+          {
+            sampleRate,
+            channels: message.channels,
+            maxFrames: 128,
+            seed: message.seed
+          }
+        );
+      }
+      this.ready = true;
+      this.port.postMessage({ type: 'ready' });
+    } catch (error) {
+      this.port.postMessage({
+        type: 'initializationError',
+        ...errorMessage(
+          error,
+          'The AudioWorklet DSP processor could not be initialized.'
+        )
+      });
+    }
+  }
+
+  applyCommands() {
+    for (const command of this.pendingCommands.splice(0)) {
+      try {
+        if (command.type === 'setParam') {
+          this.session?.setPacked(
+            command.effectId,
+            command.values,
+            command.hash,
+            command.bytes
+          );
+        } else if (command.type === 'reset') {
+          this.session?.reset();
+        } else if (command.type === 'setTelemetryEnabled') {
+          this.telemetryEnabled = command.enabled === true;
+          this.session?.setTelemetryEnabled(this.telemetryEnabled);
+          continue;
+        }
+        this.port.postMessage({ type: 'commandResult', commandId: command.commandId, ok: true });
+      } catch (error) {
+        this.port.postMessage({
+          type: 'commandResult',
+          commandId: command.commandId,
+          ok: false,
+          ...errorMessage(error, 'The AudioWorklet command failed.')
+        });
+      }
+    }
+  }
+
+  drainTelemetry() {
+    if (!this.session || !this.telemetryEnabled) return;
+    const buffer = this.telemetryPackets.pop();
+    const packet = buffer ? new Uint8Array(buffer) : this.telemetryDiscardPacket;
+    const { bytes, dropped } = this.session.readTelemetryPacket(packet);
+    if (!buffer) {
+      this.telemetryDropped += dropped + countTelemetryFrames(packet, bytes);
+      return;
+    }
+    if (bytes === 0) {
+      this.telemetryDropped += dropped;
+      this.telemetryPackets.push(buffer);
+      return;
+    }
+    this.port.postMessage({
+      type: 'telemetry',
+      packet: buffer,
+      bytes,
+      dropped: this.telemetryDropped + dropped
+    }, [buffer]);
+    this.telemetryDropped = 0;
+  }
+
+  passthrough(input, output) {
+    for (let channel = 0; channel < output.length; channel++) {
+      const source = input[channel];
+      if (source) output[channel].set(source);
+      else output[channel].fill(0);
+    }
+  }
+
+  process(inputs, outputs) {
+    if (this.closed) return false;
+    const input = inputs[0] ?? [];
+    const output = outputs[0] ?? [];
+    if (!this.ready) {
+      this.passthrough(input, output);
+      return true;
+    }
+    this.applyCommands();
+    if (!this.session) {
+      this.passthrough(input, output);
+      return true;
+    }
+    for (let channel = 0; channel < this.channels; channel++) {
+      this.sourceChannels[channel] = input[channel] ?? output[channel];
+      this.targetChannels[channel] = output[channel];
+    }
+    try {
+      this.session.process(this.sourceChannels, this.targetChannels, 0, 128, sampleRate);
+      this.drainTelemetry();
+    } catch (error) {
+      this.session.close();
+      this.session = null;
+      for (const channel of output) channel.fill(0);
+      this.port.postMessage({
+        type: 'processingError',
+        ...errorMessage(error, 'Audio processing failed.')
+      });
+      return false;
+    }
+    return true;
+  }
+}
+
+registerProcessor('effetune-dsp-processor', EffeTuneDspProcessor);

package/dist/worklet.d.ts

@@ -0,0 +1,32 @@
+import type {
+  ArtifactOptions,
+  AssetResolver,
+  BundleDocument,
+  ChainDocumentInput,
+  ChainEffectInput,
+  TelemetryCallback
+} from './index.js';
+import type { Effect } from './effect.js';
+
+export interface EffeTuneNodeOptions extends ArtifactOptions {
+  readonly channels?: number;
+  readonly seed?: number;
+  readonly assetResolver?: AssetResolver | { resolve: AssetResolver };
+  readonly processorUrl?: string | URL;
+}
+
+export declare class EffeTuneNode extends AudioWorkletNode {
+  private constructor();
+  static create(
+    context: BaseAudioContext,
+    input: string | ChainDocumentInput | BundleDocument |
+      readonly (Effect | ChainEffectInput)[],
+    options?: EffeTuneNodeOptions
+  ): Promise<EffeTuneNode>;
+  readonly droppedTelemetryFrames: number;
+  subscribe(callback: TelemetryCallback): () => void;
+  unsubscribe(callback: TelemetryCallback): boolean;
+  setParam(effectId: string, parameterName: string, value: unknown): Promise<void>;
+  reset(): Promise<void>;
+  close(): void;
+}

package/dist/worklet.js

@@ -0,0 +1,386 @@
+import { loadDspArtifact } from './artifacts.js';
+import { resolveChainAssets, splitBundle } from './assets.js';
+import {
+  EffeTuneRuntimeError,
+  errorFromMessage,
+  StateError,
+  ValidationError
+} from './errors.js';
+import {
+  normalizeChainDocument,
+  channelRange,
+  packEffect,
+  setEffectParameter,
+  validateStreamParameterUpdate,
+  validateEffectSampleRate,
+  validateSeed
+} from './semantics.js';
+import { decodeTelemetryPacket } from './telemetry.js';
+
+const PROCESSOR_NAME = 'effetune-dsp-processor';
+const AudioWorkletNodeBase = globalThis.AudioWorkletNode ?? class {};
+const moduleLoads = new WeakMap();
+
+function activeEffects(document) {
+  return document.chain.filter(effect => effect.enabled);
+}
+
+function cloneDocument(document) {
+  return {
+    version: 1,
+    chain: document.chain.map(effect => ({
+      ...effect,
+      parameters: Object.fromEntries(
+        Object.entries(effect.parameters).map(([name, value]) => [
+          name,
+          Array.isArray(value) ? [...value] : value
+        ])
+      ),
+      ...(effect.assets ? { assets: { ...effect.assets } } : {})
+    }))
+  };
+}
+
+function validateChannels(channels) {
+  if (!Number.isInteger(channels) || channels < 1 || channels > 8) {
+    throw new ValidationError('channels must be an integer from 1 to 8.');
+  }
+  return channels;
+}
+
+function loadProcessorModule(context, processorUrl) {
+  if (!context?.audioWorklet || typeof context.audioWorklet.addModule !== 'function') {
+    throw new ValidationError('An AudioContext with AudioWorklet support is required.');
+  }
+  let byUrl = moduleLoads.get(context.audioWorklet);
+  if (!byUrl) {
+    byUrl = new Map();
+    moduleLoads.set(context.audioWorklet, byUrl);
+  }
+  const key = String(processorUrl);
+  if (!byUrl.has(key)) {
+    let load;
+    try {
+      load = Promise.resolve(context.audioWorklet.addModule(processorUrl));
+    } catch (error) {
+      throw new EffeTuneRuntimeError(
+        'Unable to load the AudioWorklet DSP processor module.',
+        { cause: error }
+      );
+    }
+    const cached = load.catch(error => {
+      if (byUrl.get(key) === cached) byUrl.delete(key);
+      throw new EffeTuneRuntimeError(
+        'Unable to load the AudioWorklet DSP processor module.',
+        { cause: error }
+      );
+    });
+    byUrl.set(key, cached);
+  }
+  return byUrl.get(key);
+}
+
+function validateProcessorUrl(value) {
+  const url = value instanceof URL ? value : new URL(String(value), import.meta.url);
+  if (!['file:', 'https:', 'http:'].includes(url.protocol)) {
+    throw new ValidationError(`Unsupported AudioWorklet processor URL scheme: ${url.protocol}`);
+  }
+  if (url.protocol === 'http:') {
+    const moduleUrl = new URL(import.meta.url);
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (!local && url.origin !== moduleUrl.origin) {
+      throw new ValidationError('Cross-origin AudioWorklet processors must use HTTPS.');
+    }
+  }
+  return url;
+}
+
+function cloneAssetsForWorklet(resolvedAssets) {
+  const cloned = new Map();
+  const transfer = [];
+  for (const [effectId, assets] of resolvedAssets) {
+    const values = {};
+    for (const [name, asset] of Object.entries(assets)) {
+      const bytes = new Uint8Array(asset.bytes);
+      values[name] = { ...asset, bytes };
+      transfer.push(bytes.buffer);
+    }
+    cloned.set(effectId, values);
+  }
+  return { cloned, transfer };
+}
+
+export class EffeTuneNode extends AudioWorkletNodeBase {
+  static async create(context, input, options = {}) {
+    const channels = validateChannels(options.channels ?? 2);
+    const seed = validateSeed(options.seed ?? 0);
+    const source = typeof input === 'string'
+      ? (() => {
+          try {
+            return JSON.parse(input);
+          } catch (error) {
+            throw new ValidationError('Chain input is not valid JSON.', { cause: error });
+          }
+        })()
+      : input;
+    const { chain, manifest } = splitBundle(source);
+    const document = normalizeChainDocument(chain);
+    const resolvedAssets = await resolveChainAssets(document, {
+      assetResolver: options.assetResolver,
+      manifest
+    });
+    for (const effect of activeEffects(document)) {
+      validateEffectSampleRate(effect, context.sampleRate);
+      channelRange(effect.channel, channels);
+    }
+
+    const processorUrl = validateProcessorUrl(
+      options.processorUrl ?? new URL('./worklet-processor.js', import.meta.url)
+    );
+    await loadProcessorModule(context, processorUrl);
+    const artifact = activeEffects(document).length > 0
+      ? await loadDspArtifact({
+          variant: options.variant,
+          wasmUrl: options.wasmUrl,
+          simdWasmUrl: options.simdWasmUrl,
+          metaUrl: options.metaUrl,
+          fetch: options.fetch,
+          webAssembly: options.webAssembly,
+          cache: options.cache
+        })
+      : null;
+    const node = new EffeTuneNode(context, channels, document, seed);
+    const wasmBytes = artifact ? artifact.bytes.slice(0) : null;
+    const assets = cloneAssetsForWorklet(resolvedAssets);
+    const transfer = [...assets.transfer, ...(wasmBytes ? [wasmBytes] : [])];
+    node.port.postMessage({
+      type: 'initialize',
+      document,
+      resolvedAssets: assets.cloned,
+      wasmBytes,
+      channels,
+      seed
+    }, transfer);
+    try {
+      await node._waitUntilReady();
+      return node;
+    } catch (error) {
+      node.close();
+      throw error;
+    }
+  }
+
+  constructor(context, channels, document, seed) {
+    super(context, PROCESSOR_NAME, {
+      numberOfInputs: 1,
+      numberOfOutputs: 1,
+      outputChannelCount: [channels],
+      channelCount: channels,
+      channelCountMode: 'explicit',
+      channelInterpretation: 'discrete'
+    });
+    this._initialDocument = cloneDocument(document);
+    this._document = cloneDocument(document);
+    this._seed = seed;
+    this._closed = false;
+    this._runtimeError = null;
+    this._nextCommandId = 1;
+    this._pending = new Map();
+    this._telemetryCallbacks = new Set();
+    this._telemetryPendingDropped = 0;
+    this._droppedTelemetryFrames = 0;
+    let tapId = 1;
+    this._telemetryNodesByTap = new Map();
+    for (const [effectIndex, effect] of document.chain.entries()) {
+      if (!effect.enabled) continue;
+      this._telemetryNodesByTap.set(tapId++, {
+        effectType: effect.type,
+        effectId: effect.id,
+        effectIndex
+      });
+    }
+    this._mutationQueue = Promise.resolve();
+    this._ready = new Promise((resolve, reject) => {
+      this._resolveReady = resolve;
+      this._rejectReady = reject;
+    });
+    this.port.onmessage = event => this._handleMessage(event.data);
+    this.port.start?.();
+  }
+
+  _handleMessage(message) {
+    if (message?.type === 'telemetry') {
+      const packet = message.packet;
+      const dropped = Number.isInteger(message.dropped) && message.dropped >= 0
+        ? message.dropped
+        : 0;
+      this._droppedTelemetryFrames += dropped;
+      if (packet instanceof ArrayBuffer) {
+        const decoded = decodeTelemetryPacket(
+          new Uint8Array(packet),
+          message.bytes,
+          this._telemetryNodesByTap,
+          this._telemetryPendingDropped + dropped
+        );
+        this._telemetryPendingDropped = decoded.pendingDropped;
+        for (const frame of decoded.frames) {
+          for (const callback of this._telemetryCallbacks) {
+            try {
+              callback(frame);
+            } catch (error) {
+              console.warn('EffeTune telemetry callback failed.', error);
+            }
+          }
+        }
+        this.port.postMessage({ type: 'telemetryReturn', packet }, [packet]);
+      }
+      return;
+    }
+    if (message?.type === 'ready') {
+      this._resolveReady();
+      return;
+    }
+    if (message?.type === 'initializationError') {
+      this._rejectReady(errorFromMessage(
+        message.errorType,
+        message.message,
+        'The AudioWorklet DSP processor could not be initialized.'
+      ));
+      return;
+    }
+    if (message?.type === 'processingError') {
+      const error = errorFromMessage(
+        message.errorType,
+        message.message,
+        'The AudioWorklet DSP processor stopped after a processing error.'
+      );
+      this._runtimeError = error;
+      for (const pending of this._pending.values()) pending.reject(error);
+      this._pending.clear();
+      this.dispatchEvent?.(new Event('processorerror'));
+      return;
+    }
+    if (message?.type !== 'commandResult') return;
+    const pending = this._pending.get(message.commandId);
+    if (!pending) return;
+    this._pending.delete(message.commandId);
+    if (message.ok) pending.resolve();
+    else pending.reject(errorFromMessage(
+      message.errorType,
+      message.message,
+      'The AudioWorklet command failed.'
+    ));
+  }
+
+  async _waitUntilReady() {
+    const timeout = new Promise((_, reject) => {
+      const timer = setTimeout(() => {
+        reject(errorFromMessage(
+          'EffeTuneRuntimeError',
+          undefined,
+          'Timed out while initializing the AudioWorklet DSP processor.'
+        ));
+      }, 10000);
+      this._ready.then(
+        () => clearTimeout(timer),
+        () => clearTimeout(timer)
+      );
+    });
+    return Promise.race([this._ready, timeout]);
+  }
+
+  _assertOpen() {
+    if (this._closed) throw new StateError('The EffeTuneNode is closed.');
+    if (this._runtimeError) throw this._runtimeError;
+  }
+
+  _command(command) {
+    this._assertOpen();
+    const commandId = this._nextCommandId++;
+    const promise = new Promise((resolve, reject) => {
+      this._pending.set(commandId, { resolve, reject });
+    });
+    this.port.postMessage({ ...command, commandId });
+    return promise;
+  }
+
+  _mutate(operation) {
+    const result = this._mutationQueue.then(operation);
+    this._mutationQueue = result.catch(() => {});
+    return result;
+  }
+
+  get droppedTelemetryFrames() {
+    this._assertOpen();
+    return this._droppedTelemetryFrames;
+  }
+
+  subscribe(callback) {
+    this._assertOpen();
+    if (typeof callback !== 'function') {
+      throw new TypeError('Telemetry callback must be a function.');
+    }
+    const wasEmpty = this._telemetryCallbacks.size === 0;
+    this._telemetryCallbacks.add(callback);
+    if (wasEmpty) {
+      this.port.postMessage({ type: 'setTelemetryEnabled', enabled: true });
+    }
+    return () => this.unsubscribe(callback);
+  }
+
+  unsubscribe(callback) {
+    this._assertOpen();
+    const removed = this._telemetryCallbacks.delete(callback);
+    if (removed && this._telemetryCallbacks.size === 0) {
+      this.port.postMessage({ type: 'setTelemetryEnabled', enabled: false });
+    }
+    return removed;
+  }
+
+  setParam(effectId, parameterName, value) {
+    return this._mutate(async () => {
+      this._assertOpen();
+      const index = this._document.chain.findIndex(effect => effect.id === effectId);
+      if (index < 0) throw new ValidationError(`Unknown effect id: ${effectId}`);
+      const effects = [...this._document.chain];
+      validateStreamParameterUpdate(effects[index], parameterName);
+      effects[index] = setEffectParameter(effects[index], parameterName, value);
+      if (effects[index].enabled) {
+        const packed = packEffect(effects[index]);
+        await this._command({
+          type: 'setParam',
+          effectId,
+          values: packed.values,
+          hash: packed.hash,
+          bytes: packed.bytes
+        });
+      }
+      this._document = { version: 1, chain: effects };
+    });
+  }
+
+  reset() {
+    return this._mutate(async () => {
+      this._assertOpen();
+      await this._command({ type: 'reset' });
+      this._document = cloneDocument(this._initialDocument);
+    });
+  }
+
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this._telemetryCallbacks.clear();
+    this.port.postMessage({ type: 'close' });
+    for (const pending of this._pending.values()) {
+      pending.reject(new StateError('The EffeTuneNode was closed before its command completed.'));
+    }
+    this._pending.clear();
+    this.port.onmessage = null;
+    try {
+      this.disconnect();
+    } catch {
+      // Already disconnected.
+    }
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@effetune/dsp",
+  "version": "0.0.0",
+  "description": "EffeTune's deterministic WebAssembly audio effects for JavaScript and AudioWorklet",
+  "type": "module",
+  "license": "MIT",
+  "author": "Yoshiyuki Kobayashi",
+  "homepage": "https://effetune.frieve.com/dsp/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Frieve-A/effetune",
+    "directory": "dsp/bindings/js"
+  },
+  "bugs": {
+    "url": "https://github.com/Frieve-A/effetune/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": [
+    "./dist/worklet-processor.js"
+  ],
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md",
+    "THIRD_PARTY_NOTICES.txt"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./worklet": {
+      "types": "./dist/worklet.d.ts",
+      "import": "./dist/worklet.js"
+    },
+    "./processor": "./dist/worklet-processor.js",
+    "./schemas/chain-v1.json": "./dist/schemas/chain-v1.schema.json",
+    "./schemas/bundle-v1.json": "./dist/schemas/bundle-v1.schema.json",
+    "./catalog": {
+      "types": "./dist/catalog-entry.d.ts",
+      "import": "./dist/catalog-entry.js"
+    },
+    "./catalog.json": "./dist/catalog/effects-v1.json"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "pack:check": "node scripts/verify-pack.mjs",
+    "install:check": "node scripts/verify-install.mjs"
+  }
+}