visualization_bridge.hpp

Go to the documentation of this file.

#pragma once

 
#include <algorithm>
#include <array>
#include <atomic>
#include <cmath>
#include <cstdint>
#include <pulp/audio/planar_audio_ring_buffer.hpp>
#include <pulp/runtime/triple_buffer.hpp>
#include <pulp/signal/multi_channel_meter.hpp>
#include <pulp/signal/spectrogram.hpp>
#include <pulp/signal/stft.hpp>
#include <vector>
 
namespace pulp::dataplane {

struct VisualizationBenchSink {
    std::atomic<double>* audio_copy_total_us = nullptr;
    std::atomic<double>* triplebuffer_publish_total_us = nullptr;
};

struct SpectrumData {
    static constexpr int kMaxBins = 4097; // FFT 8192 → 4097 bins
 
    std::array<float, kMaxBins> magnitude_db{};
    int num_bins = 0;
    std::uint64_t epoch = 0;
    std::uint64_t sequence_number = 0;
    std::uint64_t dropped_frames = 0;
    int source_channels = 0;
    int fft_size = 0;
    float sample_rate = 0.0f;
    float floor_db = -120.0f;
};

struct WaveformData {
    static constexpr int kMaxSamples = 8192;
 
    std::array<float, kMaxSamples> samples{};
    int num_samples = 0;
    int num_channels = 0; // source layout; samples contain first channel only
    std::uint64_t epoch = 0;
    std::uint64_t sequence_number = 0;
    std::uint64_t dropped_frames = 0;
};

enum class VisualizationBacklogPolicy {
    in_order,
    latest_window,
};

struct VisualizationConfig {
    // STFT
    int fft_size = 1024;
    int hop_size = 256;
    signal::WindowFunction::Type window = signal::WindowFunction::Type::hann;
    float window_param = 0.0f;
 
    // Metering and capture layout. The captured channel count is invariant
    // until the bridge is quiescent and configured again. Blocks with another
    // layout are metered but intentionally not added to the analyzer stream.
    int num_channels = 2;
    float sample_rate = 44100.0f;
 
    // Waveform capture
    bool capture_waveform = true;
    int waveform_length = 1024; // samples to capture per snapshot
 
    // Audio frames retained between non-RT polls. Zero selects an automatic
    // capacity of at least four FFT windows and max_callback_frames. When the
    // consumer falls behind, new frames are dropped and the cumulative count
    // is stamped in snapshots.
    int capture_buffer_frames = 0;
 
    // Optional upper bound on frames analyzed by one poll. Zero consumes the
    // frame count visible at entry. A positive value supports predictable UI
    // pacing while leaving the remainder queued for the next tick.
    int max_frames_per_poll = 0;
 
    // dB value published for silence and used as the finite lower bound.
    float spectrum_floor_db = -120.0f;
 
    // Largest frame count the host can deliver in one audio callback. The
    // automatic capture capacity and any smaller explicit capacity are raised
    // to this bound so a valid callback can always be published atomically.
    // Set this to the host's offline/variable-block maximum before configure().
    int max_callback_frames = 4096;
 
    // Backlog handling for a consumer that polls slower than audio arrives.
    // A spectrum display that polls from its frame tick should usually select
    // latest_window; in_order preserves every hop for consumers that need
    // continuous analysis history. Declared last so positional aggregate
    // initialization of the earlier fields keeps its meaning.
    VisualizationBacklogPolicy backlog_policy = VisualizationBacklogPolicy::in_order;
};

class VisualizationBridge {
  public:
    VisualizationBridge() = default;

    void configure(const VisualizationConfig& config) {
        config_ = config;
        config_.num_channels = std::clamp(config.num_channels, 0, signal::kMaxMeterChannels);
        config_.sample_rate = std::isfinite(config.sample_rate) && config.sample_rate > 0.0f
                                  ? config.sample_rate
                                  : 44100.0f;
        config_.spectrum_floor_db = std::isfinite(config.spectrum_floor_db)
                                        ? std::clamp(config.spectrum_floor_db, -300.0f, 0.0f)
                                        : -120.0f;
        config_.max_frames_per_poll = std::max(0, config.max_frames_per_poll);
        config_.max_callback_frames = std::max(1, config.max_callback_frames);
 
        // Configure one independent STFT per channel. Combining complex audio
        // before the FFT would make anti-phase stereo disappear visually.
        signal::StftConfig stft_cfg;
        stft_cfg.fft_size = config_.fft_size;
        stft_cfg.hop_size = config_.hop_size;
        stft_cfg.window = config_.window;
        stft_cfg.window_param = config_.window_param;
        channel_stfts_.clear();
        channel_stfts_.resize(static_cast<std::size_t>(config_.num_channels));
        for (auto& stft : channel_stfts_)
            stft.configure(stft_cfg);
        spectrum_edge_scale_ = 1.0;
        spectrum_interior_scale_ = 1.0;
        if (!channel_stfts_.empty()) {
            const double window_sum = static_cast<double>(channel_stfts_.front().window_sum());
            if (std::isfinite(window_sum) && std::abs(window_sum) > 1.0e-12) {
                spectrum_edge_scale_ = 1.0 / window_sum;
                spectrum_interior_scale_ = 2.0 / window_sum;
            }
        }
 
        // Configure meter
        meter_.prepare(config_.sample_rate, config_.num_channels);
 
        // Waveform capture setup
        waveform_length_ = config_.capture_waveform
                               ? std::clamp(config_.waveform_length, 1,
                                            static_cast<int>(WaveformData::kMaxSamples))
                               : 0;
        waveform_pos_ = 0;
 
        const int automatic_capacity = std::max(
            {config_.fft_size * 4, std::max(1, waveform_length_), config_.max_callback_frames});
        const int requested_capacity =
            config_.capture_buffer_frames > 0 ? config_.capture_buffer_frames : automatic_capacity;
        capture_capacity_frames_ =
            std::max({config_.fft_size, requested_capacity, config_.max_callback_frames});
        capture_ready_ = capture_.prepare(static_cast<std::uint32_t>(channel_stfts_.size()),
                                          static_cast<std::uint64_t>(capture_capacity_frames_));
 
        consumer_chunk_frames_ = std::min(capture_capacity_frames_, 4096);
        consumer_storage_.assign(
            channel_stfts_.size() * static_cast<std::size_t>(consumer_chunk_frames_), 0.0f);
        consumer_channels_.resize(channel_stfts_.size());
        for (std::size_t ch = 0; ch < channel_stfts_.size(); ++ch) {
            consumer_channels_[ch] =
                consumer_storage_.data() + ch * static_cast<std::size_t>(consumer_chunk_frames_);
        }
 
        dropped_capture_frames_.store(0, std::memory_order_relaxed);
        discontinuity_generation_.store(0, std::memory_order_relaxed);
        acknowledged_discontinuity_.store(0, std::memory_order_relaxed);
        observed_discontinuity_ = 0;
        spectrum_sequence_ = 0;
        waveform_sequence_ = 0;
        if (++epoch_ == 0)
            ++epoch_;
        spectrum_buf_.write(SpectrumData{});
        waveform_buf_.write(WaveformData{});
    }

