types.h

#pragma once
 
#include <nlohmann/json.hpp>
 
#include <array>
#include <cstdint>
#include <numbers>
#include <optional>
#include <variant>
#include <vector>
 
namespace sfFDN
{
 
// helper type for the visitor #4
// The overload-set idiom inherits from a pack of lambdas so that std::visit can dispatch on it. The multiple
// inheritance is the whole point, so misc-multiple-inheritance does not apply.
template <class... Ts>
// NOLINTNEXTLINE(misc-multiple-inheritance)
struct overloaded : Ts...
{
    using Ts::operator()...;
};
// explicit deduction guide (not needed as of C++20)
template <class... Ts>
overloaded(Ts...) -> overloaded<Ts...>;
 
constexpr uint32_t kDefaultSampleRate = 48000;
constexpr uint32_t kDefaultBlockSize = 128;
 
// ENUMS
 
enum class ScalarMatrixType : uint8_t
{
    Identity = 0,          
    Random = 1,            
    Householder = 2,       
    RandomHouseholder = 3, 
    Hadamard = 4,          
    Circulant = 5,         
    Allpass = 6,           
    NestedAllpass = 7,     
    VariableDiffusion = 8, 
    Count = 9
};
 
enum class DelayInterpolationType : uint8_t
{
    None = 0,
 
    Linear = 1,
 
    Allpass = 2,
 
    Lagrange = 3,
    Count = 4,
};
 
enum class DelayLengthType : uint8_t
{
    Random = 0,
 
    Gaussian = 1,
 
    Primes = 2,
 
    Uniform = 3,
 
    PrimePower = 4,
 
    SteamAudio = 5,
 
    Count = 6,
};
 
enum class ParallelGainsMode : uint8_t
{
    Split,
 
    Merge,
 
    Parallel
};
 
enum class TimeVaryingMatrixMode : uint8_t
{
    Hadamard = 0,  
    RealSchur = 1, 
    Count = 2      
};
 
// STRUCTS
 
struct ScalarFeedbackMatrixOptions
{
    uint32_t matrix_size{0};
 
    ScalarMatrixType type{ScalarMatrixType::Random};
 
    std::optional<std::vector<float>> custom_matrix{std::nullopt};
 
    uint32_t rng_seed{0};
 
    // the diffusion parameter.
    std::optional<float> arg{std::nullopt};
};
 
struct CascadedFeedbackMatrixOptions
{
    uint32_t matrix_size{0}; 
    uint32_t stage_count{0}; 
    float sparsity{1.f};     
    ScalarMatrixType type{
        ScalarMatrixType::Random}; 
    float gain_per_samples{1.f};   
};
 
struct ModulationOptions
{
    float frequency{0.f}; 
    float amplitude{0.f}; 
    float initial_phase{0.f}; 
};
 
struct TimeVaryingFeedbackMatrixOptions
{
    uint32_t matrix_size{0}; 
    TimeVaryingMatrixMode mode{TimeVaryingMatrixMode::Hadamard}; 
    std::vector<ModulationOptions>
        time_varying_config; 
    uint32_t rng_seed{0};    
};
 
struct ParallelGainsOptions
{
    ParallelGainsMode mode{ParallelGainsMode::Split}; 
    std::vector<float>
        gains; 
    std::vector<ModulationOptions>
        time_varying_config; 
};
 
struct DelayOptions
{
    float delay{256.f};      /*< Delay in samples. This can be a fractional value if interpolation is used. */
    uint32_t max_delay{512}; /*< Maximum delay in samples. This is used to determine the size of the delay buffer and
                             must be greater than or equal to `delay`. */
    sfFDN::DelayInterpolationType interp_type{
        sfFDN::DelayInterpolationType::None}; /*< Interpolation type for fractional delays. */
    std::optional<sfFDN::ModulationOptions> lfo_config{
        std::nullopt}; /*< Optional LFO configuration for time-varying delay modulation. If provided, the delay will be
                          modulated according to the specified parameters. */
};
 
struct DelayBankOptions
{
    std::vector<float>
        delays; /*< Delay values for each channel in samples. These can be fractional values if interpolation is used.
              The size of the vector determines the number of channels in the delay bank. */
    uint32_t block_size{kDefaultBlockSize}; /*< Block size for processing audio. This is used to determine the size of
                                               internal buffers and can affect performance. */
    DelayInterpolationType interpolation_type{
        DelayInterpolationType::None}; /*< Interpolation type for fractional delays. */
};
 
struct DelayBankTimeVaryingOptions
{
    std::vector<float> delays; /*< Initial delay values for each channel in samples. These can be fractional values if
              interpolation is used. The size of the vector determines the number of channels in the delay bank. */
    uint32_t max_delay{0};     /*< Maximum delay in samples. This is used to determine the size of the delay buffer and
                                    must be greater than or equal to the initial delays. */
    DelayInterpolationType interpolation_type{
        DelayInterpolationType::None};                  /*< Interpolation type for fractional delays. */
    std::vector<ModulationOptions> time_varying_config; /*< Time-varying modulation configuration for each channel. The
                                                           size of the vector must match the size of `delays`. */
};
 
struct FilterCoefficients
{
    float b0;
 
