modal_extraction.hpp

Go to the documentation of this file.

#pragma once

 
#include <cstddef>
#include <span>
#include <string>
#include <vector>
 
#include <pulp/signal/modal_spec.hpp>
 
namespace pulp::test::audio {
 
// ── Modes ─────────────────────────────────────────────────────────────────

struct MeasuredMode {
    double freq_hz = 0.0;   
    double t60_s = 0.0;     
    double amplitude = 0.0; 
    double confidence = 0.0;
    double prominence_db = 0.0;
    int fit_points = 0;
    std::string note;
};

struct ModeAnalysisOptions {
    int fft_length = 32768;
    double search_low_hz = 20.0;
    double search_high_hz = 20000.0;
    double peak_floor_db = -60.0;
    double min_separation_hz = 8.0;
    int max_modes = 64;

    double refine_span_cents = 60.0;
    double refine_step_cents = 2.0;
    int refine_window = 8192;

    double fit_start_db = -3.0;
    double fit_end_db = -30.0;
    double fit_offset_s = 0.005;
    int envelope_window = 2048;
    int envelope_hop = 512;
    int min_fit_points = 4;
    int channel = 0;
};

struct ModeAnalysis {
    std::vector<MeasuredMode> modes;
    double sample_rate = 0.0;
    double bin_hz = 0.0;          
    double resolution_limit_hz = 0.0;
    int discovered_peaks = 0;     
    bool ok = false;              
    std::string message;          
};

ModeAnalysis analyze_modes(std::span<const float> ir, double sample_rate,
                           const ModeAnalysisOptions& options = {});

MeasuredMode measure_mode(std::span<const float> ir, double sample_rate,
                          double guess_hz,
                          const ModeAnalysisOptions& options = {});

std::string summarize(const ModeAnalysis& analysis);
std::string summarize(const MeasuredMode& mode);
 
// ── Partials and inharmonicity ────────────────────────────────────────────

struct MeasuredPartial {
    int index = 0;                 
    double freq_hz = 0.0;          
    double harmonic_hz = 0.0;      
    double deviation_cents = 0.0;  
    double amplitude = 0.0;        
    bool found = false;            
};

struct InharmonicityOptions {
    int num_partials = 12;
    double search_span_cents = 120.0;
    double partial_floor_db = -60.0;
    ModeAnalysisOptions mode_options{};
};

struct InharmonicityResult {
    double f0_hz = 0.0;               
    double b_coefficient = 0.0;       
    double rms_deviation_cents = 0.0; 
    double rms_harmonic_deviation_cents = 0.0;
    std::vector<MeasuredPartial> partials;
    int found_partials = 0;
    bool ok = false;
    std::string message;
};

InharmonicityResult measure_inharmonicity(std::span<const float> signal,
                                          double sample_rate, double f0_guess,
                                          const InharmonicityOptions& options = {});
 
std::string summarize(const InharmonicityResult& result);
 
// ── Time-resolved f0(t), sigma(t), Q(t) ───────────────────────────────────

struct CycleObservation {
    double time_s = 0.0;        
    double freq_hz = 0.0;       
    double envelope = 0.0;      
    double sigma_np_s = 0.0;    
    double q = 0.0;             
    bool sigma_valid = false;
    bool directional_only = false;
};

struct CycleTrackOptions {
    double onset_threshold = 1.0e-3;
    double start_offset_s = 0.021;
    double tail_floor_ratio = 3.0e-4;
    int sigma_half_window = 3;
    int min_cycles = 4;
};

struct CycleTrack {
    std::vector<CycleObservation> cycles;
    double onset_s = 0.0;
    double sample_rate = 0.0;
    double monocomponent_confidence = 0.0;
    bool ok = false;
    std::string message;

    double mean_f0(double from_s, double to_s) const;
    double mean_sigma(double from_s, double to_s) const;
    double mean_q(double from_s, double to_s) const;
    double sigma_span_percent(double from_s, double to_s) const;
    double f0_span_percent(double from_s, double to_s) const;
    double f0_q_correlation(double from_s, double to_s) const;
};

CycleTrack track_cycles(std::span<const float> signal, double sample_rate,
                        const CycleTrackOptions& options = {});

struct Ar2Observation {
    double time_s = 0.0;      
    double freq_hz = 0.0;     
    double sigma_np_s = 0.0;  
    double q = 0.0;           
    double residual_ratio = 0.0;
};

struct Ar2TrackOptions {
    double window_s = 0.080;
    double hop_s = 0.020;
    double onset_threshold = 1.0e-3;
    double start_offset_s = 0.021;
    double silence_threshold = 1.0e-7;
};

struct Ar2Track {
    std::vector<Ar2Observation> windows;
    bool ok = false;
    std::string message;
};
 
Ar2Track track_ar2(std::span<const float> signal, double sample_rate,
                   const Ar2TrackOptions& options = {});
 
std::string summarize(const CycleTrack& track);
std::string summarize(const Ar2Track& track);
 
// ── Primitives ────────────────────────────────────────────────────────────

double windowed_magnitude(std::span<const float> x, std::size_t start,
                          std::size_t length, double freq_hz,
                          double sample_rate);
 
// ── Shipped offline compiler ─────────────────────────────────────────────
 
enum class ModalExtractionError {
    none,
    empty_input,
    input_too_short,
    silent_input,
    non_finite_input,
    invalid_sample_rate,
    invalid_options,
    no_modes,
};
 
struct ModalExtractionOptions {
    ModeAnalysisOptions analysis{};
    int max_input_samples = 1 << 20;
    int max_modes = 64;
    double min_separation_cents = 25.0;
    double confidence_floor = 0.70;
    double snr_floor_db = -60.0;
    std::string recipe = "modal-extraction-v1";
};
 
struct ModalExtractionCandidate {
    pulp::signal::ModalMode mode{};
    double confidence = 0.0;
    double prominence_db = 0.0;
    double ranking_score = 0.0;
    bool merged = false;
    bool kept = false;
};
 
struct ModalExtractionResult {
    ModalExtractionError error = ModalExtractionError::none;
    bool ok = false;
    std::string message;
    std::string recipe;
    pulp::signal::ModalSpec spec;
    std::vector<ModalExtractionCandidate> candidates;
};

ModalExtractionResult compile_modal_spec(
    std::span<const float> impulse, double sample_rate,
    const ModalExtractionOptions& options = {});
 
} // namespace pulp::test::audio