OpenAudio_ArduinoLibrary/AudioEffectCompressor2_F32.h

/*
 *        AudioEffectCompressor2_F32.h
 *
 * Bob Larkin  W7PUA  11 December 2020
 *
 * This is a general purpose audio compressor block (C++ class). It works by determining
 * the average input of the input signal, and based on a pre-determined curve,
 * changes the gain going through the block.
 * A good discussion is the Wikipedia page:
 *     https://en.wikipedia.org/wiki/Dynamic_range_compression
 * This compressor includes up to 5 dB/dB line segments allowing for most of the
 * features listed.  These include
 *   Multi segment compression curves, up to 5
 *   Limiting
 *   Approximation to "soft knees"
 *   Expansion for suppressing low-level artifacts
 *   Anticipation
 *   Scale offset for use such as hearing-aid audiology
 * This is derived from the WDRC compressor. Chip Audette (OpenAudio) Feb 2017
 * Which was derived From: WDRC_circuit from CHAPRO from BTNRC: https://github.com/BTNRH/chapro
 * As of Feb 2017, CHAPRO license is listed as "Creative Commons?"
 *
 * MIT License.  Use at your own risk.
 */
/* Compressor #2.  Amplifies input signals by varying amoounts depending
 * on the signal level.  This is controlled by up to 5 line segments specified
 * by a point at the highest input level for the line along with a compression ratio
 * (1/slope) for the line segment. This can provide limiting at the highest inputs
 * by setting compressionRatio[0]=1000.0 (i.e., some big value).  Expansion at the
 * lw levels provides a squelch action, using a very small compression
 * ratio like 0.01.
 *
 * A special case is the [0] segment, that continues at the same slope for inputs up
 * to any level.  For this the kneeDB[0] can be the expected 0.0  or other values
 * on that line.  The output level for kneeDB[0] is the input variable, marginDB.
 * This allows gain control near clipping but below.  marginDB is typically 1 or 2 dB.
 *
    Vout dB
      |
      |
  0.0 +                                     kneeDB[0]
 marg +                        kneeDB[1]        @********************
      |                            @************    1:compressionRatio[0]
      |                        ****
      |                     ***
      |                  ***
      |               *** 1:compressionRatio[1]
      | kneeDB[2]  ***
      |        @***
      |       *
      |      *
      |     *
      |    *
      |   * 1:compressionRatio[2]
      |  *
      | *                         ===  Vout in dB vs. Vin in dB  ===
      |*                               Three segment example
      *                          Knees (breakpoints) are shown with '@'
     *|    compressionRatio[] are ratio of: input change (in dB):output change in dB
    * |
   *  |________|___________________|____________________________|________ vIn dB
               k1                  k2                          0.0

 * The graph shows the changes in gain on a log or dB scale.  A compressionRatio
 * of 1 represents a constant gain with level.  When the compressionRatio is greater
 * than 1, say 2.0, the voltage gain is decreasing as the input level increases.
 *
 * vInDB refers to the time averaged envelope voltage.
 * The zero reference is the full ADC range output. This is ±1.0
 * peak or 0.707 RMS in F32 terminology.
 *
 * The curve is for gainOffsetDB = 0.0. This parameter raises and lowers the
 * input scale for the kneeDB[] parameter.
 *
 * Timing: For 44.1 kHz sample rate and 256 samples per update, the update( ) time
 * runs 240 to 270 icroseconds using Teensy 3.6.
 */

#ifndef _AUDIO_EFFECT_COMPRESSOR2_F32_H
#define _AUDIO_EFFECT_COMPRESSOR2_F32_H

#include <Arduino.h>
#include <AudioStream_F32.h>

// The following 3 defines are simplified implementations for common uses.
// They replace the begin() function that is otherwise required.
// See testCompressor2.ino example for how to use these defines.
// None of these support offsetting the input scale as done in Tympan.

