@effetune/dsp 0.0.0

package/dist/catalog-entry.d.ts

@@ -0,0 +1,9 @@
+import type { EffectChannel } from './generated-effects.js';
+
+export declare function getEffectCatalog(): Readonly<{
+  version: 1;
+  channels: readonly EffectChannel[];
+  effects: readonly Readonly<Record<string, unknown>>[];
+}>;
+
+export declare const EFFECT_CATALOG: ReturnType<typeof getEffectCatalog>;

package/dist/catalog-entry.js

@@ -0,0 +1,5 @@
+export { getEffectCatalog } from './catalog.js';
+
+import { getEffectCatalog } from './catalog.js';
+
+export const EFFECT_CATALOG = getEffectCatalog();

package/dist/catalog.js

@@ -0,0 +1,50 @@
+import * as generated from './generated-effects.js';
+import { EffectError } from './errors.js';
+
+let publicCatalog;
+let publicByType;
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function metadata() {
+  const value = generated.EFFECT_METADATA;
+  if (!value || value.version !== 1 || !Array.isArray(value.effects)) {
+    throw new EffectError('The effect catalog is unavailable or incompatible.');
+  }
+  return value;
+}
+
+function ensureCatalog() {
+  if (!publicCatalog) {
+    publicCatalog = deepFreeze(cloneJson(metadata()));
+    publicByType = new Map(publicCatalog.effects.map(effect => [effect.type, effect]));
+  }
+  return publicCatalog;
+}
+
+export function getEffectCatalog() {
+  return ensureCatalog();
+}
+
+export function getEffectDefinition(type) {
+  ensureCatalog();
+  const effect = publicByType.get(type);
+  if (!effect) throw new EffectError(`Unknown effect type: ${String(type)}`);
+  return effect;
+}
+
+export function getEffectImplementation(type) {
+  const implementation = generated._EFFECT_IMPLEMENTATION?.[type];
+  if (!implementation) {
+    throw new EffectError(`The ${String(type)} effect is unavailable in this build.`);
+  }
+  return implementation;
+}

package/dist/effect.d.ts

@@ -0,0 +1,23 @@
+import type { EffectChannel, EffectType } from './generated-effects.js';
+
+export declare const EFFECT_CHANNELS: readonly EffectChannel[];
+
+export declare class Effect {
+  readonly type: EffectType;
+  readonly id?: string;
+  readonly enabled: boolean;
+  readonly channel: EffectChannel;
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly assets?: Readonly<Record<string, string>>;
+  constructor(type: EffectType, options?: Readonly<Record<string, unknown>>);
+  toJSON(): EffectDefinition;
+}
+
+export interface EffectDefinition {
+  readonly id?: string;
+  readonly type: EffectType;
+  readonly enabled?: boolean;
+  readonly channel?: EffectChannel;
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly assets?: Readonly<Record<string, string>>;
+}

package/dist/effect.js

