hart_process_audio.hpp

Go to the documentation of this file.

#pragma once
 
#include <algorithm>  // min()
#include <cassert>
#include <cmath>
#include <functional>
#include <iomanip>
#include <memory>
#include <sstream>
#include <vector>
 
#include "hart_analysis_context.hpp"
#include "hart_audio_buffer.hpp"
#include "hart_condition.hpp"
#include "dsp/hart_dsp_all.hpp"
#include "dsp/hart_dsp_function.hpp"
#include "hart_expectation_failure_messages.hpp"
#include "matchers/hart_matcher.hpp"
#include "matchers/hart_matcher_function.hpp"
#include "hart_plot.hpp"
#include "hart_precision.hpp"
#include "hart_preparation.hpp"
#include "hart_wavwriter.hpp"
#include "signals/hart_signals_all.hpp"
#include "hart_utils.hpp"                  // make_unique()
 
namespace hart {
 
/// @defgroup TestRunner Test Runner
/// @brief Runs the tests
 
/// @brief Determines when to save a file
/// @ingroup TestRunner
enum class Save
{
    always,  ///< File will be saved always, after the test is performed
    whenFails,  ///< File will be saved only when the test has failed
    never  ///< File will not be saved
};
 
/// @brief Determines whether to reset the Signal in a given context
/// @ingroup TestRunner
enum class ResetSignal
{
    no,  ///< The signal will continue from whatever state it was in
    yes  ///< The signal's state will be reset
};
 
/// @brief A DSP host used for building and running tests inside a test case
/// @ingroup TestRunner
template <typename SampleType>
class AudioTestBuilder
{
public:
    /// @brief Moves the DSP instance into the host
    /// @details DSP instance will be moved into this host, and then returned by @ref process(), so you can re-use it.
    /// You can only pass a DSP by moving it, since some of the custom DSP wrappers can be non-copyable.
    /// If you do want to copy a DSP instance here, use its DSPBase::copy() method explicitly.
    /// @param dsp Your DSP instance
    template <typename DSPType>
    AudioTestBuilder (DSPType&& dsp,
        typename std::enable_if<
            ! std::is_lvalue_reference<DSPType&&>::value &&
            std::is_base_of<DSPBase<SampleType>, typename std::decay<DSPType>::type>::value
        >::type* = 0)
    : m_processor (std::forward<DSPType> (dsp).move())
    {
    }
 
    /// @brief Transfers the DSP smart pointer into the host
    /// @details Use this if your DSP does not support copying or moving. It will be owned by this host,
    /// and then returned by @ref process(), so you can re-use it.
    /// @param dsp A smart pointer to your DSP instance
    AudioTestBuilder (std::unique_ptr<DSPBase<SampleType>> dsp)
    : m_processor (std::move (dsp))
    {
    }
 
    /// @brief Sets the sample rate for the test
    /// @details All the signals, effects and sub hosts are guaranteed to be initialized to this sample rate
    /// @param sampleRateHz Sample rate in Hz. You can use frequency-related literails from @ref Units.
    AudioTestBuilder& withSampleRate (double sampleRateHz)
    {
        if (sampleRateHz <= 0)
            HART_THROW_OR_RETURN (hart::ValueError, "Sample rate should be a positive value in Hz", *this);
 
        if (! m_processor->supportsSampleRate (sampleRateHz))
            HART_THROW_OR_RETURN (hart::SampleRateError, "Sample rate is not supported by the tested DSP", *this);
 
        m_sampleRateHz = sampleRateHz;
        return *this;
    }
 
    /// @brief Sets the block size for the test
    /// @param blockSizeFrames Block size in frames (samples)
    AudioTestBuilder& withBlockSize (size_t blockSizeFrames)
    {
        if (blockSizeFrames == 0)
            HART_THROW_OR_RETURN (hart::SizeError, "Illegal block size - should be a positive value in frames (samples)", *this);
 
        m_blockSizeFrames = blockSizeFrames;
        return *this;
    }
 
    /// @brief Sets the initial param value for the tested DSP
    /// @details It will call @ref DSP::setValue() for DSP under test
    /// @param id Parameter ID (see @ref DSP::setValue())
    /// @param value Value that needs to be set
    AudioTestBuilder& withValue (int id, double value)
    {
        // TODO: Handle cases when processor already has an envelope for this id
        paramValues.emplace_back (ParamValue { id, value });
        return *this;
    }
 
    /// @brief Sets the total duration of the input signal to be processed
    /// @param durationSeconds of the signal in seconds. You can use time-related literails from @ref Units.
    AudioTestBuilder& withDuration (double durationSeconds)
    {
        if (durationSeconds < 0)
            HART_THROW_OR_RETURN(hart::ValueError, "Signal duration should be a non-negative value in seconds", *this);
 
        m_testDurationSeconds = durationSeconds;
        return *this;
    }
 
    /// @brief Sets whether to call reset() and/or prepare() on DSP testee before rendering audio
    /// @details It is useful when you re-use your DSP instance, to control whether you want to
    /// preserve its pre-existing state. If you also request `withWarmUp()`, this call will only
    /// affect pre-warp-up preparation. Post-warm-up preparaton is selected via `withWarmUp()` args.
    AudioTestBuilder& withDspPreparation (Preparation dspPreparation)
    {
        m_dspPreparationBeforeWarmUp = dspPreparation;
        return *this;
    }
 
