FX Class: Compressor

Interactive example

Overview

This compressor effect is used to reduce the span between the softest and loudest sounds or dynamic range. It is often used to control maximum levels and maintain higher average loudness.

The inputGainDb and outputGainDb properties are set with values between -24 and 24 with a default of 0. The wet property controls the balance between the audio and the effect with a range of 0 to 1. The attackSec and releaseSec properties are limited to values between `0.0001 - 1` and `0.1 - 4` respectively (both in seconds). The thresholdDb and ratio properties are integral to the effect with the ratio specifying the amount of attenuation applied to the signal and threshold setting the level at which the compression effect is engaged. The hpCutOffHz represents the integrated highpass filter frequency which in this case is limited to values between 1 and 1000. Finally, there is a getGainReductionDb() method which will return the maximum gain reduction in decibels since the last getGainReductionDb() call.

The compressor class doesn't allocate any internal buffers and needs less than 1 kb of memory.

Implementation example

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

class SuperpoweredCompressorStageProcessor extends SuperpoweredWebAudio.AudioWorkletProcessor {
    // runs after the constructor
    onReady() {
        this.compressor = new this.Superpowered.Compressor(
            this.samplerate, // The initial sample rate in Hz.
        );

        this.compressor.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.compressor.destruct();
    }

    // messages are received from the main scope through this method.
    onMessageFromMainScope(message) {
        if (typeof message.inputGainDb !== 'undefined') this.compressor.inputGainDb = message.inputGainDb;
        if (typeof message.outputGainDb !== 'undefined') this.compressor.outputGainDb = message.outputGainDb;
        if (typeof message.wet !== 'undefined') this.compressor.wet = message.wet;
        if (typeof message.attackSec !== 'undefined') this.compressor.attackSec = message.attackSec;
        if (typeof message.releaseSec !== 'undefined') this.compressor.releaseSec = message.releaseSec;
        if (typeof message.ratio !== 'undefined') this.compressor.ratio = message.ratio;
        if (typeof message.thresholdDb !== 'undefined') this.compressor.thresholdDb = message.thresholdDb;
        if (typeof message.hpCutOffHz !== 'undefined') this.compressor.hpCutOffHz = message.hpCutOffHz;
        if (typeof message.enabled !== 'undefined') this.compressor.enabled = message.enabled;
    }


    processAudio(inputBuffer, outputBuffer, buffersize, parameters) {
         // Ensure the samplerate is in sync on every audio processing callback
        this.compressor.samplerate = this.samplerate;

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

#include "SuperpoweredCompressor.h"

void initCompressor() {
    unsigned int sampleRate = 44100;
    compressor = new Superpowered::Compressor(sampleRate);
}

void configureCompressor() {
    compressor->inputGainDb = 0;
    compressor->outputGainDb = 0;
    compressor->wet = 1;
    compressor->attackSec = 0.003;
    compressor->releaseSec = 0.3;
    compressor->ratio = 3;
    compressor->thresholdDb = 0;
    compressor->hpCutOffHz = 1;

    compressor->enabled = true;
}

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

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

Properties

Number

float

Number

float

Number

float

Number

float

Number

float

Number

float

Number

float

Number

float

Boolean

bool

Number

unsigned int

Methods

• constructor

  METHOD

  Creates an instance of the Compressor class.

  Parameters

  Name	Type	Description
  samplerate	Number	The initial sample rate in Hz.

  Returns

  Type	Description
  Superpowered.Compressor	The constructed instance

• constructor

  METHOD

  Creates an instance of the Compressor class.

  Parameters

  Name	Type	Default	Description
  samplerate	unsigned int		The initial sample rate in Hz.

  Returns

  Type	Description
  Superpowered::Compressor	The constructed instance

• getGainReductionDb

  METHOD

  Returns the maximum gain reduction in decibels since the last getGainReductionDb() call.

  Parameters

  None

  Returns

  Type	Description
  Number	Reduction in db.

• getGainReductionDb

  METHOD

  Returns the maximum gain reduction in decibels since the last getGainReductionDb() call.

  Parameters

  None

  Returns

  Type	Description
  float	Reduction in db.

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