audio-inspect

TypeScript-first audio analysis library for offline and realtime use.

Install

npm i audio-inspect

Public API

audio-inspect exports only these top-level APIs:

• load(source, options?)
• analyze(audio, request)
• inspect(source, request) (load + analyze convenience)
• monitor(options) (realtime session)
• prepareWorklet(context, options?) (optional preload)
• FEATURES
• AudioInspectError, isAudioInspectError

Quick Start (Offline)

import { inspect } from 'audio-inspect';

const result = await inspect('audio.mp3', {
  load: { normalize: true, sampleRate: 48000, resampleQuality: 'high' },
  features: {
    rms: { asDB: true },
    spectrum: { fftSize: 2048 }
  }
});

console.log(result.results.rms);
console.log(result.results.spectrum?.frequencies.length);

Decode Once, Analyze Many

import { load, analyze } from 'audio-inspect';

const audio = await load(file);

const pass1 = await analyze(audio, {
  features: { rms: true, peak: true }
});

const pass2 = await analyze(audio, {
  range: { start: 30, end: 45 },
  features: { lufs: true, spectralFeatures: true }
});

Realtime Monitor

import { monitor } from 'audio-inspect';

const session = await monitor({
  context: audioContext,
  source: micStream,
  features: {
    rms: { asDB: true },
    peak: { asDB: true }
  },
  realtimePolicy: 'warn',
  heavyFeatureInterval: 4,
  emit: 'raf'
});

function loop() {
  const frame = session.read();
  if (frame) {
    // frame.sampleIndex is hop-aligned and useful for sync.
    renderMeters(frame.results.rms, frame.results.peak);
  }
  requestAnimationFrame(loop);
}

loop();

Realtime policy options:

• realtimePolicy: 'warn' | 'allow' | 'strict' (default: 'warn')
• heavyFeatureInterval (default: 4)

Behavior:

• 'allow': execute all selected features every hop.
• 'warn': keep heavy features enabled, but execute them every heavyFeatureInterval frames.
• 'strict': ignore heavy realtime features and emit REALTIME_POLICY_WARNING.

Dynamic Realtime Features

await session.setFeature('spectrum', { fftSize: 2048 });
await session.setFeature('spectrogram', {
  fftSize: 2048,
  frameSize: 2048,
  hopSize: 512,
  maxFrames: 60
});
await session.removeFeature('rms');
await session.setFeatures({ lufs: true, vad: { method: 'adaptive' } });

Worklet Strategy

monitor() is AudioWorklet-only. If AudioWorklet is unavailable, it throws WORKLET_NOT_SUPPORTED.

Optional preload:

import { prepareWorklet } from 'audio-inspect';

await prepareWorklet(audioContext, {
  moduleUrl: '/core/realtime/processor.js'
});

Node.js Offline Decode

In Node.js, compressed/container decoding requires decoder injection:

import { load } from 'audio-inspect';

const audio = await load(buffer, {
  decoder: {
    name: 'my-decoder',
    async decode(input) {
      // return AudioData
      return decodedAudioData;
    }
  }
});

If decode backend is missing, load() throws DECODE_BACKEND_MISSING.

If sampleRate conversion is requested, high-quality resampling is the default.

• Browser: uses OfflineAudioContext when available.
• Node.js: provide load.resampler for high-quality conversion, or set resampleQuality: 'fast' to opt into linear interpolation.

Error Handling

All public failures throw AudioInspectError.

import { isAudioInspectError } from 'audio-inspect';

try {
  // ...
} catch (error) {
  if (isAudioInspectError(error)) {
    console.error(error.code, error.message);
  }
}

Feature Selection Basics

features in analyze, inspect, and monitor supports two forms:

// 1) Object form (recommended when setting options)
features: {
  rms: true,                       // true = default options
  spectrum: { fftSize: 2048 }      // override options
}

// 2) Array form (default options only)
features: ['rms', 'peak', 'lufs']

You can list all available feature IDs with FEATURES:

import { FEATURES } from 'audio-inspect';
console.log(FEATURES);

For option types in TypeScript:

import type { FeatureOptions } from 'audio-inspect';
type LufsOptions = FeatureOptions<'lufs'>;

Feature Quick Reference

Time / Level

