audio_metrics.hpp File Reference

Deterministic offline signal metrics for rendered audio buffers. More...

#include <pulp/audio/buffer.hpp>
#include <cstdint>
#include <span>
#include <string>
#include <vector>

Go to the source code of this file.

Classes
struct	pulp::test::audio::AnalyzeOptions
	Options for analyze(). More...
struct	pulp::test::audio::ChannelMetrics
	Per-channel facts about a rendered buffer. More...
struct	pulp::test::audio::BufferMetrics
	Whole-buffer facts. channels.size() == channel count. More...
struct	pulp::test::audio::FrequencyEstimate
	Result of estimate_frequency(). More...

Namespaces
namespace	pulp
namespace	pulp::test
namespace	pulp::test::audio

Functions
double	pulp::test::audio::to_dbfs (double linear)
	Linear amplitude (1.0 == full scale) to dBFS, clamped to kSilenceFloorDb.
double	pulp::test::audio::from_dbfs (double dbfs)
	dBFS to linear amplitude.
BufferMetrics	pulp::test::audio::analyze (const pulp::audio::BufferView< const float > &buffer, double sample_rate, const AnalyzeOptions &options={})
	Analyze a const view. Pure arithmetic; safe for any buffer size.
BufferMetrics	pulp::test::audio::analyze (const pulp::audio::Buffer< float > &buffer, double sample_rate, const AnalyzeOptions &options={})
	Convenience overload for an owning Buffer.
FrequencyEstimate	pulp::test::audio::estimate_frequency (std::span< const float > samples, double sample_rate)
	Estimate the dominant frequency of one channel.
std::string	pulp::test::audio::summarize (const BufferMetrics &metrics, const FrequencyEstimate &frequency={})
	Compact, agent-readable signal summary.

Variables
constexpr double	pulp::test::audio::kSilenceFloorDb = -200.0
	Floor used when converting a zero/negative linear level to dBFS, so summaries and messages stay finite.

Detailed Description

Deterministic offline signal metrics for rendered audio buffers.

Test/tool layer only — analyzes buffers that have already left the audio thread (typically rendered through pulp::format::HeadlessHost). Nothing here is realtime-safe or intended to run inside an audio callback.

Analyzer determinism contract: every measurement in this header is pure arithmetic over the input samples — no FFT, no windowing, no randomness, no platform-dependent math beyond IEEE-754 float/double. The frequency estimator is a positive-going zero-crossing detector with linear interpolation (see estimate_frequency for its stated limits). Results are bit-stable for identical input on a given platform.