KeyDetector.h

// DSPark - Professional Audio DSP Framework
// Copyright (c) 2026 Cristian Moresi - MIT License
 
#pragma once
 
#include "../Core/AudioBuffer.h"
#include "../Core/AudioSpec.h"
#include "../Core/DspMath.h"
#include "ChordDetector.h"
#include "HarmonyConstants.h"
 
#include <algorithm>
#include <array>
#include <atomic>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <span>
#include <string_view>
 
namespace dspark {
 
template <FloatType T>
class KeyDetector final
{
public:
    enum class Profile : std::uint8_t
    {
        KrumhanslKessler = 0,   
        Temperley               
    };
 
    struct Key
    {
        int tonicPitchClass = -1;       
        bool isMinor = false;           
        T confidence = T(0);            
        int runnerUpPitchClass = -1;    
        bool runnerUpMinor = false;     
        int relativeAlternativePitchClass = -1; 
        bool relativeAlternativeMinor = false;  
        int relativeAlternativeRank = 0; 
    };
 
    // -- Lifecycle ---------------------------------------------------------------
 
    void prepare(const AudioSpec& spec, int windowSize = 0)
    {
        // The shared front end validates the complete specification and its
        // strict Nyquist bound before changing any state. Only commit wrapper
        // state after it reports that the same request was accepted.
        if (!front_.prepare(spec, windowSize)) return;
        prepared_.store(true, std::memory_order_release);
        reset();
    }
 
    void reset() noexcept
    {
        front_.reset();
        accum_.fill(0.0);
        chromaOut_.fill(T(0));
        maxFrameTotal_ = 0.0;
        lastFrame_ = 0;
        framesUsed_ = 0;
        packed_.store(pack(Key {}), std::memory_order_relaxed);
    }
 
    void setProfile(Profile p) noexcept
    {
        profile_.store(static_cast<std::uint8_t>(p), std::memory_order_relaxed);
    }
 
    [[nodiscard]] Profile getProfile() const noexcept
    {
        return static_cast<Profile>(profile_.load(std::memory_order_relaxed));
    }
 
    [[nodiscard]] int getWindowSize() const noexcept { return front_.getWindowSize(); }
 
    // -- Processing -------------------------------------------------------------------
 
    void processBlock(AudioBufferView<const T> buffer) noexcept
    {
        if (!prepared_.load(std::memory_order_acquire)) return;
        const int hop = front_.getHopSize();
        const int n = buffer.getNumSamples();
        if (hop <= 0 || n <= 0) return;
        for (int off = 0; off < n; off += hop)
        {
            front_.processBlock(buffer.getSubView(off, std::min(hop, n - off)));
            consumeFrames();
        }
    }
 
    void pushSamples(std::span<const T> samples) noexcept
    {
        if (!prepared_.load(std::memory_order_acquire)) return;
        const int hop = front_.getHopSize();
        if (hop <= 0) return;
        const auto step = static_cast<std::size_t>(hop);
        for (std::size_t off = 0; off < samples.size(); off += step)
        {
            front_.pushSamples(samples.subspan(off, std::min(step, samples.size() - off)));
            consumeFrames();
        }
    }
 
    // -- Readout ----------------------------------------------------------------------
 
    [[nodiscard]] Key getKey() const noexcept
    {
        return unpack(packed_.load(std::memory_order_relaxed));
    }
 
    [[nodiscard]] const std::array<T, 12>& chroma() const noexcept { return chromaOut_; }
 
    [[nodiscard]] std::uint64_t getFrameCount() const noexcept { return framesUsed_; }
 
    static int getKeyName(const Key& key, char* dest, int size) noexcept
    {
        if (dest == nullptr || size <= 0) return 0;
        // Parenthesised on purpose: inside a class template MSVC can read a
        // bare `a.b < ... || a.b > ...` chain as a template argument list.
        if ((key.tonicPitchClass < 0) || (key.tonicPitchClass > 11))
        {
            dest[0] = '\0';
            return 0;
        }
        const std::string_view root =
            harmony::noteName(key.tonicPitchClass, key.tonicPitchClass);
        int len = 0;
        for (char c : root)
        {
            if (len >= size - 1) break;
            dest[len++] = c;
        }
        if (key.isMinor && len < size - 1) dest[len++] = 'm';
        dest[len] = '\0';
        return len;
    }
 
    // -- Published key profiles -------------------------------------------------------
 
    static constexpr std::array<double, 12> kKrumhanslKesslerMajor {
        6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88
    };
 
    static constexpr std::array<double, 12> kKrumhanslKesslerMinor {
        6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17
    };
 
    static constexpr std::array<double, 12> kTemperleyMajor {
        5.0, 2.0, 3.5, 2.0, 4.5, 4.0, 2.0, 4.5, 2.0, 3.5, 1.5, 4.0
    };
 