    /// @brief Sets whether to call reset() and/or prepare() on the input Signal before rendering audio
    /// @details It is useful when you re-use your Signal instance, to control whether you want to
    /// preserve its pre-existing state. If you also request `withWarmUp()`, this call will only
    /// affect pre-warp-up preparation. Post-warm-up preparaton is selected via `withWarmUp()` args.
    AudioTestBuilder& withSignalPreparation (Preparation signalPreparation)
    {
        m_signalPreparationBeforeWarmUp = signalPreparation;
        return *this;
    }
 
    /// @brief Adds a warm‑up period before the main test.
    /// @details The signal will be processed for this time, but no matchers will be invoked.
    /// This can be useful if your DSP uses parameter smoothers internally, that need to settle
    /// before performing the test, or has some sort of attack envelope stage, like a compressor,
    /// that you want to skip. This time will be added up with a regular test render run, i.e.
    /// `processAudioWith (...).withDuration (100_ms).withWarmUp (10_ms)` will result in
    /// 10 + 100 = 110 ms of total rendered audio.
    /// @note Calling `saveOutputTo()` (both for wav files and `AudioBuffer`s) and `savePlotTo()`
    /// will always output the entire rendered piece of audio, including this warm-up stage.
    /// @param warmUpDurationSeconds Duration of the warm‑up in seconds
    /// @param signalPreparation Whether to call reset() and/or prepare() on an input signal
    /// after the warm-up stage
    /// @param dspPreparation Whether to call reset() and/or prepare() on the DSP testee
    /// after the warm-up stage
    AudioTestBuilder& withWarmUp (
        double warmUpDurationSeconds,
        Preparation signalPreparation = Preparation::none,
        Preparation dspPreparation = Preparation::none
        )
    {
        if (warmUpDurationSeconds < 0)
            HART_THROW_OR_RETURN (hart::ValueError, "Warm-up should be a non-negative value in seconds", *this);
 
        m_warmUpDurationSeconds = warmUpDurationSeconds;
        m_signalPreparationAfterWarmUp = signalPreparation;
        m_dspPreparationAfterWarmUp = dspPreparation;
        return *this;
    }
 
    /// @brief Sets the input signal for the test by copying it
    /// @param signal Input signal, see @ref Signals
    AudioTestBuilder& withInputSignal (const SignalBase<SampleType>& signal)
    {
        m_inputSignal = std::move (signal.copy());
        return *this;
    }
 
    /// @brief Sets the input signal for the test by moving it
    /// @param signal Input signal, see @ref Signals
    AudioTestBuilder& withInputSignal (SignalBase<SampleType>&& signal)
    {
        m_inputSignal = std::move (signal.move());
        return *this;
    }
 
    /// @brief Sets the input signal for the test by transfering its smart pointer
    /// @note The ownership of the smart pointer will be transferred to this class
    /// @param signal Input signal, see @ref Signals
    AudioTestBuilder& withInputSignal (std::unique_ptr<SignalBase<SampleType>> signal)
    {
        m_inputSignal = std::move (signal);
        return *this;
    }
 
    /// @brief Sets the input signal using a function-based signal definition
    /// @param signalFunction Function that generates the signal buffer. It will moved to a Signal object. 
    /// @param label Human-readable label for the signal to use in the test error output
    /// @param loop Determines whether the generated buffer should loop
    /// @details
    /// This overload constructs a @ref SignalFunction internally, allowing inline
    /// definition of signals without explicitly creating a Signal object, for slightly
    /// less verbose syntax.
    ///
    /// The function must have the signature:
    /// `void (AudioBuffer<SampleType>&)`
    ///
    /// This method echoes the ctor of the hart::SignalFunction class, so see its
    /// documentaion for more detailed description.
    ///
    /// @note To re-use the signal made with your function, you can use `saveInputSignalTo()`.
    /// @see SignalFunction
    AudioTestBuilder& withInputSignal (
        std::function<void (AudioBuffer<SampleType>&)> signalFunction,
        const std::string& label = {},
        Loop loop = Loop::yes)
    {
        m_inputSignal = hart::make_unique<SignalFunction<SampleType>>(
            std::move (signalFunction),
            label,
            loop
        );
 
        return *this;
    }
 
    /// @brief Sets arbitrary number of input channels
    /// @details For common mono and stereo cases, you may use dedicated methods like @ref inStereo() or
    /// @ref withMonoInput() instead of this one for better readability.
    /// @param numInputChannels Number of input channels
    AudioTestBuilder& withInputChannels (size_t numInputChannels)
    {
        if (numInputChannels == 0)
            HART_THROW_OR_RETURN (SizeError, "There should be at least one (mono) audio channel", *this);
 
        if (numInputChannels > 128)
            HART_THROW_OR_RETURN (SizeError, "The number of channels is unexpectedly large... Do people really use so many channels?", *this);
 
        m_numInputChannels = numInputChannels;
        return *this;
    }
 
    /// @brief Sets arbitrary number of output channels
    /// @details For common mono and stereo cases, you may use dedicated methods like @ref inMono() or
    /// @ref withStereoOutput() instead of this one for better readability.
    /// @param numOutputChannels Number of output channels
    AudioTestBuilder& withOutputChannels (size_t numOutputChannels)
    {
        if (numOutputChannels == 0)
            HART_THROW_OR_RETURN(SizeError, "There should be at least one (mono) audio channel", *this);
 
        if (numOutputChannels > 128)
            HART_THROW_OR_RETURN(SizeError, "The number of channels is unexpectedly large... Do people really use so many channels?", *this);
 
        m_numOutputChannels = numOutputChannels;
        return *this;
    }
 
