audio_probe.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/audio/audio_probe_snapshot.hpp>
#include <pulp/audio/audio_stats.hpp>
#include <pulp/audio/buffer.hpp>
#include <pulp/runtime/spsc_ring_index.hpp>
#include <pulp/runtime/triple_buffer.hpp>
 
#include <cstdint>
#include <memory>
#include <vector>
 
namespace pulp::audio {

struct AudioProbeCaptureConfig {
    int capture_frames = 0;
};

class AudioProbe {
public:
    AudioProbe() = default;

    using CaptureConfig = AudioProbeCaptureConfig;

    void prepare(int max_channels,
                 int max_frames,
                 double sample_rate,
                 AudioProbeStage stage = AudioProbeStage::kStandaloneOutputBoundary,
                 CaptureConfig capture = {});

    void analyze_output(const BufferView<const float>& output) noexcept;

    AudioProbeSnapshot latest() { return summary_buf_.read(); }

    AudioStats stats();

    int read_capture(float* dst, int max_frames);

    int read_capture(BufferView<float> dst, int max_frames);

    void reset() noexcept;
 
    int max_channels() const noexcept { return max_channels_; }
    int max_frames() const noexcept { return max_frames_; }
    bool capture_enabled() const noexcept { return capture_frames_ > 0; }

    void set_silence_threshold(float linear) noexcept { silence_threshold_ = linear; }
    void set_clip_ceiling(float linear) noexcept { clip_ceiling_ = linear; }
 
private:
    void publish_empty_snapshot() noexcept;
 
    int max_channels_ = 0;
    int max_frames_ = 0;
    int capture_frames_ = 0;
    double sample_rate_ = 0.0;
    AudioProbeStage stage_ = AudioProbeStage::kUnknown;
 
    float silence_threshold_ = 3.1622776e-5f;  // ~ -90 dBFS
    float clip_ceiling_ = 1.0f;
 
    std::uint64_t sequence_number_ = 0;
    std::uint64_t clip_count_ = 0;      // per-sample
    std::uint64_t nan_inf_count_ = 0;   // per-sample
    std::uint64_t clipped_blocks_ = 0;  // per-block: blocks with >=1 clip
    std::uint64_t nan_blocks_ = 0;      // per-block: blocks with >=1 NaN/Inf
    std::uint64_t callbacks_ = 0;
    std::uint64_t silence_run_blocks_ = 0;
    std::uint64_t dropped_capture_frames_ = 0;
 
    runtime::TripleBuffer<AudioProbeSnapshot> summary_buf_;
 
    // Optional last-N capture: SpscRingIndex over preallocated, probe-owned
    // storage. The FIFO indexes frames; storage is channel-major with
    // `capture_storage_channels_` lanes, each `capture_frames_ + 1` samples
    // long. The ring is sized at prepare(); analyze_output() never resizes it.
    std::vector<float> capture_storage_;
    int capture_storage_channels_ = 0;
    std::unique_ptr<runtime::SpscRingIndex> capture_fifo_;
};
 
}  // namespace pulp::audio