audio-processor.js

Overview

The audio-processor.js file defines an AudioProcessor class that extends the AudioWorkletProcessor interface provided by the Web Audio API. Its primary function is to capture audio input data, optionally resample it to a target sample rate (defaulting to 22,000 Hz), and send the processed audio data to the main thread for further handling. This processing occurs in the audio rendering thread, enabling low-latency and efficient audio data manipulation.

Classes and Methods

Class: AudioProcessor

Extends: AudioWorkletProcessor

This class is a specialized audio processor designed to resample incoming audio streams from the browser's native sample rate to a target sample rate and communicate the processed audio data back to the main thread.

Constructor: constructor()

• Purpose: Initializes the audio processor with sample rate parameters and calculates the resampling ratio.

• Properties:

  • targetSampleRate (number): The desired output sample rate. Default is 22000 Hz.

  • originalSampleRate (number): The sample rate of the audio context/browser, given by the global sampleRate variable.

  • resampleRatio (number): The ratio between the original and target sample rates, used to downsample or upsample audio data.

Method: process(inputs, outputs, parameters)

• Parameters:

  • inputs (Array<Array>): An array of input audio channels. Each element represents an input node; the first input's channels are accessed as inputs[0].

  • outputs (Array<Array>): Outputs for this processor (not used in this implementation).

  • parameters (Object): Audio parameters (not used here).

• Returns: boolean — Always true to keep the processor alive.

• Functionality:

  • Accesses the first audio input channel (inputs[0][0]).

  • If the resampleRatio is not 1, calls the resample method to convert the audio data to the target sample rate.

  • Sends the processed audio data to the main thread via this.port.postMessage.

• Usage Example:

  // This method is automatically called by the AudioWorklet system.
  // It processes audio buffers frame-by-frame.
  

Method: resample(audioData)

• Parameters:

  • audioData (Float32Array): The input audio buffer to be resampled.

• Returns: Float32Array — The resampled audio buffer.

• Algorithm:

  • Calculates the length of the new audio buffer based on the resample ratio.

  • Uses nearest neighbor resampling by mapping each output sample index to the closest source sample index.

  • Copies samples accordingly to produce a resampled buffer.

• Implementation Details:

  • This is a straightforward nearest neighbor resampling approach, which is efficient but may introduce aliasing or quality loss compared to interpolation methods.

• Usage Example:

  const resampledData = audioProcessor.resample(originalAudioData);
  

Registration

• The processor is registered under the name 'audio-processor' using:

  registerProcessor('audio-processor', AudioProcessor);
  

• This makes the processor available for use by an AudioWorkletNode in the main thread.

Important Implementation Details

• Resampling Strategy: The resampling uses a simple nearest neighbor approach for efficiency. This method selects the closest corresponding sample from the original data without interpolation. While fast, this can introduce artifacts and is best suited for simple downsampling where audio quality is less critical.

• Sample Rate Handling: The processor determines the browser's native sample rate via the global sampleRate variable and calculates a ratio to the target sample rate. This allows dynamic adjustment to different operating environments.

• Communication: Processed audio frames are sent asynchronously to the main thread via the MessagePort (this.port.postMessage). This decouples audio processing from UI or other main-thread logic, improving performance and responsiveness.

• Processor Lifecycle: The process method always returns true, signaling the audio worklet to keep running continuously.

Interaction with Other System Components

• This file is intended to be used as part of an audio processing pipeline where an AudioWorkletNode is created on the main thread referencing this processor by name.

• The main thread handles the incoming audio data posted by the processor through the MessagePort and can perform further processing, analysis, or streaming.

• The processor operates in the audio rendering thread, ensuring that audio capture and resampling occur with minimal latency and without blocking the main thread.

• Integration with the broader audio system requires setup code on the main thread that loads this processor and instantiates an AudioWorkletNode to route audio input through it.

Structure Diagram

classDiagram
class AudioProcessor {
-targetSampleRate: number
-originalSampleRate: number
-resampleRatio: number
+constructor()
+process(inputs, outputs, parameters): boolean
+resample(audioData): Float32Array
}
AudioProcessor ..|> AudioWorkletProcessor

This diagram shows the AudioProcessor class extending AudioWorkletProcessor and its key methods and properties related to audio resampling and processing.