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);

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

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

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

    bool isBackbeat() const { return mBackbeatDetected; }

    u8 getLastBackbeatNumber() const { return mLastBackbeatNumber; }

    float getConfidence() const { return mConfidence; }

    float getStrength() const { return mCurrentStrength; }

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

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

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

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

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

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

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

    void setBeatDetector(shared_ptr<Beat> beatDetector);

    void setDownbeatDetector(shared_ptr<Downbeat> downbeatDetector);
 
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);
    void updateBeatPosition();
    MultibandAccent calculateMultibandAccent(const fft::Bins& fft);
    float detectBackbeatAccent(const MultibandAccent& accent);
    bool isBackbeatPosition() const;
    bool detectBackbeat(float accentStrength, const fft::Bins& fft);
    void updateAdaptiveThresholds();
    void updateBackbeatProfile(const fft::Bins& fft);
    float calculatePatternConfidence(const fft::Bins& fft);
};
 
} // namespace detector
} // namespace audio
} // namespace fl