frequency_bin_mapper.h

Go to the documentation of this file.

#pragma once
 
#include "fl/stl/int.h"
#include "fl/stl/vector.h"
#include "fl/stl/span.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
namespace audio {

enum class FrequencyBinMode {
    Bins16 = 16,  // 16-bin mode (default, matches WLED)
    Bins32 = 32   // 32-bin mode (higher resolution)
};

struct FrequencyBinMapperConfig {
    FrequencyBinMode mode = FrequencyBinMode::Bins16;

    float minFrequency = 20.0f;

    float maxFrequency = 16000.0f;

    u32 sampleRate = 22050;

    u32 fftBinCount = 256;

    bool useLogSpacing = true;
};

class FrequencyBinMapper {
public:
    FrequencyBinMapper() FL_NO_EXCEPT;
    explicit FrequencyBinMapper(const FrequencyBinMapperConfig& config) FL_NO_EXCEPT;
    ~FrequencyBinMapper() FL_NO_EXCEPT;

    void configure(const FrequencyBinMapperConfig& config) FL_NO_EXCEPT;

    void mapBins(span<const float> fftBins, span<float> outputBins) const FL_NO_EXCEPT;

    float getBassEnergy(span<const float> frequencyBins) const FL_NO_EXCEPT;

    float getMidEnergy(span<const float> frequencyBins) const FL_NO_EXCEPT;

    float getTrebleEnergy(span<const float> frequencyBins) const FL_NO_EXCEPT;

    struct FrequencyRange {
        float minFreq;
        float maxFreq;
    };
    FrequencyRange getBinFrequencyRange(size binIndex) const FL_NO_EXCEPT;

    const FrequencyBinMapperConfig& getConfig() const FL_NO_EXCEPT { return mConfig; }

    size getNumBins() const FL_NO_EXCEPT { return static_cast<size>(mConfig.mode); }

    struct Stats {
        u32 binMappingCount = 0;    // Total bin mappings performed
        u32 lastFFTBinsUsed = 0;    // Number of FFT bins used in last mapping
        float maxMagnitude = 0.0f;  // Maximum magnitude in last mapping
    };
 
    const Stats& getStats() const FL_NO_EXCEPT { return mStats; }
 
private:
    void calculateBinBoundaries() FL_NO_EXCEPT;

    void calculateBinMappings() FL_NO_EXCEPT;

    float frequencyToFFTBin(float frequency) const FL_NO_EXCEPT;

    void calculateLogFrequencies() FL_NO_EXCEPT;

    void calculateLinearFrequencies() FL_NO_EXCEPT;
 
    FrequencyBinMapperConfig mConfig;
    Stats mStats;

    vector<float> mBinFrequencies;

    struct BinMapping {
        u32 startBin;  // First FFT bin (inclusive)
        u32 endBin;    // Last FFT bin (exclusive)
    };
    vector<BinMapping> mBinMappings;

    static constexpr size BASS_BIN_START = 0;
    static constexpr size BASS_BIN_END = 2;    // Bins 0-1 (exclusive end)
    static constexpr size MID_BIN_START = 6;
    static constexpr size MID_BIN_END = 8;     // Bins 6-7 (exclusive end)
    static constexpr size TREBLE_BIN_START = 14;
    static constexpr size TREBLE_BIN_END = 16; // Bins 14-15 (exclusive end)
};
 
} // namespace audio
} // namespace fl