    static constexpr std::array<double, 12> kTemperleyMinor {
        5.0, 2.0, 3.5, 4.5, 2.0, 4.0, 2.0, 4.5, 3.5, 2.0, 1.5, 4.0
    };
 
private:
    static constexpr double kFrameGateFraction = 1.0e-3;
 
    static constexpr double kFrameEnergyFloor = 1.0e-12;
 
    void consumeFrames() noexcept
    {
        const std::uint64_t fc = front_.getFrameCount();
        if (fc == lastFrame_) return;
        lastFrame_ = fc;
 
        const std::array<T, 12>& frame = front_.getChroma();
        double total = 0.0;
        for (const T v : frame) total += static_cast<double>(v);
        if (!(total > kFrameEnergyFloor)) return;
 
        if (total > maxFrameTotal_) maxFrameTotal_ = total;
        if (total < kFrameGateFraction * maxFrameTotal_) return;
 
        // Equal weight per frame: the input to the method is how LONG each
        // pitch class sounds, so a frame's own level must not scale its vote.
        const double inv = 1.0 / total;
        for (int pc = 0; pc < 12; ++pc)
            accum_[static_cast<std::size_t>(pc)] +=
                static_cast<double>(frame[static_cast<std::size_t>(pc)]) * inv;
        ++framesUsed_;
 
        estimate();
    }
 
    void estimate() noexcept
    {
        double sum = 0.0;
        for (const double v : accum_) sum += v;
        if (!(sum > 0.0)) return;
 
        // The correlation reads the ACCUMULATOR, not the normalized readout
        // built below. Pearson subtracts each argument's mean and divides by
        // its spread, so multiplying the chroma by any positive constant
        // divides straight back out of r: normalizing first cannot move an
        // argmax, a top correlation or a confidence, only their last bits.
        // The normalization exists for the readout alone, for the reason
        // stated at chroma(), and is deliberately not in the path of the
        // estimate.
        const double inv = 1.0 / sum;
        for (int pc = 0; pc < 12; ++pc)
            chromaOut_[static_cast<std::size_t>(pc)] =
                static_cast<T>(accum_[static_cast<std::size_t>(pc)] * inv);
 
        const bool temperley = (getProfile() == Profile::Temperley);
        const auto& major = temperley ? kTemperleyMajor : kKrumhanslKesslerMajor;
        const auto& minor = temperley ? kTemperleyMinor : kKrumhanslKesslerMinor;
 
        std::array<double, 24> scores {};
 
        for (int mode = 0; mode < 2; ++mode)
        {
            const auto& p = (mode == 0) ? major : minor;
            for (int tonic = 0; tonic < 12; ++tonic)
            {
                const double r = pearsonRotated(accum_, p, tonic);
                scores[static_cast<std::size_t>(mode * 12 + tonic)] = r;
            }
        }
 
        // Fixed-size stable insertion sort: score descending, exact ties in
        // candidate ordinal order. Retaining the complete order makes both the
        // numerical runner-up and the relative candidate's real rank explicit
        // without allocating on the processing path.
        std::array<int, 24> order {};
        for (int ordinal = 0; ordinal < 24; ++ordinal)
        {
            int pos = ordinal;
            while (pos > 0
                   && scores[static_cast<std::size_t>(ordinal)]
                      > scores[static_cast<std::size_t>(order[static_cast<std::size_t>(pos - 1)])])
            {
                order[static_cast<std::size_t>(pos)] =
                    order[static_cast<std::size_t>(pos - 1)];
                --pos;
            }
            order[static_cast<std::size_t>(pos)] = ordinal;
        }
 
        const int bestOrdinal = order[0];
        const int secondOrdinal = order[1];
        const double best = scores[static_cast<std::size_t>(bestOrdinal)];
        const double second = scores[static_cast<std::size_t>(secondOrdinal)];
        const int bestPc = bestOrdinal % 12;
        const bool bestMinor = bestOrdinal >= 12;
 
        // A major key's relative minor is nine semitones above it; a minor
        // key's relative major is three above. It is a named policy candidate,
        // never a replacement for the numerical runner-up.
        const int relativePc = (bestPc + (bestMinor ? 3 : 9)) % 12;
        const bool relativeMinor = !bestMinor;
        const int relativeOrdinal = (relativeMinor ? 12 : 0) + relativePc;
        int relativeRank = 0;
        for (int rank = 0; rank < 24; ++rank)
        {
            if (order[static_cast<std::size_t>(rank)] == relativeOrdinal)
            {
                relativeRank = rank + 1;
                break;
            }
        }
 
        Key key;
        key.tonicPitchClass = bestPc;
        key.isMinor = bestMinor;
        key.runnerUpPitchClass = secondOrdinal % 12;
        key.runnerUpMinor = secondOrdinal >= 12;
        key.relativeAlternativePitchClass = relativePc;
        key.relativeAlternativeMinor = relativeMinor;
        key.relativeAlternativeRank = relativeRank;
        // Undefined where the winner is not itself a positive correlation:
        // dividing by a zero or negative top would turn "no tonal structure"
        // into a large number of the wrong sign.
        key.confidence = (best > 0.0)
                       ? static_cast<T>(std::clamp(
                             (best - second) / best, 0.0, 1.0))
                       : T(0);
        packed_.store(pack(key), std::memory_order_relaxed);
    }
 
