downbeat.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 {

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

    Downbeat() FL_NOEXCEPT;
 
    ~Downbeat() 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 "Downbeat"; }
    void reset() override;
 
    // ----- Callbacks (multiple listeners supported) -----

    function_list<void()> onDownbeat;

    function_list<void(u8 beatNumber)> onMeasureBeat;

    function_list<void(u8 beatsPerMeasure)> onMeterChange;

    function_list<void(float phase)> onMeasurePhase;
 
    // ----- State Access -----

    bool isDownbeat() const { return mDownbeatDetected; }

    u8 getCurrentBeat() const { return mCurrentBeat; }

    u8 getBeatsPerMeasure() const { return mBeatsPerMeasure; }

    float getMeasurePhase() const { return mMeasurePhase; }

    float getConfidence() const { return mConfidence; }
 
    // ----- Configuration -----

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

    void setAccentThreshold(float threshold) { mAccentThreshold = threshold; }

    void setAutoMeterDetection(bool enable) { mAutoMeterDetection = enable; }

    void setTimeSignature(u8 beatsPerMeasure);

    void setBeatDetector(shared_ptr<Beat> beatDetector);
 
private:
    // ----- Beat Management -----
    shared_ptr<Beat> mBeatDetector;
    bool mOwnsBeatDetector;  // True if we created our own Beat
 
    // ----- State -----
    bool mDownbeatDetected;
    u8 mCurrentBeat;          // 1-based beat number (1 = downbeat)
    u8 mBeatsPerMeasure;      // Detected time signature
    float mMeasurePhase;      // 0-1 within measure
    float mConfidence;
 
    // ----- Configuration -----
    float mConfidenceThreshold;
    float mAccentThreshold;
    bool mAutoMeterDetection;
    bool mManualMeter;
 
    // ----- Beat Tracking -----
    u32 mLastDownbeatTime;
    u32 mLastBeatTime;
    u8 mBeatsSinceDownbeat;
 
    // ----- Accent Detection -----
    float mPreviousEnergy;
    deque<float> mBeatAccents;  // Recent beat accent strengths
    static constexpr size MAX_BEAT_HISTORY = 32;
 
    // ----- Meter Detection -----
    deque<u8> mMeterCandidates;  // Recent detected meters
    static constexpr size METER_HISTORY_SIZE = 8;
 
    // ----- Pending Callback Flags -----
    bool mFireDownbeat = false;
    bool mFireMeasureBeat = false;
    u8 mPendingBeatNumber = 0;
    bool mFireMeterChange = false;
    u8 mPendingMeter = 0;
 
    shared_ptr<const fft::Bins> mRetainedFFT;
 
    // ----- Helper Methods -----
    void updateBeatDetector(shared_ptr<Context> context);
    float calculateBeatAccent(const fft::Bins& fft, float bassEnergy);
    bool detectDownbeat(u32 timestamp, float accent);
    void detectMeter();
    void updateMeasurePhase(u32 timestamp);
    u8 findMostCommonMeter() const;
};
 
} // namespace detector
} // namespace audio
} // namespace fl