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

``bash
npm install als-audio-analyzer
`

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

---

Usage Examples

$3

`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.');
`

$3

`html












`

---

API

$3

`js
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.

---

$3

- 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.
---

$3

#### restore()

`js
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)

`js
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()

`js
analyzer.resetQuery()
`

Resets frequency and time-point filters on all channels.

- Returns: AudioAnalyzer for chaining.

---

#### freqIndexes(arr)

`js
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)

`js
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)

`js
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)

`js
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)

`js
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)

`js
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)

`js
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()

`js
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)

`js
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.

$3

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

$3

- 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.