    [[nodiscard]] static double pearsonRotated(const std::array<double, 12>& x,
                                               const std::array<double, 12>& profile,
                                               int tonic) noexcept
    {
        double mx = 0.0, mp = 0.0;
        for (int i = 0; i < 12; ++i)
        {
            mx += x[static_cast<std::size_t>(i)];
            mp += profile[static_cast<std::size_t>(i)];
        }
        mx /= 12.0;
        mp /= 12.0;
 
        double num = 0.0, dx = 0.0, dp = 0.0;
        for (int pc = 0; pc < 12; ++pc)
        {
            const double a = x[static_cast<std::size_t>(pc)] - mx;
            const double b = profile[static_cast<std::size_t>((pc - tonic + 12) % 12)] - mp;
            num += a * b;
            dx  += a * a;
            dp  += b * b;
        }
        const double den = std::sqrt(dx * dp);
        return (den > 0.0) ? (num / den) : 0.0;
    }
 
    // One packed word so a reader never sees fields from different estimates:
    // bits 0-15 confidence; 16/17-20 winner mode/tonic+1; 21/22-25 numerical
    // runner-up mode/tonic+1; 26/27-30 relative mode/tonic+1; 31-35 rank.
    [[nodiscard]] static std::uint64_t pack(const Key& k) noexcept
    {
        const auto q = static_cast<std::uint64_t>(
            std::clamp(static_cast<double>(k.confidence), 0.0, 1.0) * 65535.0 + 0.5);
        const auto t  = static_cast<std::uint64_t>(
            std::clamp(k.tonicPitchClass, -1, 11) + 1);
        const auto ru = static_cast<std::uint64_t>(
            std::clamp(k.runnerUpPitchClass, -1, 11) + 1);
        const auto rel = static_cast<std::uint64_t>(
            std::clamp(k.relativeAlternativePitchClass, -1, 11) + 1);
        const auto rank = static_cast<std::uint64_t>(
            std::clamp(k.relativeAlternativeRank, 0, 24));
        return q
             | (static_cast<std::uint64_t>(k.isMinor ? 1 : 0) << 16)
             | (t << 17)
             | (static_cast<std::uint64_t>(k.runnerUpMinor ? 1 : 0) << 21)
             | (ru << 22)
             | (static_cast<std::uint64_t>(k.relativeAlternativeMinor ? 1 : 0) << 26)
             | (rel << 27)
             | (rank << 31);
    }
 
    [[nodiscard]] static Key unpack(std::uint64_t v) noexcept
    {
        Key k;
        k.confidence = static_cast<T>(static_cast<double>(v & 0xFFFFu) / 65535.0);
        k.isMinor = ((v >> 16) & 1u) != 0u;
        k.tonicPitchClass = static_cast<int>((v >> 17) & 0xFu) - 1;
        k.runnerUpMinor = ((v >> 21) & 1u) != 0u;
        k.runnerUpPitchClass = static_cast<int>((v >> 22) & 0xFu) - 1;
        k.relativeAlternativeMinor = ((v >> 26) & 1u) != 0u;
        k.relativeAlternativePitchClass = static_cast<int>((v >> 27) & 0xFu) - 1;
        k.relativeAlternativeRank = static_cast<int>((v >> 31) & 0x1Fu);
        return k;
    }
 
    static_assert(std::atomic<std::uint64_t>::is_always_lock_free,
                  "audio-thread stores must not lock");
 
    ChordDetector<T> front_;
    std::atomic<bool> prepared_ { false };
 
    std::array<double, 12> accum_ {};
    std::array<T, 12> chromaOut_ {};
    double maxFrameTotal_ = 0.0;
    std::uint64_t lastFrame_ = 0;
    std::uint64_t framesUsed_ = 0;
 
    std::atomic<std::uint64_t> packed_ { 0 };
    std::atomic<std::uint8_t> profile_ { static_cast<std::uint8_t>(Profile::KrumhanslKessler) };
};
 
} // namespace dspark