@effetune/dsp 0.0.0

package/dist/internal/dsp-wasm-loader.js

@@ -0,0 +1,346 @@
+import { instantiateDspBinding } from './dsp-engine-binding.js';
+
+export const EXPECTED_ABI_VERSION = 1;
+
+// A minimal module whose only function returns a v128.const value.
+export const SIMD_PROBE_BYTES = new Uint8Array([
+    0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
+    0x01, 0x05, 0x01, 0x60, 0x00, 0x01, 0x7b,
+    0x03, 0x02, 0x01, 0x00,
+    0x0a, 0x16, 0x01, 0x14, 0x00, 0xfd, 0x0c,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x0b
+]);
+
+const moduleCache = new Map();
+
+function defaultWarning(message) {
+    if (globalThis.console?.warn) {
+        globalThis.console.warn(message);
+    }
+}
+
+function warn(warning, message) {
+    warning(`[dsp-wasm] ${message}`);
+}
+
+function joinAssetPath(basePath, relativePath) {
+    const base = String(basePath || '');
+    if (!base) return relativePath;
+    if (base === '/') return `/${relativePath}`;
+    return `${base.replace(/\/$/, '')}/${relativePath}`;
+}
+
+function assertResponse(response, url) {
+    if (!response || response.ok === false) {
+        const status = response?.status ? ` (${response.status})` : '';
+        throw new Error(`Failed to fetch ${url}${status}`);
+    }
+    return response;
+}
+
+async function readJsonResponse(response, url) {
+    assertResponse(response, url);
+    if (typeof response.json === 'function') return response.json();
+    if (typeof response.text === 'function') return JSON.parse(await response.text());
+    throw new Error(`Response for ${url} cannot be read as JSON`);
+}
+
+async function readBinaryResponse(response, url) {
+    assertResponse(response, url);
+    if (typeof response.arrayBuffer !== 'function') {
+        throw new Error(`Response for ${url} cannot be read as an ArrayBuffer`);
+    }
+    const bytes = await response.arrayBuffer();
+    if (!(bytes instanceof ArrayBuffer)) {
+        throw new Error(`Response for ${url} did not return an ArrayBuffer`);
+    }
+    return bytes;
+}
+
+function normalizeKernel(kernel, index) {
+    if (!kernel || typeof kernel.name !== 'string' || kernel.name.length === 0) {
+        throw new Error(`Invalid DSP metadata kernel at index ${index}`);
+    }
+    if (!Number.isInteger(kernel.hash) || kernel.hash < 0 || kernel.hash > 0xffffffff) {
+        throw new Error(`Invalid DSP parameter hash for ${kernel.name}`);
+    }
+    const byteCapacity = kernel.byteCapacity ?? 0;
+    if (!Number.isInteger(byteCapacity) || byteCapacity < 0 || byteCapacity > 4096) {
+        throw new Error(`Invalid DSP structured parameter capacity for ${kernel.name}`);
+    }
+    return { name: kernel.name, hash: kernel.hash >>> 0, byteCapacity };
+}
+
+export function validateDspMeta(meta) {
+    if (!meta || typeof meta !== 'object') throw new Error('DSP metadata is not an object');
+    if (!Number.isInteger(meta.abiVersion) || meta.abiVersion < 0) {
+        throw new Error('DSP metadata has an invalid ABI version');
+    }
+    if (!Array.isArray(meta.kernels)) throw new Error('DSP metadata kernels must be an array');
+
+    const seen = new Set();
+    const kernels = meta.kernels.map((kernel, index) => {
+        const normalized = normalizeKernel(kernel, index);
+        if (seen.has(normalized.name)) throw new Error(`Duplicate DSP kernel ${normalized.name}`);
+        seen.add(normalized.name);
+        return normalized;
+    });
+    return { ...meta, abiVersion: meta.abiVersion >>> 0, kernels };
+}
+
+export function detectSimdSupport(webAssembly = globalThis.WebAssembly) {
+    if (!webAssembly || typeof webAssembly.validate !== 'function') return false;
+    try {
+        return webAssembly.validate(SIMD_PROBE_BYTES);
+    } catch {
+        return false;
+    }
+}
+
+export function detectWasmExceptionHandlingSupport(webAssembly = globalThis.WebAssembly) {
+    return Boolean(
+        webAssembly
+        && typeof webAssembly.Tag === 'function'
+        && typeof webAssembly.Exception === 'function'
+    );
+}
+
+export function canCloneWasmModule(module, structuredCloneImpl = globalThis.structuredClone) {
+    if (typeof structuredCloneImpl !== 'function') return false;
+    try {
+        structuredCloneImpl(module);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function reconcileKernels(meta, capabilities, warning) {
+    const available = new Map(capabilities.kernels.map(kernel => [kernel.name, kernel]));
+    const compatible = [];
+    for (const kernel of meta.kernels) {
+        const actual = available.get(kernel.name);
+        if (actual && (actual.hash >>> 0) === kernel.hash &&
+            (actual.byteCapacity ?? 0) === kernel.byteCapacity) {
+            compatible.push(kernel);
+        } else {
+            const reason = actual === undefined
+                ? 'is absent from the module'
+                : 'has a parameter layout mismatch';
+            warn(warning, `${kernel.name} ${reason}; disabling its WASM path`);
+        }
+    }
+    return { ...meta, kernels: compatible };
+}
+
+function findHash(generatedModule, typeName) {
+    const candidates = [
+        `${typeName}_PARAMS_HASH`,
+        `${typeName}ParamsHash`,
+        `${typeName.toUpperCase()}_PARAMS_HASH`
+    ];
+    for (const name of candidates) {
+        if (Number.isInteger(generatedModule?.[name])) return generatedModule[name] >>> 0;
+    }
+    return null;
+}
+
+function normalizePackerCollection(collection) {
+    if (collection instanceof Map) return collection;
+    if (collection && typeof collection === 'object') return new Map(Object.entries(collection));
+    return null;
+}
+
+export function createDspParamPackers(generatedModule, kernels = null, warning = defaultWarning) {
+    const kernelHashes = kernels
+        ? new Map(kernels.map(kernel => [kernel.name, kernel.hash >>> 0]))
+        : null;
+    const kernelByteCapacities = kernels
+        ? new Map(kernels.map(kernel => [kernel.name, kernel.byteCapacity ?? 0]))
+        : null;
+    const packers = new Map();
+    const declared = normalizePackerCollection(
+        generatedModule?.DSP_PARAM_PACKERS ||
+        generatedModule?.dspParamPackers ||
+        generatedModule?.PARAM_PACKERS
+    );
+
+    if (declared) {
+        for (const [typeName, value] of declared) {
+            const pack = typeof value === 'function' ? value : value?.pack;
+            const packBytes = typeof value?.packBytes === 'function' ? value.packBytes : null;
+            const byteCapacity = Number.isInteger(value?.byteCapacity) ? value.byteCapacity : 0;
+            const hash = Number.isInteger(value?.hash) ? value.hash >>> 0 : findHash(generatedModule, typeName);
+            if (typeof pack !== 'function' || hash === null) continue;
+            if (kernelHashes && (kernelHashes.get(typeName) !== hash ||
+                kernelByteCapacities.get(typeName) !== byteCapacity)) {
+                warn(warning, `${typeName} generated parameter layout does not match the loaded kernel`);
+                continue;
+            }
+            packers.set(typeName, {
+                pack,
+                hash,
+                ...(packBytes ? { packBytes, byteCapacity } : {})
+            });
+        }
+        return packers;
+    }
+
+    for (const [exportName, pack] of Object.entries(generatedModule || {})) {
+        const match = /^pack(.+)Params$/.exec(exportName);
+        if (!match || typeof pack !== 'function') continue;
+        const typeName = match[1];
+        const hash = findHash(generatedModule, typeName);
+        if (hash === null) continue;
+        if (kernelHashes && kernelHashes.get(typeName) !== hash) {
+            warn(warning, `${typeName} generated parameter layout does not match the loaded kernel`);
+            continue;
+        }
+        packers.set(typeName, { pack, hash });
+    }
+    return packers;
+}
+
+export function publishDspParamPackers(generatedModule, {
+    target = globalThis.window,
+    kernels = null,
+    warning = defaultWarning
+} = {}) {
+    const packers = createDspParamPackers(generatedModule, kernels, warning);
+    if (target && (typeof target === 'object' || typeof target === 'function')) {
+        target.dspParamPackers = packers;
+    }
+    return packers;
+}
+
+async function importGeneratedParamPackers() {
+    try {
+        return await import('./dsp-params.generated.js');
+    } catch {
+        return null;
+    }
+}
+
+async function loadAndValidate({
+    basePath,
+    fetchImpl,
+    webAssembly,
+    structuredCloneImpl,
+    expectedAbiVersion,
+    instantiateImpl,
+    warning,
+    paramPackersModule,
+    publishTarget
+}) {
+    const simd = detectSimdSupport(webAssembly);
+    const artifactName = simd ? 'effetune-dsp.simd.wasm' : 'effetune-dsp.wasm';
+    const artifactUrl = joinAssetPath(basePath, `plugins/dsp/${artifactName}`);
+    const metaUrl = joinAssetPath(basePath, 'plugins/dsp/effetune-dsp.meta.json');
+
+    const [binaryResponse, metaResponse] = await Promise.all([
+        fetchImpl(artifactUrl),
+        fetchImpl(metaUrl)
+    ]);
+    const [bytes, rawMeta] = await Promise.all([
+        readBinaryResponse(binaryResponse, artifactUrl),
+        readJsonResponse(metaResponse, metaUrl)
+    ]);
+    const meta = validateDspMeta(rawMeta);
+    if (meta.abiVersion !== expectedAbiVersion) {
+        throw new Error(`Metadata ABI ${meta.abiVersion} does not match host ABI ${expectedAbiVersion}`);
+    }
+    if (!webAssembly || typeof webAssembly.compile !== 'function') {
+        throw new Error('WebAssembly.compile is unavailable');
+    }
+    const module = await webAssembly.compile(bytes);
+
+    let binding = null;
+    let capabilities;
+    try {
+        binding = await instantiateImpl(module, { webAssembly, warning });
+        capabilities = binding.getCapabilities();
+    } finally {
+        binding?.close();
+    }
+    if (capabilities.abiVersion !== expectedAbiVersion) {
+        throw new Error(`Module ABI ${capabilities.abiVersion} does not match host ABI ${expectedAbiVersion}`);
+    }
+    if (capabilities.simd !== simd) {
+        throw new Error(`Module SIMD flag does not match selected artifact ${artifactName}`);
+    }
+
+    const compatibleMeta = reconcileKernels(meta, capabilities, warning);
+    const generated = paramPackersModule === undefined
+        ? await importGeneratedParamPackers()
+        : paramPackersModule;
+    const paramPackers = publishDspParamPackers(generated, {
+        target: publishTarget,
+        kernels: compatibleMeta.kernels,
+        warning
+    });
+
+    return {
+        module,
+        bytes,
+        moduleCloneable: canCloneWasmModule(module, structuredCloneImpl),
+        simd,
+        meta: compatibleMeta,
+        paramPackers
+    };
+}
+
+export async function loadDspModule({
+    basePath = '',
+    fetchImpl = globalThis.fetch,
+    webAssembly = globalThis.WebAssembly,
+    structuredCloneImpl = globalThis.structuredClone,
+    expectedAbiVersion = EXPECTED_ABI_VERSION,
+    instantiateImpl = instantiateDspBinding,
+    warning = defaultWarning,
+    paramPackersModule,
+    publishTarget = globalThis.window,
+    cache = true
+} = {}) {
+    if (typeof fetchImpl !== 'function') {
+        warn(warning, 'fetch is unavailable; using the JavaScript DSP path');
+        return null;
+    }
+
+    if (!detectWasmExceptionHandlingSupport(webAssembly)) {
+        warn(warning, 'WebAssembly exception handling is unavailable; using the JavaScript DSP path');
+        return null;
+    }
+
+    const simd = detectSimdSupport(webAssembly);
+    const artifactName = simd ? 'effetune-dsp.simd.wasm' : 'effetune-dsp.wasm';
+    const cacheKey = `${basePath}|${artifactName}|${expectedAbiVersion}`;
+    if (cache && moduleCache.has(cacheKey)) return moduleCache.get(cacheKey);
+
+    const loadPromise = loadAndValidate({
+        basePath,
+        fetchImpl,
+        webAssembly,
+        structuredCloneImpl,
+        expectedAbiVersion,
+        instantiateImpl,
+        warning,
+        paramPackersModule,
+        publishTarget
+    }).catch(error => {
+        if (cache) moduleCache.delete(cacheKey);
+        warn(warning, `load failed: ${error?.message || String(error)}; using the JavaScript DSP path`);
+        return null;
+    });
+    if (cache) moduleCache.set(cacheKey, loadPromise);
+    return loadPromise;
+}
+
+export function clearDspModuleCache() {
+    moduleCache.clear();
+}
+
+export function instantiateDsp(moduleOrBytes, options) {
+    return instantiateDspBinding(moduleOrBytes, options);
+}

package/dist/internal/ir-asset-payload.js

@@ -0,0 +1,98 @@
+export const IR_ASSET_FORMAT_TAG = 1;
+export const IR_ASSET_HEADER_BYTES = 32;
+export const IR_ASSET_MAGIC = 0x31415445;
+
+export const IR_ASSET_TOPOLOGY = Object.freeze({
+  unspecified: 0,
+  mono: 1,
+  independent: 2,
+  trueStereo: 3,
+  matrix: 4
+});
+
+const MAX_CHANNELS = 8;
+const MAX_MATRIX_PATHS = 8;
+const MATRIX_PATH_BYTES = 12;
+
+function validateChannels(channels) {
+  if (!Array.isArray(channels) || channels.length < 1 || channels.length > MAX_CHANNELS) {
+    throw new TypeError('IR channels must contain between 1 and 8 Float32Array values');
+  }
+  const frames = channels[0] instanceof Float32Array ? channels[0].length : 0;
+  if (frames === 0) throw new TypeError('IR channels must not be empty');
+  for (const channel of channels) {
+    if (!(channel instanceof Float32Array) || channel.length !== frames) {
+      throw new TypeError('IR channels must be equally sized Float32Array values');
+    }
+    for (const sample of channel) {
+      if (!Number.isFinite(sample)) throw new TypeError('IR samples must be finite');
+    }
+  }
+  return frames;
+}
+
+function validateTopology(topology, paths, channelCount) {
+  if (!Number.isInteger(topology) || topology < 0 || topology > IR_ASSET_TOPOLOGY.matrix) {
+    throw new TypeError('IR topology must be a supported integer enum value');
+  }
+  if (topology !== IR_ASSET_TOPOLOGY.matrix) {
+    if (paths !== undefined && paths.length !== 0) {
+      throw new TypeError('IR paths are only valid for matrix topology');
+    }
+    return [];
+  }
+  if (!Array.isArray(paths) || paths.length < 1 || paths.length > MAX_MATRIX_PATHS) {
+    throw new TypeError('Matrix topology requires between 1 and 8 paths');
+  }
+  return paths.map(path => {
+    const inputSlot = path?.inputSlot;
+    const outputSlot = path?.outputSlot;
+    const irChannel = path?.irChannel;
+    if (![inputSlot, outputSlot, irChannel].every(Number.isSafeInteger) ||
+        inputSlot < 0 || inputSlot > 0xffffffff || outputSlot < 0 || outputSlot > 0xffffffff ||
+        irChannel < 0 || irChannel >= channelCount) {
+      throw new TypeError('Matrix paths require non-negative slots and a valid IR channel');
+    }
+    return { inputSlot, outputSlot, irChannel };
+  });
+}
+
+export function buildIrAssetPayload({
+  channels,
+  sampleRate,
+  topology = IR_ASSET_TOPOLOGY.unspecified,
+  paths
+}) {
+  const frames = validateChannels(channels);
+  if (!Number.isSafeInteger(sampleRate) || sampleRate <= 0 || sampleRate > 0xffffffff) {
+    throw new TypeError('IR sample rate must be a positive 32-bit integer');
+  }
+  const matrixPaths = validateTopology(topology, paths, channels.length);
+  const pathBytes = matrixPaths.length * MATRIX_PATH_BYTES;
+  const sampleBytes = channels.length * frames * Float32Array.BYTES_PER_ELEMENT;
+  const payload = new ArrayBuffer(IR_ASSET_HEADER_BYTES + pathBytes + sampleBytes);
+  const view = new DataView(payload);
+
+  view.setUint32(0, IR_ASSET_MAGIC, true);
+  view.setUint32(4, channels.length, true);
+  view.setUint32(8, frames, true);
+  view.setUint32(12, sampleRate, true);
+  view.setUint32(16, topology, true);
+  view.setUint32(20, matrixPaths.length, true);
+
+  let offset = IR_ASSET_HEADER_BYTES;
+  for (const path of matrixPaths) {
+    view.setUint32(offset, path.inputSlot, true);
+    view.setUint32(offset + 4, path.outputSlot, true);
+    view.setUint32(offset + 8, path.irChannel, true);
+    offset += MATRIX_PATH_BYTES;
+  }
+  for (const channel of channels) {
+    for (const sample of channel) {
+      view.setFloat32(offset, sample, true);
+      offset += Float32Array.BYTES_PER_ELEMENT;
+    }
+  }
+
+  return payload;
+}

package/dist/internal/ir-plugin-contract.js

@@ -0,0 +1,265 @@
+import { IR_ASSET_HEADER_BYTES, IR_ASSET_TOPOLOGY } from './ir-asset-payload.js';
+
+export const IR_ASSET_SLOT = 0;
+export const IR_KERNEL_ASSET_CAPACITY_BYTES = 32 * 1024 * 1024;
+
+const KERNEL_FIXED_FOOTPRINT_BYTES = 2 * 1024 * 1024;
+const KERNEL_PATH_FRAME_BYTES = 16;
+const CONVOLVER_IMPL_BYTES_UPPER_BOUND = 512;
+const CONVOLVER_STAGE_BYTES_UPPER_BOUND = 512;
+const PFFFT_SETUP_FIXED_BYTES_UPPER_BOUND = 136;
+const MATRIX_PATH_BYTES = 12;
+
+function topologyPathCount(topology, assetChannels, processingChannels, pathCount = 0) {
+  if (topology === IR_ASSET_TOPOLOGY.mono) return processingChannels;
+  if (topology === IR_ASSET_TOPOLOGY.trueStereo) return 4;
+  if (topology === IR_ASSET_TOPOLOGY.matrix) return pathCount;
+  return assetChannels;
+}
+
+function topologyInputCount(topology, processingChannels, inputCount = 0) {
+  if (topology === IR_ASSET_TOPOLOGY.trueStereo) return 2;
+  if (topology === IR_ASSET_TOPOLOGY.matrix) return inputCount;
+  return processingChannels;
+}
+
+export function selectedIrChannelCount(channel, engineChannels) {
+  if (!Number.isInteger(engineChannels) || engineChannels < 1 || engineChannels > 8) return 0;
+  if (channel === 'A') return engineChannels;
+  if (channel === null || channel === undefined) return engineChannels >= 2 ? 2 : 1;
+  if (channel === 'L' || channel === 'R' || /^[1-8]$/.test(String(channel))) return 1;
+  if (channel === '34') return engineChannels >= 4 ? 2 : 0;
+  if (channel === '56') return engineChannels >= 6 ? 2 : 0;
+  if (channel === '78') return engineChannels >= 8 ? 2 : 0;
+  return 0;
+}
+
+function diagonalPaths(channelCount, selectedChannels) {
+  const count = Math.min(channelCount, selectedChannels, 8);
+  return Array.from({ length: count }, (_, index) => ({
+    inputSlot: index,
+    outputSlot: index,
+    irChannel: index
+  }));
+}
+
+function nextPowerOfTwo(value) {
+  let result = 1;
+  while (result < value) result *= 2;
+  return result;
+}
+
+function convolutionStages(frames, headBlock) {
+  const latency = headBlock ?? 128;
+  if (![0, 128, 256, 512, 1024].includes(latency)) {
+    throw new TypeError('IR head block must be a supported latency value');
+  }
+  const head = latency === 0 ? 128 : latency;
+  const stages = [];
+  const add = (block, offset, end) => {
+    if (offset >= frames || end <= offset) return;
+    stages.push({ block, offset, segmentFrames: Math.min(end, frames) - offset });
+  };
+  add(head, latency === 0 ? 128 : 0, 4 * head);
+  for (let block = 2 * head; block < 4096; block *= 2) {
+    add(block, 2 * block, 4 * block);
+  }
+  add(4096, 8192, frames);
+  return { latency, stages };
+}
+
+export function estimateIrConvolverMemoryUpperBound({
+  frames,
+  assetChannels,
+  topology,
+  processingChannels,
+  headBlock = 128,
+  pathCount = 0,
+  inputCount = 0
+}) {
+  const paths = topologyPathCount(topology, assetChannels, processingChannels, pathCount);
+  const inputs = topologyInputCount(topology, processingChannels, inputCount);
+  if (paths < 1 || inputs < 1) throw new TypeError('IR topology requires at least one path and input');
+  const { latency, stages } = convolutionStages(frames, headBlock);
+  let requiredRing = latency + 4096;
+  let bytes = CONVOLVER_IMPL_BYTES_UPPER_BOUND;
+  for (const stage of stages) {
+    const required = latency + stage.offset + stage.block + 4096;
+    if (required > requiredRing) requiredRing = required;
+    const fft = 2 * stage.block;
+    const partitions = Math.ceil(stage.segmentFrames / stage.block);
+    const floatCount = 3 * inputs * stage.block + 2 * fft +
+      (inputs + assetChannels) * partitions * fft + 2 * processingChannels * fft;
+    bytes += CONVOLVER_STAGE_BYTES_UPPER_BOUND + floatCount * 4 +
+      nextPowerOfTwo(paths) * 12 + PFFFT_SETUP_FIXED_BYTES_UPPER_BOUND + fft * 4;
+  }
+  bytes += processingChannels * nextPowerOfTwo(requiredRing) * 4;
+  if (latency === 0) bytes += (assetChannels + inputs) * 128 * 4;
+  bytes += inputs * 4;
+  return bytes;
+}
+
+export function resolveIrProcessingConfig({
+  sampleRate,
+  channelCount,
+  engineChannels = 8,
+  selectedChannels,
+  channel,
+  channelMode = 'auto',
+  latency = '128',
+  convolutionRate = 'auto'
+}) {
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    return { valid: false, message: 'The current audio sample rate is unavailable.' };
+  }
+  if (!Number.isInteger(channelCount) || channelCount < 1 || channelCount > 8) {
+    return { valid: false, message: 'This impulse response has an unsupported channel count.' };
+  }
+  const routedChannels = selectedChannels ?? selectedIrChannelCount(channel, engineChannels);
+  if (!Number.isInteger(routedChannels) || routedChannels < 1 || routedChannels > engineChannels) {
+    return { valid: false, message: 'The selected audio channels are not available.' };
+  }
+  if (!['auto', 'mono', 'indep', 'true', 'multi'].includes(channelMode)) {
+    return { valid: false, message: 'Choose a supported channel mode.' };
+  }
+
+  const headBlock = Number(latency);
+  if (![0, 128, 256, 512, 1024].includes(headBlock)) {
+    return { valid: false, message: 'Choose a supported latency setting.' };
+  }
+
+  let rateMode = convolutionRate;
+  if (headBlock === 0) rateMode = 'full';
+  if (rateMode === 'auto') rateMode = sampleRate >= 88200 ? 'half' : 'full';
+  if (!['full', 'half', 'quarter'].includes(rateMode)) {
+    return { valid: false, message: 'Choose a supported convolution rate.' };
+  }
+  if (rateMode === 'quarter' && sampleRate < 176400) {
+    return {
+      valid: false,
+      message: 'Quarter rate is available at sample rates of 176.4 kHz or higher.'
+    };
+  }
+
+  const rateDivider = rateMode === 'quarter' ? 4 : rateMode === 'half' ? 2 : 1;
+  let resolvedMode = channelMode;
+  if (resolvedMode === 'auto') {
+    if (channelCount === 1) resolvedMode = 'mono';
+    else if (channelCount === 4 && routedChannels === 2) {
+      resolvedMode = 'true';
+    } else if (channelCount === routedChannels) {
+      resolvedMode = 'indep';
+    } else {
+      resolvedMode = 'multi';
+    }
+  }
+
+  let topology;
+  let assetChannels;
+  let paths = [];
+  if (resolvedMode === 'mono') {
+    topology = IR_ASSET_TOPOLOGY.mono;
+    assetChannels = 1;
+  } else if (resolvedMode === 'true') {
+    if (channelCount !== 4 || routedChannels !== 2) {
+      return { valid: false, message: 'True Stereo requires a four-channel IR and a stereo channel selection.' };
+    }
+    topology = IR_ASSET_TOPOLOGY.trueStereo;
+    assetChannels = 4;
+  } else if (resolvedMode === 'indep') {
+    if (channelCount < routedChannels) {
+      return { valid: false, message: 'Independent mode requires one IR channel for each selected audio channel.' };
+    }
+    topology = IR_ASSET_TOPOLOGY.independent;
+    assetChannels = routedChannels;
+  } else {
+    paths = diagonalPaths(channelCount, routedChannels);
+    if (paths.length === 0) {
+      return { valid: false, message: 'Matrix mode could not create a valid channel route.' };
+    }
+    topology = IR_ASSET_TOPOLOGY.matrix;
+    assetChannels = channelCount;
+  }
+  const pathCount = topology === IR_ASSET_TOPOLOGY.matrix ? paths.length : 0;
+  const inputCount = topology === IR_ASSET_TOPOLOGY.matrix
+    ? new Set(paths.map(path => path.inputSlot)).size
+    : 0;
+
+  return {
+    valid: true,
+    channelMode: resolvedMode,
+    topology,
+    assetChannels,
+    selectedChannels: routedChannels,
+    processingChannels: routedChannels,
+    paths,
+    pathCount,
+    inputCount,
+    headBlock,
+    rateMode,
+    rateDivider,
+    sampleRate: Math.round(sampleRate / rateDivider)
+  };
+}
+
+export function estimateIrKernelCommitFootprint({
+  frames,
+  assetChannels,
+  topology,
+  processingChannels,
+  headBlock,
+  pathCount = 0,
+  inputCount = 0
+}) {
+  if (!Number.isInteger(frames) || frames < 1 ||
+      !Number.isInteger(assetChannels) || assetChannels < 1 ||
+      !Number.isInteger(processingChannels) || processingChannels < 1) {
+    throw new TypeError('IR footprint inputs must be positive integers');
+  }
+  const paths = topologyPathCount(topology, assetChannels, processingChannels, pathCount);
+  const payloadBytes = IR_ASSET_HEADER_BYTES +
+    (topology === IR_ASSET_TOPOLOGY.matrix ? paths * MATRIX_PATH_BYTES : 0) +
+    frames * assetChannels * Float32Array.BYTES_PER_ELEMENT;
+  const kernelBeginBound = payloadBytes + frames * assetChannels * KERNEL_PATH_FRAME_BYTES +
+    KERNEL_FIXED_FOOTPRINT_BYTES;
+  const convolverBound = payloadBytes + estimateIrConvolverMemoryUpperBound({
+    frames,
+    assetChannels,
+    topology,
+    processingChannels,
+    headBlock,
+    pathCount,
+    inputCount
+  });
+  return Math.max(kernelBeginBound, convolverBound);
+}
+
+export function maximumIrFramesForKernel({
+  sourceFrames,
+  assetChannels,
+  topology,
+  processingChannels,
+  headBlock,
+  pathCount = 0,
+  inputCount = 0,
+  capacityBytes = IR_KERNEL_ASSET_CAPACITY_BYTES
+}) {
+  if (!Number.isInteger(sourceFrames) || sourceFrames < 1) return 1;
+  let low = 1;
+  let high = sourceFrames;
+  while (low < high) {
+    const middle = Math.ceil((low + high) / 2);
+    const footprint = estimateIrKernelCommitFootprint({
+      frames: middle,
+      assetChannels,
+      topology,
+      processingChannels,
+      headBlock,
+      pathCount,
+      inputCount
+    });
+    if (footprint <= capacityBytes) low = middle;
+    else high = middle - 1;
+  }
+  return low;
+}