    void process(const float* const* channels, int num_channels, int num_samples) noexcept;
 
#ifdef PULP_BENCHMARK
    void set_bench_sink(const VisualizationBenchSink& sink) {
        bench_sink_ = sink;
    }
#endif
 
    // ── Non-RT analysis and UI snapshot reads ───────────────────────────────

    bool poll();

    const SpectrumData& peek_spectrum() {
        return spectrum_buf_.read();
    }

    const SpectrumData& read_spectrum() {
        return peek_spectrum();
    }

    const signal::MultiChannelMeterData& read_meter() {
        return meter_buf_.read();
    }

    const WaveformData& peek_waveform() {
        return waveform_buf_.read();
    }

    const WaveformData& read_waveform() {
        return peek_waveform();
    }
 
    // ── Accessors ───────────────────────────────────────────────────────────
 
    int fft_size() const {
        return config_.fft_size;
    }
    int num_bins() const {
        return channel_stfts_.empty() ? 0 : channel_stfts_.front().num_bins();
    }
    int num_channels() const {
        return config_.num_channels;
    }
    float sample_rate() const {
        return config_.sample_rate;
    }

    void reset() {
        capture_.reset();
        for (auto& stft : channel_stfts_)
            stft.reset();
        meter_.reset();
        waveform_pos_ = 0;
        std::fill(waveform_ring_.begin(), waveform_ring_.end(), 0.0f);
        dropped_capture_frames_.store(0, std::memory_order_relaxed);
        discontinuity_generation_.store(0, std::memory_order_relaxed);
        acknowledged_discontinuity_.store(0, std::memory_order_relaxed);
        observed_discontinuity_ = 0;
        spectrum_sequence_ = 0;
        waveform_sequence_ = 0;
        if (++epoch_ == 0)
            ++epoch_;
        spectrum_buf_.write(SpectrumData{});
        meter_buf_.write(signal::MultiChannelMeterData{});
        waveform_buf_.write(WaveformData{});
    }
 
  private:
    void reset_analysis_continuity();
 
    VisualizationConfig config_;
 
    // Fixed SPSC tap (audio producer, one UI consumer).
    audio::PlanarAudioRingBuffer capture_;
    bool capture_ready_ = false;
    int capture_capacity_frames_ = 0;
 
    // Non-RT consumer analysis state.
    std::vector<signal::Stft> channel_stfts_;
    std::vector<float> consumer_storage_;
    std::vector<float*> consumer_channels_;
    int consumer_chunk_frames_ = 0;
    // Coherent-gain correction for the one-sided real FFT. Calculated only in
    // quiescent configure(); poll() applies it after the audio-thread copy.
    double spectrum_edge_scale_ = 1.0;
    double spectrum_interior_scale_ = 1.0;
 
    // Multi-channel meter (audio thread)
    signal::MultiChannelMeter meter_;
 
    // Lock-free publication buffers
    runtime::TripleBuffer<SpectrumData> spectrum_buf_;
    runtime::TripleBuffer<signal::MultiChannelMeterData> meter_buf_;
    runtime::TripleBuffer<WaveformData> waveform_buf_;
 
    // Waveform capture ring buffer
    std::array<float, WaveformData::kMaxSamples> waveform_ring_{};
    int waveform_length_ = 1024;
    int waveform_pos_ = 0;
 
    std::atomic<std::uint64_t> dropped_capture_frames_{0};
    // A rejected producer block creates a time discontinuity. Capture remains
    // suspended until poll() flushes the old continuity and acknowledges it,
    // so post-gap audio can never be concatenated with the old STFT history.
    std::atomic<std::uint64_t> discontinuity_generation_{0};
    std::atomic<std::uint64_t> acknowledged_discontinuity_{0};
    std::uint64_t observed_discontinuity_ = 0; // poll owner only
    std::uint64_t spectrum_sequence_ = 0;
    std::uint64_t waveform_sequence_ = 0;
    std::uint64_t epoch_ = 0;
 
#ifdef PULP_BENCHMARK
    VisualizationBenchSink bench_sink_{};
#endif
};
 
} // namespace pulp::dataplane