FX Class: Filter

Interactive example

Overview

Filters are used to alter the harmonic content of a signal. This Filter effect internally is a classic IIR (Infinite Impulse Response) filter. It doesn't allocate any internal buffers and needs just a few bytes of memory.

Filter is an IIR filter based on the typical direct form 1 formula:

y[n] = (b0/a0)*x[n] + (b1/a0)*x[n-1] + (b2/a0)*x[n-2] - (a1/a0)*y[n-1] - (a2/a0)*y[n-2]

Implementation example

The Filter is initialized with an initial filter type and sample rate. It has five adjustable properties: frequency, decibel, resonance, octave, and slope.

Different Filter types are available as constants on the Filter class:

• Parametric
• Resonant_Lowpass
• Resonant_Highpass
• Bandlimited_Bandpass
• Bandlimited_Notch
• LowShelf
• HighShelf
• CustomCoefficients

CustomCoefficients allows to use your own IIR filter coefficients. You should call setCustomCoefficients() in the following way:

// Changes will be smoothly handled to prevent audio artifacts. Do not call this concurrently with process().
this.filter.setCustomCoefficients(
    1, // b0/a0
    1, // b1/a0
    1, // b2/a0
    1, // a1/a0
    1  // a2/a0
);

// Changes will be smoothly handled to prevent audio artifacts. Do not call this concurrently with process().
filter->setCustomCoefficients(
    1, // b0/a0
    1, // b1/a0
    1, // b2/a0
    1, // a1/a0
    1  // a2/a0
);

The filter is an FX class, it expects both an input and output buffer. The process() function should be called on every loop of the audio processing block.

class SuperpoweredFilterProcessor extends SuperpoweredWebAudio.AudioWorkletProcessor {

    // Called when the AudioWorklet is ready to start processing audio
    onReady() {
        this.filter = new this.Superpowered.Filter(
            Superpowered.Filter.Resonant_Lowpass, // The initial filter type
            44100 // initial sample rate
        );
        this.filter.enabled = true;
    }

    // Runs before the node is destroyed.
    // Clean up memory and objects here (such as free allocated linear memory or destruct Superpowered objects).
    onDestruct() {
        this.filter.destruct();
    }

    // The shape of the message we pass from our main thread is up to you
    onMessageFromMainScope(message) {

        if (typeof message.frequency !== 'undefined') this.filter.frequency = message.frequency;
        if (typeof message.decibel !== 'undefined') this.filter.decibel = message.decibel;
        if (typeof message.resonance !== 'undefined') this.filter.resonance = message.resonance;
        if (typeof message.octave !== 'undefined') this.filter.octave = message.octave;
        if (typeof message.slope !== 'undefined') this.filter.slope = message.slope;
        if (typeof message.type !== 'undefined') this.filter.type = this.Superpowered.Filter[message.type];

        if (typeof message.enabled !== 'undefined') this.filter.enabled = Boolean(message.enabled);

    }

    // This is the process loop which is passed pointers to buffers
    // from the WebAudio API (inputBuffer and outputBuffer), with the buffersize (128 samples when running as a native AudioWorklet)
    processAudio(inputBuffer, outputBuffer, buffersize) {
        // Ensure the samplerate is in sync on every audio processing callback
        this.filter.samplerate = this.samplerate;

        // Render the output buffers
        if (!this.filter.process(inputBuffer.pointer, outputBuffer.pointer, buffersize)) {
            for (let n = 0; n < buffersize * 2 ; n++) outputBuffer.array[n] = inputBuffer.array[n];
        }
    }
}

#include "SuperpoweredFilter.h"

void initFilterEffect() {
    unsigned int sampleRate = 44100;
    filter = new Superpowered::Filter(Superpowered::Filter::Parametric, sampleRate);
    filter->enabled = true;
}

void configureFilterEffect() {
    filter->frequency = 4000;
    filter->decibel = 6;    
}

void processAudio(float *interleavedInput, float *interleavedOutput, unsigned int numberOfFrames, unsigned int samplerate) {
    // Ensure the samplerate is in sync on every audio processing callback
    filter->samplerate = samplerate;

    // Render the output buffers
    bool outputChanged = filter->process(interleavedInput, interleavedOutput, numberOfFrames);
    ...
}

Constants

• Superpowered.Filter

  CONSTANTS

  Filter types.

  Value	Description
  Resonant_Lowpass	Resonant lowpass filter - frequency, resonance controllable.
  Resonant_Highpass	Resonant highpass filter - frequency, resonance controllable.
  Bandlimited_Bandpass	Bandlimited bandpass filter - frequency, octave controllable.
  Bandlimited_Notch	Bandlimited notch filter - frequency, octave controllable.
  LowShelf	Low shelf filter - frequency, slope, decibel controllable.
  HighShelf	High shelf filter - frequency, slope, decibel controllable.
  Parametric	Parametric filter - frequency, octave, decibel controllable.
  CustomCoefficients	User defined filter coefficients. Once set, call setCustomCoefficients().