    /// @brief Sets number of input channels to two
    AudioTestBuilder& withStereoInput()
    {
        return this->withInputChannels (2);
    }
 
    /// @brief Sets number of output channels to two
    AudioTestBuilder& withStereoOutput()
    {
        return this->withOutputChannels (2);
    }
 
    /// @brief Sets number of input channels to one
    AudioTestBuilder& withMonoInput()
    {
        return this->withInputChannels (1);
    }
 
    /// @brief Sets number of output channels to one
    AudioTestBuilder& withMonoOutput()
    {
        return this->withOutputChannels (1);
    }
 
    /// @brief Sets number of input and output channels to one
    AudioTestBuilder& inMono()
    {
        return this->withMonoInput().withMonoOutput();
    }
 
    /// @brief Sets number of input and output channels to two
    AudioTestBuilder& inStereo()
    {
        return this->withStereoInput().withStereoOutput();
    }
 
    /// @brief Adds an "expect" check using a Matcher object
    /// @param matcher Matcher to perform the check, see @ref Matchers
    template<typename MatcherType>
    AudioTestBuilder& expectTrue (MatcherType&& matcher)
    {
        addCheck (std::forward<MatcherType> (matcher), SignalAssertionLevel::expect, true);
        return *this;
    }
 
    /// @brief Adds a reversed "expect" check using a Matcher object
    /// @param matcher Matcher to perform the check, see @ref Matchers
    template<typename MatcherType>
    AudioTestBuilder& expectFalse (MatcherType&& matcher)
    {
        addCheck (std::forward<MatcherType> (matcher), SignalAssertionLevel::expect, false);
        return *this;
    }
 
    /// @brief Adds an "assert" check using a Matcher object
    /// @param matcher Matcher to perform the check, see @ref Matchers
    template<typename MatcherType>
    AudioTestBuilder& assertTrue (MatcherType&& matcher)
    {
        addCheck (std::forward<MatcherType> (matcher), SignalAssertionLevel::assert, true);
        return *this;
    }
 
    /// @brief Adds a reversed "assert" check using a Matcher object
    /// @param matcher Matcher to perform the check, see @ref Matchers
    template<typename MatcherType>
    AudioTestBuilder& assertFalse (MatcherType&& matcher)
    {
        addCheck (std::forward<MatcherType> (matcher), SignalAssertionLevel::assert, false);
        return *this;
    }
 
    // TODO: Add expect/assert overloads for smart pointers as well
 