| Feature | What it does | Common options | | -------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------- | | rms, peak | Level measurement (linear or dB) | channel, asDB, reference, truePeak, oversamplingFactor, interpolation | | zeroCrossing | Zero-crossing rate | channel | | peaks | Peak detection | count, threshold, channel, minDistance | | waveform | Lightweight waveform summary | framesPerSecond, channel, method | | rmsAnalysis, peaksAnalysis, waveformAnalysis | TypedArray-oriented analysis results | Base feature options + onProgress | | energy | Short-time energy over frames | frameSize, hopSize, channel, normalized, windowFunction |

Frequency / Spectral

| Feature | What it does | Common options | | ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | fft | Single-frame FFT | fftSize, windowFunction, channel, provider, enableProfiling | | spectrum | Band-limited single-frame spectrum | fftSize, minFrequency, maxFrequency, scale, normalization, windowFunction, channel | | spectrogram | Multi-frame STFT/spectrogram sequence | fftSize, frameSize, hopSize, maxFrames, minFrequency, maxFrequency, scale, normalization, windowFunction, channel | | spectralFeatures | Centroid/bandwidth/rolloff/flatness and more | fftSize, windowFunction, minFrequency, maxFrequency, rolloffThreshold | | timeVaryingSpectralFeatures | Time-series version of spectral features | frameSize, hopSize, numFrames + spectral feature options | | spectralEntropy | Spectral entropy | fftSize, windowFunction, minFrequency, maxFrequency | | spectralCrest | Spectral crest factor | fftSize, windowFunction, minFrequency, maxFrequency, asDB |

Mel / CQT / MFCC

| Feature | What it does | Common options | | ---------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | melSpectrogram | Mel spectrogram | frameSizeMs, hopSizeMs, fftSize, numMelFilters, minFrequency, maxFrequency, preEmphasis, power, logScale | | cqt | CQT (FFT-based approximation) | frameSizeMs, hopSizeMs, fftSize, fMin, binsPerOctave, numBins, preEmphasis, power, logScale | | mfcc | MFCC coefficients | frameSizeMs, hopSizeMs, fftSize, numMelFilters, numMfccCoeffs, minFrequency, maxFrequency, preEmphasis, lifterCoeff | | mfccWithDelta | MFCC + delta + delta-delta | All mfcc options + deltaWindowSize, computeDelta, computeDeltaDelta |

Loudness / Voice / Dynamics

| Feature | What it does | Common options | | ------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | lufs | Integrated/momentary/short-term/LRA/true-peak loudness | channelMode, gated, calculateMomentary, calculateShortTerm, collectSeries, calculateLoudnessRange, calculateTruePeak, truePeakMethod, truePeakOversamplingFactor, truePeakInterpolation | | vad | Voice activity detection | method, frameSizeMs, hopSizeMs, energyThreshold, zcrThresholdLow, zcrThresholdHigh, adaptiveAlpha, noiseFactor, preEmphasis, smoothing | | crestFactor | Crest factor analysis | channel, windowSize, hopSize, method |

lufs.truePeakMethod defaults to bs1770 (polyphase FIR). In bs1770 mode, truePeakOversamplingFactor must be 2 or 4. lufs.momentary and lufs.shortTerm are scalar snapshots. For offline frame series, set collectSeries.

Stereo

| Feature | What it does | Common options | | ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------- | | stereo | Correlation/width/balance/phase/ITD/ILD | frameSize, hopSize, calculatePhase, calculateITD, calculateILD, provider, enableProfiling | | timeVaryingStereo | Time-varying stereo metrics | windowSize + stereo options |

Presets (Copy/Paste)

1) Lightweight meter

features: {
  rms: { asDB: true },
  peak: { asDB: true, truePeak: true }
}

2) Spectrum visualization

features: {
  spectrogram: {
    fftSize: 2048,
    frameSize: 2048,
    hopSize: 512,
    maxFrames: 120,
    minFrequency: 20,
    maxFrequency: 20000,
    scale: 'dbfs'
  }
}

3) Voice activity detection (VAD)

features: {
  vad: {
    method: 'adaptive',
    frameSizeMs: 25,
    hopSizeMs: 10,
    preEmphasis: true,
    smoothing: true
  }
}

4) Music-oriented bundle

features: {
  lufs: { calculateShortTerm: true, calculateTruePeak: true },
  spectralFeatures: true,
  mfccWithDelta: { numMfccCoeffs: 13, computeDelta: true, computeDeltaDelta: true },
  stereo: { calculatePhase: true }
}

LICENSE

MIT