Add the Stereo Field Meter rack effect

- A QPainter goniometer drawn over marked mono, side and channel axes,
  with amplitude rings to read distance from the centre by

- Correlation broadband and per band, so a mix that will not survive
  mono says where it is failing, plus mid and side levels and balance

- Analysis is gated on the dialog, so a meter left in a rack is free

Author: juzzlin

CHANGELOG

@@ -5,6 +5,15 @@ Release date:
 
 New features:
 
+* Add the Stereo Field Meter rack effect
+  - A goniometer drawn over marked mono, side and channel axes, with
+    amplitude rings to read distance from the centre by
+  - Correlation broadband and per band, so a mix that will not survive
+    mono says where it is failing, plus mid and side levels and balance
+  - Names the field Mono, Narrow, Medium, Wide, Very Wide or Phase Risk,
+    latched so the word does not chatter on a boundary
+  - Costs nothing while its dialog is closed
+
 * Add the Stereo Widener rack effect
   - Widens or narrows the low, mid and high bands on their own terms, so the
     top can be opened up without the bottom smearing

src/CMakeLists.txt

@@ -116,6 +116,7 @@ set(QML_SOURCE_FILES
     ${QML_BASE_DIR}/Dialogs/PianoSynthV2Dialog_Global.qml
     ${QML_BASE_DIR}/Dialogs/PianoSynthV2Dialog_Hammer.qml
     ${QML_BASE_DIR}/Dialogs/PianoSynthV2Dialog_String.qml
+    ${QML_BASE_DIR}/Dialogs/StereoFieldMeterDialog.qml
     ${QML_BASE_DIR}/Dialogs/StereoEnhancerDialog.qml
     ${QML_BASE_DIR}/Dialogs/StereoExciterDialog.qml
     ${QML_BASE_DIR}/Dialogs/StereoWidenerDialog.qml

src/application/application.cpp

@@ -55,6 +55,7 @@
 #include "../view/controllers/wavetable_synth_controller.hpp"
 #include "../view/qml/Components/oscilloscope_renderer.hpp"
 #include "../view/qml/Dialogs/rta_renderer.hpp"
+#include "../view/qml/Dialogs/stereo_field_renderer.hpp"
 #include "../view/qml/Editor/line_number_renderer.hpp"
 #include "../view/qml/Editor/note_column_renderer.hpp"
 #include "models/audio_settings_model.hpp"
@@ -223,6 +224,7 @@ void Application::registerTypes()
     qmlRegisterType<NoteColumnLineContainerHelper>("Noteahead", majorVersion, minorVersion, "NoteColumnLineContainerHelper");
     qmlRegisterType<NoteColumnRenderer>("Noteahead", majorVersion, minorVersion, "NoteColumnRenderer");
     qmlRegisterType<RtaRenderer>("Noteahead", majorVersion, minorVersion, "RtaRenderer");
+    qmlRegisterType<StereoFieldRenderer>("Noteahead", majorVersion, minorVersion, "StereoFieldRenderer");
     qmlRegisterType<OscilloscopeRenderer>("Noteahead", majorVersion, minorVersion, "OscilloscopeRenderer");
     qmlRegisterType<PitchBendAutomationsModel>("Noteahead", majorVersion, minorVersion, "PitchBendAutomationsModel");
     qmlRegisterType<PropertyService>("Noteahead", majorVersion, minorVersion, "PropertyService");

src/common/constants.cpp

@@ -256,6 +256,11 @@ QString stereoWidener()
     return "stereoWidener";
 }
 
+QString stereoFieldMeter()
+{
+    return "stereoFieldMeter";
+}
+
 QString limiter()
 {
     return "limiter";
@@ -2357,6 +2362,16 @@ QString xmlKeySpeed()
     return "speed";
 }
 
