room_sense.h

Go to the documentation of this file.

// room_sense.h - what the room sounds like, as a handful of smooth signals.
//
// RoomListener polls the audio Processor once per frame and fills RoomSense.
// Everything downstream reads RoomSense and nothing else, so the audio
// pipeline can change without touching a single visual.
//
// There is no state enum. The three regimes (calm room, busy room, music
// with a beat) are three weights that always sum to one. They move with
// asymmetric attack and release, which gives the same "slow to enter
// silence, fast to leave it" feel the old classifier needed timers for.
#pragma once
 
#include "FastLED.h"
#include "fl/audio/audio_processor.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/stdint.h"
 
namespace mood_ring {

struct RoomEvents {
    bool beat = false;
    bool downbeat = false;
    bool kick = false;
    bool snare = false;
    bool hihat = false;
};

struct RoomSense {
    // Regime blend. calm + flow + groove == 1.
    float presence = 0.0f; 
    float calm = 1.0f;
    float flow = 0.0f;
    float groove = 0.0f;
 
    // Energy.
    float energy = 0.0f;  
    float trend = 0.0f;   
    float punch = 0.0f;   
    float shimmer = 0.0f; 
    float low = 0.0f;
    float mid = 0.0f;
    float high = 0.0f;
 
    // Rhythm.
    float bpm = 0.0f;
    float beatPhase = 0.0f;    
    float measurePhase = 0.0f; 
    float grooveConfidence = 0.0f;
 
    // Mood.
    float warmth = 0.5f;  
    float arousal = 0.0f; 
 
    RoomEvents events;
};

struct ListenerTuning {
    float presenceAttackMs = 150.0f;  
    float presenceReleaseMs = 900.0f; 
    float grooveAttackMs = 800.0f;    
    float grooveReleaseMs = 1500.0f;  
    float grooveEnter = 0.60f;        
    float grooveExit = 0.35f;         
    float punchGain = 1.5f;           
};

class Follower {
  public:
    float update(float target, float dtMs, float attackMs, float releaseMs);
    float value() const { return mValue; }
    void reset(float v) { mValue = v; }
 
  private:
    float mValue = 0.0f;
};
 
class RoomListener {
  public:
    explicit RoomListener(fl::shared_ptr<fl::audio::Processor> processor);

    void begin();

    void update(fl::u32 nowMs);

    void rest(fl::u32 nowMs);
 
    const RoomSense &sense() const { return mSense; }

    const char *regimeName() const;
 
    ListenerTuning tuning;
 
  private:
    float stepClock(fl::u32 nowMs);
    void deriveBlend(float dtMs);
    void blendFrom(float presenceTarget, float grooveConf, float dtMs);
    void deriveEnergy(float dtMs);
    void deriveRhythm(fl::u32 nowMs);
    void deriveMood(float dtMs);
    void deriveEvents();
 
    fl::shared_ptr<fl::audio::Processor> mProcessor;
    RoomSense mSense;
    fl::u32 mLastMs = 0;
 
    Follower mPresence;
    Follower mGroove;
    Follower mEnergyFast;
    Follower mEnergySlow;
    Follower mPunch;
    Follower mShimmer;
    Follower mLow;
    Follower mMid;
    Follower mHigh;
    Follower mWarmth;
    Follower mArousal;
 
    // Event timestamps written by Processor callbacks, consumed by update().
    fl::u32 mLastBeatMs = 0;
    fl::u32 mLastDownbeatMs = 0;
    fl::u32 mLastKickMs = 0;
    fl::u32 mLastSnareMs = 0;
    fl::u32 mLastHiHatMs = 0;
    fl::u32 mSeenBeatMs = 0;
    fl::u32 mSeenDownbeatMs = 0;
    fl::u32 mSeenKickMs = 0;
    fl::u32 mSeenSnareMs = 0;
    fl::u32 mSeenHiHatMs = 0;
};
 
} // namespace mood_ring