@effetune/dsp 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026, Yoshiyuki Kobayashi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# @effetune/dsp
+
+<!-- BEGIN DSP-LIBRARY-JAVASCRIPT-SUMMARY -->
+EffeTune DSP provides the same MIT-licensed C++ audio kernels used by EffeTune
+as a self-contained WebAssembly package for Node.js and evergreen browsers.
+Version 0.1.0 exposes all 76 catalog types through the generic Chain and
+`createEffect` APIs and 76 generated named convenience classes,
+decoded analyzer telemetry, versioned semantic presets, deterministic seeds, and an AudioWorklet wrapper.
+<!-- END DSP-LIBRARY-JAVASCRIPT-SUMMARY -->
+
+Documentation: [effetune.frieve.com/dsp/](https://effetune.frieve.com/dsp/)
+
+Source and issues:
+[Frieve-A/effetune](https://github.com/Frieve-A/effetune)
+
+<!-- BEGIN DSP-LIBRARY-JAVASCRIPT-START -->
+```console
+npm install @effetune/dsp
+```
+
+```js
+import { createChain } from '@effetune/dsp';
+
+const frames = 512;
+const mono = Float32Array.from(
+  { length: frames },
+  (_, frame) => 0.5 * Math.sin(2 * Math.PI * frame / 97)
+);
+const input = [mono.slice(), mono.slice()];
+const chain = await createChain({
+  version: 1,
+  chain: [{
+    id: 'volume',
+    type: 'Volume',
+    parameters: { volume: -6 }
+  }]
+});
+const output = await chain.process(input, { sampleRate: 48000 });
+console.log(output.length, output[0].length, output[0][0]);
+chain.close();
+```
+<!-- END DSP-LIBRARY-JAVASCRIPT-START -->
+
+The package is ESM-only. Save the example as `start.mjs` and run
+`node start.mjs`, or set `"type": "module"` in the consumer's `package.json`.
+CommonJS `require()` is not supported.
+
+Public package entry points are:
+
+- `@effetune/dsp` for the main ESM API
+- `@effetune/dsp/worklet` for `EffeTuneNode`
+- `@effetune/dsp/processor` for the side-effect AudioWorklet processor
+- `@effetune/dsp/schemas/chain-v1.json` for the Chain v1 JSON Schema
+- `@effetune/dsp/schemas/bundle-v1.json` for the Bundle v1 JSON Schema
+- `@effetune/dsp/catalog` for ESM catalog exports
+- `@effetune/dsp/catalog.json` for the machine-readable catalog JSON
+
+Every offline `process()` call starts from fresh DSP state and returns newly
+owned `Float32Array` channels. Input arrays are never mutated. Effects run in
+array order; a disabled effect and an empty chain are identity operations.
+All samples must be finite. Offline and streaming calls reject `NaN`,
+`Infinity`, and `-Infinity` with `ValidationError` before native processing;
+an invalid stream block does not change filter state.
+
+Use a stream when DSP state must continue across blocks or when parameters
+change at an exact frame:
+
+```js
+const stream = await chain.stream({
+  sampleRate: 48000,
+  channels: 2,
+  blockSize: 128,
+  seed: 42
+});
+
+const output = await stream.process([left, right], {
+  events: [{
+    frame: 256,
+    effectId: 'voice',
+    parameters: { threshold: -24, ratio: 4 }
+  }]
+});
+
+stream.setParam('voice', 'threshold', -20);
+stream.reset();
+stream.close();
+```
+
+Event frames are relative to the start of that `process()` input. They must be
+integers in input order from `0` through `frames - 1`; events sharing a frame
+are applied in array order before that sample. Each parameter object is merged
+with the effect's current semantic parameters and the complete packed block is
+committed without recreating DSP state. `reset()` restores the parameters,
+seed, and DSP state from stream creation.
+
+`setParam()` and events cannot change parameters that require convolution
+assets to be staged again. Open a new stream after changing
+`IRReverb.channelMode`, `latency`, or `convolutionRate`;
+`FIRCrossover.bandCount`, `latencyMode`, or `filterDelaySamples`; or
+`latencyMode` / `filterDelaySamples` on `FiveBandFIRPEQ`, `GroupDelayEQ`, or
+`RoomEQ`. The same restriction applies to `EffeTuneNode.setParam()`.
+
+Canonical presets use semantic long parameter names:
+
+```json
+{
+  "version": 1,
+  "chain": [
+    {
+      "id": "voice",
+      "type": "Compressor",
+      "enabled": true,
+      "channel": "stereo",
+      "parameters": { "threshold": -18, "ratio": 4 }
+    }
+  ]
+}
+```
+
+Application `pipeline` and `plugins` presets are not canonical presets.
+Convert a preset whose effects form one ordered serial path explicitly with
+`importLegacyPreset()` before calling `createChain()`. Branched and multi-bus
+routing is rejected because flattening it would change the acoustic result.
+Move or copy the desired effects into one serial path in the app and export it
+again, or reproduce the branching in the host around separate Chains.
+Unsupported fields produce a validation error.
+
+FIR Crossover, Five Band FIR PEQ, Group Delay EQ, IR Reverb, and Room EQ
+require an `assets.impulseResponse` reference and an `assetResolver`. The four
+FIR filter effects use prepared coefficient impulses at the processing sample
+rate. Use the public `encodeEta1({ channels, sampleRate, topology, paths })`
+helper to encode raw planar float32 arrays for a resolver. Bundle manifests
+verify exact byte length and SHA-256 before accepting an ETA1 payload. The
+complete payload and convolution footprint must fit the 32 MiB kernel cap.
+
+`EFFECT_CATALOG` and `getEffectCatalog()` expose the machine-readable semantic
+catalog for all 76 root classes and their `create<Type>()` factories. The
+catalog contains channel choices, parameters, required assets, telemetry, and
+latency declarations, but no private implementation mapping.
+
+For stateful processing, `ChainStream.latencySamples` reports aggregate runtime
+latency and matches Python `Stream.latency_samples` for the same chain and
+sample rate. `chain.latencySamples({ sampleRate })` reports the same value
+without opening a stream, which aligns offline `process()` output.
+`EffeTuneNode` does not expose a latency getter.
+
+For real-time processing:
+
+```js
+import { EffeTuneNode } from '@effetune/dsp/worklet';
+
+const node = await EffeTuneNode.create(context, preset, {
+  channels: 2,
+  seed: 42,
+  assetResolver
+});
+source.connect(node).connect(context.destination);
+await node.setParam('voice', 'threshold', -20);
+await node.reset();
+node.close();
+```
+
+`LevelMeter`, `Oscilloscope`, `SpectrumAnalyzer`, `Spectrogram`, and
+`StereoMeter` provide opt-in decoded telemetry:
+
+```js
+const unsubscribe = node.subscribe(frame => {
+  if (frame.kind === 'level') console.log(frame.channels);
+});
+console.log(node.droppedTelemetryFrames);
+unsubscribe();
+```
+
+Offline `Chain.process()` accepts `onTelemetry`; a stream accepts the same
+option and also provides `subscribe()`, `unsubscribe()`, and
+`droppedTelemetryFrames`. The first subscriber enables observations and the
+last unsubscribe disables them. Arrays in delivered frames belong to the
+caller. Raw DSP telemetry and AudioWorklet messages are not public APIs.
+
+`EffeTuneNode.create()` waits until the package-owned worklet processor has
+instantiated the selected baseline or SIMD artifact and committed every
+required asset. Serve the package files from the same origin or provide
+explicit `processorUrl`, `wasmUrl`, and `simdWasmUrl` options.
+
+The package does not decode or encode audio files. Provide planar float32 audio
+from Web Audio, WebCodecs, an audio-file library, or your own I/O layer.

package/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,11 @@
+EffeTune DSP includes PFFFT v1.1.0.
+
+PFFFT source: https://github.com/marton78/pffft
+
+Copyright (c) 2020 Dario Mambro
+Copyright (c) 2019 Hayati Ayguen
+Copyright (c) 2013 Julien Pommier
+Copyright (c) 2004 the University Corporation for Atmospheric Research
+
+PFFFT is distributed under a permissive BSD-style license. The complete
+upstream notice is included in dist/assets/NOTICE.txt.

package/dist/artifacts.js

@@ -0,0 +1,185 @@
+import { detectSimdSupport } from './internal/dsp-wasm-loader.js';
+import { instantiateDspBinding } from './internal/dsp-engine-binding.js';
+import { getEffectCatalog, getEffectImplementation } from './catalog.js';
+import { EffeTuneRuntimeError, ValidationError } from './errors.js';
+
+const EXPECTED_ABI_VERSION = 1;
+const cache = new Map();
+
+function resourceUrl(value, fallback) {
+  if (value instanceof URL) return value;
+  if (value === undefined) return fallback;
+  try {
+    return new URL(String(value), import.meta.url);
+  } catch (error) {
+    throw new ValidationError(`Invalid DSP resource URL: ${String(value)}`, { cause: error });
+  }
+}
+
+async function readFileUrl(url, binary) {
+  try {
+    const { readFile } = await import('node:fs/promises');
+    const data = await readFile(url);
+    return binary
+      ? data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)
+      : data.toString('utf8');
+  } catch (error) {
+    throw new EffeTuneRuntimeError(`Unable to read packaged DSP resource ${url.pathname}.`, { cause: error });
+  }
+}
+
+async function fetchResource(url, fetchImpl, binary) {
+  if (url.protocol === 'file:') return readFileUrl(url, binary);
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new ValidationError(`Unsupported DSP resource 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 DSP resources must use HTTPS.');
+    }
+  }
+  if (typeof fetchImpl !== 'function') {
+    throw new EffeTuneRuntimeError('fetch is required to load DSP resources in this environment.');
+  }
+  let response;
+  try {
+    response = await fetchImpl(url);
+  } catch (error) {
+    throw new EffeTuneRuntimeError(`Unable to load DSP resource ${url}.`, { cause: error });
+  }
+  if (!response?.ok) {
+    throw new EffeTuneRuntimeError(`Unable to load DSP resource ${url} (HTTP ${response?.status ?? 'error'}).`);
+  }
+  try {
+    return await (binary ? response.arrayBuffer() : response.text());
+  } catch (error) {
+    throw new EffeTuneRuntimeError(`Unable to read DSP resource ${url}.`, { cause: error });
+  }
+}
+
+function selectVariant(requested, webAssembly) {
+  if (!['auto', 'baseline', 'simd'].includes(requested)) {
+    throw new ValidationError('variant must be auto, baseline, or simd.');
+  }
+  const supported = detectSimdSupport(webAssembly);
+  if (requested === 'simd' && !supported) {
+    throw new EffeTuneRuntimeError('This WebAssembly runtime does not support SIMD.');
+  }
+  return requested === 'auto' ? (supported ? 'simd' : 'baseline') : requested;
+}
+
+function validateMeta(meta) {
+  if (!meta || meta.abiVersion !== EXPECTED_ABI_VERSION || !Array.isArray(meta.kernels)) {
+    throw new EffeTuneRuntimeError('The packaged DSP metadata is incompatible.');
+  }
+  return new Map(meta.kernels.map(kernel => [kernel.name, kernel]));
+}
+
+function validateCapabilities(capabilities, kernels, variant) {
+  if (capabilities.abiVersion !== EXPECTED_ABI_VERSION) {
+    throw new EffeTuneRuntimeError('The packaged DSP module uses an incompatible ABI.');
+  }
+  if (capabilities.simd !== (variant === 'simd')) {
+    throw new EffeTuneRuntimeError(`The packaged ${variant} DSP artifact has inconsistent build flags.`);
+  }
+  const available = new Map(capabilities.kernels.map(kernel => [kernel.name, kernel]));
+  for (const effect of getEffectCatalog().effects) {
+    const implementation = getEffectImplementation(effect.type);
+    const meta = kernels.get(implementation.internalType);
+    const actual = available.get(implementation.internalType);
+    if (!meta || !actual ||
+        (meta.hash >>> 0) !== (implementation.layoutHash >>> 0) ||
+        (actual.hash >>> 0) !== (implementation.layoutHash >>> 0)) {
+      throw new EffeTuneRuntimeError(`${effect.type} is incompatible with the packaged DSP artifact.`);
+    }
+  }
+}
+
+async function loadUncached({
+  variant,
+  webAssembly,
+  fetchImpl,
+  wasmUrl,
+  simdWasmUrl,
+  metaUrl
+}) {
+  if (!webAssembly || typeof webAssembly.compile !== 'function') {
+    throw new EffeTuneRuntimeError('WebAssembly is unavailable.');
+  }
+  const selected = selectVariant(variant, webAssembly);
+  const baselineDefault = new URL('./assets/effetune-dsp.wasm', import.meta.url);
+  const simdDefault = new URL('./assets/effetune-dsp.simd.wasm', import.meta.url);
+  const metadataDefault = new URL('./assets/effetune-dsp.meta.json', import.meta.url);
+  const selectedUrl = selected === 'simd'
+    ? resourceUrl(simdWasmUrl, simdDefault)
+    : resourceUrl(wasmUrl, baselineDefault);
+  const resolvedMetaUrl = resourceUrl(metaUrl, metadataDefault);
+
+  const [bytes, metaText] = await Promise.all([
+    fetchResource(selectedUrl, fetchImpl, true),
+    fetchResource(resolvedMetaUrl, fetchImpl, false)
+  ]);
+  let meta;
+  try {
+    meta = JSON.parse(metaText);
+  } catch (error) {
+    throw new EffeTuneRuntimeError('The packaged DSP metadata is not valid JSON.', { cause: error });
+  }
+  const kernels = validateMeta(meta);
+  let module;
+  try {
+    module = await webAssembly.compile(bytes);
+  } catch (error) {
+    throw new EffeTuneRuntimeError(`Unable to compile the packaged ${selected} DSP artifact.`, { cause: error });
+  }
+
+  let binding;
+  try {
+    binding = await instantiateDspBinding(module, { webAssembly, warning: () => {} });
+    validateCapabilities(binding.getCapabilities(), kernels, selected);
+  } catch (error) {
+    if (error instanceof EffeTuneRuntimeError) throw error;
+    throw new EffeTuneRuntimeError(`Unable to initialize the packaged ${selected} DSP artifact.`, { cause: error });
+  } finally {
+    binding?.close();
+  }
+  return { variant: selected, module, bytes, meta };
+}
+
+export async function loadDspArtifact(options = {}) {
+  const webAssembly = options.webAssembly ?? globalThis.WebAssembly;
+  const variant = selectVariant(options.variant ?? 'auto', webAssembly);
+  const wasmUrl = variant === 'simd' ? options.simdWasmUrl : options.wasmUrl;
+  const key = options.cache === false ||
+      options.fetch !== undefined ||
+      options.webAssembly !== undefined
+    ? null
+    : [
+        variant,
+        String(wasmUrl ?? ''),
+        String(options.metaUrl ?? ''),
+        options.fetch === undefined ? 'default-fetch' : 'custom-fetch'
+      ].join('|');
+  if (key && cache.has(key)) return cache.get(key);
+  const promise = loadUncached({
+    variant,
+    webAssembly,
+    fetchImpl: options.fetch ?? globalThis.fetch,
+    wasmUrl: options.wasmUrl,
+    simdWasmUrl: options.simdWasmUrl,
+    metaUrl: options.metaUrl
+  });
+  if (key) cache.set(key, promise);
+  try {
+    return await promise;
+  } catch (error) {
+    if (key) cache.delete(key);
+    throw error;
+  }
+}
+
+export function clearArtifactCache() {
+  cache.clear();
+}

package/dist/assets/NOTICE.txt

@@ -0,0 +1,30 @@
+EffeTune DSP third-party notices
+================================
+
+PFFFT v1.1.0
+Source: https://github.com/marton78/pffft
+
+Copyright (c) 2020 Dario Mambro (dario.mambro@gmail.com)
+Copyright (c) 2019 Hayati Ayguen (h_ayguen@web.de)
+Copyright (c) 2013 Julien Pommier (pommier@modartt.com)
+Copyright (c) 2004 the University Corporation for Atmospheric Research (UCAR)
+
+Redistribution and use of the Software in source and binary forms, with or without
+modification, is permitted provided that the following conditions are met:
+
+- Neither the names of NCAR's Computational and Information Systems Laboratory, the
+  University Corporation for Atmospheric Research, nor the names of its sponsors or
+  contributors may be used to endorse or promote products derived from this Software
+  without specific prior written permission.
+- Redistributions of source code must retain the above copyright notices, this list of
+  conditions, and the disclaimer below.
+- Redistributions in binary form must reproduce the above copyright notice, this list
+  of conditions, and the disclaimer below in the documentation and/or other materials
+  provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE SOFTWARE.