/* limiterBegin(pointerObject, float marDB, float linearInDB) has 2 segments.
 * It is linear up to an input of linearInDB (typically -15.0f) and
 * then virtually limits for higher input levels.  The output level at
 * this point is marDB, the margin to prevent clipping, like -2 dB.
 * This is not a clipper with waveform distortion, but rather decreases
 * the gain, dB for dB, as the input increases in the limiter region.
 * pobject is a pointer to the INO AudioEffectCompressor2_F32 object.
 * This function replaces begin() for the AudioEffectCompressor2_F32 object.
 */
#define limiterBegin(pobject, marDB, linearInDB)  struct compressionCurve _curv={marDB,0.0f,{0.0,linearInDB,-1000.0f,-1000.0f,-1000.0f},{100.0,1.0f,1.0f,1.0f,1.0f}}; pobject->setCompressionCurve(&_curv); pobject->begin();

/* basicCompressorBegin has a 3 segments.  It is linear up to an input linearInDB
 * and then decreases gain according to compressionRatioDB up to an input -10 dB where it
 * is almost limited, with an increase of output level of 1 dB for a 10 dB increase
 * in input level.  The output level at full input is 1 dB below full output.
 * This function replaces begin() for the AudioEffectCompressor2_F32 object.
 */
#define basicCompressorBegin(pobject, linearInDB, compressionRatio)  struct compressionCurve _curv={-1.0,0.0f,{0.0,-10.0f,linearInDB,-1000.0f,-1000.0f},{10.0f,compressionRatio,1.0f,1.0f,1.0f}}; pobject->setCompressionCurve(&_curv); pobject->begin();

/* squelchCompressorBegin is similar to basicCompression above, except that there is
 * an expansion region for low levels.  So, the call defines the four regions in
 * terms of the input levels.  squelchInDB sets the lowest input level
 * before the squelching effect starts. */
#define squelchCompressorBegin(pobject, squelchInDB, linearInDB, compressionInDB, compressionRatio) struct compressionCurve _curv={-1.0,0.0f,{0.0,compressionInDB,linearInDB,squelchInDB,-1000.0f},{10.0,compressionRatio,1.0f,0.1f,1.0f}}; pobject->setCompressionCurve(&_curv); pobject->begin();

// Basic definition of compression curve:
struct compressionCurve {
   float marginDB;
   float offsetDB;
   float kneeDB[5];
   float compressionRatio[5];
};

// ---------------------------------------------------------------------------

class AudioEffectCompressor2_F32 : public AudioStream_F32
{
//GUI: inputs:1, outputs:1  //this line used for automatic generation of GUI node
//GUI: shortName: Compressor2
  public:
    AudioEffectCompressor2_F32(void): AudioStream_F32(1, inputQueueArray) {
       setAttackReleaseSec(0.005f, 0.100f);
       }

    AudioEffectCompressor2_F32(const AudioSettings_F32 &settings): AudioStream_F32(1, inputQueueArray) {
       //setSampleRate_Hz(settings.sample_rate_Hz);
       setAttackReleaseSec(0.005f, 0.100f);
       }

    virtual void update(void);
    void begin(void);
    void setCompressionCurve(struct compressionCurve*);
    // A delay of 256 samples is 256/44100 = 0.0058 sec = 5.8 mSec
    void setDelayBufferSize(int16_t _delaySize) { // Any power of 2, i.e., 256, 128, 64, etc.
       delaySize = _delaySize;
       delayBufferMask = _delaySize - 1;
       in_index = 0;
       }
    void printOn(bool _printIO) { printIO = _printIO; } // Diagnostics ONLY. Not for general INO
    float getCurrentInputDB(void) { return sampleInputDB; }
    float getCurrentGainDB(void)  { return sampleGainDB; }
    float getvInMaxDB(void)  {
       float vRet = vInMaxDB;
       vInMaxDB = -1000.0f;   // Reset for next max measure
       return vRet;
       }
    //convert time constants from seconds to unitless parameters, from CHAPRO, agc_prepare.c
    void setAttackReleaseSec(const float atk_sec, const float rel_sec) {
        // convert ANSI attack & release times to filter time constants
        float ansi_atk = atk_sec * sample_rate_Hz / 2.425f;
        float ansi_rel = rel_sec * sample_rate_Hz / 1.782f;
        alpha = (float) (ansi_atk / (1.0f + ansi_atk));
        oneMinusAlpha = 1.0f - alpha;
        beta = (float) (ansi_rel / (1.0f + ansi_rel));
        }

