types.h

#pragma once
 
#include <nlohmann/json.hpp>
 
#include <array>
#include <cstdint>
#include <numbers>
#include <optional>
#include <tuple>
#include <variant>
#include <vector>
 
namespace sfFDN
{
 
// helper type for the visitor #4
template <class... Ts>
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 interpolation.
    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
};
 
// STRUCTS
 
struct ScalarFeedbackMatrixOptions
{
    uint32_t matrix_size;
 
    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; 
    uint32_t stage_count; 
    float sparsity{1.f};  
    ScalarMatrixType type{
        ScalarMatrixType::Random}; 
    float gain_per_samples{1.f};   
};
 
struct ModulationOptions
{
    float frequency{0.f};     /*< Frequency of the modulation, normalized to [0, 1] by the sampling rate. */
    float amplitude{0.f};     /*< Amplitude of the modulation. */
    float initial_phase{0.f}; /*< Initial phase of the modulation, normalized to [0, 1]. */
};
 
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;        /*< 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;          /*< 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 / a0, b1 / a0, b2 / a0, 1.0f, a1 / a0, 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 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 HomogenousFilterOptions
{
    float t60 = 1.f; /*< Target T60 value for the filter. */
    float delay;     /*< 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; /*< 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; /*< 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;
 
    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>;
 
using single_channel_processor_variant_t =
    std::variant<SchroederAllpassSectionOptions, AllpassFilterOptions, CascadedBiquadsOptions, FirOptions, DelayOptions,
                 GraphicEQOptions>;
 
using multi_channel_processor_variant_t =
    std::variant<ParallelGainsOptions, MultichannelSchroederAllpassSectionOptions, AttenuationFilterBankOptions,
                 DelayBankOptions, DelayBankTimeVaryingOptions, CascadedFeedbackMatrixOptions,
                 ScalarFeedbackMatrixOptions>;
 
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"}});
 
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(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(SchroederAllpassSectionOptions, delays, gains, parallel);
NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(MultichannelSchroederAllpassSectionOptions, sections);
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