@effetune/dsp 0.0.0

package/dist/semantics.js

@@ -0,0 +1,309 @@
+import { DSP_PARAM_PACKERS } from './internal/dsp-params.generated.js';
+import { getEffectDefinition, getEffectImplementation } from './catalog.js';
+import { Effect, validateChannel, validateParameterValue } from './effect.js';
+import { AssetError, EffeTuneError, EffectError, ValidationError } from './errors.js';
+
+const DOCUMENT_KEYS = new Set(['version', 'chain']);
+const EFFECT_KEYS = new Set(['id', 'type', 'enabled', 'channel', 'parameters', 'assets']);
+const STREAM_RECONFIGURATION_PARAMETERS = new Map([
+  ['FIRCrossover', new Set(['bandCount', 'latencyMode', 'filterDelaySamples'])],
+  ['FiveBandFIRPEQ', new Set(['latencyMode', 'filterDelaySamples'])],
+  ['GroupDelayEQ', new Set(['latencyMode', 'filterDelaySamples'])],
+  ['IRReverb', new Set(['channelMode', 'latency', 'convolutionRate'])],
+  ['RoomEQ', new Set(['latencyMode', 'filterDelaySamples'])]
+]);
+
+// App preset envelopes are recognized here rather than in the preset parser so that
+// every entry point into the semantic chain document (parsePreset, createChain and
+// the AudioWorklet loader) reports the same guidance instead of a generic
+// "unsupported field" complaint. The Python binding keeps the same detection in
+// effetune.presets.load_preset_document.
+const LEGACY_ENVELOPE_KEYS_V1 = ['pipeline', 'plugins'];
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function rejectAppPresetEnvelope(input) {
+  if (!isRecord(input)) return;
+  const envelopes = LEGACY_ENVELOPE_KEYS_V1.filter(key => Object.hasOwn(input, key));
+  if (envelopes.length === 0) return;
+  throw new ValidationError(
+    `Preset contains the EffeTune app preset field(s): ${envelopes.join(', ')}; ` +
+    'this is an app preset rather than a semantic chain document. ' +
+    'Import it with importLegacyPreset().'
+  );
+}
+
+function cloneEffect(effect) {
+  return {
+    id: effect.id,
+    type: effect.type,
+    enabled: effect.enabled,
+    channel: effect.channel,
+    parameters: Object.fromEntries(
+      Object.entries(effect.parameters).map(([name, value]) => [
+        name,
+        Array.isArray(value) ? [...value] : value
+      ])
+    ),
+    ...(effect.assets === undefined ? {} : { assets: { ...effect.assets } })
+  };
+}
+
+function fromPlainEffect(value, index) {
+  if (!isRecord(value)) throw new ValidationError(`Chain entry ${index} must be an object.`);
+  for (const key of Object.keys(value)) {
+    if (!EFFECT_KEYS.has(key)) {
+      throw new ValidationError(`Chain entry ${index} has an unsupported field: ${key}`);
+    }
+  }
+  if (typeof value.type !== 'string') {
+    throw new ValidationError(`Chain entry ${index} requires an effect type.`);
+  }
+  if (!isRecord(value.parameters)) {
+    throw new ValidationError(`Chain entry ${index} requires a parameters object.`);
+  }
+  const definition = getEffectDefinition(value.type);
+  const id = value.id;
+  if (id !== undefined &&
+      (typeof id !== 'string' || id.length < 1 || id.length > 128)) {
+    throw new ValidationError(`Chain entry ${index} has an invalid effect id.`);
+  }
+  const enabled = value.enabled ?? true;
+  if (typeof enabled !== 'boolean') {
+    throw new ValidationError(`Chain entry ${index} enabled must be boolean.`);
+  }
+  const channel = validateChannel(value.channel ?? 'all');
+  const parameterByName = new Map(definition.parameters.map(parameter => [parameter.name, parameter]));
+  for (const key of Object.keys(value.parameters)) {
+    if (!parameterByName.has(key)) {
+      throw new ValidationError(`Unknown parameter ${value.type}.${key}.`);
+    }
+  }
+  const parameters = {};
+  for (const parameter of definition.parameters) {
+    const supplied = Object.hasOwn(value.parameters, parameter.name)
+      ? value.parameters[parameter.name]
+      : parameter.default;
+    parameters[parameter.name] = validateParameterValue(value.type, parameter, supplied);
+  }
+  const declaredAssets = definition.assets ?? [];
+  let assets;
+  if (declaredAssets.length === 0) {
+    if (value.assets !== undefined) throw new AssetError(`${value.type} does not accept external assets.`);
+  } else {
+    if (!isRecord(value.assets)) throw new AssetError(`${value.type} requires an assets object.`);
+    const allowed = new Set(declaredAssets.map(asset => asset.name));
+    for (const name of Object.keys(value.assets)) {
+      if (!allowed.has(name)) throw new AssetError(`${value.type} has no asset named ${name}.`);
+    }
+    assets = {};
+    for (const asset of declaredAssets) {
+      const reference = value.assets[asset.name];
+      if (asset.required && (typeof reference !== 'string' || reference.length < 1 || reference.length > 128)) {
+        throw new AssetError(`${value.type}.${asset.name} requires a non-empty asset reference.`);
+      }
+      if (reference !== undefined) assets[asset.name] = reference;
+    }
+  }
+  return { id, type: value.type, enabled, channel, parameters, ...(assets ? { assets } : {}) };
+}
+
+function assignIds(effects) {
+  const explicit = new Set();
+  for (const effect of effects) {
+    if (effect.id === undefined) continue;
+    if (explicit.has(effect.id)) {
+      throw new ValidationError(`Duplicate effect id: ${effect.id}`);
+    }
+    explicit.add(effect.id);
+  }
+  const counters = new Map();
+  return effects.map(effect => {
+    if (effect.id !== undefined) return effect;
+    let count = counters.get(effect.type) ?? 0;
+    let id;
+    do {
+      count += 1;
+      id = `${effect.type}#${count}`;
+    } while (explicit.has(id));
+    counters.set(effect.type, count);
+    explicit.add(id);
+    return { ...effect, id };
+  });
+}
+
+export function normalizeChainDocument(input) {
+  let entries;
+  if (Array.isArray(input)) {
+    entries = input;
+  } else {
+    rejectAppPresetEnvelope(input);
+    if (!isRecord(input)) throw new ValidationError('A chain must be an array or a v1 chain document.');
+    for (const key of Object.keys(input)) {
+      if (!DOCUMENT_KEYS.has(key)) throw new ValidationError(`Unsupported chain document field: ${key}`);
+    }
+    if (input.version !== 1) throw new ValidationError('Only chain document version 1 is supported.');
+    if (!Array.isArray(input.chain)) throw new ValidationError('Chain document chain must be an array.');
+    entries = input.chain;
+  }
+  const effects = entries.map((entry, index) =>
+    fromPlainEffect(entry instanceof Effect ? entry.toJSON() : entry, index)
+  );
+  return {
+    version: 1,
+    chain: assignIds(effects).map(cloneEffect)
+  };
+}
+
+export function validateSeed(seed = 0) {
+  if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+    throw new ValidationError('seed must be an integer from 0 to 4294967295.');
+  }
+  return seed >>> 0;
+}
+
+export function validateSampleRate(sampleRate) {
+  if (!Number.isInteger(sampleRate) || sampleRate <= 0 || sampleRate > 0xffffffff) {
+    throw new ValidationError('sampleRate must be a positive 32-bit integer.');
+  }
+  return sampleRate;
+}
+
+export function validateEffectSampleRate(effect, sampleRate) {
+  const definition = getEffectDefinition(effect.type);
+  if (definition.sampleRates && !definition.sampleRates.includes(sampleRate)) {
+    throw new ValidationError(`${effect.type} does not support a sample rate of ${sampleRate} Hz.`);
+  }
+}
+
+function toInternalValue(transform, value) {
+  switch (transform?.kind ?? 'identity') {
+    case 'identity':
+      return value;
+    case 'naturalLog':
+      return Math.log(value);
+    case 'log10':
+      return Math.log10(value);
+    case 'decibelsFromReference':
+      return 20 * Math.log10(value / transform.reference);
+    case 'map': {
+      const mapping = transform.values.find(entry => Object.is(entry.public, value));
+      if (!mapping) throw new ValidationError('A semantic parameter mapping is unavailable.');
+      return mapping.internal;
+    }
+    default:
+      throw new EffectError(`Unsupported semantic transform: ${String(transform?.kind)}`);
+  }
+}
+
+export function packEffect(effect) {
+  const implementation = getEffectImplementation(effect.type);
+  const packer = DSP_PARAM_PACKERS.get(implementation.internalType);
+  if (!packer || (packer.hash >>> 0) !== (implementation.layoutHash >>> 0)) {
+    throw new EffectError(`${effect.type} is incompatible with the packaged DSP artifact.`);
+  }
+  const internal = {};
+  for (const mapping of implementation.packedParameters) {
+    const value = effect.parameters[mapping.publicName];
+    if (mapping.count === 1) {
+      internal[mapping.keys[0]] = toInternalValue(mapping.transform, value);
+    } else {
+      for (let index = 0; index < mapping.count; index++) {
+        internal[mapping.keys[index]] = toInternalValue(mapping.transform, value[index]);
+      }
+    }
+  }
+  const structured = implementation.structuredParameter;
+  if (structured) {
+    internal[structured.key] = effect.parameters[structured.publicName];
+  }
+  // The generated packer reports capacity limits with plain JavaScript errors.
+  // Translating them here keeps every public entry point (process, stream, setParam)
+  // inside the documented error taxonomy, matching the Python binding which already
+  // raises ValidationError for the same input.
+  let bytes;
+  if (structured) {
+    try {
+      bytes = packer.packBytes?.(internal);
+    } catch (error) {
+      if (error instanceof EffeTuneError) throw error;
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new ValidationError(
+        `${effect.type}.${structured.publicName} cannot be packed: ${detail}`,
+        { cause: error }
+      );
+    }
+  }
+  if (structured && !(bytes instanceof Uint8Array)) {
+    throw new EffectError(`${effect.type} structured parameters are unavailable.`);
+  }
+  return {
+    internalType: implementation.internalType,
+    hash: implementation.layoutHash >>> 0,
+    values: packer.pack(internal),
+    ...(bytes ? { bytes } : {})
+  };
+}
+
+export function setEffectParameter(effect, parameterName, value) {
+  const definition = getEffectDefinition(effect.type);
+  const parameter = definition.parameters.find(entry => entry.name === parameterName);
+  if (!parameter) throw new ValidationError(`Unknown parameter ${effect.type}.${parameterName}.`);
+  const validated = validateParameterValue(effect.type, parameter, value);
+  return {
+    ...cloneEffect(effect),
+    parameters: { ...effect.parameters, [parameterName]: validated }
+  };
+}
+
+export function validateStreamParameterUpdate(effect, parameterName) {
+  if (STREAM_RECONFIGURATION_PARAMETERS.get(effect.type)?.has(parameterName)) {
+    throw new ValidationError(
+      `${effect.type}.${parameterName} cannot be updated while a stream is open; ` +
+      'create a new stream with the updated effect.'
+    );
+  }
+}
+
+export function channelRange(channel, channelCount) {
+  validateChannel(channel);
+  if (!Number.isInteger(channelCount) || channelCount < 1 || channelCount > 8) {
+    throw new ValidationError('Audio must contain between 1 and 8 channels.');
+  }
+  if (channel === 'all') return { start: 0, count: channelCount };
+  if (channel === 'stereo') return { start: 0, count: channelCount >= 2 ? 2 : 1 };
+  if (channel === 'left') return { start: 0, count: 1 };
+  if (channel === 'right') {
+    if (channelCount < 2) throw new ValidationError('The right channel is unavailable in mono audio.');
+    return { start: 1, count: 1 };
+  }
+  if (channel === '34' || channel === '56' || channel === '78') {
+    const start = Number(channel[0]) - 1;
+    if (channelCount < start + 2) {
+      throw new ValidationError(`Channel pair ${channel} is unavailable in ${channelCount}-channel audio.`);
+    }
+    return { start, count: 2 };
+  }
+  const start = Number(channel) - 1;
+  if (channelCount <= start) {
+    throw new ValidationError(`Channel ${channel} is unavailable in ${channelCount}-channel audio.`);
+  }
+  return { start, count: 1 };
+}
+
+export function channelToEngine(channel) {
+  if (channel === 'all') return 'A';
+  if (channel === 'stereo') return null;
+  if (channel === 'left') return 'L';
+  if (channel === 'right') return 'R';
+  return channel;
+}
+
+export function requireResolvedAsset(effect, resolvedAssets) {
+  if (effect.assets === undefined) return null;
+  const asset = resolvedAssets?.get(effect.id)?.impulseResponse;
+  if (!asset) throw new AssetError(`${effect.id} is missing its impulseResponse asset.`);
+  return asset;
+}

