hart_peaksat.hpp

Go to the documentation of this file.

#pragma once
 
#include <algorithm>  // max()
#include <cmath>  // abs()
#include <iomanip>
#include <sstream>
 
#include "matchers/hart_matcher.hpp"
#include "hart_precision.hpp"
#include "hart_utils.hpp"                  // decibelsToRatio(), ratioToDecibels()
 
namespace hart
{
 
/// @brief Checks whether the audio peaks at specific level
/// @details This matcher will calculate peak value of a full audio signal (not a per-block peaks)
/// and compare against a value provided during instantiation with a provided tolerance.
/// It checks where all selected channels peak collectively, not for each individual channel.
/// To do more strict per channel checks, use multiple matchers with @ref atChannel(), so that
/// each matcher only targets one specific channel. 
/// @attention It checks the sample peaks, not the inter-sample peaks (a popular metric in audio
/// mastering community). For inter-sample peak checking, see `TruePeaksBelow` and `truePeak()`.
/// For more versatile expressions, check the `samplePeak()` metric.
/// @ingroup Matchers
template<typename SampleType>
class PeaksAt:
    public Matcher<SampleType, PeaksAt<SampleType>>
{
public:
    /// @brief Creates a matcher for a specific peak level
    /// @param targetDb Expected sample peak value in decibels
    /// @param toleranceLinear Absolute tolerance for comparing frames, in linear domain (not decibels)
    PeaksAt (double targetDb, double toleranceLinear = 1e-3):
        m_targetDb ((SampleType) targetDb),
        m_targetLinear ((SampleType) decibelsToRatio (targetDb)),
        m_toleranceLinear ((SampleType) toleranceLinear)
    {
    }
 
    void prepare (double /*sampleRateHz*/, size_t /* numInputChannels */, size_t /* numOutputChannels */, size_t /* maxBlockSizeFrames */) override {}
 
    bool match (AnalysisContext<SampleType> context) override
    {
        const AudioBuffer<SampleType>& observedOutputAudio = context.outputAudio();
        SampleType observedPeakLinear = 0;
        size_t frameOfObservedPeakLinear = 0;
        size_t channelOfObservedPeakLinear = 0;
 
        for (size_t channel = 0; channel < observedOutputAudio.getNumChannels(); ++channel)
        {
            if (! this->appliesToChannel (channel))
                continue;
 
            for (size_t frame = 0; frame < observedOutputAudio.getNumFrames(); ++frame)
            {
                const SampleType currentPeakLinear = std::abs (observedOutputAudio[channel][frame]);
 
                if (currentPeakLinear > observedPeakLinear)
                {
                    observedPeakLinear = currentPeakLinear;
                    frameOfObservedPeakLinear = frame;
                    channelOfObservedPeakLinear = channel;
                }
            }
        }
 
        if (std::abs (observedPeakLinear - m_targetLinear) > m_toleranceLinear)
        {
            m_failedFrame = frameOfObservedPeakLinear;
            m_failedChannel = (int) channelOfObservedPeakLinear;
            m_observedPeakDb = ratioToDecibels (observedPeakLinear);
            return false;
        }
 
        return true;
    }
 
    bool canOperatePerBlock() const override
    {
        return false;
    }
 
    virtual MatcherFailureDetails getFailureDetails() const override
    {
        std::stringstream stream;
        stream << dbPrecision << "Observed audio peaks at " << m_observedPeakDb << " dB";
 
        MatcherFailureDetails details;
        details.frame = m_failedFrame;
        details.channel = m_failedChannel;
        details.description = stream.str();
        return details;
    }
 
    void represent (std::ostream& stream) const override
    {
        stream << "PeaksAt ("
            << dbPrecision << m_targetDb << "_dB, "
            << linPrecision << m_toleranceLinear << ')';
    }
 
private:
    const SampleType m_targetDb;
    const SampleType m_targetLinear;
    const SampleType m_toleranceLinear;
 
    size_t m_failedFrame = 0;
    size_t m_failedChannel = 0;
    SampleType m_observedPeakDb = (SampleType) 0;
};
 
HART_MATCHER_DECLARE_ALIASES_FOR (PeaksAt)
 
}  // namespace hart