EnvelopeFollower.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Containers/Array.h"
#include "DSP/AlignedBuffer.h"
#include "DSP/FloatArrayMath.h"
#include "DSP/Dsp.h"
#include "HAL/Platform.h"
 
namespace Audio
{
    // Different modes for the envelope follower
    namespace EPeakMode
    {
        enum Type
        {
            MeanSquared,
            RootMeanSquared,
            Peak,
            Count
        };
    }
 
 
    class FAttackRelease
    {
        // see https://en.wikipedia.org/wiki/RC_time_constant
        // Time constants indicate how quickly the envelope follower responds to changes in input
        static constexpr float AnalogTimeConstant = 1.00239343f;
        static constexpr float DigitalTimeConstant = 4.60517019f;
 
    public:
        SIGNALPROCESSING_API FAttackRelease(float InSampleRate, float InAttackTimeMsec, float InReleaseTimeMsec, bool bInIsAnalog);
 
        SIGNALPROCESSING_API void SetAnalog(bool bInIsAnalog);
        SIGNALPROCESSING_API void SetAttackTime(float InAttackTimeMsec);
        SIGNALPROCESSING_API void SetReleaseTime(float InReleaseTimeMsec);
 
        inline bool GetAnalog() const { return bIsAnalog; }
 
        inline float GetAttackTimeSamples() const { return AttackTimeSamples; }
 
        inline float GetReleaseTimeSamples() const { return ReleaseTimeSamples; }
 
        inline float GetAttackTimeMsec() const { return AttackTimeMsec; }
 
        inline float GetReleaseTimeMsec() const { return ReleaseTimeMsec; }
 
        inline float GetSampleRate() const { return SampleRate; }
 
    protected:
 
        SIGNALPROCESSING_API void SetSampleRate(float InSampleRate);
 
    private:
 
        float SampleRate;
        float AttackTimeSamples;
        float AttackTimeMsec;
        float ReleaseTimeSamples;
        float ReleaseTimeMsec;
        bool bIsAnalog;
    };
    
 
    class FAttackReleaseSmoother : public FAttackRelease
    {
    public:
        SIGNALPROCESSING_API FAttackReleaseSmoother(float InSampleRate, int32 InNumChannels, float InAttackTimeMsec, float InReleaseTimeMsec, bool bInIsAnalog);
 
        SIGNALPROCESSING_API void ProcessAudio(const float* InBuffer, int32 InNumFrames);
 
        SIGNALPROCESSING_API void ProcessAudio(const float* InBuffer, int32 InNumFrames, float* OutBuffer);
 
        SIGNALPROCESSING_API const TArray<float>& GetEnvelopeValues() const;
 
        SIGNALPROCESSING_API void SetNumChannels(int32 InNumChannels);
 
        SIGNALPROCESSING_API void Reset();
 
    private:
        int32 NumChannels;
        TArray<float> PriorEnvelopeValues;
    };
 
    class FMeanSquaredFIR
    {
        static constexpr int32 DefaultHistoryCapacity = 16384;
 
    public:
 
        SIGNALPROCESSING_API FMeanSquaredFIR(float InSampleRate, int32 InNumChannels, float InWindowTimeMsec);
 
        SIGNALPROCESSING_API void SetWindowSize(float InWindowTimeMsec);
 
        SIGNALPROCESSING_API void SetNumChannels(int32 InNumChannels);
 
        SIGNALPROCESSING_API void Reset();
 
        SIGNALPROCESSING_API void ProcessAudio(const float* InBuffer, int32 InNumFrames, float* OutBuffer);
 
    private:
        float SampleRate;
        int32 NumChannels;
        int32 WindowTimeFrames;
        int32 WindowTimeSamples;
        float NormFactor;
 
        TArray<float> ChannelValues;
        TCircularAudioBuffer<float> HistorySquared;
        FAlignedFloatBuffer SquaredHistoryBuffer;
        FAlignedFloatBuffer SquaredInputBuffer;
    };
 
    class FMeanSquaredIIR
    {
    public:
        SIGNALPROCESSING_API FMeanSquaredIIR(float InSampleRate, int32 InNumChannels, float InWindowTimeMsec);
 
        SIGNALPROCESSING_API void SetWindowSize(float InWindowTimeMsec);
 
        SIGNALPROCESSING_API void SetNumChannels(int32 InNumChannels);
 
        SIGNALPROCESSING_API void Reset();
 