@@ -0,0 +1,167 @@
+import { AssetError, ValidationError } from './errors.js';
+
+export const EFFECT_CHANNELS = Object.freeze([
+  'all', 'stereo', 'left', 'right',
+  '1', '2', '3', '4', '5', '6', '7', '8',
+  '34', '56', '78'
+]);
+
+const COMMON_KEYS = new Set(['id', 'enabled', 'channel', 'assets', 'parameters']);
+const CHANNEL_SET = new Set(EFFECT_CHANNELS);
+const ASSET_NAMES_BY_EFFECT = new Map([
+  ['FIRCrossover', ['impulseResponse']],
+  ['FiveBandFIRPEQ', ['impulseResponse']],
+  ['GroupDelayEQ', ['impulseResponse']],
+  ['IRReverb', ['impulseResponse']],
+  ['RoomEQ', ['impulseResponse']]
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateId(id) {
+  if (id === undefined) return undefined;
+  if (typeof id !== 'string' || id.length < 1 || id.length > 128) {
+    throw new ValidationError('Effect id must contain between 1 and 128 characters.');
+  }
+  return id;
+}
+
+export function validateChannel(channel = 'all') {
+  if (!CHANNEL_SET.has(channel)) {
+    throw new ValidationError(`Unsupported effect channel: ${String(channel)}`);
+  }
+  return channel;
+}
+
+export function validateParameterValue(effectType, definition, value) {
+  const label = `${effectType}.${definition.name}`;
+  const values = definition.count > 1 ? value : [value];
+  if (definition.count > 1 &&
+      (!Array.isArray(value) || value.length !== definition.count)) {
+    throw new ValidationError(`${label} must contain exactly ${definition.count} values.`);
+  }
+
+  for (const item of values) {
+    if (definition.type === 'number' || definition.type === 'integer') {
+      if (typeof item !== 'number' || !Number.isFinite(item) ||
+          (definition.type === 'integer' && !Number.isInteger(item))) {
+        throw new ValidationError(`${label} must be ${definition.type === 'integer' ? 'an integer' : 'a finite number'}.`);
+      }
+      if (definition.minimum !== undefined && item < definition.minimum) {
+        throw new ValidationError(`${label} must be at least ${definition.minimum}.`);
+      }
+      if (definition.maximum !== undefined && item > definition.maximum) {
+        throw new ValidationError(`${label} must be at most ${definition.maximum}.`);
+      }
+    } else if (definition.type === 'string') {
+      if (typeof item !== 'string') {
+        throw new ValidationError(`${label} must be a string.`);
+      }
+      if (definition.maximumLength !== undefined && item.length > definition.maximumLength) {
+        throw new ValidationError(
+          `${label} must contain at most ${definition.maximumLength} characters.`
+        );
+      }
+      if (definition.pattern !== undefined) {
+        const match = new RegExp(definition.pattern, 'u').exec(item);
+        if (match?.[0] !== item) {
+          const example = typeof definition.default === 'string'
+            ? ` (for example '${definition.default}')`
+            : '';
+          throw new ValidationError(
+            `${label} has an invalid format; expected a string matching ${definition.pattern}${example}.`
+          );
+        }
+      }
+    } else if (definition.type === 'boolean' && typeof item !== 'boolean') {
+      throw new ValidationError(`${label} must be a boolean.`);
+    }
+    if (definition.values && !definition.values.some(allowed => Object.is(allowed, item))) {
+      throw new ValidationError(`${label} has an unsupported value.`);
+    }
+  }
+  return Array.isArray(value) ? Object.freeze([...value]) : value;
+}
+
+function normalizeBaseAssets(effectType, assets) {
+  const assetNames = ASSET_NAMES_BY_EFFECT.get(effectType);
+  if (!assetNames) {
+    if (assets !== undefined) throw new AssetError(`${effectType} does not accept external assets.`);
+    return undefined;
+  }
+  if (!isRecord(assets)) {
+    throw new AssetError(`${effectType} requires an assets object.`);
+  }
+  const allowed = new Set(assetNames);
+  for (const name of Object.keys(assets)) {
+    if (!allowed.has(name)) throw new AssetError(`${effectType} has no asset named ${name}.`);
+  }
+  const normalized = {};
+  for (const name of assetNames) {
+    const reference = assets[name];
+    if (typeof reference !== 'string' || reference.length < 1 || reference.length > 128) {
+      throw new AssetError(`${effectType}.${name} requires a non-empty asset reference.`);
+    }
+    normalized[name] = reference;
+  }
+  return Object.freeze(normalized);
+}
+
+function collectParameters(effectType, options) {
+  const nested = options.parameters;
+  if (nested !== undefined && !isRecord(nested)) {
+    throw new ValidationError(`${effectType}.parameters must be an object.`);
+  }
+  if (nested !== undefined) {
+    for (const key of Object.keys(options)) {
+      if (!COMMON_KEYS.has(key)) {
+        throw new ValidationError(`${effectType} cannot mix parameters with top-level parameter options.`);
+      }
+    }
+  }
+  const supplied = nested ?? options;
+  const parameters = {};
+  for (const key of Object.keys(supplied)) {
+    if (nested === undefined && COMMON_KEYS.has(key)) continue;
+    const value = supplied[key];
+    parameters[key] = Array.isArray(value) ? Object.freeze([...value]) : value;
+  }
+  return Object.freeze(parameters);
+}
+
+export class Effect {
+  constructor(type, options = {}) {
+    if (!isRecord(options)) throw new ValidationError(`${String(type)} options must be an object.`);
+    const id = validateId(options.id);
+    const enabled = options.enabled ?? true;
+    if (typeof enabled !== 'boolean') {
+      throw new ValidationError(`${type}.enabled must be boolean.`);
+    }
+
+    this.type = type;
+    this.id = id;
+    this.enabled = enabled;
+    this.channel = validateChannel(options.channel ?? 'all');
+    this.parameters = collectParameters(type, options);
+    this.assets = normalizeBaseAssets(type, options.assets);
+    Object.freeze(this);
+  }
+
+  toJSON() {
+    return {
+      ...(this.id === undefined ? {} : { id: this.id }),
+      type: this.type,
+      enabled: this.enabled,
+      channel: this.channel,
+      parameters: Object.fromEntries(
+        Object.entries(this.parameters).map(([name, value]) => [
+          name,
+          Array.isArray(value) ? [...value] : value
+        ])
+      ),
+      ...(this.assets === undefined ? {} : { assets: { ...this.assets } })
+    };
+  }
+}

package/dist/engine.js

@@ -0,0 +1,291 @@
+import { instantiateDspBinding, ET_OK } from './internal/dsp-engine-binding.js';
+import { getEffectImplementation } from './catalog.js';
+import { prepareConvolutionAsset } from './assets.js';
+import { EffeTuneError, EffeTuneRuntimeError } from './errors.js';
+import { channelRange, packEffect } from './semantics.js';
+import {
+  decodeTelemetryPacket,
+  TELEMETRY_RATE_HZ,
+  TELEMETRY_RING_BYTES
+} from './telemetry.js';
+
+function requireOk(status, operation) {
+  if (status !== ET_OK) {
+    throw new EffeTuneRuntimeError(`DSP ${operation} failed.`);
+  }
+}
+
+export async function createEngineSession(artifact, effects, resolvedAssets, {
+  sampleRate,
+  channels,
+  maxFrames,
+  seed
+}) {
+  let binding;
+  const nodes = [];
+  try {
+    binding = await instantiateDspBinding(artifact.module ?? artifact.bytes ?? artifact, {
+      warning: () => {}
+    });
+    binding.createEngine();
+    requireOk(
+      binding.prepare(sampleRate, channels, maxFrames, TELEMETRY_RING_BYTES),
+      'preparation'
+    );
+    requireOk(binding.setTelemetryRate(0), 'telemetry configuration');
+    let tapId = 1;
+    for (const [effectIndex, effect] of effects.entries()) {
+      if (!effect.enabled) continue;
+      const packed = packEffect(effect);
+      const instanceId = binding.createInstance(packed.internalType);
+      if (!instanceId) throw new EffeTuneRuntimeError(`Unable to create ${effect.type}.`);
+      requireOk(binding.instanceSetTap(instanceId, tapId), `${effect.type} telemetry mapping`);
+      requireOk(binding.instanceSetSeed(instanceId, seed), `${effect.type} seed configuration`);
+      requireOk(
+        binding.instanceSetParams(instanceId, packed.values, packed.hash),
+        `${effect.type} parameter configuration`
+      );
+      if (packed.bytes) {
+        requireOk(
+          binding.instanceSetParamBytes(instanceId, packed.bytes, packed.hash),
+          `${effect.type} structured parameter configuration`
+        );
+      }
+      const implementation = getEffectImplementation(effect.type);
+      if (implementation.assets?.length) {
+        const prepared = prepareConvolutionAsset(effect, resolvedAssets, {
+          sampleRate,
+          engineChannels: channels
+        });
+        const slot = implementation.assets?.find(asset => asset.publicName === 'impulseResponse')?.slot ?? 0;
+        requireOk(
+          binding.instanceSetAsset(
+            instanceId,
+            slot,
+            prepared.payload,
+            prepared.beginInfo,
+            prepared.formatTag
+          ),
+          `${effect.type} asset preparation`
+        );
+        const arena = binding.getArenaViews();
+        const warmupFrames = 128;
+        const processingChannels = prepared.beginInfo.processingChannels;
+        const silence = arena.scratch.allChannels.subarray(
+          0,
+          processingChannels * warmupFrames
+        );
+        const silencePtr = binding.pointerForArenaView(silence);
+        let state = binding.instanceAssetState(instanceId, slot);
+        const maximumWarmupBlocks = Math.ceil(2 * sampleRate / warmupFrames);
+        for (let block = 0; (state & 0xff) === 2 && block < maximumWarmupBlocks; block++) {
+          silence.fill(0);
+          requireOk(
+            binding.instanceProcess(
+              instanceId,
+              silencePtr,
+              processingChannels,
+              warmupFrames,
+              block * warmupFrames / sampleRate
+            ),
+            `${effect.type} asset prewarming`
+          );
+          state = binding.instanceAssetState(instanceId, slot);
+        }
+        if ((state & 0xff) !== 3) {
+          throw new EffeTuneRuntimeError(`${effect.type} asset did not become active.`);
+        }
+        requireOk(binding.resetInstance(instanceId), `${effect.type} post-prewarm reset`);
+        requireOk(binding.instanceSetSeed(instanceId, seed), `${effect.type} post-prewarm seed reset`);
+        requireOk(
+          binding.instanceSetParams(instanceId, packed.values, packed.hash),
+          `${effect.type} post-prewarm parameter reset`
+        );
+      }
+      nodes.push({
+        effectId: effect.id,
+        effectType: effect.type,
+        effectIndex,
+        instanceId,
+        tapId: tapId++,
+        range: channelRange(effect.channel, channels),
+        initialValues: new Float32Array(packed.values),
+        initialBytes: packed.bytes ? new Uint8Array(packed.bytes) : null,
+        hash: packed.hash
+      });
+    }
+    return new EngineSession(binding, nodes, { channels, maxFrames, seed });
+  } catch (error) {
+    binding?.close();
+    if (error instanceof EffeTuneError) throw error;
+    throw new EffeTuneRuntimeError('Unable to create the DSP processing state.', { cause: error });
+  }
+}
+
+export class EngineSession {
+  constructor(binding, nodes, { channels, maxFrames, seed }) {
+    this.binding = binding;
+    this.nodes = nodes;
+    this.channels = channels;
+    this.maxFrames = maxFrames;
+    this.seed = seed;
+    this.closed = false;
+    this.arena = binding.getArenaViews().combined;
+    this.arenaByteOffset = this.arena.byteOffset;
+    this.fullChannelViews = Array.from({ length: channels }, (_, channel) =>
+      this.arena.subarray(channel * maxFrames, (channel + 1) * maxFrames)
+    );
+    this.nodesByTap = new Map(nodes.map(node => [node.tapId, node]));
+    this.telemetryBuffer = new Uint8Array(TELEMETRY_RING_BYTES);
+    this.telemetryCallbacks = new Set();
+    this.telemetryEnabled = false;
+    this.telemetryPendingDropped = 0;
+    this.droppedTelemetryFrames = 0;
+  }
+
+  get latencySamples() {
+    if (this.closed) throw new EffeTuneRuntimeError('DSP processing state is closed.');
+    let latency = 0;
+    for (const node of this.nodes) {
+      latency += this.binding.instanceLatency(node.instanceId);
+    }
+    return latency;
+  }
+
+  process(input, output, offset, frameCount, sampleRate, timeFrame = offset) {
+    if (this.closed) throw new EffeTuneRuntimeError('DSP processing state is closed.');
+    for (let channel = 0; channel < this.channels; channel++) {
+      const target = frameCount === this.maxFrames
+        ? this.fullChannelViews[channel]
+        : this.arena.subarray(channel * frameCount, (channel + 1) * frameCount);
+      target.set(offset === 0 && input[channel].length === frameCount
+        ? input[channel]
+        : input[channel].subarray(offset, offset + frameCount));
+    }
+    for (const node of this.nodes) {
+      const audioPtr = this.arenaByteOffset +
+        node.range.start * frameCount * Float32Array.BYTES_PER_ELEMENT;
+      requireOk(
+        this.binding.instanceProcess(
+          node.instanceId,
+          audioPtr,
+          node.range.count,
+          frameCount,
+          timeFrame / sampleRate
+        ),
+        `${node.effectType} processing`
+      );
+    }
+    for (let channel = 0; channel < this.channels; channel++) {
+      const source = frameCount === this.maxFrames
+        ? this.fullChannelViews[channel]
+        : this.arena.subarray(channel * frameCount, (channel + 1) * frameCount);
+      output[channel].set(source, offset);
+    }
+    if (this.telemetryCallbacks.size > 0) this.drainTelemetry();
+  }
+
+  setTelemetryEnabled(enabled) {
+    if (this.closed) throw new EffeTuneRuntimeError('DSP processing state is closed.');
+    if (this.telemetryEnabled === enabled) return;
+    requireOk(
+      this.binding.setTelemetryRate(enabled ? TELEMETRY_RATE_HZ : 0),
+      'telemetry configuration'
+    );
+    this.telemetryEnabled = enabled;
+  }
+
+  subscribe(callback) {
+    if (typeof callback !== 'function') {
+      throw new TypeError('Telemetry callback must be a function.');
+    }
+    this.telemetryCallbacks.add(callback);
+    if (this.telemetryCallbacks.size === 1) this.setTelemetryEnabled(true);
+    return () => this.unsubscribe(callback);
+  }
+
+  unsubscribe(callback) {
+    const removed = this.telemetryCallbacks.delete(callback);
+    if (removed && this.telemetryCallbacks.size === 0) this.setTelemetryEnabled(false);
+    return removed;
+  }
+
+  readTelemetryPacket(packet = this.telemetryBuffer) {
+    if (!(packet instanceof Uint8Array) || packet.byteLength < TELEMETRY_RING_BYTES) {
+      throw new TypeError(`Telemetry packet must hold at least ${TELEMETRY_RING_BYTES} bytes.`);
+    }
+    const bytes = this.binding.telemetryRead(packet);
+    const dropped = this.binding.lastTelemetryDroppedFrames;
+    this.droppedTelemetryFrames += dropped;
+    return { bytes, dropped };
+  }
+
+  decodeTelemetry(packet, bytes, dropped = 0) {
+    const decoded = decodeTelemetryPacket(
+      packet,
+      bytes,
+      this.nodesByTap,
+      this.telemetryPendingDropped + dropped
+    );
+    this.telemetryPendingDropped = decoded.pendingDropped;
+    return decoded.frames;
+  }
+
+  drainTelemetry() {
+    const { bytes, dropped } = this.readTelemetryPacket();
+    if (bytes === 0) {
+      this.telemetryPendingDropped += dropped;
+      return [];
+    }
+    const frames = this.decodeTelemetry(this.telemetryBuffer, bytes, dropped);
+    for (const frame of frames) {
+      for (const callback of this.telemetryCallbacks) {
+        try {
+          callback(frame);
+        } catch (error) {
+          console.warn('EffeTune telemetry callback failed.', error);
+        }
+      }
+    }
+    return frames;
+  }
+
+  setPacked(effectId, values, hash, bytes = null) {
+    const node = this.nodes.find(entry => entry.effectId === effectId);
+    if (!node) throw new EffeTuneRuntimeError(`Effect ${effectId} is not active.`);
+    requireOk(
+      this.binding.instanceSetParams(node.instanceId, values, hash),
+      `${node.effectType} parameter update`
+    );
+    if (bytes) {
+      requireOk(
+        this.binding.instanceSetParamBytes(node.instanceId, bytes, hash),
+        `${node.effectType} structured parameter update`
+      );
+    }
+  }
+
+  reset() {
+    for (const node of this.nodes) {
+      requireOk(this.binding.resetInstance(node.instanceId), `${node.effectType} reset`);
+      requireOk(this.binding.instanceSetSeed(node.instanceId, this.seed), `${node.effectType} seed reset`);
+      requireOk(
+        this.binding.instanceSetParams(node.instanceId, node.initialValues, node.hash),
+        `${node.effectType} parameter reset`
+      );
+      if (node.initialBytes) {
+        requireOk(
+          this.binding.instanceSetParamBytes(node.instanceId, node.initialBytes, node.hash),
+          `${node.effectType} structured parameter reset`
+        );
+      }
+    }
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.telemetryCallbacks.clear();
+    this.binding.close();
+  }
+}

package/dist/errors.js

@@ -0,0 +1,31 @@
+export class EffeTuneError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = new.target.name;
+  }
+}
+
+export class ValidationError extends EffeTuneError {}
+export class EffectError extends EffeTuneError {}
+export class AssetError extends EffeTuneError {}
+export class EffeTuneRuntimeError extends EffeTuneError {}
+export class StateError extends EffeTuneError {}
+
+const ERROR_TYPES = Object.freeze({
+  ValidationError,
+  EffectError,
+  AssetError,
+  EffeTuneRuntimeError,
+  StateError
+});
+
+export function errorMessage(error, fallback) {
+  return error instanceof EffeTuneError
+    ? { errorType: error.name, message: error.message }
+    : { errorType: 'EffeTuneRuntimeError', message: fallback };
+}
+
+export function errorFromMessage(errorType, message, fallback) {
+  const ErrorType = ERROR_TYPES[errorType] ?? EffeTuneRuntimeError;
+  return new ErrorType(message || fallback);
+}