v0.12

Add Autocorrelation Tempogram

Author: hqrrr

CMakeLists.txt

@@ -2,7 +2,7 @@
 
 cmake_minimum_required(VERSION 3.22)
 
-project(PerceptoMap VERSION 0.11)
+project(PerceptoMap VERSION 0.12)
 
 
 ### Dependency versions ###

README.md

@@ -216,7 +216,14 @@ Unlike typical spectrum or spectrogram analyzers, it supports perceptual visuali
       </sub>
     </td>
     <td align="center" valign="top">
-      <img src="_pics/blank_800x630.png" width="100%" alt="blank" />
+      <img src="_pics/gui_autocorrelation_tempogram.png" width="100%" alt="blank" />
+      <br/>
+      <sub>
+        <strong>Autocorrelation Tempogram:</strong>
+        <i>
+          Rhythm/tempo map from windowed autocorrelation of the onset/novelty signal, robust to phase; includes a dynamic tempo track <span style="color: gray;">[added in v0.12]</span>
+        </i>
+      </sub>
     </td>
     <td align="center" valign="top">
       <img src="_pics/blank_800x630.png" width="100%" alt="blank" />
@@ -240,7 +247,7 @@ Unlike typical spectrum or spectrogram analyzers, it supports perceptual visuali
 | Enhanced Mel Spectrogram with Time–Frequency Reassignment (Mel+) | ✅ Done (v0.7) | Mel-scaled spectrogram with sharper harmonic ridges and crisper transients by reassigning each STFT bins energy to its true instantaneous frequency, then projecting onto the Mel axis | Based on the same reassignment principle as Linear+. Mapped to Mel. |
 | Y-axis Range Control | ✅ Done (v0.8) | Precise control over visible frequency band | Dual-handle range slider + editable min/max fields |
 | Fourier Tempogram | ✅ Done (v0.10) | Rhythm/tempo map showing BPM energy over time, with dynamic tempo track (Tempo Line), sharper separation of nearby tempo | Based on [[10.1109/ICASSP.2010.5495219](https://doi.org/10.1109/ICASSP.2010.5495219)]. Positive spectral flux on log-compressed STFT; STFT of the novelty with a Hann window of length `wantWinSec` seconds (default: 8s); BPM axis sampled on a log scale. Per-frame prior-weighted peak picking (log-normal prior) overlays a continuous tempo line.<br/> **Note:** the tempogram and tempo line update with a delay = `wantWinSec` (window accumulation). On entering this mode the FFT size will be auto-bumped to >= 4096 for a more stable onset envelope. |
-| Autocorrelation Tempogram | ⏳ Planned | Time-lag periodicity map (tempo strength over time, mapped to BPM) with dynamic Tempo Line, naturally highlights double/half-time relationships | - |
+| Autocorrelation Tempogram | ✅ Done (v0.12) | Time-lag periodicity map (tempo strength over time, mapped to BPM) with dynamic Tempo Line, robust to local phase, naturally highlights double/half-time relationships | Similar to the Fourier Tempogram, but computed via windowed autocorrelation of the onset/novelty signal. The AutoCorrelation Function (ACF) is normalized by the zero-lag term; the BPM axis is log-spaced, and a per-frame log-normal prior guides peak picking to draw the Tempo Line. Note: entering this mode auto-sets FFT size to 2048 for improved temporal resolution. |
 | Spectral Flatness / Contrast | ⏳ Planned | Measures of timbral characteristics | - |
 
 [Back to top ↥](#perceptomap)

Source/PluginEditor.cpp

@@ -154,6 +154,7 @@ SpectrogramAudioProcessorEditor::SpectrogramAudioProcessorEditor(SpectrogramAudi
         "- Spectral Centroid: STFT spectrogram with added curves showing where the energy is centered and how widely it is spread across frequencies.\n"
         "- Chroma: Chromagram showing the energy distribution across the 12 pitch classes (C to B), regardless of octave. Useful for analyzing harmonic content and key.\n"
         "- Fourier Tempogram: Tempo (BPM) energy vs. time computed from the onset envelope via STFT, overlays a dynamic tempo line (peak per frame with log-normal prior). Tip: Use a higher FFT size like 4096.\n"
+        "- Autocorr Tempogram: Tempo (BPM) vs. time via autocorrelation of the onset envelope. More robust to local phase than Fourier Tempogram.\n"
     );
     spectrogramModeBox.addItem("Linear", static_cast<int>(SpectrogramComponent::SpectrogramMode::Linear));
     spectrogramModeBox.addItem("Linear+", static_cast<int>(SpectrogramComponent::SpectrogramMode::LinearPlus));
@@ -163,6 +164,8 @@ SpectrogramAudioProcessorEditor::SpectrogramAudioProcessorEditor(SpectrogramAudi
     spectrogramModeBox.addItem("Spectral Centroid", static_cast<int>(SpectrogramComponent::SpectrogramMode::LinearWithCentroid));
     spectrogramModeBox.addItem("Chroma", static_cast<int>(SpectrogramComponent::SpectrogramMode::Chroma));
     spectrogramModeBox.addItem("Fourier Tempogram", static_cast<int>(SpectrogramComponent::SpectrogramMode::FourierTempogram));
+    spectrogramModeBox.addItem("Autocorr Tempogram", static_cast<int>(SpectrogramComponent::SpectrogramMode::AutoTempogram));
+
 
     spectrogramModeBox.setSelectedId(static_cast<int>(SpectrogramComponent::SpectrogramMode::Linear));  // default: linear
 
@@ -461,6 +464,23 @@ void SpectrogramAudioProcessorEditor::MenuDisableControl(SpectrogramComponent::S
                 fftSizeBox.setSelectedId(12, juce::sendNotificationSync);
             break;
         }
+        // Autocorr Tempogram
+        case SpectrogramComponent::SpectrogramMode::AutoTempogram:
+        {
+            logScaleBox.setEnabled(false);
+            yRangeSlider.setEnabled(false);
+            yMinHzEdit.setEnabled(false);
+            yMaxHzEdit.setEnabled(false);
+            floorDbSlider.setEnabled(true);
+            noteAxisToggle.setEnabled(false);
+            tempoAvgResetBtn.setVisible(true);
+            // auto switch FFT size to =2048 for better tempogram results
+            const int curOrder = fftSizeBox.getSelectedId();
+            if (curOrder != 11)  // 2^11=2048
+                fftSizeBox.setSelectedId(11, juce::sendNotificationSync);
+
+            break;
+        }
         // Linear STFT
         default:
             logScaleBox.setEnabled(true);

Source/SpectrogramComponent.cpp

@@ -222,9 +222,10 @@ void SpectrogramComponent::pushNextFFTBlock(const float* data, size_t numSamples
 
             forwardFFT.performFrequencyOnlyForwardTransform(fftData.data());
 
-            // Fourier tempogram
+            // Fourier tempogram / Autocorrelation tempogram
             // compute spectral flux novelty and push into novelty ring buffer
-            if (currentMode == SpectrogramMode::FourierTempogram)
+            if (currentMode == SpectrogramMode::FourierTempogram 
+                || currentMode == SpectrogramMode::AutoTempogram)
             {
                 // current magnitude spectrum in [0 ... fftSize/2)
                 const int nBins = fftSize / 2;
@@ -1057,6 +1058,156 @@ void SpectrogramComponent::drawFourierTempogram(int x, std::vector<float>& dBCol
     }
 }
 
+void SpectrogramComponent::drawAutoTempogram(int x, std::vector<float>& dBColumn, int imageHeight)
+{
+    if (noveltyRing.empty() || noveltyWinLen <= 2 || imageHeight <= 0)
+        return;
+
+    // novelty (consistent with Fourier Tempogram)
+    std::vector<float> seg(noveltyWinLen, 0.0f);
+    for (int i = 0; i < noveltyWinLen; ++i)
+    {
+        int idx = (int)noveltyWrite - 1 - i;
+        if (idx < 0) idx += (int)noveltyRing.size();
+        seg[noveltyWinLen - 1 - i] = noveltyRing[(size_t)idx];
+    }
+
+    float mu = 0.0f;
+    for (float v : seg) mu += v;
+    mu /= (float)noveltyWinLen;
+
+    float activity = 0.0f;
+    for (int i = 0; i < noveltyWinLen; ++i)
+    {
+        seg[i] = std::max(0.0f, seg[i] - mu);
+        activity += seg[i];
+    }
+    if (activity < activityThresh)
+    {
+        for (int y = 0; y < imageHeight; ++y)
+        {
+            dBColumn[y] = floorDb;
+            spectrogramImage.setPixelAt(x, y, getColourForValue(0.0f));
+        }
+        lastFourierTempoY = -1;
+        return;
+    }
+
+    // Calculate windowed autocorrelation
+    // ACF on seg * window, then normalize / acf[0]
+    const double winSum = std::accumulate(noveltyWin.begin(), noveltyWin.end(), 0.0);
+    const double normW = (winSum > 1e-12) ? (1.0 / winSum) : 1.0;
+
+    std::vector<float> wseg(noveltyWinLen);
+    for (int i = 0; i < noveltyWinLen; ++i)
+        wseg[i] = seg[i] * noveltyWin[i] * (float)normW;
+
+    // Precompute 0-lag energy for normalization
+    double acf0 = 0.0;
+    for (int i = 0; i < noveltyWinLen; ++i) acf0 += (double)wseg[i] * (double)wseg[i];
+    if (acf0 < 1e-12) acf0 = 1e-12;
+
+    // Divide the "BPM axis (logarithmically uniform)" into M discrete points and 
+    // calculate the corresponding lag for each BPM (rounding down).
+    const int M = juce::jmax(8, tempoBins);
+    std::vector<float> tempoBPM(M), mag(M, 0.0f);
+
+    const double logMin = std::log10(juce::jmax(1.0f, tempoMinBPM));
+    const double logMax = std::log10(juce::jmax(tempoMinBPM + 1.0f, tempoMaxBPM));
+    for (int m = 0; m < M; ++m)
+    {
+        double alpha = (double)m / (double)(M - 1);
+        double bpm = std::pow(10.0, logMin + alpha * (logMax - logMin));
+        tempoBPM[m] = (float)bpm;
+
+        double periodSec = 60.0 / juce::jmax(1e-9, bpm);
+        int lag = (int)std::round(periodSec / juce::jmax(1e-12, noveltySamplePeriod));
+
+        // Only retain reasonable lag
+        if (lag >= 1 && lag < noveltyWinLen)
+        {
+            double s = 0.0;
+            // sum_t wseg[t] * wseg[t-lag]
+            for (int t = lag; t < noveltyWinLen; ++t)
+                s += (double)wseg[t] * (double)wseg[t - lag];
+
+            float val = (float)(s / acf0);
+            mag[m] = juce::jlimit(0.0f, 1.0f, val);
+        }
+    }
+
+    // Mapped to the image column
+    for (int y = 0; y < imageHeight; ++y)
+    {
+        float frac = 1.0f - ((float)y / (float)(imageHeight - 1));
+        int   m = juce::jlimit(0, M - 1, (int)std::round(frac * (M - 1)));
+
+        float v = mag[m] * normFactor;
+        float dB = 20.0f * std::log10(v + 1e-9f);
+        float dbC = juce::jlimit(floorDb, 0.0f, dB);
+        dBColumn[y] = dbC;
+
+        float bright = juce::jmap(dbC, floorDb, 0.0f, 0.0f, 1.0f);
+        spectrogramImage.setPixelAt(x, y, getColourForValue(bright));
+    }
+
+    // Overlay tempo curve (using the same logarithmic prior as Fourier to suppress frequency ambiguity)
+    juce::Colour tempoLineColour;
+    switch (colourScheme)
+    {
+    case ColourScheme::Grayscale:
+    case ColourScheme::GrayscaleEnhanced: tempoLineColour = juce::Colour::fromRGB(0, 200, 255); break;
+    case ColourScheme::Magma:
+    case ColourScheme::MagmaEnhanced:     tempoLineColour = juce::Colour::fromRGB(0, 255, 128); break;
+    default:                               tempoLineColour = juce::Colour::fromRGB(255, 255, 255); break;
+    }
+
+    int   mPeak = 0;
+    float bestVal = -1.0e30f;
+    float bestBPM = tempoBPM[0];
+    for (int m = 0; m < M; ++m)
+    {
+        const float bpm = tempoBPM[m];
+        const float score = mag[m] * fourierTempoPrior(bpm);
+        if (score > bestVal) { bestVal = score; mPeak = m; bestBPM = bpm; }
+    }
+
+    const int yTempo = (int)std::round(bpmToImageY(bestBPM, imageHeight));
+    if (yTempo >= 0 && yTempo < imageHeight)
+    {
+        juce::Graphics imgG(spectrogramImage);
+        imgG.setColour(tempoLineColour.withAlpha(0.95f));
+
+        if (lastFourierTempoY >= 0)
+            imgG.drawLine((float)(x - 1), (float)lastFourierTempoY, (float)x, (float)yTempo, 2.0f);
+        else
+            for (int dy = -1; dy <= 1; ++dy)
+                spectrogramImage.setPixelAt(x, juce::jlimit(0, imageHeight - 1, yTempo + dy), tempoLineColour);
+        lastFourierTempoY = yTempo;
+    }
+
+    // BPM tempo statistics
+    if (bestBPM > 0.0f && std::isfinite(bestBPM))
+    {
+        // avg
+        tempoAvgSum += bestBPM;
+        tempoAvgCount += 1;
+        globalTempoBPM = (float)(tempoAvgSum / std::max(1, tempoAvgCount));
+
+        // min/max
+        tempoMin = std::min(tempoMin, bestBPM);
+        tempoMax = std::max(tempoMax, bestBPM);
+
+        // median
+        tempoHistory.push_back(bestBPM);
+        std::vector<float> tmp = tempoHistory;
+        std::sort(tmp.begin(), tmp.end());
+        const size_t n = tmp.size();
+        tempoMedian = (n % 2) ? tmp[n / 2]
+            : 0.5f * (tmp[n / 2 - 1] + tmp[n / 2]);
+    }
+}
+
 void SpectrogramComponent::drawNextLineOfSpectrogram()
 {
     const int imageWidth = spectrogramImage.getWidth();
@@ -1104,6 +1255,10 @@ void SpectrogramComponent::drawNextLineOfSpectrogram()
         case SpectrogramMode::FourierTempogram:
             drawFourierTempogram(x, dBColumn, imageHeight);
             break;
+        case SpectrogramMode::AutoTempogram:
+            drawAutoTempogram(x, dBColumn, imageHeight);
+            break;
+
         default:
             drawLinearSpectrogram(x, dBColumn, imageHeight, maxFreq);
             break;
@@ -1564,6 +1719,9 @@ void SpectrogramComponent::paint(juce::Graphics& g)
         case SpectrogramMode::FourierTempogram:
             paintTempoYAxis(g, width, imageHeight);
             break;
+        case SpectrogramMode::AutoTempogram:
+            paintTempoYAxis(g, width, imageHeight);
+            break;
 
         default:
             paintSTFTYAxis(g, width, imageHeight);
@@ -1662,6 +1820,9 @@ void SpectrogramComponent::paint(juce::Graphics& g)
             case SpectrogramMode::FourierTempogram:
                 labelText = drawTempogramTooltip(dB, imgY, imageHeight);
                 break;
+            case SpectrogramMode::AutoTempogram:
+                labelText = drawTempogramTooltip(dB, imgY, imageHeight);
+                break;
 
             default:
                 labelText = drawSTFTTooltip(dB, imgY, freq);

Source/SpectrogramComponent.h

@@ -37,8 +37,9 @@ class SpectrogramComponent : public juce::Component,
         Chroma,
         LinearPlus,
         MelPlus,
-        FourierTempogram
-        // TODO: add Autocorrelation Tempogram, Rhythm, etc.
+        FourierTempogram,
+        AutoTempogram
+        // TODO: add Rhythm, etc.
     };
 
     SpectrogramComponent();
@@ -171,6 +172,8 @@ class SpectrogramComponent : public juce::Component,
     void drawReassignedMelSpectrogram(int x, std::vector<float>& dBColumn, int imageHeight);
     // draw Fourier Tempogram
     void drawFourierTempogram(int x, std::vector<float>& dBColumn, int imageHeight);
+    // draw Autocorrelation Tempogram
+    void drawAutoTempogram(int x, std::vector<float>& dBColumn, int imageHeight);
 
     SpectrogramMode currentMode = SpectrogramMode::Linear;