        SIGNALPROCESSING_API void ProcessAudio(const float* InBuffer, int32 InNumFrames, float* OutBuffer);
 
    private:
        float SampleRate;
        int32 NumChannels;
        float Alpha;
        float Beta;
 
        TArray<float> ChannelValues;
    };
 
    struct FEnvelopeFollowerInitParams
    {
        float SampleRate = 48000.f;
        int32 NumChannels = 1;
        float AttackTimeMsec = 10.0f;
        float ReleaseTimeMsec = 100.0f;
        EPeakMode::Type Mode = EPeakMode::Peak;
        bool bIsAnalog = true;
        float AnalysisWindowMsec=5.f;
    };
 
    class FEnvelopeFollower
    {
    public:
        SIGNALPROCESSING_API FEnvelopeFollower();
 
        SIGNALPROCESSING_API FEnvelopeFollower(const FEnvelopeFollowerInitParams& InParams);
 
        SIGNALPROCESSING_API void Init(const FEnvelopeFollowerInitParams& InParams);
 
        SIGNALPROCESSING_API int32 GetNumChannels() const;
 
        SIGNALPROCESSING_API float GetSampleRate() const;
 
        SIGNALPROCESSING_API float GetAttackTimeMsec() const;
 
        SIGNALPROCESSING_API float GetReleaseTimeMsec() const;
 
        SIGNALPROCESSING_API bool GetAnalog() const;
 
        SIGNALPROCESSING_API EPeakMode::Type GetMode() const;
 
        SIGNALPROCESSING_API void SetNumChannels(int32 InNumChannels);
 
        SIGNALPROCESSING_API void SetAnalog(bool bInIsAnalog);
 
        SIGNALPROCESSING_API void SetAttackTime(float InAttackTimeMsec);
 
        SIGNALPROCESSING_API void SetReleaseTime(float InReleaseTimeMsec);
 
        SIGNALPROCESSING_API void SetMode(EPeakMode::Type InMode);
 
        SIGNALPROCESSING_API void ProcessAudio(const float* InBuffer, int32 InNumFrames, float* OutBuffer);
 
        SIGNALPROCESSING_API void ProcessAudio(const float* InBuffer, int32 InNumFrames);
        
        SIGNALPROCESSING_API const TArray<float>& GetEnvelopeValues() const;
 
        SIGNALPROCESSING_API void Reset();
 
    private:
        void ProcessWorkBuffer(const float* InBuffer, int32 InNumFrames);
 
        FAlignedFloatBuffer WorkBuffer;
        FMeanSquaredIIR MeanSquaredProcessor; 
        FAttackReleaseSmoother Smoother;
 
        int32 NumChannels;
        EPeakMode::Type EnvMode;
    };
 
    struct FInlineEnvelopeFollowerInitParams
    {
        float SampleRate = 48000.f;
        float AttackTimeMsec = 10.0f;
        float ReleaseTimeMsec = 100.0f;
        EPeakMode::Type Mode = EPeakMode::Peak;
        bool bIsAnalog = true;
        float AnalysisWindowMsec=5.f;
    };
 
    class FInlineEnvelopeFollower : public FAttackRelease
    {
 
    public:
 
        FInlineEnvelopeFollower(const FInlineEnvelopeFollowerInitParams& InParams)
        : FAttackRelease(InParams.SampleRate, InParams.AttackTimeMsec, InParams.ReleaseTimeMsec, InParams.bIsAnalog)
        , Value(0.f)
        , Mode(InParams.Mode)
        , AnalysisValue(0.f)
        , AnalysisWindowMsec(5.f)
        {
            SetAnalysisWindow(InParams.AnalysisWindowMsec);
        }
 
        FInlineEnvelopeFollower()
        : FInlineEnvelopeFollower(FInlineEnvelopeFollowerInitParams{})
        {
        }
 
        void Init(const FInlineEnvelopeFollowerInitParams& InParams)
        {
            SetSampleRate(InParams.SampleRate);
            SetAttackTime(InParams.AttackTimeMsec);
            SetReleaseTime(InParams.ReleaseTimeMsec);
            SetMode(InParams.Mode);
            SetAnalog(InParams.bIsAnalog);
            SetAnalysisWindow(InParams.AnalysisWindowMsec);
        }
 
        /* Sets the input analysis mode of the envelope follower */
        void SetMode(EPeakMode::Type InMode)
        {
            Mode = InMode;
        }
 