    /// @brief Adds an "expect" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& output) { return HART_LESS_THAN (crestFactorDb (output), 3_dB); }
    /// @endcode
    /// @param label Optional label used in failure reports
    AudioTestBuilder& expectTrue (std::function<Condition (const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return expectTrue (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Adds an "expect" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& input,
    ///            const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& input, const AudioBuffer<SampleType>& output)
    /// {
    ///     return HART_LESS_THAN (crestFactorDb (output), crestFactorDb (input));
    /// }
    /// @endcode
    /// @param label Optional label used in failure reports
    /// @note If your matcher function only cares about the output, and not the input,
    /// just use the overload that takes `Condition (const AudioBuffer<SampleType>& output)`.
    AudioTestBuilder& expectTrue (std::function<Condition (const AudioBuffer<SampleType>&, const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return expectTrue (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Adds a reversed "expect" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& output) { return HART_LESS_THAN (crestFactorDb (output), 3_dB); }
    /// @endcode
    /// @param label Optional label used in failure reports
    AudioTestBuilder& expectFalse (std::function<Condition (const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return expectFalse (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Adds a reversed "expect" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& input,
    ///            const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& input, const AudioBuffer<SampleType>& output)
    /// {
    ///     return HART_LESS_THAN (crestFactorDb (output), crestFactorDb (input));
    /// }
    /// @endcode
    /// @param label Optional label used in failure reports
    /// @note If your matcher function only cares about the output, and not the input,
    /// just use the overload that takes `Condition (const AudioBuffer<SampleType>& output)`.
    AudioTestBuilder& expectFalse (std::function<Condition (const AudioBuffer<SampleType>&, const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return expectFalse (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Adds an "assert" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& output) { return HART_LESS_THAN (crestFactorDb (output), 3_dB); }
    /// @endcode
    /// @param label Optional label used in failure reports
    AudioTestBuilder& assertTrue (std::function<Condition (const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return assertTrue (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Adds an "assert" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& input,
    ///            const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& input, const AudioBuffer<SampleType>& output)
    /// {
    ///     return HART_LESS_THAN (crestFactorDb (output), crestFactorDb (input));
    /// }
    /// @endcode
    /// @param label Optional label used in failure reports
    /// @note If your matcher function only cares about the output, and not the input,
    /// just use the overload that takes `Condition (const AudioBuffer<SampleType>& output)`.
    AudioTestBuilder& assertTrue (std::function<Condition (const AudioBuffer<SampleType>&, const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return assertTrue (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Adds a reversed "assert" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& output) { return HART_LESS_THAN (crestFactorDb (output), 3_dB); }
    /// @endcode
    /// @param label Optional label used in failure reports
    AudioTestBuilder& assertFalse (std::function<Condition (const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return assertFalse (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Adds a reversed "assert" check using a function matcher
    /// @details Intended for simple inline expressions. For anything more than
    /// that, consider making a custom hart::Matcher subclass and use it instead.
    /// @see MatcherFunction
    /// @param matcherFunction Function with signature:
    /// @code
    /// Condition (const AudioBuffer<SampleType>& input,
    ///            const AudioBuffer<SampleType>& output)
    /// @endcode
    ///
    /// Example:
    /// @code
    /// [] (const AudioBuffer<SampleType>& input, const AudioBuffer<SampleType>& output)
    /// {
    ///     return HART_LESS_THAN (crestFactorDb (output), crestFactorDb (input));
    /// }
    /// @endcode
    /// @param label Optional label used in failure reports
    /// @note If your matcher function only cares about the output, and not the input,
    /// just use the overload that takes `Condition (const AudioBuffer<SampleType>& output)`.
    AudioTestBuilder& assertFalse (std::function<Condition (const AudioBuffer<SampleType>&, const AudioBuffer<SampleType>&)> matcherFunction, const std::string& label = {})
    {
        return assertFalse (MatcherFunction<SampleType> (std::move (matcherFunction), label));
    }
 
    /// @brief Enables saving output audio to a wav file
    /// @note If you're using `withWarmUp()`, this warm-up section of audio will also be included in the output file
    /// @param path File path - relative or absolute. If relative path is set, it will be appended to the provided `--data-root-path` CLI argument.
    /// @param mode When to save, see @ref hart::Save
    /// @param wavFormat Format of the wav file, see hart::WavFormat for supported options
    /// @see HART_REQUIRES_DATA_PATH_ARG
    AudioTestBuilder& saveOutputTo (const std::string& path, Save mode = Save::always, WavFormat wavFormat = WavFormat::pcm24)
    {
        if (path.empty())
            return *this;
 
        m_saveOutputPath = toAbsolutePath (path);
        m_saveOutputMode = mode;
        m_saveOutputWavFormat = wavFormat;
        return *this;
    }
 
    /// @brief Enables saving output audio to a provided buffer
    /// @note If you're using `withWarmUp()`, this warm-up section of audio will also be included in the output buffer
    /// @details Tip: You can use @ref HART_STR() to construct file names using "<<" syntax.
    /// @warning The target directory has to exist!
    /// @param receivingBuffer An output buffer to receive the data. You can pass an unitialised buffer, among other things, as it will be move-assigned.
    AudioTestBuilder& saveOutputTo (AudioBuffer<SampleType>& receivingBuffer)
    {
        m_outputBufferSink = [&receivingBuffer] (AudioBuffer<SampleType>&& outputBuffer)
        {
            receivingBuffer = std::move (outputBuffer);
        };
 
        return *this;
    }
 
    /// @brief Enables saving output audio via provided callback
    /// @note If you're using `withWarmUp()`, this warm-up section of audio will also be included in the output buffer
    /// @details Tip: You can use @ref HART_STR() to construct file names using "<<" syntax.
    /// @warning The target directory has to exist!
    /// @param outputBufferSink A callable that accepts a buffer rvalue. The buffer is moved into the provided sink. The test runner takes ownership of the callable object.
    AudioTestBuilder& saveOutputTo (std::function<void (AudioBuffer<SampleType>&&)> outputBufferSink)
    {
        m_outputBufferSink = std::move (outputBufferSink);
        return *this;
    }
 
    /// @brief Enables saving a plot to an SVG file
    /// @details This will plot an input and output audio as a waveform
    /// @note If you're using `withWarmUp()`, this warm-up section of audio will also be included in the plot
    /// Tip: You can use @ref HART_STR() to construct file names using "<<" syntax.
    /// @param path File path - relative or absolute. If relative path is set, it will be appended to the provided `--data-root-path` CLI argument.
    /// @param mode When to save, see @ref hart::Save
    /// @see HART_REQUIRES_DATA_PATH_ARG
    AudioTestBuilder& savePlotTo (const std::string& path, Save mode = Save::always)
    {
        if (path.empty())
            return *this;
 
        m_savePlotPath = toAbsolutePath (path);
        m_savePlotMode = mode;
        return *this;
    }
 
    /// @brief Moves the input signal after the processing into the provided smart pointer
    /// @details It's useful if you want to re-use your signal, query it for something,
    /// or extract some DSP instance from its DSP chain after the test.
    /// @param receivingSignal A smart pointer that will receive the moved signal
    AudioTestBuilder& saveInputSignalTo (std::unique_ptr<SignalBase<SampleType>>& receivingSignal)
    {
        m_inputSignalSink = [&receivingSignal] (std::unique_ptr<SignalBase<SampleType>>&& usedSignal)
        {
            receivingSignal = std::move (usedSignal);
        };
 
        return *this;
    }
 
    /// @brief Moves the input signal after the processing via provided callback
    /// @details It's useful if you want to re-use your signal, query it for something,
    /// or extract some DSP instance from its DSP chain after the test.
    /// @param inputSignalSink A callable that accepts the moved signal
    AudioTestBuilder& saveInputSignalTo (std::function<void (std::unique_ptr<SignalBase<SampleType>>&&)> inputSignalSink)
    {
        m_inputSignalSink = std::move (inputSignalSink);
        return *this;
    }
 
    /// @brief Adds a label to the test
    /// @details Useful when you call @ref process() multiple times in one test case - the label
    /// will be put into test failure report to indicate exactly which test has failed.
    /// Tip: You can use @ref HART_STR() to construct label strings using "<<" syntax.
    /// @param testLabel Any text, to be used as a label
    AudioTestBuilder& withLabel (const std::string& testLabel)
    {
        m_testLabel = testLabel;
        return *this;
    }
 
    /// @brief Performs the test
    /// @details Call this after setting all the test parameters
    std::unique_ptr<DSPBase<SampleType>> process()
    {
        const size_t totalDurationFrames = (size_t) std::round (m_sampleRateHz * (m_testDurationSeconds + m_warmUpDurationSeconds));
        const size_t warmUpDurationFrames = (size_t) std::round (m_sampleRateHz * m_warmUpDurationSeconds);
        const size_t testDurationFrames = totalDurationFrames - warmUpDurationFrames;
 
        if (totalDurationFrames == 0)
            HART_THROW_OR_RETURN (hart::SizeError, "Nothing to process", std::move (m_processor));
 
        const bool perBlockChecksPreparationSuccessful = prepareChecks (perBlockChecks);
        const bool fullSignalChecksPreparationSuccessful = prepareChecks (fullSignalChecks);
 
        if (! perBlockChecksPreparationSuccessful || ! fullSignalChecksPreparationSuccessful)
            return std::move (m_processor);
 
        if (! m_processor->supportsSampleRate (m_sampleRateHz))
            HART_THROW_OR_RETURN (hart::SampleRateError, "DSP testee does not support requested sample rate", std::move (m_processor));
 
        if (! m_processor->supportsChannelLayout (m_numInputChannels, m_numOutputChannels))
            HART_THROW_OR_RETURN (hart::ChannelLayoutError, "DSP testee does not support requested channel layout", std::move (m_processor));
 
        if (m_dspPreparationBeforeWarmUp == Preparation::reset || m_dspPreparationBeforeWarmUp == Preparation::resetAndPrepare)
            m_processor->reset();
 
        if (m_dspPreparationBeforeWarmUp == Preparation::prepare || m_dspPreparationBeforeWarmUp == Preparation::resetAndPrepare)
            m_processor->prepareWithEnvelopes (m_sampleRateHz, m_numInputChannels, m_numOutputChannels, m_blockSizeFrames);
 
        for (const ParamValue& paramValue : paramValues)
        {
            // TODO: Add true/false return to indicate if setting the parameter was successful
            m_processor->setValue (paramValue.id, paramValue.value);
        }
 
        if (m_inputSignal == nullptr)
            m_inputSignal = std::move (hart::make_unique<Silence<SampleType>>());
 
        if (! m_inputSignal->supportsSampleRateWithDSPChain (m_sampleRateHz))
            HART_THROW_OR_RETURN (hart::SampleRateError, "Input signal or an effect in its DSP chain does not support requested sample rate", std::move (m_processor));
 
        if (! m_inputSignal->supportsNumChannelsWithDSPChain (m_numInputChannels))
            HART_THROW_OR_RETURN (hart::ChannelLayoutError, "Input signal or an effect in its DSP chain does not support requested number of channels", std::move (m_processor));
 
        if (m_signalPreparationBeforeWarmUp == Preparation::reset || m_signalPreparationBeforeWarmUp == Preparation::resetAndPrepare)
            m_inputSignal->resetWithDSPChain();
 
        if (m_signalPreparationBeforeWarmUp == Preparation::prepare || m_signalPreparationBeforeWarmUp == Preparation::resetAndPrepare)
            m_inputSignal->prepareWithDSPChain (m_sampleRateHz, m_numInputChannels, m_blockSizeFrames);
 
        offsetFrames = 0;
 
        // TODO: Pre-allocate full buffer sizes here, as they're already known at this point
        AudioBuffer<SampleType> fullInputBuffer (m_numInputChannels, 0, m_sampleRateHz);
        AudioBuffer<SampleType> fullOutputBuffer (m_numOutputChannels, 0, m_sampleRateHz);
        bool atLeastOneCheckFailed = false;
 
        // Warm-up render
        while (offsetFrames < warmUpDurationFrames)
        {
            const size_t blockSizeFrames = std::min (m_blockSizeFrames, warmUpDurationFrames - offsetFrames);
 
            hart::AudioBuffer<SampleType> inputBlock (m_numInputChannels, blockSizeFrames, m_sampleRateHz);
            hart::AudioBuffer<SampleType> outputBlock (m_numOutputChannels, blockSizeFrames, m_sampleRateHz);
            m_inputSignal->renderNextBlockWithDSPChain (inputBlock);
            m_processor->processWithEnvelopes (inputBlock, outputBlock);
 
            fullInputBuffer.appendFrom (inputBlock);
            fullOutputBuffer.appendFrom (outputBlock);
 
            offsetFrames += blockSizeFrames;
        }
 
        if (m_dspPreparationAfterWarmUp == Preparation::reset || m_dspPreparationAfterWarmUp == Preparation::resetAndPrepare)
            m_processor->reset();
 
        if (m_dspPreparationAfterWarmUp == Preparation::prepare || m_dspPreparationAfterWarmUp == Preparation::resetAndPrepare)
            m_processor->prepareWithEnvelopes (m_sampleRateHz, m_numInputChannels, m_numOutputChannels, m_blockSizeFrames);
 
        if (m_signalPreparationAfterWarmUp == Preparation::reset || m_signalPreparationAfterWarmUp == Preparation::resetAndPrepare)
            m_inputSignal->resetWithDSPChain();
 
        if (m_signalPreparationAfterWarmUp == Preparation::prepare || m_signalPreparationAfterWarmUp == Preparation::resetAndPrepare)
            m_inputSignal->prepareWithDSPChain (m_sampleRateHz, m_numInputChannels, m_blockSizeFrames);
 
        // Main test render
        while (offsetFrames < totalDurationFrames)
        {
            // TODO: Do not continue if there are no checks, or all checks should skip and there's no input and output file to write
            // TODO: Avoid re-allocating inputBlock and outputBlock in every iteration of this loop
 
            const size_t blockSizeFrames = std::min (m_blockSizeFrames, totalDurationFrames - offsetFrames);
 
            hart::AudioBuffer<SampleType> inputBlock (m_numInputChannels, blockSizeFrames, m_sampleRateHz);
            hart::AudioBuffer<SampleType> outputBlock (m_numOutputChannels, blockSizeFrames, m_sampleRateHz);
            m_inputSignal->renderNextBlockWithDSPChain (inputBlock);
            m_processor->processWithEnvelopes (inputBlock, outputBlock);
 
            const bool allChecksPassed = processChecks (perBlockChecks, inputBlock, outputBlock, offsetFrames);
            atLeastOneCheckFailed |= ! allChecksPassed;
            fullInputBuffer.appendFrom (inputBlock);
            fullOutputBuffer.appendFrom (outputBlock);
 
            offsetFrames += blockSizeFrames;
        }
 
        if (testDurationFrames != 0 && ! fullSignalChecks.empty())
        {
            // Full audio buffers for full audio matchers
            // We want to skip the warm-up pieces for those
            AudioBuffer<SampleType> fullInputNoWarmUpBuffer (m_numInputChannels, testDurationFrames, m_sampleRateHz);
            AudioBuffer<SampleType> fullOutputNoWarmUpBuffer (m_numOutputChannels, testDurationFrames, m_sampleRateHz);
 
            for (size_t channel = 0; channel < m_numInputChannels; ++channel)
                fullInputNoWarmUpBuffer.copyFrom (channel, 0, fullInputBuffer, channel, warmUpDurationFrames, testDurationFrames);
 
            for (size_t channel = 0; channel < m_numOutputChannels; ++channel)
                fullOutputNoWarmUpBuffer.copyFrom (channel, 0, fullOutputBuffer, channel, warmUpDurationFrames, testDurationFrames);
 
            const bool allChecksPassed = processChecks (fullSignalChecks, fullInputNoWarmUpBuffer, fullOutputNoWarmUpBuffer, warmUpDurationFrames);
            atLeastOneCheckFailed |= ! allChecksPassed;
        }
 
        if (m_saveOutputMode == Save::always || (m_saveOutputMode == Save::whenFails && atLeastOneCheckFailed))
            WavWriter<SampleType>::writeBuffer (fullOutputBuffer, m_saveOutputPath, m_saveOutputWavFormat);
 
        if (m_savePlotMode == Save::always || (m_savePlotMode == Save::whenFails && atLeastOneCheckFailed))
            plotData (fullInputBuffer, fullOutputBuffer, m_savePlotPath);
 
        if (m_outputBufferSink != nullptr)
            m_outputBufferSink (std::move (fullOutputBuffer));
 
        if (m_inputSignalSink != nullptr)
            m_inputSignalSink (std::move (m_inputSignal));
 
        return std::move (m_processor);
    }
 
private:
    struct ParamValue
    {
        int id;
        double value;
    };
 
    enum class SignalAssertionLevel
    {
        expect,
        assert,
    };
 
    struct Check
    {
        std::unique_ptr<MatcherBase<SampleType>> matcher;
        SignalAssertionLevel signalAssertionLevel;
        bool shouldSkip;
        bool shouldPass;
    };
 
    std::unique_ptr<DSPBase<SampleType>> m_processor;
    std::unique_ptr<SignalBase<SampleType>> m_inputSignal;
    double m_sampleRateHz = CLIConfig::getInstance().getDefaultSampleRateHz();
    size_t m_blockSizeFrames = CLIConfig::getInstance().getGefaultBlockSizeFrames();
    size_t m_numInputChannels = CLIConfig::getInstance().getDefaultNumInputChannels();
    size_t m_numOutputChannels = CLIConfig::getInstance().getDefaultNumOutputChannels();
    std::vector<ParamValue> paramValues;
    double m_testDurationSeconds = CLIConfig::getInstance().getDefaultRenderDurationSeconds();
    double m_warmUpDurationSeconds = 0.0;
    size_t offsetFrames = 0;
    std::string m_testLabel = {};
 
    Preparation m_signalPreparationBeforeWarmUp = Preparation::resetAndPrepare;
    Preparation m_signalPreparationAfterWarmUp = Preparation::none;
    Preparation m_dspPreparationBeforeWarmUp = Preparation::resetAndPrepare;
    Preparation m_dspPreparationAfterWarmUp = Preparation::none;
 
    std::vector<Check> perBlockChecks;
    std::vector<Check> fullSignalChecks;
 
    std::string m_saveOutputPath;
    Save m_saveOutputMode = Save::never;
    WavFormat m_saveOutputWavFormat = WavFormat::pcm24;
 
    std::string m_savePlotPath;
    Save m_savePlotMode = Save::never;
 
    std::function<void (AudioBuffer<SampleType>&&)> m_outputBufferSink = nullptr;
    std::function<void (std::unique_ptr<SignalBase<SampleType>>&&)> m_inputSignalSink = nullptr;
 
    template<
        typename MatcherType,
        typename = typename std::enable_if<
            ! std::is_same<
                typename std::decay<MatcherType>::type,
                MatcherBase<SampleType>
                >::value
        >::type>
    void addCheck (MatcherType&& matcher, SignalAssertionLevel assertionLevel, bool shouldPass)
    {
        using Derived = typename std::decay<MatcherType>::type;
        static_assert (std::is_base_of<MatcherBase<SampleType>, Derived>::value, "matcher argument must derive from hart::Matcher");
 
        const bool forceFullSignal = !shouldPass;
        auto& group = (matcher.canOperatePerBlock() && !forceFullSignal)
            ? perBlockChecks
            : fullSignalChecks;
 
        // TODO: emplace_back()
        group.push_back ({
            std::forward<MatcherType>(matcher).move(),
            assertionLevel,
            false,
            shouldPass
        });
    }
 
    void addCheck (const MatcherBase<SampleType>& matcher, SignalAssertionLevel assertionLevel, bool shouldPass)
    {
        const bool forceFullSignal = ! shouldPass;
        auto& group = (matcher.canOperatePerBlock() && ! forceFullSignal)
            ? perBlockChecks
            : fullSignalChecks;
 
        // TODO: emplace_back()
        group.push_back({ matcher.copy(), assertionLevel, false, shouldPass });
    }
 
    bool prepareChecks (std::vector<Check>& checks)
    {
        for (auto& check : checks)
        {
            if (! check.matcher->supportsSampleRate (m_sampleRateHz))
                HART_THROW_OR_RETURN (hart::SampleRateError, "Matcher not support requested sample rate", false);
 
            if (! check.matcher->supportsChannelLayout (m_numInputChannels, m_numOutputChannels))
                HART_THROW_OR_RETURN (hart::ChannelLayoutError, "Matcher not support requested number of channels", false);
 
            check.matcher->prepareWithActiveChannels (m_sampleRateHz, m_numInputChannels, m_numOutputChannels, m_blockSizeFrames);
            check.shouldSkip = false;
        }
 
        return true;
    }
 
    bool processChecks (std::vector<Check>& checksGroup, const AudioBuffer<SampleType>& inputAudio, const AudioBuffer<SampleType>& outputAudio, size_t baseFrameOffset)
    {
        for (auto& check : checksGroup)
        {
            if (check.shouldSkip)
                continue;
 
            auto& assertionLevel = check.signalAssertionLevel;
            auto& matcher = check.matcher;
 
            const AnalysisContext<SampleType> analysisContext (inputAudio, outputAudio);
            const bool matchPassed = matcher->match (analysisContext);
 
            if (matchPassed != check.shouldPass)
            {
                check.shouldSkip = true;
 
                if (assertionLevel == SignalAssertionLevel::assert)
                {
                    std::stringstream stream;
                    stream << (check.shouldPass ? "assertTrue() failed" : "assertFalse() failed");
 
                    if (! m_testLabel.empty())
                        stream << " at \"" << m_testLabel << "\"";
 
                    stream << std::endl << "Condition: " << *matcher;
                    appendFailureDetails (stream, matcher->getFailureDetails(), inputAudio, outputAudio, baseFrameOffset);
 
                    throw hart::TestAssertException (std::string (stream.str()));
                }
                else
                {
                    std::stringstream stream;
                    stream << (check.shouldPass ? "expectTrue() failed" : "expectFalse() failed");
 
                    if (!m_testLabel.empty())
                        stream << " at \"" << m_testLabel << "\"";
 
                    stream << std::endl << "Condition: " << * matcher;
                    appendFailureDetails (stream, matcher->getFailureDetails(), inputAudio, outputAudio, baseFrameOffset);
 
                    hart::ExpectationFailureMessages::get().emplace_back (stream.str());
                }
 
                // TODO: FIXME: Do not throw inside of per-block loop if requested to write input or output to a wav file, throw after the loop instead
                // TODO: Stop processing if expect has failed and outputting to a file wasn't requested
                // TODO: Skip all checks if check failed, but asked to output a wav file
                return false;
            }
        }
 
        return true;
    }
 
    void appendFailureDetails (std::stringstream& stream, const MatcherFailureDetails& details, const AudioBuffer<SampleType>& inputAudio, const AudioBuffer<SampleType>& observedOutputAudio, size_t baseFrameOffset)
    {
        const size_t frameOverall = baseFrameOffset + details.frame;
        const double timestampOverall = static_cast<double> (frameOverall) / m_sampleRateHz;
        const size_t warmUpDurationFrames = (size_t) std::round (m_sampleRateHz * m_warmUpDurationSeconds);
        const SampleType inputSampleValue = inputAudio[details.channel][details.frame];
        const SampleType outputSampleValue = observedOutputAudio[details.channel][details.frame];
 
        stream << std::endl
            << "Input signal: " << *m_inputSignal << std::endl
            << "Channel: " << details.channel << std::endl;
 
        if (warmUpDurationFrames == 0)
        {
            stream
                << "Frame: " << frameOverall << std::endl
                << secPrecision << "Timestamp: " << timestampOverall << " seconds";
        }
        else
        {
            const size_t framePostWarmUp = frameOverall - warmUpDurationFrames;
            const double timestampPostWarmUp = static_cast<double> (framePostWarmUp) / m_sampleRateHz;
            stream
                << "Frame (overall): " << frameOverall << std::endl
                << "Frame (post warm-up): " << framePostWarmUp << std::endl
                << secPrecision
                << "Timestamp (overall): " << timestampOverall << " seconds" << std::endl
                << "Timestamp (post warm-up): " << timestampPostWarmUp << " seconds";
        }
 
        stream << std::endl
            << linPrecision << "Input sample value: " << inputSampleValue
            << dbPrecision << " (" << ratioToDecibels (std::abs (inputSampleValue)) << " dB)" << std::endl
            << linPrecision << "Output sample value: " << outputSampleValue
            << dbPrecision << " (" << ratioToDecibels (std::abs (outputSampleValue)) << " dB)" << std::endl
            << details.description;
    }
};
 
/// @brief Call this to start building your test using a DSP object
/// @param dsp Instance of your DSP effect
/// @return @ref AudioTestBuilder instance - you can chain a bunch of test parameters with it.
/// @ingroup TestRunner
template <typename DSPType>
AudioTestBuilder<typename std::decay<DSPType>::type::SampleTypePublicAlias> processAudioWith (DSPType&& dsp)
{
    return AudioTestBuilder<typename std::decay<DSPType>::type::SampleTypePublicAlias> (std::forward<DSPType>(dsp));
}
 
/// @brief Call this to start building your test using a smart pointer to a DSP object
/// @details Call this for DSP objects that do not support moving or copying
/// @param dsp Instance of your DSP effect wrapped in a smart pointer
/// @return @ref AudioTestBuilder instance - you can chain a bunch of test parameters with it.
/// @ingroup TestRunner
template <typename DSPType>
AudioTestBuilder<typename DSPType::SampleTypePublicAlias> processAudioWith (std::unique_ptr<DSPType>&& dsp)
{
    using SampleType = typename DSPType::SampleTypePublicAlias;
    return AudioTestBuilder<SampleType> (std::unique_ptr<DSPBase<SampleType>> (dsp.release()));
}
 
namespace aliases_float
{
/// @brief Call this to start building your test using a sample-wise function
/// @details
/// This overload allows defining a DSP processor using a function or lambda
/// that operates on individual samples.
///
/// @par Function signature
/// @code
/// float (float value)
/// @endcode
///
/// The function is applied independently to each sample.
///
/// For more details, see `DSPFunction` documentation, as it merely forwards
/// the arguments to its constructor.
///
/// @note
/// If your DSP requires access to sample rate or channel context,
/// consider using one of the block-wise overloads instead.
///
/// @param dspFunction Function to process each sample.
/// @param label Optional human-readable label for error reporting.
/// @return @ref AudioTestBuilder instance - you can chain a bunch of test parameters with it.
/// @ingroup TestRunner
inline AudioTestBuilder<float> processAudioWith (std::function<float (float)> dspFunction, const std::string& label = {})
{
    return AudioTestBuilder<float> (hart::make_unique<hart::DSPFunction<float>> (std::move (dspFunction), label));
}
 
/// @brief Call this to start building your test using a block-wise in-place function
/// @details
/// The provided function processes audio in-place. The buffer is pre-filled
/// with input data and must be modified directly.
///
/// @par Function signature
/// @code
/// void (AudioBuffer<float>& buffer)
/// @endcode
///
/// @par Buffer invariants
/// The function must not change:
/// - Number of channels
/// - Number of frames
/// - Sample rate
///
/// For more details, see `DSPFunction` documentation, as it merely forwards
/// the arguments to its constructor.
///
/// @param dspFunction Function that processes the buffer in-place.
/// @param label Optional human-readable label for error reporting.
/// @return @ref AudioTestBuilder instance - you can chain a bunch of test parameters with it.
/// @ingroup TestRunner
inline AudioTestBuilder<float> processAudioWith (std::function<void (AudioBuffer<float>&)> dspFunction, const std::string& label = {})
{
    return AudioTestBuilder<float> (hart::make_unique<hart::DSPFunction<float>> (std::move (dspFunction), label));
}
 
/// @brief Call this to start building your test using a block-wise non-replacing function
/// @details This overload provides separate input and output buffers for processing.
///
/// @par Function signature
/// @code
/// void (const AudioBuffer<float>& input,
///       AudioBuffer<float>& output)
/// @endcode
///
/// @par Buffer invariants
/// The function must not change:
/// - Number of channels
/// - Number of frames
/// - Sample rate
///
/// For more details, see `DSPFunction` documentation, as it merely forwards
/// the arguments to its constructor.
///
/// @param dspFunction Function that generates output from input.
/// @param label Optional human-readable label for error reporting.
/// @return @ref AudioTestBuilder instance - you can chain a bunch of test parameters with it.
/// @ingroup TestRunner
inline AudioTestBuilder<float> processAudioWith (std::function<void (const AudioBuffer<float>&, AudioBuffer<float>&)> dspFunction, const std::string& label = {})
{
    return AudioTestBuilder<float> (hart::make_unique<hart::DSPFunction<float>> (std::move (dspFunction), label));
}
 
using hart::processAudioWith;
 
}  // namespace aliases_float
 
namespace aliases_double
{
 
/// @brief See the description of the `float` version of this function
/// @ingroup TestRunner
inline AudioTestBuilder<double> processAudioWith (std::function<double (double)> dspFunction, const std::string& label = {})
{
    return AudioTestBuilder<double> (hart::make_unique<hart::DSPFunction<double>> (std::move (dspFunction), label));
}
 
/// @brief See the description of the `float` version of this function
/// @ingroup TestRunner
inline AudioTestBuilder<double> processAudioWith (std::function<void (AudioBuffer<double>&)> dspFunction, const std::string& label = {})
{
    return AudioTestBuilder<double> (hart::make_unique<hart::DSPFunction<double>> (std::move (dspFunction), label));
}
 
/// @brief See the description of the `float` version of this function
/// @ingroup TestRunner
inline AudioTestBuilder<double> processAudioWith (std::function<void (const AudioBuffer<double>&, AudioBuffer<double>&)> dspFunction, const std::string& label = {})
{
    return AudioTestBuilder<double> (hart::make_unique<hart::DSPFunction<double>> (std::move (dspFunction), label));
}
 
using hart::processAudioWith;
 
}  // namespace aliases_double
 
}  // namespace hart