audio-inspect

A lightweight yet powerful audio analysis library for web and Node.js environments

Features

• Time Domain Analysis: Peak detection, RMS calculation, zero-crossing rate, waveform extraction
• Frequency Domain Analysis: FFT analysis, spectrum analysis, spectrogram generation
• Advanced Audio Features: LUFS loudness, spectral features, voice activity detection (VAD)
• Real-time Processing: AudioWorklet-based real-time analysis with custom AudioNode
• Enhanced Audio Analysis: A-weighted crest factor, True Peak detection, MFCC, spectral entropy/crest
• High Performance: Float32Array-based results, parallel batch processing
• TypeScript Ready: Full type definitions with comprehensive error handling
• Tree-shaking Support: Import only what you need for optimal bundle size

Installation

# Install the latest version
npm install audio-inspect

# Or from GitHub
npm install github:romot-co/audio-inspect

Quick Start

Basic Usage

import { load, getPeaksAnalysis, getSpectrum } from 'audio-inspect';

// Load audio file
const audio = await load('path/to/audio.mp3');

// Enhanced peak analysis with Float32Array results
const peaks = getPeaksAnalysis(audio, {
  count: 50,
  threshold: 0.1,
  onProgress: (percent, message) => console.log(`${percent}%: ${message}`)
});

// Spectrum analysis with frequency filtering
const spectrum = await getSpectrum(audio, {
  fftSize: 2048,
  minFrequency: 80,
  maxFrequency: 8000
});

console.log(peaks.positions);    // Float32Array of peak positions
console.log(peaks.amplitudes);  // Float32Array of peak amplitudes

Real-time Audio Analysis

import { createAudioInspectNode } from 'audio-inspect';

const audioContext = new AudioContext();
const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
const sourceNode = audioContext.createMediaStreamSource(mediaStream);

// Create AudioInspectNode
const inspectNode = await createAudioInspectNode(audioContext, {
  featureName: 'getRMS',
  bufferSize: 1024,
  hopSize: 512
});

// Set up event handlers
inspectNode.onresult = (event) => {
  console.log('RMS:', event.data, 'at', event.timestamp);
};

// Connect to Web Audio API graph
sourceNode.connect(inspectNode);

// Update analysis in real-time
inspectNode.updateOptions({
  featureName: 'getPeaks',
  featureOptions: { count: 5, threshold: 0.5 }
});

Enhanced Audio Analysis Features

1. Weighted Crest Factor (A-Weighted Crest Factor)

IEC 61672-1:2013 compliant A-weighting filter for perceptual crest factor measurement.

import { getCrestFactor } from 'audio-inspect/features/dynamics';

const audio = await load('audio.mp3');

// Traditional crest factor (unweighted)
const simpleCF = getCrestFactor(audio, { method: 'simple' });

// A-weighted crest factor for perceptual analysis
const weightedCF = getCrestFactor(audio, { method: 'weighted' });

console.log(`Crest Factor: ${simpleCF.crestFactor} dB`);
console.log(`A-weighted CF: ${weightedCF.crestFactor} dB`);
console.log(`Peak: ${simpleCF.peak}, RMS: ${simpleCF.rms}`);

// Time-varying crest factor analysis
const timeVaryingCF = getCrestFactor(audio, {
  method: 'weighted',
  windowSize: 0.1,  // 100ms analysis window
  hopSize: 0.05     // 50ms hop size
});

if (timeVaryingCF.timeVarying) {
  console.log(`Time-varying analysis: ${timeVaryingCF.timeVarying.values.length} frames`);
  console.log(`Max CF: ${Math.max(...timeVaryingCF.timeVarying.values)} dB`);
}

// Real-time crest factor monitoring
import { createAudioInspectNode } from 'audio-inspect';
const audioContext = new AudioContext();
const crestNode = await createAudioInspectNode(audioContext, {
  featureName: 'getCrestFactor',
  featureOptions: { method: 'weighted' },
  bufferSize: 2048,
  hopSize: 1024
});

crestNode.onresult = (event) => {
  console.log(`Real-time Crest Factor: ${event.data.crestFactor} dB`);
};

2. True Peak Detection (Inter-Sample Peak Detection)

Oversampling-based inter-sample peak detection to prevent digital clipping.

import { getPeakAmplitude } from 'audio-inspect/features/time';

const audio = await load('audio.mp3');

// True Peak with 4x oversampling and cubic interpolation
const truePeak = getPeakAmplitude(audio, { 
  truePeak: true,
  oversamplingFactor: 4,
  interpolation: 'cubic'
});

console.log(`True Peak: ${truePeak} dB`);

3. MFCC (Mel-Frequency Cepstral Coefficients)

Comprehensive MFCC implementation for machine learning and speech analysis.

import { getMFCC, getMFCCWithDelta } from 'audio-inspect/features/spectral';

const audio = await load('speech.wav');

// Basic MFCC
const mfcc = await getMFCC(audio, {
  frameSizeMs: 25,
  hopSizeMs: 10,
  numMfccCoeffs: 13,
  numMelFilters: 40
});

// MFCC with delta and delta-delta coefficients
const mfccWithDelta = await getMFCCWithDelta(audio, {
  computeDelta: true,
  computeDeltaDelta: true
});

