hart_matcher.hpp

Go to the documentation of this file.

#pragma once
 
#include <memory>
#include <string>
 
#include "hart_audio_buffer.hpp"
#include "hart_matcher_failure_details.hpp"
#include "hart_utils.hpp"                  // make_unique()
 
/// @defgroup Matchers Matchers
/// @brief Check audio
 
namespace hart
{
 
/// @brief Base for audio matchers
/// @details Those matchers get a piece of audio generated by some DSP effect and asked if if satisfies their condition or not
/// @tparam SampleType Type of data in the buffers to be checked, typically ```float``` or ```double```.
/// @ingroup Matchers
template<typename SampleType>
class Matcher
{
public:
    /// @brief Prepare for processing
    /// It is guaranteed that all subsequent process() calls will be in line with the arguments received in this callback.
    /// This callback is guaranteed to be called after canOperatePerBlock()
    /// If any of the values supplied by this callback are not supported by the matcher, it is expected to act as if
    /// the match has failed when match() gets called.
    /// @param sampleRateHz sample rate at which the audio should be interpreted
    /// @param numChannels Number of audio channels
    /// @param maxBlockSizeFrames Maximum block size in frames (samples)
    virtual void prepare (double sampleRateHz, size_t numChannels, size_t maxBlockSizeFrames) = 0;
 
    /// @brief Tells the host if the piece of audio satisfies Matcher's condition or not
    /// @details It is guaranteed to be called only after prepare(), or not be called at all.
    /// It is guaranteed to be handed an AudioBuffer in line with values set by the last prepare() call.
    /// If canOperatePerBlock() has returned \c false, this callback is guaranteed to be handed a full piece of
    /// audio to check. Otherwise, it may still get a full piece of audio, or get data on a block-by-block basis.
    /// @param observedAudio A piece of audio to check
    /// @returns true if the audio satisfies the Matcher's condition, false otherwise
    virtual bool match (const AudioBuffer<SampleType>& observedAudio) = 0;
 
    /// @brief Tells the host is if can operate on a block-by-block basis
    /// @details Some types of conditions absolutely require having a full piece of audio
    /// to produce an appropriate responce. For example, @ref PeaksAt matcher.
    /// Those types of matchers will return false on this callback.
    /// Matcher is guaranteed to receive a full piece of audio if this callback has
    /// returned \c false. Otherwise, it may receive audio either block-by-block
    /// basis, or still get a full piece of audio, if the host decides to do so.
    virtual bool canOperatePerBlock() = 0;
 
    /// Resets the matcher to its initial state
    virtual void reset() = 0;
 
    /// @brief Returns a smart pointer with a copy of this object
    /// @details Just put one of those two macros into your class body, and your @ref copy() and @ref move() are sorted:
    ///  - @ref HART_MATCHER_DEFINE_COPY_AND_MOVE() for movable and copyable classes
    ///  - @ref HART_MATCHER_FORBID_COPY_AND_MOVE for non-movable and non-copyable classes
    ///
    /// Read their description, and choose one that fits your class.
    /// You can, of course, make your own implementation, but you're not supposed to, unless you're doing something obscure.
    virtual std::unique_ptr<Matcher<SampleType>> copy() const = 0;
 
    /// @brief Returns a smart pointer with a moved instance of this object
    /// @details Just pick a macro to define it - see description for @ref copy() for details
    virtual std::unique_ptr<Matcher<SampleType>> move() = 0;
 
    /// @brief Returns a description of why the match has failed
    /// @details It is guaranteed to be called strictly after calling match(), or not called at all
    /// @note This method is a callback for the test host, so you probably don't need to call it
    /// yourself ever. If you're making a custom matcher, use it to communicate the data with test host.
    /// @retval MatcherFailureDetails::frame Index of frame at which the match has failed
    /// @retval MatcherFailureDetails::channel Index of channel at which the failure was detected
    /// @retval MatcherFailureDetails::description Readable description of why the match has failed.
    /// Do not include the value of observed frame value or its timing in the description, as well as
    /// any of values printed by represent(), as all of this will be added to the output anyway.
    /// Also, query @ref CLIConfig for number of displayed decimal places, whenever applicable.
    /// @see MatcherFailureDetails
    virtual MatcherFailureDetails getFailureDetails() const = 0;
 
