Lightweight yet powerful audio analysis library
npm install audio-inspectTypeScript-first audio analysis library for offline and realtime use.
``bash`
npm i audio-inspect
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
`ts
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);
`
`ts
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 }
});
`
`ts
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.
`ts`
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' } });
monitor() is AudioWorklet-only. If AudioWorklet is unavailable, it throws WORKLET_NOT_SUPPORTED.
Optional preload:
`ts
import { prepareWorklet } from 'audio-inspect';
await prepareWorklet(audioContext, {
moduleUrl: '/core/realtime/processor.js'
});
`
In Node.js, compressed/container decoding requires decoder injection:
`ts
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.load.resampler
- Node.js: provide for high-quality conversion, or set resampleQuality: 'fast' to opt into linear interpolation.
All public failures throw AudioInspectError.
`ts
import { isAudioInspectError } from 'audio-inspect';
try {
// ...
} catch (error) {
if (isAudioInspectError(error)) {
console.error(error.code, error.message);
}
}
`
features in analyze, inspect, and monitor supports two forms:
`ts
// 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:
`ts`
import { FEATURES } from 'audio-inspect';
console.log(FEATURES);
For option types in TypeScript:
`ts`
import type { FeatureOptions } from 'audio-inspect';
type LufsOptions = FeatureOptions<'lufs'>;
| 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 |
| 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 |
| 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 |
| 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.
| 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 |
`ts`
features: {
rms: { asDB: true },
peak: { asDB: true, truePeak: true }
}
`ts`
features: {
spectrogram: {
fftSize: 2048,
frameSize: 2048,
hopSize: 512,
maxFrames: 120,
minFrequency: 20,
maxFrequency: 20000,
scale: 'dbfs'
}
}
`ts`
features: {
vad: {
method: 'adaptive',
frameSizeMs: 25,
hopSizeMs: 10,
preEmphasis: true,
smoothing: true
}
}
`ts``
features: {
lufs: { calculateShortTerm: true, calculateTruePeak: true },
spectralFeatures: true,
mfccWithDelta: { numMfccCoeffs: 13, computeDelta: true, computeDeltaDelta: true },
stereo: { calculatePhase: true }
}
MIT