package/dist/telemetry.js

@@ -0,0 +1,322 @@
+const HEADER_BYTES = 16;
+const LEVEL_FRAME = 1;
+const SCOPE_FRAME = 3;
+const SPECTRUM_FRAME = 4;
+const SPECTROGRAM_FRAME = 5;
+const STEREO_FRAME = 6;
+
+const ANALYZER_FRAMES = Object.freeze({
+  LevelMeter: [LEVEL_FRAME, 1],
+  Oscilloscope: [SCOPE_FRAME, 2],
+  SpectrumAnalyzer: [SPECTRUM_FRAME, 1],
+  Spectrogram: [SPECTROGRAM_FRAME, 1],
+  StereoMeter: [STEREO_FRAME, 2]
+});
+
+export const TELEMETRY_RING_BYTES = 256 * 1024;
+export const TELEMETRY_RATE_HZ = 60;
+
+export function supportsTelemetry(effectType) {
+  return Object.hasOwn(ANALYZER_FRAMES, effectType);
+}
+
+function common(node, kind, sequence, dropped) {
+  return {
+    kind,
+    effectType: node.effectType,
+    effectId: node.effectId,
+    effectIndex: node.effectIndex,
+    sequence,
+    dropped
+  };
+}
+
+function decodeLevel(payload, node, sequence, dropped) {
+  if (payload.byteLength < 16) return null;
+  const channelCount = payload.getUint32(0, true);
+  if (channelCount < 1 || channelCount > 8 || payload.byteLength !== 8 + channelCount * 8) {
+    return null;
+  }
+  const clipFlags = payload.getUint32(4 + channelCount * 8, true);
+  if ((clipFlags & ~((1 << channelCount) - 1)) !== 0) return null;
+  const channels = new Array(channelCount);
+  for (let channel = 0; channel < channelCount; channel++) {
+    const offset = 4 + channel * 8;
+    const peak = payload.getFloat32(offset, true);
+    const rms = payload.getFloat32(offset + 4, true);
+    if (!Number.isFinite(peak) || peak < 0 || !Number.isFinite(rms) || rms < 0) {
+      return null;
+    }
+    channels[channel] = { peak, rms, clipped: (clipFlags & (1 << channel)) !== 0 };
+  }
+  return { ...common(node, 'level', sequence, dropped), channels };
+}
+
+function decodeOscilloscope(payload, node, sequence, dropped) {
+  if (payload.byteLength < 20) return null;
+  const sampleRate = payload.getFloat32(0, true);
+  const captureSampleCount = payload.getUint32(4, true);
+  const triggerOffset = payload.getUint32(8, true);
+  const bucketCount = payload.getUint16(12, true);
+  const encoding = payload.getUint8(14);
+  const flags = payload.getUint8(15);
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0 ||
+      captureSampleCount < 1 || captureSampleCount > 65536 ||
+      triggerOffset >= captureSampleCount || (flags & ~1) !== 0) {
+    return null;
+  }
+  if (encoding === 0) {
+    if (bucketCount !== 0 || captureSampleCount > 2048 ||
+        payload.byteLength !== 16 + captureSampleCount * 4) {
+      return null;
+    }
+    const sampleIndices = new Uint32Array(captureSampleCount);
+    const values = new Float32Array(captureSampleCount);
+    for (let index = 0; index < captureSampleCount; index++) {
+      const value = payload.getFloat32(16 + index * 4, true);
+      if (!Number.isFinite(value)) return null;
+      sampleIndices[index] = index;
+      values[index] = value;
+    }
+    return {
+      ...common(node, 'oscilloscope', sequence, dropped),
+      sampleRate,
+      captureSampleCount,
+      triggerOffset,
+      triggered: (flags & 1) !== 0,
+      encoding: 'samples',
+      sampleIndices,
+      values
+    };
+  }
+  if (encoding !== 1 || captureSampleCount <= 2048 || bucketCount !== 512 ||
+      payload.byteLength !== 16 + bucketCount * 18) {
+    return null;
+  }
+  const sampleIndices = new Uint32Array(bucketCount * 4);
+  const values = new Float32Array(bucketCount * 4);
+  let pointCount = 0;
+  const append = (sampleIndex, value) => {
+    if (pointCount > 0 && sampleIndices[pointCount - 1] === sampleIndex) {
+      return values[pointCount - 1] === value;
+    }
+    sampleIndices[pointCount] = sampleIndex;
+    values[pointCount] = value;
+    pointCount += 1;
+    return true;
+  };
+  for (let bucket = 0; bucket < bucketCount; bucket++) {
+    const begin = Math.floor(bucket * captureSampleCount / bucketCount);
+    const end = Math.floor((bucket + 1) * captureSampleCount / bucketCount);
+    const bucketLength = end - begin;
+    const offset = 16 + bucket * 18;
+    const first = payload.getFloat32(offset, true);
+    const minimum = payload.getFloat32(offset + 4, true);
+    const maximum = payload.getFloat32(offset + 8, true);
+    const last = payload.getFloat32(offset + 12, true);
+    const minimumOffset = payload.getUint8(offset + 16);
+    const maximumOffset = payload.getUint8(offset + 17);
+    if (!Number.isFinite(first) || !Number.isFinite(minimum) ||
+        !Number.isFinite(maximum) || !Number.isFinite(last) || minimum > maximum ||
+        first < minimum || first > maximum || last < minimum || last > maximum ||
+        minimumOffset >= bucketLength || maximumOffset >= bucketLength) {
+      return null;
+    }
+    const minimumIndex = begin + minimumOffset;
+    const maximumIndex = begin + maximumOffset;
+    if (!append(begin, first)) return null;
+    if (minimumIndex <= maximumIndex) {
+      if (!append(minimumIndex, minimum) || !append(maximumIndex, maximum)) return null;
+    } else if (!append(maximumIndex, maximum) || !append(minimumIndex, minimum)) {
+      return null;
+    }
+    if (!append(end - 1, last)) return null;
+  }
+  return {
+    ...common(node, 'oscilloscope', sequence, dropped),
+    sampleRate,
+    captureSampleCount,
+    triggerOffset,
+    triggered: (flags & 1) !== 0,
+    encoding: 'minMax',
+    sampleIndices: sampleIndices.slice(0, pointCount),
+    values: values.slice(0, pointCount)
+  };
+}
+
+function decodeSpectrum(payload, node, sequence, dropped) {
+  if (payload.byteLength < 28) return null;
+  const sampleRate = payload.getFloat32(0, true);
+  const binCount = payload.getUint32(4, true);
+  const points = payload.getUint16(8, true);
+  const flags = payload.getUint16(10, true);
+  const binsTruncated = (flags & 1) !== 0;
+  const fullBinCount = points >= 8 && points <= 14 ? (1 << (points - 1)) + 1 : 0;
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0 || fullBinCount === 0 ||
+      (flags & ~1) !== 0 || payload.byteLength !== 12 + binCount * 8 ||
+      (points === 14
+        ? !binsTruncated || binCount !== 8190 || fullBinCount - binCount !== 3
+        : binsTruncated || binCount !== fullBinCount)) {
+    return null;
+  }
+  const currentDb = new Float32Array(binCount);
+  const peakDb = new Float32Array(binCount);
+  const peakOffset = 12 + binCount * 4;
+  for (let bin = 0; bin < binCount; bin++) {
+    const current = payload.getFloat32(12 + bin * 4, true);
+    const peak = payload.getFloat32(peakOffset + bin * 4, true);
+    if (!Number.isFinite(current) || !Number.isFinite(peak)) return null;
+    currentDb[bin] = current;
+    peakDb[bin] = peak;
+  }
+  return {
+    ...common(node, 'spectrum', sequence, dropped),
+    sampleRate,
+    points,
+    binsTruncated,
+    currentDb,
+    peakDb
+  };
+}
+
+function decodeSpectrogram(payload, node, sequence, dropped) {
+  if (payload.byteLength !== 268) return null;
+  const sampleRate = payload.getFloat32(0, true);
+  const timeSeconds = payload.getFloat32(4, true);
+  const cellCount = payload.getUint16(8, true);
+  const points = payload.getUint16(10, true);
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0 || !Number.isFinite(timeSeconds) ||
+      cellCount !== 256 || points < 8 || points > 14) {
+    return null;
+  }
+  const intensities = new Uint8Array(256);
+  for (let cell = 0; cell < 256; cell++) intensities[cell] = payload.getUint8(12 + cell);
+  return {
+    ...common(node, 'spectrogram', sequence, dropped),
+    sampleRate,
+    timeSeconds,
+    points,
+    intensities
+  };
+}
+
+function decodeStereo(payload, node, sequence, dropped) {
+  if (payload.byteLength < 1464) return null;
+  const sampleRate = payload.getFloat32(0, true);
+  const sampleCount = payload.getUint16(4, true);
+  const flags = payload.getUint16(6, true);
+  const expectedBytes = 8 + sampleCount * 8 + 360 * 4 + 16;
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0 || sampleCount > 8000 ||
+      (flags & ~1) !== 0 || payload.byteLength !== expectedBytes) {
+    return null;
+  }
+  const samples = new Float32Array(sampleCount * 2);
+  for (let sample = 0; sample < sampleCount; sample++) {
+    const offset = 8 + sample * 8;
+    const side = payload.getFloat32(offset, true);
+    const mid = payload.getFloat32(offset + 4, true);
+    if (!Number.isFinite(side) || !Number.isFinite(mid)) return null;
+    samples[sample * 2] = side;
+    samples[sample * 2 + 1] = mid;
+  }
+  const envelopeOffset = 8 + sampleCount * 8;
+  const envelope = new Float32Array(360);
+  for (let bin = 0; bin < 360; bin++) {
+    const peak = payload.getFloat32(envelopeOffset + bin * 4, true);
+    if (!Number.isFinite(peak) || peak < 0) return null;
+    envelope[bin] = peak;
+  }
+  const statisticsOffset = envelopeOffset + 360 * 4;
+  const correlation = payload.getFloat32(statisticsOffset, true);
+  const balance = payload.getFloat32(statisticsOffset + 4, true);
+  const peakLeft = payload.getFloat32(statisticsOffset + 8, true);
+  const peakRight = payload.getFloat32(statisticsOffset + 12, true);
+  if (!Number.isFinite(correlation) || correlation < -1 || correlation > 1 ||
+      !Number.isFinite(balance) || !Number.isFinite(peakLeft) || peakLeft < 0 ||
+      !Number.isFinite(peakRight) || peakRight < 0) {
+    return null;
+  }
+  return {
+    ...common(node, 'stereo', sequence, dropped),
+    sampleRate,
+    discontinuity: (flags & 1) !== 0,
+    samples,
+    envelope,
+    correlation,
+    balance,
+    peakLeft,
+    peakRight
+  };
+}
+
+function decodePayload(frameType, payload, node, sequence, dropped) {
+  switch (frameType) {
+    case LEVEL_FRAME:
+      return decodeLevel(payload, node, sequence, dropped);
+    case SCOPE_FRAME:
+      return decodeOscilloscope(payload, node, sequence, dropped);
+    case SPECTRUM_FRAME:
+      return decodeSpectrum(payload, node, sequence, dropped);
+    case SPECTROGRAM_FRAME:
+      return decodeSpectrogram(payload, node, sequence, dropped);
+    case STEREO_FRAME:
+      return decodeStereo(payload, node, sequence, dropped);
+    default:
+      return null;
+  }
+}
+
+export function decodeTelemetryPacket(packet, bytes, nodesByTap, initialDropped = 0) {
+  if (!(packet instanceof Uint8Array) || !Number.isInteger(bytes) ||
+      bytes < 0 || bytes > packet.byteLength) {
+    return { frames: [], pendingDropped: initialDropped };
+  }
+  const view = new DataView(packet.buffer, packet.byteOffset, bytes);
+  const frames = [];
+  let offset = 0;
+  let pendingDropped = initialDropped;
+  while (offset < bytes) {
+    if (bytes - offset < HEADER_BYTES) break;
+    const frameType = view.getUint16(offset, true);
+    const formatVersion = view.getUint16(offset + 2, true);
+    const tapId = view.getUint32(offset + 4, true);
+    const sequence = view.getUint32(offset + 8, true);
+    const payloadBytes = view.getUint16(offset + 12, true);
+    const frameBytes = (HEADER_BYTES + payloadBytes + 3) & ~3;
+    if (frameBytes > bytes - offset) break;
+    const node = nodesByTap.get(tapId);
+    const expected = node ? ANALYZER_FRAMES[node.effectType] : null;
+    if (expected?.[0] === frameType && expected[1] === formatVersion) {
+      const payload = new DataView(
+        packet.buffer,
+        packet.byteOffset + offset + HEADER_BYTES,
+        payloadBytes
+      );
+      const decoded = decodePayload(frameType, payload, node, sequence, pendingDropped);
+      if (decoded) {
+        frames.push(decoded);
+        pendingDropped = 0;
+      }
+    }
+    offset += frameBytes;
+  }
+  return { frames, pendingDropped };
+}
+
+export function countTelemetryFrames(packet, bytes) {
+  if (!(packet instanceof Uint8Array) || !Number.isInteger(bytes) ||
+      bytes < 0 || bytes > packet.byteLength) {
+    return 0;
+  }
+  const view = new DataView(packet.buffer, packet.byteOffset, bytes);
+  let count = 0;
+  let offset = 0;
+  while (bytes - offset >= HEADER_BYTES) {
+    const payloadBytes = view.getUint16(offset + 12, true);
+    const frameBytes = (HEADER_BYTES + payloadBytes + 3) & ~3;
+    if (frameBytes > bytes - offset) break;
+    count += 1;
+    offset += frameBytes;
+  }
+  return count;
+}