    /// @brief Makes a text representation of this Macther for test failure outputs.
    /// @details It is strongly encouraged to follow python's
    /// <a href="https://docs.python.org/3/reference/datamodel.html#object.__repr__" target="_blank">repr()</a>
    /// conventions for returned text - basically, put something like "MyClass(value1, value2)" (with no quotes)
    /// into the stream whenever possible, or "<Readable info in angled brackets>" otherwise.
    /// Also, use built-in stream manipulators like @ref dbPrecision wherever applicable.
    /// Use @ref HART_DEFINE_GENERIC_REPRESENT() to get a basic implementation for this method.
    /// @param[out] stream Output stream to write to
    virtual void represent (std::ostream& stream) const = 0;
 
    /// @brief Destructor
    virtual ~Matcher() = default;
};
 
/// @brief Prints readable text representation of the Matcher object into the I/O stream
/// @relates Matcher
/// @ingroup Matchers
template <typename SampleType>
inline std::ostream& operator<< (std::ostream& stream, const Matcher<SampleType>& dsp)
{
    dsp.represent (stream);
    return stream;
}
 
/// @brief Defines @ref hart::Matcher::copy() and @ref hart::Matcher::move() methods
/// @details Put this into your class body's ```public``` section if either is true:
///  - Your class is trivially copyable and movable
///  - You have your Rule Of Five methods explicitly defined in this class
/// (see <a href="https://en.cppreference.com/w/cpp/language/rule_of_three.html" target="_blank">Rule Of Three/Five/Zero</a>)
///
/// If neither of those is true, or you're unsure, use @ref HART_MATCHER_FORBID_COPY_AND_MOVE instead
///
/// Despite returning a smart pointer to an abstract Matcher class, those two methods must construct
/// an object of a specific class, hence the mandatory boilerplate methods - sorry!
/// @param ClassName Name of your class
/// @ingroup Matchers
#define HART_MATCHER_DEFINE_COPY_AND_MOVE(ClassName)
    std::unique_ptr<Matcher<SampleType>> copy() const override {
        return hart::make_unique<ClassName> (*this);
    }
    std::unique_ptr<Matcher<SampleType>> move() override {
        return hart::make_unique<ClassName> (std::move (*this));
    }
 
/// @brief Forbids @ref hart::Matcher::copy() and @ref hart::Matcher::move() methods
/// @details Put this into your class body's ```public``` section if either is true:
///  - Your class is not trivially copyable and movable
///  - You don't want to trouble yourself with implementing move and copy semantics for your class
///
/// Otherwise, use @ref HART_MATCHER_DEFINE_COPY_AND_MOVE() instead.
/// Obviously, you won't be able to pass your class to the host
/// by reference, copy or explicit move, but you still can pass
/// it wrapped into a smart pointer like so:
/// ```cpp
/// processAudioWith (hart::make_unique<MyDspType>()).withThis().withThat().process();
/// ```
/// But it's still better to get your move and copy semantics figured out - this is a
/// perfect chance to stress-test your effect's resource management, among other things!
/// @ingroup Matchers
#define HART_MATCHER_FORBID_COPY_AND_MOVE
    std::unique_ptr<Matcher<SampleType>> copy() const override {
        static_assert (false, "This Matcher cannot be copied");
        return nullptr;
    }
    std::unique_ptr<Matcher<SampleType>> move() override {
        static_assert (false, "This Matcher cannot be moved");
        return nullptr;
    }
 
 
}  // namespace hart
 
/// @private
#define HART_MATCHER_DECLARE_ALIASES_FOR(ClassName)
    namespace aliases_float{
        using ClassName = hart::ClassName<float>;
    }
    namespace aliases_double{
        using ClassName = hart::ClassName<double>;
    }