+QString xmlKeyZoom()
+{
+    return "zoom";
+}
+
+QString xmlKeyShowGuides()
+{
+    return "showGuides";
+}
+
 QString xmlKeyFftRate()
 {
     return "fftRate";

src/common/constants.hpp

@@ -174,6 +174,7 @@ QString waveDesigner();
 QString stereoEnhancer();
 QString stereoExciter();
 QString stereoWidener();
+QString stereoFieldMeter();
 QString limiter();
 QString endless();
 QString panner();
@@ -648,6 +649,8 @@ QString xmlKeyDbRange();
 QString xmlKeyShowPinkNoise();
 QString xmlKeyPinkNoiseLevel();
 QString xmlKeySpeed();
+QString xmlKeyZoom();
+QString xmlKeyShowGuides();
 QString xmlKeyFftRate();
 
 QString embeddedDataPathPrefix();

src/domain/CMakeLists.txt

@@ -120,6 +120,7 @@ set(HEADER_FILES
     utility/loudness_analyzer.hpp
     utility/lufs_meter.hpp
     utility/rta.hpp
+    utility/stereo_field_meter.hpp
 )
 
 set(SOURCE_FILES
@@ -245,6 +246,7 @@ set(SOURCE_FILES
     utility/loudness_analyzer.cpp
     utility/lufs_meter.cpp
     utility/rta.cpp
+    utility/stereo_field_meter.cpp
 )
 
 add_library(${DomainLibName} STATIC ${HEADER_FILES} ${SOURCE_FILES})

src/domain/effects/effect_factory.cpp

@@ -19,6 +19,7 @@
 #include "../utility/dbtp_meter.hpp"
 #include "../utility/lufs_meter.hpp"
 #include "../utility/rta.hpp"
+#include "../utility/stereo_field_meter.hpp"
 #include "air_band_eq.hpp"
 #include "all_pass_filter.hpp"
 #include "auto_ducker.hpp"
@@ -116,6 +117,7 @@ void EffectFactory::init()
     registerEffect(Panner::typeIdString(), []() { return std::make_shared<Panner>(); });
     registerEffect(Phaser::typeIdString(), []() { return std::make_shared<Phaser>(); });
     registerEffect(Rta::typeIdString(), []() { return std::make_shared<Rta>(); });
+    registerEffect(StereoFieldMeter::typeIdString(), []() { return std::make_shared<StereoFieldMeter>(); });
     registerEffect(Reverb::typeIdString(), []() { return std::make_shared<Reverb>(); });
     registerEffect(Saturator::typeIdString(), []() { return std::make_shared<Saturator>(); });
     registerEffect(TubeStage::typeIdString(), []() { return std::make_shared<TubeStage>(); });
@@ -139,6 +141,7 @@ void EffectFactory::init()
     registerEffect(Constants::RackEffectType::phaser().toStdString(), []() { return std::make_shared<Phaser>(); });
     registerEffect(Constants::RackEffectType::reverb().toStdString(), []() { return std::make_shared<Reverb>(); });
     registerEffect(Constants::RackEffectType::rta().toStdString(), []() { return std::make_shared<Rta>(); });
+    registerEffect(Constants::RackEffectType::stereoFieldMeter().toStdString(), []() { return std::make_shared<StereoFieldMeter>(); });
     registerEffect(Constants::RackEffectType::saturator().toStdString(), []() { return std::make_shared<Saturator>(); });
     registerEffect(Constants::RackEffectType::vintagePassiveEq().toStdString(), []() { return std::make_shared<VintagePassiveEq>(); });
     registerEffect(Constants::RackEffectType::airBandEq().toStdString(), []() { return std::make_shared<AirBandEq>(); });
@@ -158,6 +161,7 @@ void EffectFactory::init()
     registerLegacyEffect("auto_filter", []() { return std::make_shared<AutoFilter>(); });
     registerLegacyEffect("multiband_compressor", []() { return std::make_shared<MultibandCompressor>(); });
     registerLegacyEffect("stereo_widener", []() { return std::make_shared<StereoWidener>(); });
+    registerLegacyEffect("stereo_field_meter", []() { return std::make_shared<StereoFieldMeter>(); });
     registerLegacyEffect("multibandStereoWidth", []() { return std::make_shared<StereoWidener>(); });
     registerLegacyEffect("multiband_stereo_width", []() { return std::make_shared<StereoWidener>(); });
     registerLegacyEffect("bass_grinder", []() { return std::make_shared<BassGrinder>(); });

src/domain/utility/stereo_field_meter.cpp

@@ -0,0 +1,265 @@
+// This file is part of Noteahead.
+// Copyright (C) 2026 Jussi Lind <jussi.lind@iki.fi>
+//
+// Noteahead is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+// Noteahead is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Noteahead. If not, see <http://www.gnu.org/licenses/>.
+
+#include "stereo_field_meter.hpp"
+
+#include "../../common/constants.hpp"
+#include "../../common/utils.hpp"
+#include "../dsp/audio_context.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace noteahead {
+
+namespace {
+
+//! Where the three measured bands are divided. Fixed rather than adjustable: these are the regions
+//! width behaves differently in, not a crossover anything is summed back across.
+constexpr double lowerCrossoverHz = 250.0;
+constexpr double upperCrossoverHz = 3000.0;
+
+//! What the Speed control selects, in milliseconds. Fast follows a phrase, Slow follows a mix.
+constexpr std::array<double, 3> meterTimeConstantsMs { 80.0, 300.0, 1000.0 };
+
+//! Anything quieter than this is silence as far as the readings are concerned.
+constexpr double silenceFloor = 1.0e-9;
+
+//! Floor the level readings rest on, so a silent meter does not report minus infinity.
+constexpr float floorDb = -100.0f;
+
+} // namespace
+
+StereoFieldMeter::StereoFieldMeter()
+{
+    addParameter(Parameter { Constants::NahdXml::xmlKeySpeed().toStdString(), 1.0f, 0, 2, 1, 1, Parameter::Type::Discrete });
+    addParameter(Parameter { Constants::NahdXml::xmlKeyZoom().toStdString(), 0.5f, 0, 10000, 5000, 100, Parameter::Type::Continuous });
+    addParameter(Parameter { Constants::NahdXml::xmlKeyShowGuides().toStdString(), 1.0f, 0, 1, 1, 1, Parameter::Type::Boolean });
+
+    syncParameters();
+}
+
+void StereoFieldMeter::PairMeter::update(double a, double b, double coefficient)
+{
+    productAb += (a * b - productAb) * coefficient;
+    squareA += (a * a - squareA) * coefficient;
+    squareB += (b * b - squareB) * coefficient;
+}
+
+float StereoFieldMeter::PairMeter::correlation() const
+{
+    const double energy = std::sqrt(squareA * squareB);
+
+    // Silence has no correlation to report. Reading it as centred is what keeps the meter still
+    // between notes instead of wandering on the noise floor.
+    if (energy < silenceFloor) {
+        return 1.0f;
+    }
+
+    return static_cast<float>(std::clamp(productAb / energy, -1.0, 1.0));
+}
+
+double StereoFieldMeter::PairMeter::rmsA() const
+{
+    return std::sqrt(std::max(squareA, 0.0));
+}
+
+double StereoFieldMeter::PairMeter::rmsB() const
+{
+    return std::sqrt(std::max(squareB, 0.0));
+}
+
+void StereoFieldMeter::PairMeter::reset()
+{
+    productAb = 0.0;
+    squareA = 0.0;
+    squareB = 0.0;
+}
+
+void StereoFieldMeter::Splitter::setCutoffs(double lowerFrequency, double upperFrequency, double sampleRate)
+{
+    lowSplit.setSampleRate(sampleRate);
+    highSplit.setSampleRate(sampleRate);
+    lowSplit.setCutoff(lowerFrequency);
+    highSplit.setCutoff(upperFrequency);
+}
+
+void StereoFieldMeter::Splitter::split(double input, std::array<double, NumBands> & bands)
+{
+    double low = 0.0;
+    double aboveLow = 0.0;
+    lowSplit.process(input, low, aboveLow);
+
+    double mid = 0.0;
+    double high = 0.0;
+    highSplit.process(aboveLow, mid, high);
+
+    bands[0] = low;
+    bands[1] = mid;
+    bands[2] = high;
+}
+
+void StereoFieldMeter::Splitter::reset()
+{
+    lowSplit.reset();
+    highSplit.reset();
+}
+
+std::string StereoFieldMeter::typeIdString()
+{
+    return "7e1c94b6-2fa8-4d53-9c6b-05e8d3417a92";
+}
+
+std::string StereoFieldMeter::type() const
+{
+    return Constants::RackEffectType::stereoFieldMeter().toStdString();
+}
+
+std::string StereoFieldMeter::typeId() const
+{
+    return typeIdString();
+}
+
+void StereoFieldMeter::setAnalysisEnabled(bool enabled)
+{
+    m_analysisEnabled.store(enabled, std::memory_order_relaxed);
+    m_scope.setActive(enabled);
+}
+
+void StereoFieldMeter::analyse(double left, double right)
+{
+    m_broadband.update(left, right, m_meterCoefficient);
+
+    const double mid = (left + right) * 0.5;
+    const double side = (left - right) * 0.5;
+    m_midSide.update(mid, side, m_meterCoefficient);
+
+    std::array<double, NumBands> bandsLeft {};
+    std::array<double, NumBands> bandsRight {};
+    m_splitterL.split(left, bandsLeft);
+    m_splitterR.split(right, bandsRight);
+
+    for (size_t i = 0; i < NumBands; i++) {
+        m_bands[i].update(bandsLeft[i], bandsRight[i], m_meterCoefficient);
+    }
+}
+
+void StereoFieldMeter::processSample(double & left, double & right)
+{
+    if (!m_analysisEnabled.load(std::memory_order_relaxed) || m_sampleRate <= 0) {
+        return;
+    }
+
+    updateState();
+    analyse(left, right);
+}
+
+void StereoFieldMeter::processBlock(AudioContext & context)
+{
+    if (!m_analysisEnabled.load(std::memory_order_relaxed)) {
+        return;
+    }
+
+    if (context.sampleRate != m_lastSampleRate) {
+        m_lastSampleRate = context.sampleRate;
+        m_shouldSyncParameters = true;
+    }
+    if (m_shouldSyncParameters) {
+        syncParameters();
+        m_shouldSyncParameters = false;
+    }
+
+    for (uint32_t i = 0; i < context.frameCount; i++) {
+        analyse(context.buffer[i * 2], context.buffer[i * 2 + 1]);
+    }
+
+    m_scope.write(context.buffer.data(), context.frameCount, context.sampleRate);
+
+    // Published once per block rather than per sample: the dialog reads it thirty times a second,
+    // and taking the lock for every frame would be the only expensive thing this effect does.
+    Reading reading;
+    reading.correlation = m_broadband.correlation();
+    for (size_t i = 0; i < NumBands; i++) {
+        reading.bandCorrelation[i] = m_bands[i].correlation();
+    }
+    reading.midDb = std::max(Utils::Dsp::linearToDb(static_cast<float>(m_midSide.rmsA())), floorDb);
+    reading.sideDb = std::max(Utils::Dsp::linearToDb(static_cast<float>(m_midSide.rmsB())), floorDb);
+
+    const double leftRms = m_broadband.rmsA();
+    const double rightRms = m_broadband.rmsB();
+    const double total = leftRms + rightRms;
+    reading.balance = total > silenceFloor ? static_cast<float>((rightRms - leftRms) / total) : 0.0f;
+
+    {
+        const std::lock_guard<std::mutex> lock { m_readingMutex };
+        m_reading = reading;
+    }
+}
+
+StereoFieldMeter::Reading StereoFieldMeter::reading() const
+{
+    const std::lock_guard<std::mutex> lock { m_readingMutex };
+    return m_reading;
+}
+
+AudioScope::Snapshot StereoFieldMeter::trace(size_t maxPoints) const
+{
+    return m_scope.snapshot(maxPoints);
+}
+
+void StereoFieldMeter::updateState()
+{
+    if (static_cast<uint32_t>(m_sampleRate) != m_lastSampleRate || m_shouldSyncParameters) {
+        syncParameters();
+        m_lastSampleRate = static_cast<uint32_t>(m_sampleRate);
+        m_shouldSyncParameters = false;
+    }
+}
+
+void StereoFieldMeter::syncParameters()
+{
+    const double sampleRate = m_sampleRate > 0 ? m_sampleRate : (m_lastSampleRate > 0 ? m_lastSampleRate : 48000.0);
+
+    m_splitterL.setCutoffs(lowerCrossoverHz, upperCrossoverHz, sampleRate);
+    m_splitterR.setCutoffs(lowerCrossoverHz, upperCrossoverHz, sampleRate);
+
+    size_t speedIndex = 1;
+    if (const auto p = parameter(Constants::NahdXml::xmlKeySpeed().toStdString()); p) {
+        speedIndex = std::min(static_cast<size_t>(std::lround(p->get().value())), meterTimeConstantsMs.size() - 1);
+    }
+
+    m_meterCoefficient = 1.0 - std::exp(-1.0 / (meterTimeConstantsMs[speedIndex] * 0.001 * sampleRate));
+}
+
+void StereoFieldMeter::reset()
+{
+    m_broadband.reset();
+    m_midSide.reset();
+    for (auto && band : m_bands) {
+        band.reset();
+    }
+    m_splitterL.reset();
+    m_splitterR.reset();
+
+    const std::lock_guard<std::mutex> lock { m_readingMutex };
+    m_reading = Reading {};
+}
+
+void StereoFieldMeter::sync()
+{
+    m_shouldSyncParameters = true;
+}
+
+} // namespace noteahead