        void SetAnalysisWindow(float InAnalysisWindowMsec)
        {
            if (ensure(InAnalysisWindowMsec > 0.f))
            {
                AnalysisWindowMsec = InAnalysisWindowMsec;
                InitMeanSquaredCoefficients(AnalysisWindowMsec, GetSampleRate());
            }
        }
 
        inline float ProcessSample(float InSample)
        {
            float NormSample = NormalizeSample(InSample);
 
            float Diff = Value - NormSample;
            if (Diff <= 0.f)
            {
                Value = (GetAttackTimeSamples() * Diff) + NormSample;
            }
            else
            {
                Value = (GetReleaseTimeSamples() * Diff) + NormSample;
            }
 
            return Value;
        }
 
        inline void ProcessBuffer(const float* InSamples, const int32 InNumSamples, float* OutSamples)
        {
            check(InSamples != OutSamples);
 
            NormalizeSamples(InSamples, InNumSamples, OutSamples);
 
            for (int32 SampleIndex = 0; SampleIndex < InNumSamples; ++SampleIndex)
            {
                float NormSample = OutSamples[SampleIndex];
                float Diff = Value - NormSample;
                if (Diff <= 0.f)
                {
                    Value = (GetAttackTimeSamples() * Diff) + NormSample;
                }
                else
                {
                    Value = (GetReleaseTimeSamples() * Diff) + NormSample;
                }
                OutSamples[SampleIndex] = Value;
            }
        }
 
        void Reset()
        {
            Value = 0.f;
        }
 
        inline float GetValue() const
        {
            return Value;
        }
 
    private:
        inline float NormalizeSample(float InSample)
        {
            switch (Mode)
            {
                case EPeakMode::Peak:
                    return FMath::Abs(InSample);
                    
                case EPeakMode::MeanSquared:
 
                    {
                        float SampleSquared = InSample * InSample;
                        AnalysisValue = AnalysisFilterBeta * SampleSquared + AnalysisFilterAlpha * AnalysisValue;
                        return AnalysisValue;
                    }
 
                case EPeakMode::RootMeanSquared:
 
                    {
                        float SampleSquared = InSample * InSample;
                        AnalysisValue = AnalysisFilterBeta * SampleSquared + AnalysisFilterAlpha * AnalysisValue;
                        return FMath::Sqrt(AnalysisValue);
                    }
 
                default:
                {
                    checkNoEntry();
                }
            }
 
            return InSample;
        }
 
        inline void NormalizeSamples(const float* InSamples, const int32 InNumSamples, float* OutSamples)
        {
            TArrayView<const float> In = TArrayView<const float>(InSamples, InNumSamples);
            TArrayView<float> Out = TArrayView<float>(OutSamples, InNumSamples);
            switch (Mode)
            {
            case EPeakMode::Peak:
                ArrayAbs(In, Out);
                return;
 
            case EPeakMode::MeanSquared:
            {
                ArraySquare(In, Out);
                for (int32 SampleIndex = 0; SampleIndex < InNumSamples; ++SampleIndex)
                {
                    AnalysisValue = AnalysisFilterBeta * OutSamples[SampleIndex] + AnalysisFilterAlpha * AnalysisValue;
                    OutSamples[SampleIndex] = AnalysisValue;
                }
                return;
            }
 
            case EPeakMode::RootMeanSquared:
 
            {
                ArraySquare(In, Out);
                for (int32 SampleIndex = 0; SampleIndex < InNumSamples; ++SampleIndex)
                {
                    AnalysisValue = AnalysisFilterBeta * OutSamples[SampleIndex] + AnalysisFilterAlpha * AnalysisValue;
                    OutSamples[SampleIndex] = AnalysisValue;
                }
                ArraySqrtInPlace(Out);
                return;
            }
 
            default:
            {
                checkNoEntry();
            }
            }
        }
 
        void InitMeanSquaredCoefficients(float InWinMsec, float InSampleRate)
        {
            if (ensure((InSampleRate > 0.f) && (InWinMsec > 0.f)))
            {
                AnalysisFilterAlpha = FMath::Exp(-1000.f / (InSampleRate * InWinMsec));
                AnalysisFilterBeta = 1.f - AnalysisFilterAlpha;
            }
        }
 
        float Value = 0.f;
        EPeakMode::Type Mode = EPeakMode::Peak;
        float AnalysisValue = 0.f;
        float AnalysisWindowMsec = 10.f;
        float AnalysisFilterAlpha = 0.f;
        float AnalysisFilterBeta = 1.f;
    };
}