als-audio-analyzer

v2.2.0

Published

a year ago

A lightweight library for reading, analyzing, and modifying WAV audio signals through frequency-domain transformations. Built on top of [als-wave-parser](https://www.npmjs.com/package/als-wave-parser) for WAV parsing and [als-fft](https://www.npmjs.com/pa

0High
0Medium
0Low

alexsorkin

als-audio-analyzer

A lightweight library for reading, analyzing, and modifying WAV audio signals through frequency-domain transformations. Built on top of als-wave-parser for WAV parsing and als-fft for Fast Fourier Transform (FFT) computations.

Features

WAV Parsing: Loads audio data from WAV files using als-wave-parser.
Multi-channel Support: Automatically separates and processes multiple audio channels.
Frequency Manipulation: Select and modify specific frequency ranges using FFT (powered by als-fft).
Time Manipulation: Cut or exclude specific time segments from the audio.
Export Options: Export modified audio as a WAV buffer or data URL (Node.js v18+ or browser).
Chaining API: Fluent interface for easy method chaining.
Short-Time Fourier Transform (STFT): Supports overlapping segments and windowing for advanced time-frequency analysis (via als-fft v3.2.0+).

Installation

npm install als-audio-analyzer

Dependencies:

als-wave-parser
als-fft (v3.2.0 or higher recommended for STFT support)

Usage Examples

Node.js

const fs = require('fs');
const AudioAnalyzer = require('als-audio-analyzer');

// Read WAV file into ArrayBuffer
const arrayBuffer = fs.readFileSync('./samples/input.wav').buffer;

// Initialize with segment size of 2048 and STFT options
const analyzer = new AudioAnalyzer(arrayBuffer, 2048, {
  hopSizeFactor: 0.25, // 75% overlap
  hannWindow: true     // Apply Hann window
});

// Mute frequencies between 300-600 Hz in all channels
analyzer.frequencies(300, 600).applyToChannels('modify', 0);

// Cut the first 100 ms
analyzer.cutByTime(0, 100);

// Restore modified samples with overlap-add normalization
analyzer.restore();

// Export to WAV buffer and save to file
const wavBuffer = analyzer.toWavBuffer();
fs.writeFileSync('./samples/output.wav', Buffer.from(wavBuffer));
console.log('Audio processing complete.');

Browser

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>als-audio-analyzer Example</title>
  <script src="/node_modules/als-audio-analyzer/lib/index.js"></script>
</head>
<body>
  <audio controls></audio>
  <script>
    async function fetchAudio(url) {
      const response = await fetch(url);
      return await response.arrayBuffer();
    }

    async function main() {
      const arrayBuffer = await fetchAudio('./samples/input.wav');
      const analyzer = new AudioAnalyzer(arrayBuffer, 2048, {
        hopSizeFactor: 0.5, // 50% overlap
        hannWindow: true    // Use Hann window
      });

      // Mute frequencies 300-600 Hz in the first channel
      analyzer.channels[0].frequencies(300, 600).modify(0);

      // Cut first 15 time segments
      analyzer.cutTimepointsRange(0, 15);

      // Restore and set as audio source
      analyzer.restore();
      const audioUrl = analyzer.wavDataUrl();
      document.querySelector('audio').src = audioUrl;
    }

    main();
  </script>
</body>
</html>

API

Constructor

new AudioAnalyzer(arrayBuffer, segmentSize = 2048, options = {})

Creates an instance of AudioAnalyzer for processing WAV audio.

arrayBuffer (ArrayBuffer): The WAV audio data as an ArrayBuffer.
segmentSize (number, optional): The size of FFT segments. Must be a positive number (recommended to be a power of 2, e.g., 2048). Defaults to 2048.
options (object, optional): Additional configuration for STFT:
- hopSizeFactor (number, optional): Fraction of segmentSize defining the step size between segments (0 < hopSizeFactor <= 1). Defaults to 1 (no overlap).
- hannWindow (boolean, optional): Apply a Hann window to each segment if true. Defaults to false.
Throws:
- Error if arrayBuffer is not an ArrayBuffer.
- Error if segmentSize is not a finite positive number.
- Error if hopSizeFactor is not a finite number or exceeds 1.

Properties

segmentSize (number)
The FFT segment size used for frequency analysis.
channels (AudioChannel[])
Array of AudioChannel instances, one per audio channel.
freqStep (number)
Frequency resolution in Hz, calculated as sampleRate / segmentSize.
samples (Float32Array[])
Array of audio samples per channel, updated after restore().
sampleRate (number)
Sample rate of the audio (inherited from WAV file).
numChannels (number)
Number of audio channels in the WAV file.
hopSizeFactor (number)
The step size factor for STFT, as set in the constructor.
hannWindow (boolean)
Whether a Hann window is applied, as set in the constructor.
segmentTimeIntervalMs (number)
Duration of one segment in milliseconds, calculated as (segmentSize / sampleRate) * 1000.

Methods

restore()

analyzer.restore()

Restores the modified frequency-domain data back to time-domain samples for all channels. Updates analyzer.samples. When hopSizeFactor < 1 and/or hannWindow is enabled, uses overlap-add normalization for accurate reconstruction.

Returns: AudioAnalyzer for chaining.

applyToChannels(fnName, ...params)

analyzer.applyToChannels('frequencies', 300, 600)

Applies a specified method to all AudioChannel instances.

fnName (string): Name of the method to call on each channel (e.g., 'frequencies', 'modify').
params (any[]): Arguments to pass to the method.
Returns: AudioAnalyzer for chaining.

resetQuery()

analyzer.resetQuery()

Resets frequency and time-point filters on all channels.

Returns: AudioAnalyzer for chaining.

freqIndexes(arr)

analyzer.freqIndexes([10, 20, 30])

Selects specific frequency bin indexes for modification on all channels.

arr (number[]): Array of frequency bin indexes.
Returns: AudioAnalyzer for chaining.

frequencies(from, to)

analyzer.frequencies(300, 600)

Selects a frequency range (in Hz) for modification on all channels.

from (number): Start frequency in Hz.
to (number): End frequency in Hz.
Throws:
- Error if from or to is not a finite positive number.
- Error if from is greater than to.
Returns: AudioAnalyzer for chaining.

excludeTimePoints(arr)

analyzer.excludeTimePoints([1, 2, 3])

Excludes specific time segments from modification on all channels.

arr (number[]): Array of time segment indexes (based on FFT segments).
Returns: AudioAnalyzer for chaining.

onlyTimePoints(from, to)

analyzer.onlyTimePoints(0, 10)

Includes only the specified time segment range for modification, excluding all others on all channels.

from (number): Starting segment index.
to (number): Ending segment index.
Throws:
- Error if from or to is not a finite positive number.
- Error if from is greater than to.
Returns: AudioAnalyzer for chaining.

cutTimepointsRange(from, to)

analyzer.cutTimepointsRange(5, 10)

Permanently removes a range of time segments from all channels.

from (number): Starting segment index.
to (number): Ending segment index.
Returns: AudioAnalyzer for chaining.

cutTimepoints(arr)

analyzer.cutTimepoints([1, 3, 5])

Permanently removes specific time segments from all channels.

arr (number[]): Array of segment indexes to remove.
Returns: AudioAnalyzer for chaining.

cutByTime(from, to)

analyzer.cutByTime(0, 100)

Permanently removes a time range (in milliseconds) from all channels.

from (number): Start time in milliseconds.
to (number): End time in milliseconds.
Returns: AudioAnalyzer for chaining.

wavDataUrl()

const url = analyzer.wavDataUrl()

Generates a Blob URL for the modified WAV audio. Supported in Node.js v18+ and browsers.

Returns: string - A Blob URL (e.g., blob:http://...).
Throws: Error if Blob or URL APIs are not available in the environment.

mono(channelIndex)

analyzer.mono(0)

Converts the audio to mono by selecting a single channel.

channelIndex (number): Index of the channel to keep (0-based).
Throws: Error if channelIndex is invalid (negative or exceeds number of channels).
Returns: AudioAnalyzer for chaining.

AudioChannel Class

Represents a single audio channel and extends functionality from als-fft.

Properties

freqStep (number)
Frequency resolution in Hz, inherited from the parent AudioAnalyzer.

Methods

freqIndexes(arr)
Selects specific frequency bin indexes for modification.
- arr (number[]): Array of frequency bin indexes.
- Returns: AudioChannel for chaining.
frequencies(from, to)
Selects a frequency range (in Hz) for modification.
- from (number): Start frequency in Hz.
- to (number): End frequency in Hz.
- Throws:
  - Error if from or to is not a finite positive number.
  - Error if from is greater than to.
- Returns: AudioChannel for chaining.
excludeTimePoints(arr)
Excludes specific time segments from modification.
- arr (number[]): Array of segment indexes.
- Returns: AudioChannel for chaining.
onlyTimePoints(from, to)
Includes only the specified time segment range, excluding others.
- from (number): Starting segment index.
- to (number): Ending segment index.
- Throws:
  - Error if from or to is not a finite positive number.
  - Error if from is greater than to.
- Returns: AudioChannel for chaining.
modify(scale = 1, resetQuery = true)
Scales the amplitudes of selected frequencies.
- scale (number, optional): Scaling factor (e.g., 0 to mute, 0.5 to halve). Defaults to 1.
- resetQuery (boolean, optional): Whether to reset frequency and time filters after modification. Defaults to true.
- Throws: Error if scale is not a finite positive number.
- Returns: AudioChannel for chaining.
resetQuery()
Clears frequency and time-point filters.
- Returns: AudioChannel for chaining.

Notes

STFT Support: Since als-fft v3.2.0, AudioAnalyzer leverages STFT capabilities. Using hopSizeFactor < 1 increases the number of time segments due to overlap, and hannWindow reduces spectral leakage, improving signal restoration accuracy.
Backward Compatibility: The constructor remains compatible with older syntax (new AudioAnalyzer(arrayBuffer, segmentSize)), defaulting hopSizeFactor to 1 and hannWindow to false.
Performance: For large files with small hopSizeFactor values, memory usage increases due to more overlapping segments.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

als-audio-analyzer

Features

Installation

Usage Examples

Node.js

Browser

API

Constructor

Properties

Methods

restore()

applyToChannels(fnName, ...params)

resetQuery()

freqIndexes(arr)

frequencies(from, to)

excludeTimePoints(arr)

onlyTimePoints(from, to)

cutTimepointsRange(from, to)

cutTimepoints(arr)

cutByTime(from, to)

wavDataUrl()

mono(channelIndex)

AudioChannel Class

Properties

Methods

Notes