  private:
    audio_block_f32_t *inputQueueArray[1];
    float delayData[256];   // The circular delay line for the signal
    uint16_t in_index = 0;      // Pointer to next block update entry
    // And a mask to make the circular buffer limit to a power of 2
    uint16_t delayBufferMask = 0X00FF;
    uint16_t delaySize = 256;

    float sample_rate_Hz = 44100;
    float attackSec = 0.005f;  // Q: Can this be reduced with the delay line added to the signal path??
    float releaseSec = 0.100f;
    // This alpha, beta for 5 ms attack, 100ms release, about 0.07 dB max ripple at 1000 Hz
    float alpha = 0.98912216f;
    float oneMinusAlpha = 0.01087784f;
    float beta = 0.9995961f;

    /*          Definition of the compression curve.
     * Input and output are normally referenced to the full scale range (-1.0 to 1.0 in float).
     * The full scale point is called 0 dB.
     * There are 5 slopes, specified by the top input level for each line segment (kneeDB[])
     * and the Compression Ratio (1/slope) of the segment (compressionRatio[]).
     * These are numbered from the highest to the lowest allowing
     * the number of segments to be adjusted, i.e., there is always a segment 0
     * but there may not be a segment 3 and 4, for instance. This becomes very flexible,
     * as there can be, say, compression for top levels and expansion for very low levels.
     *
     * A special case is segment 0.  On a plot of output dB vs input db, an input
     * level of kneeDB[0] produces an output of marginDB. A typical marginDB might
     * be -1.0 or -2.0.  This margin allows controlling the gain without clipping in the DAC.
     *
     * This structure can have multiple curve structures like cCurve that can be used by
     *     cmpr1.setCompressionCurve(&cCurve);
     *     cmpr1.begin();
     *
     * Unused segments can have knees like kneeDB[4] at, say -1000.0f.
     * Values below -500 will slightly speed up the update() function.  if the bottom
     * two segments are not used, kneeDB[3] would also be set to -1000.0f amd so forth.
     *
     * Finally, there is a variable offsetDB that allows for a shift in the input scale.
     * It simply shifts the definition input levels, in dB.
     * This allows converting from DSP scales that have 0dB at full DSP scale
     * to auditory scales such as are used in the Tympan library. An offsetDB=119.0
     * would allow all inputs to be in "SPL" units with a maximum input value of 119.
     */
     struct compressionCurve curve0 = { -2.0f, 0.0f,        // margin, offset
        {0.0f, -10.0f, -20.0f, -30.0f, -1000.0f},           // kneeDB[]
        {  100.0f,  2.0f,   1.5f,     1.0f,      1.0f} };   // compressionRatio
    // VoutDB at each knee, needed to find gain; determined at begin():
    float outKneeDB[5]={-2.0f, -3.0f, -8.0f -978.0f, -978.0f};
    // slopes are 1/compressionRatio determined at begin() to save update{} time
    float slope[5] = {0.01f, 0.5f, 0.666667f, 1.0f, 1.0f};

    // Save time in update() by ignoring unused (low level) segments:
    uint16_t firstIndex = 3;
    float vPeakSave = 0.0f;
    float vInMaxDB = -1000.0f;    // Only for reporting
    bool printIO = false;      // Diagnostics Only
    float sampleInputDB, sampleGainDB;
};
#endif