console.log(`MFCC: ${mfcc.mfcc.length} frames × ${mfcc.frameInfo.numCoeffs} coefficients`);

4. Spectral Entropy & Crest Factor

Measure spectral randomness and peak-to-average ratio in frequency domain.

import { getSpectralEntropy, getSpectralCrest } from 'audio-inspect/features/spectral';

const audio = await load('audio.mp3');

// Spectral entropy (noise vs. tonal content)
const entropy = await getSpectralEntropy(audio, {
  fftSize: 2048,
  minFrequency: 20,
  maxFrequency: 20000
});

// Spectral crest factor (harmonic vs. noise content)
const spectralCrest = await getSpectralCrest(audio, {
  fftSize: 2048,
  asDB: true
});

console.log(`Spectral Entropy: ${entropy.entropy} bits (${entropy.entropyNorm} normalized)`);
console.log(`Spectral Crest Factor: ${spectralCrest.crestDB} dB`);

Core API

Audio Loading

const audio = await load(source, {
  sampleRate: 44100,    // Target sample rate
  channels: 'mono',     // Channel configuration
  normalize: false      // Normalize amplitude
});

Time Domain Analysis

// Enhanced waveform analysis
const waveform = getWaveformAnalysis(audio, {
  frameCount: 3600,     // 1 minute at 60 FPS
  channel: 0,
  onProgress: (percent, message) => console.log(`${percent}%: ${message}`)
});

// Peak detection
const peaks = getPeaksAnalysis(audio, {
  count: 100,
  threshold: 0.1,
  channel: 0
});

// RMS analysis
const rms = getRMSAnalysis(audio, {
  channel: 0,
  asDB: true
});

Frequency Domain Analysis

// FFT analysis
const fft = await getFFT(audio, {
  fftSize: 2048,
  windowFunction: 'hann',
  provider: 'webfft'    // Fast WASM implementation
});

// Spectrum analysis
const spectrum = await getSpectrum(audio, {
  fftSize: 2048,
  minFrequency: 20,
  maxFrequency: 20000,
  timeFrames: 100       // Generate spectrogram
});

Audio Features

LUFS Loudness Measurement (ITU-R BS.1770-5 Compliant)

import { getLUFS } from 'audio-inspect/features/loudness';

const audio = await load('audio.mp3');

// Basic integrated loudness
const basicLoudness = getLUFS(audio);
console.log(`Integrated Loudness: ${basicLoudness.integrated} LUFS`);

// Comprehensive loudness analysis
const loudness = getLUFS(audio, {
  channelMode: 'stereo',        // 'mono' | 'stereo'
  gated: true,                  // ITU-R BS.1770 gating
  calculateShortTerm: true,     // 3-second short-term loudness
  calculateMomentary: true,     // 400ms momentary loudness
  calculateLoudnessRange: true, // LRA calculation
  calculateTruePeak: true       // True peak per channel (dBTP)
});

console.log(`Integrated: ${loudness.integrated} LUFS`);
console.log(`Loudness Range: ${loudness.loudnessRange} LU`);
console.log(`True Peak: ${loudness.truePeak?.map(tp => `${tp.toFixed(1)} dBTP`).join(', ')}`);

// Real-time loudness monitoring
import { createAudioInspectNode } from 'audio-inspect';
const audioContext = new AudioContext();
const loudnessNode = await createAudioInspectNode(audioContext, {
  featureName: 'getLUFS',
  featureOptions: { gated: true, calculateMomentary: true },
  bufferSize: 1024,
  hopSize: 512
});

loudnessNode.onresult = (event) => {
  const result = event.data;
  console.log(`Real-time LUFS: ${result.integrated}`);
};

Voice Activity Detection

const vad = getVAD(audio, {
  method: 'adaptive',
  energyThreshold: 0.01,
  frameSizeMs: 25
});

Spectral Features

const spectral = getSpectralFeatures(audio, {
  fftSize: 2048,
  features: ['centroid', 'bandwidth', 'rolloff', 'flatness']
});

Batch Processing

import { analyzeAll } from 'audio-inspect/core/batch';

const results = await analyzeAll(audio, {
  waveform: { frameCount: 1000 },
  peaks: { count: 50, threshold: 0.1 },
  rms: { channel: 0 },
  spectrum: { fftSize: 2048 },
  onProgress: (percent, currentTask) => {
    console.log(`Processing: ${percent}% (${currentTask})`);
  }
});

Tree-shaking Support

Import only the features you need:

// Time domain only
import { getPeaksAnalysis, getWaveformAnalysis } from 'audio-inspect/features/time';

// Frequency domain only
import { getFFT, getSpectrum } from 'audio-inspect/features/frequency';

// Audio features only
import { getLUFS } from 'audio-inspect/features/loudness';
import { getVAD } from 'audio-inspect/features/vad';

Browser Compatibility

• Chrome 66+ (WebAssembly support for WebFFT)
• Firefox 60+ (WebAssembly support)
• Safari 12+ (WebAssembly support)
• Edge 79+ (WebAssembly support)

Development

# Install dependencies
npm install

# Run tests
npm test

# Run E2E tests
npm run test:e2e

# Build library
npm run build

# Quality checks
npm run format && npm run lint && npm run type-check

License

MIT License - see the LICENSE file for details.