    float b1;
 
    float b2;
 
    float a0;
 
    float a1;
 
    float a2;
 
    FilterCoefficients Normalize() const
    {
        return {.b0 = b0 / a0, .b1 = b1 / a0, .b2 = b2 / a0, .a0 = 1.0f, .a1 = a1 / a0, .a2 = a2 / a0};
    }
};
 
struct AllpassFilterOptions
{
    float coeff{0.f};
};
 
struct SparseFirOptions
{
    std::vector<std::pair<uint32_t, float>> coeffs; // pair of (index, coefficient)
};
 
struct CascadedBiquadsOptions
{
    std::vector<FilterCoefficients> coeffs;
};
 
struct FirOptions
{
    std::vector<float> coeffs{1.f};
};
 
struct MultichannelFirOptions
{
    std::vector<std::vector<float>> coeffs;
};
 
struct SchroederAllpassSectionOptions
{
    std::vector<float> delays; /*< Initial delay values for each Schroeder allpass in samples. */
    std::vector<float> gains;  /*< Feedback gain values for each Schroeder allpass. The size of this vector must match
                                  the size of `delays`. */
    bool parallel{false}; /*< If true, the allpass filters in the section are connected in parallel. If false, they are
                             connected in series. */
};
 
struct MultichannelSchroederAllpassSectionOptions
{
    std::vector<SchroederAllpassSectionOptions> sections;
};
 
struct TimeVaryingSchroederAllpassSectionOptions
{
    std::vector<float> delays; 
    std::vector<float> gains;  
    std::vector<ModulationOptions>
        time_varying_config; 
    bool parallel{false};    
};
 
struct MultichannelTimeVaryingSchroederAllpassSectionOptions
{
    std::vector<TimeVaryingSchroederAllpassSectionOptions> sections;
};
 
enum class DattorroEffectType : uint8_t
{
    Vibrato,     
    Flanger,     
    WhiteChorus, 
    Doubling,    
    Echo,        
};
 
struct DattorroDelayOptions
{
    DelayOptions delay_config{
        .delay = 256.f, .max_delay = 512, .interp_type = DelayInterpolationType::Allpass, .lfo_config = std::nullopt};
    float blend{0.7071f};    /*< Gain applied to the input of the delay line. */
    float feedforward{1.f};  /*< Gain applied to the modulated output of the delay line. */
    float feedback{0.7071f}; /*< Gain applied to the fixed output of the delay line before it is fed back into the
                                delay line. The feedback is subtracted at the summing junction, so a positive value
                                recirculates with inverted polarity. Must be in the range (-1, 1) to be stable. */
};
 
struct MultichannelDattorroDelayOptions
{
    std::vector<DattorroDelayOptions> delays;
};
 
struct ControllableFullWaveRectifierOptions
{
    float alpha{1.f};
    bool antialiasing{true};
    bool dc_block{true};
    float sample_rate{static_cast<float>(kDefaultSampleRate)};
};
 
struct MultichannelControllableFullWaveRectifierOptions
{
    std::vector<std::optional<ControllableFullWaveRectifierOptions>> channels;
};
 
struct SignalDependentFractionalDelayOptions
{
    float d{1.f};
};
 
struct MultichannelSignalDependentFractionalDelayOptions
{
    std::vector<std::optional<SignalDependentFractionalDelayOptions>> channels;
};
 
struct RingModulatorOptions
{
    float frequency{0.f};
    float amplitude{std::numbers::sqrt2_v<float>};
    float initial_phase{0.f};
};
 
struct MultichannelRingModulatorOptions
{
    std::vector<std::optional<RingModulatorOptions>> channels;
};
 
struct HomogenousFilterOptions
{
    float t60 = 1.f;  /*< Target T60 value for the filter. */
    float delay{1.f}; /*< Delay in samples for the delay line preceding the filter. If set to <= 0, it will be updated
                    automatically when accessed from `CreateFDNFromConfig()`*/
    float sample_rate = kDefaultSampleRate; /*< Sample rate in Hz. This is used to calculate the filter coefficients
                                               based on the specified T60 values. */
};
 
struct TwoBandFilterOptions
{
    std::array<float, 2> t60s{1.f, 0.5f}; 
    float delay{0.f}; /*< Delay in samples for the delay line preceding the filter. If set to <= 0, it will be updated
                    automatically when accessed from `CreateFDNFromConfig()`*/
    float sample_rate = kDefaultSampleRate; /*< Sample rate in Hz. This is used to calculate the filter coefficients
                                               based on the specified T60 values. */
};
 
struct ThreeBandFilterOptions
{
    std::array<float, 3> t60s{1.f, 0.5f, 0.25f}; /*< Target T60 values for the low, mid and high bands. */
    float delay{0.f}; /*< Delay in samples for the delay line preceding the filter. If set to <= 0, it will be updated
                    automatically when accessed from `CreateFDNFromConfig()`*/
    std::array<float, 2> freqs{800.f, 8000.f};    /*< Frequency values for the low and high shelves. */
    float q = 1.f / std::numbers::sqrt2_v<float>; /*< Q-factor for the shelf filters. Q values higher than 0.707 may
                                                     cause instability if placed in a feedback loop. */
    float sample_rate = kDefaultSampleRate; /*< Sample rate in Hz. This is used to calculate the filter coefficients
                                               based on the specified T60 values. */
};
 
struct TenBandFilterOptions
{
    std::array<float, 10> t60s = {1.f, 0.9f, 0.8f, 0.7f, 0.6f, 0.5f, 0.4f, 0.3f, 0.2f, 0.1f};
 