• Superpowered::Filter

  CONSTANTS

  Filter types.

  Value	Description
  Resonant_Lowpass	Resonant lowpass filter - frequency, resonance controllable.
  Resonant_Highpass	Resonant highpass filter - frequency, resonance controllable.
  Bandlimited_Bandpass	Bandlimited bandpass filter - frequency, octave controllable.
  Bandlimited_Notch	Bandlimited notch filter - frequency, octave controllable.
  LowShelf	Low shelf filter - frequency, slope, decibel controllable.
  HighShelf	High shelf filter - frequency, slope, decibel controllable.
  Parametric	Parametric filter - frequency, octave, decibel controllable.
  CustomCoefficients	User defined filter coefficients. Once set, call setCustomCoefficients().

Properties

Number

float

Number

float

Number

float

Number

float

Number

float

Number

Superpowered.Filter

Boolean

bool

Number

unsigned int

Methods

• constructor

  METHOD

  Creates an instance of the Filter class.

  Parameters

  Name	Type	Description
  type	Superpowered.Filter.FilterType	The initial filter type.
  samplerate	Number	The initial sample rate in Hz.

  Returns

  Type	Description
  Superpowered.Filter	The constructed instance.

• constructor

  METHOD

  Creates an instance of the Filter class.

  Parameters

  Name	Type	Default	Description
  type	Superpowered::Filter::FilterType		The initial filter type.
  samplerate	unsigned int		The initial sample rate in Hz.

  Returns

  Type	Description
  Superpowered::Filter	The constructed instance.

• processMono

  METHOD

  Processes/renders mono audio. Always call it in the audio processing callback, regardless if the effect is enabled or not for smooth, audio-artifact free operation. It's never blocking for real-time usage. You can change all effect properties on any thread, concurrently with process().

  Parameters

  Name	Type	Description
  input	Number (pointer in Linear Memory)	32-bit mono input.
  output	Number (pointer in Linear Memory)	32-bit mono output.
  numberOfFrames	Number	Number of frames to process. Recommendations for best performance: multiply of 4, minimum 64.

  Returns

  Type	Description
  Boolean	If process() returns with true, the contents of output are replaced with the audio output. If process() returns with false, it indicates silence. The contents of output are not changed in this case (not overwritten with zeros).

• processMono

  METHOD

  Processes/renders mono audio. Always call it in the audio processing callback, regardless if the effect is enabled or not for smooth, audio-artifact free operation. It's never blocking for real-time usage. You can change all effect properties on any thread, concurrently with process().

  Parameters

  Name	Type	Default	Description
  input	float *		32-bit mono input.
  output	float *		32-bit mono output.
  numberOfFrames	unsigned int		Number of frames to process. Recommendations for best performance: multiply of 4, minimum 64.

  Returns

  Type	Description
  bool	If process() returns with true, the contents of output are replaced with the audio output. If process() returns with false, it indicates silence. The contents of output are not changed in this case (not overwritten with zeros).

• setCustomCoefficients

  METHOD

  For advanced use. Set custom coefficients for the filter. Changes will be smoothly handled to prevent audio artifacts. Do not call this concurrently with process().

  Parameters

  Name	Type	Description
  b0/a0	Number	First feed forward/backward coefficient.
  b1/a0	Number	Second feed forward/backward coefficient.
  b2/a0	Number	Third feed forward/backward coefficient.
  a1/a0	Number	Forth feed forward/backward coefficient.
  a2/a0	Number	Fifth feed forward/backward coefficient.

  Returns

  None

• setCustomCoefficients

  METHOD

  For advanced use. Set custom coefficients for the filter. Changes will be smoothly handled to prevent audio artifacts. Do not call this concurrently with process().

  Parameters

  Name	Type	Default	Description
  b0/a0	float		First feed forward/backward coefficient.
  b1/a0	float		Second feed forward/backward coefficient.
  b2/a0	float		Third feed forward/backward coefficient.
  a1/a0	float		Forth feed forward/backward coefficient.
  a2/a0	float		Fifth feed forward/backward coefficient.

  Returns

  None

• destruct

  METHOD

  Destructor to free Linear Memory.

  Parameters

  None

  Returns

  None

• process

  METHOD

  Processes/renders the audio. Always call it in the audio processing callback, regardless if the effect is enabled or not for smooth, audio-artifact free operation. It's never blocking for real-time usage.

  Parameters

  Name	Type	Description
  input	Number (pointer in Linear Memory)	32-bit interleaved stereo input.
  output	Number (pointer in Linear Memory)	32-bit interleaved stereo output.
  numberOfFrames	Number	Number of frames to process. Recommendations for best performance: multiply of 4, minimum 64.

  Returns

  Type	Description
  Boolean	If process() returns with true, the contents of output are replaced with the audio output. If process() returns with false, it indicates silence. The contents of output are not changed in this case (not overwritten with zeros).

• process

  METHOD

  Processes/renders the audio. Always call it in the audio processing callback, regardless if the effect is enabled or not for smooth, audio-artifact free operation. It's never blocking for real-time usage. You can change all effect properties on any thread, concurrently with process().

  Parameters

  Name	Type	Default	Description
  input	float *		32-bit interleaved stereo input.
  output	float *		32-bit interleaved stereo output.
  numberOfFrames	unsigned int		Number of frames to process. Recommendations for best performance: multiply of 4, minimum 64.

  Returns

  Type	Description
  bool	If process() returns with true, the contents of output are replaced with the audio output. If process() returns with false, it indicates silence. The contents of output are not changed in this case (not overwritten with zeros).