backbeat.h

Go to the documentation of this file.

#pragma once
 
#include "fl/audio/audio_detector.h"
#include "fl/stl/function.h"
#include "fl/stl/vector.h"
#include "fl/stl/deque.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
namespace audio {
namespace detector {

struct MultibandAccent {
    float bass;   // Bass band accent strength (0-1)
    float mid;    // Mid band accent strength (0-1) - critical for snare
    float high;   // High band accent strength (0-1)
    float total;  // Weighted combination of all bands
};

class Backbeat : public Detector {
public:
    explicit Backbeat(shared_ptr<Beat> beatDetector) FL_NO_EXCEPT;

    explicit Backbeat(shared_ptr<Beat> beatDetector,
                              shared_ptr<Downbeat> downbeatDetector) FL_NO_EXCEPT;

    Backbeat() FL_NO_EXCEPT;
 
    ~Backbeat() FL_NO_EXCEPT override;
 
    void update(shared_ptr<Context> context) FL_NO_EXCEPT override;
    void fireCallbacks() FL_NO_EXCEPT override;
    bool needsFFT() const FL_NO_EXCEPT override { return true; }
    bool needsFFTHistory() const FL_NO_EXCEPT override { return false; }
    const char* getName() const FL_NO_EXCEPT override { return "Backbeat"; }
    void reset() FL_NO_EXCEPT override;
 
    // ----- Callbacks (multiple listeners supported) -----

    function_list<void(u8 beatNumber, float confidence, float strength)> onBackbeat;
 
    // ----- State Access -----

    bool isBackbeat() const FL_NO_EXCEPT { return mBackbeatDetected; }

    u8 getLastBackbeatNumber() const FL_NO_EXCEPT { return mLastBackbeatNumber; }

    float getConfidence() const FL_NO_EXCEPT { return mConfidence; }

    float getStrength() const FL_NO_EXCEPT { return mCurrentStrength; }

    float getBackbeatRatio() const FL_NO_EXCEPT { return mBackbeatRatio; }
 
    // ----- Configuration -----

    void setConfidenceThreshold(float threshold) FL_NO_EXCEPT { mConfidenceThreshold = threshold; }

    void setBassThreshold(float threshold) FL_NO_EXCEPT { mBassThreshold = threshold; }

    void setMidThreshold(float threshold) FL_NO_EXCEPT { mMidThreshold = threshold; }

    void setHighThreshold(float threshold) FL_NO_EXCEPT { mHighThreshold = threshold; }

    void setBackbeatExpectedBeats(u8 beatMask) FL_NO_EXCEPT { mBackbeatMask = beatMask; }

    void setAdaptive(bool enable) FL_NO_EXCEPT { mAdaptive = enable; }

    void setBeatDetector(shared_ptr<Beat> beatDetector) FL_NO_EXCEPT;

    void setDownbeatDetector(shared_ptr<Downbeat> downbeatDetector) FL_NO_EXCEPT;
 
private:
    // ----- Detector Dependencies -----
    shared_ptr<Beat> mBeatDetector;
    shared_ptr<Downbeat> mDownbeatDetector;
    bool mOwnsBeatDetector;
    bool mOwnsDownbeatDetector;
 
    // ----- State -----
    bool mBackbeatDetected;
    u8 mLastBackbeatNumber;
    float mConfidence;
    float mCurrentStrength;
    float mBackbeatRatio;
 
    // ----- Configuration -----
    float mConfidenceThreshold;
    float mBassThreshold;
    float mMidThreshold;
    float mHighThreshold;
    u8 mBackbeatMask;  // Bitmask: which beats are backbeats
    bool mAdaptive;
 
    // ----- Beat Tracking -----
    u8 mCurrentBeat;
    u8 mBeatsPerMeasure;
    bool mPreviousWasBeat;
 
    // ----- Accent History -----
    MultibandAccent mPreviousAccent;
    deque<float> mBackbeatAccents;      // Accent strengths on backbeats
    deque<float> mNonBackbeatAccents;   // Accent strengths on non-backbeats
    static constexpr size MAX_ACCENT_HISTORY = 16;
 
    // ----- Adaptive Thresholds -----
    float mBackbeatMean;
    float mNonBackbeatMean;
    float mAdaptiveThreshold;
 
    // ----- Spectral Profile Learning -----
    vector<float> mBackbeatSpectralProfile;  // Average spectrum of backbeats
    static constexpr size SPECTRAL_PROFILE_SIZE = 16;
    float mProfileAlpha;  // EMA smoothing factor for profile updates
 
    shared_ptr<const fft::Bins> mRetainedFFT;
 
    // ----- Helper Methods -----
    void updateBeatDetector(shared_ptr<Context> context) FL_NO_EXCEPT;
    void updateBeatPosition() FL_NO_EXCEPT;
    MultibandAccent calculateMultibandAccent(const fft::Bins& fft) FL_NO_EXCEPT;
    float detectBackbeatAccent(const MultibandAccent& accent) FL_NO_EXCEPT;
    bool isBackbeatPosition() const FL_NO_EXCEPT;
    bool detectBackbeat(float accentStrength, const fft::Bins& fft) FL_NO_EXCEPT;
    void updateAdaptiveThresholds() FL_NO_EXCEPT;
    void updateBackbeatProfile(const fft::Bins& fft) FL_NO_EXCEPT;
    float calculatePatternConfidence(const fft::Bins& fft) FL_NO_EXCEPT;
};
 
} // namespace detector
} // namespace audio
} // namespace fl