    float delay{0.f};
 
    float sample_rate = kDefaultSampleRate;
 
    float shelf_cutoff = 8000.f;
};
 
using attenuation_filter_variant_t =
    std::variant<HomogenousFilterOptions, TwoBandFilterOptions, ThreeBandFilterOptions, TenBandFilterOptions>;
 
struct AttenuationFilterBankOptions
{
    std::vector<attenuation_filter_variant_t> filter_configs;
};
 
struct GraphicEQOptions
{
    std::array<float, 10> gains_db{};
 
    std::array<float, 10> freqs{};
 
    float sample_rate = kDefaultSampleRate;
};
 
using feedback_matrix_variant_t =
    std::variant<CascadedFeedbackMatrixOptions, ScalarFeedbackMatrixOptions, TimeVaryingFeedbackMatrixOptions>;
 
using single_channel_processor_variant_t =
    std::variant<SchroederAllpassSectionOptions, TimeVaryingSchroederAllpassSectionOptions, AllpassFilterOptions,
                 CascadedBiquadsOptions, FirOptions, DelayOptions, GraphicEQOptions, DattorroDelayOptions,
                 ControllableFullWaveRectifierOptions, SignalDependentFractionalDelayOptions, RingModulatorOptions>;
 
using multi_channel_processor_variant_t =
    std::variant<ParallelGainsOptions, MultichannelSchroederAllpassSectionOptions,
                 MultichannelTimeVaryingSchroederAllpassSectionOptions, MultichannelDattorroDelayOptions,
                 AttenuationFilterBankOptions, DelayBankOptions, DelayBankTimeVaryingOptions,
                 CascadedFeedbackMatrixOptions, ScalarFeedbackMatrixOptions, MultichannelFirOptions,
                 MultichannelControllableFullWaveRectifierOptions, MultichannelSignalDependentFractionalDelayOptions,
                 MultichannelRingModulatorOptions>;
 
NLOHMANN_JSON_SERIALIZE_ENUM(ScalarMatrixType, {{ScalarMatrixType::Identity, "Identity"},
                                                {ScalarMatrixType::Random, "Random"},
                                                {ScalarMatrixType::Householder, "Householder"},
                                                {ScalarMatrixType::RandomHouseholder, "RandomHouseholder"},
                                                {ScalarMatrixType::Hadamard, "Hadamard"},
                                                {ScalarMatrixType::Circulant, "Circulant"},
                                                {ScalarMatrixType::Allpass, "Allpass"},
                                                {ScalarMatrixType::NestedAllpass, "NestedAllpass"},
                                                {ScalarMatrixType::VariableDiffusion, "VariableDiffusion"},
                                                {ScalarMatrixType::Count, "Count"}});
 
NLOHMANN_JSON_SERIALIZE_ENUM(DelayInterpolationType, {{DelayInterpolationType::None, "None"},
                                                      {DelayInterpolationType::Linear, "Linear"},
                                                      {DelayInterpolationType::Allpass, "Allpass"},
                                                      {DelayInterpolationType::Lagrange, "Lagrange"}});
 
NLOHMANN_JSON_SERIALIZE_ENUM(DelayLengthType, {{DelayLengthType::Random, "Random"},
                                               {DelayLengthType::Gaussian, "Gaussian"},
                                               {DelayLengthType::Primes, "Primes"},
                                               {DelayLengthType::Uniform, "Uniform"},
                                               {DelayLengthType::PrimePower, "PrimePower"},
                                               {DelayLengthType::SteamAudio, "SteamAudio"}});
 
NLOHMANN_JSON_SERIALIZE_ENUM(ParallelGainsMode, {{ParallelGainsMode::Split, "Split"},
                                                 {ParallelGainsMode::Merge, "Merge"},
                                                 {ParallelGainsMode::Parallel, "Parallel"}});
 
NLOHMANN_JSON_SERIALIZE_ENUM(TimeVaryingMatrixMode, {{TimeVaryingMatrixMode::Hadamard, "Hadamard"},
                                                     {TimeVaryingMatrixMode::RealSchur, "RealSchur"},
                                                     {TimeVaryingMatrixMode::Count, "Count"}});
 
void to_json(nlohmann::json& j, const ScalarFeedbackMatrixOptions& config);
void from_json(const nlohmann::json& j, ScalarFeedbackMatrixOptions& config);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(CascadedFeedbackMatrixOptions, matrix_size, stage_count, sparsity, type,
                                   gain_per_samples);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(ModulationOptions, frequency, amplitude, initial_phase);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(TimeVaryingFeedbackMatrixOptions, matrix_size, mode, time_varying_config, rng_seed);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(ParallelGainsOptions, mode, gains, time_varying_config);
void to_json(nlohmann::json& j, const DelayOptions& config);
void from_json(const nlohmann::json& j, DelayOptions& config);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(DelayBankOptions, delays, block_size, interpolation_type);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(DelayBankTimeVaryingOptions, delays, max_delay, interpolation_type,
                                   time_varying_config);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(FilterCoefficients, b0, b1, b2, a0, a1, a2);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(AllpassFilterOptions, coeff);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(SparseFirOptions, coeffs);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(CascadedBiquadsOptions, coeffs);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(FirOptions, coeffs);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(MultichannelFirOptions, coeffs);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(SchroederAllpassSectionOptions, delays, gains, parallel);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(TimeVaryingSchroederAllpassSectionOptions, delays, gains, time_varying_config,
                                   parallel);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(DattorroDelayOptions, delay_config, blend, feedforward, feedback);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(MultichannelSchroederAllpassSectionOptions, sections);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(MultichannelTimeVaryingSchroederAllpassSectionOptions, sections);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(MultichannelDattorroDelayOptions, delays);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(ControllableFullWaveRectifierOptions, alpha, antialiasing, dc_block, sample_rate);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(SignalDependentFractionalDelayOptions, d);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(RingModulatorOptions, frequency, amplitude, initial_phase);
// The multichannel banks hold `std::optional` entries, which nlohmann does not serialize on its own. A null entry
// means the channel is left unprocessed.
void to_json(nlohmann::json& j, const MultichannelControllableFullWaveRectifierOptions& config);
void from_json(const nlohmann::json& j, MultichannelControllableFullWaveRectifierOptions& config);
void to_json(nlohmann::json& j, const MultichannelSignalDependentFractionalDelayOptions& config);
void from_json(const nlohmann::json& j, MultichannelSignalDependentFractionalDelayOptions& config);
void to_json(nlohmann::json& j, const MultichannelRingModulatorOptions& config);
void from_json(const nlohmann::json& j, MultichannelRingModulatorOptions& config);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(HomogenousFilterOptions, t60, delay, sample_rate);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(TwoBandFilterOptions, t60s, delay, sample_rate);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(ThreeBandFilterOptions, t60s, delay, freqs, q, sample_rate);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(TenBandFilterOptions, t60s, delay, sample_rate, shelf_cutoff);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(GraphicEQOptions, gains_db, freqs, sample_rate);
 
void to_json(nlohmann::json& j, const AttenuationFilterBankOptions& config);
void from_json(const nlohmann::json& j, AttenuationFilterBankOptions& config);
 
} // namespace sfFDN