pulp::test::audio::LatencyEvidence Struct Reference

One processor's latency evidence: the facts, the measurement, the verdict. More...

#include <latency_evidence.hpp>

Public Member Functions
bool	gates_failure () const
	True when the evidence must fail a gate: a disproven report, or a measurement that was asked for and could not be drawn.

Public Attributes
LatencyReportStatus	report_status = LatencyReportStatus::unsupported
std::optional< int >	reported_samples
	The report at the start of the render.
std::optional< int >	final_reported_samples
	The report at the end of the render, when observable.
LatencyReportObservation	report_observation = LatencyReportObservation::unobservable
LatencyObservationMode	observation_mode = LatencyObservationMode::none
LatencyPolicy	policy = LatencyPolicy::none
LatencyMeasurementStatus	measurement_status = LatencyMeasurementStatus::not_requested
std::optional< std::int64_t >	measured_samples
	The delay actually observed in the audio, in samples.
std::optional< std::int64_t >	delta_samples
	measured - reported. Null unless both are known.
std::int64_t	tolerance_samples = 0
	How far |delta| may stray and still count as a match.
std::optional< double >	null_depth_db
	Residual level at the winning delay, relative to the input, in dB.
std::optional< double >	ambiguity_margin_db
	How much worse the best COMPETING delay nulled, in dB — the winner's margin of victory.
std::optional< int >	expected_samples
	An optional INTENDED latency, independent of what the processor reports.
LatencyContractOutcome	contract_outcome = LatencyContractOutcome::not_requested
std::string	reason
	Why the outcome is inconclusive, or why the measurement was not possible.

Detailed Description

One processor's latency evidence: the facts, the measurement, the verdict.

Member Function Documentation

gates_failure()

bool pulp::test::audio::LatencyEvidence::gates_failure ( ) const

inline

True when the evidence must fail a gate: a disproven report, or a measurement that was asked for and could not be drawn.

A requested measurement that comes back inconclusive is NOT a pass — an unprovable claim is a failed claim. not_requested is neutral and does not gate.

Member Data Documentation

ambiguity_margin_db

std::optional<double> pulp::test::audio::LatencyEvidence::ambiguity_margin_db

How much worse the best COMPETING delay nulled, in dB — the winner's margin of victory.

Large means the delay is pinned; small means another delay explained the audio nearly as well, and the answer is a guess dressed up as a fact. Below DelayedNullOptions::ambiguity_margin_db the measurement is refused outright as not_measurable.

contract_outcome

LatencyContractOutcome pulp::test::audio::LatencyEvidence::contract_outcome = LatencyContractOutcome::not_requested

delta_samples

std::optional<std::int64_t> pulp::test::audio::LatencyEvidence::delta_samples

measured - reported. Null unless both are known.

expected_samples

std::optional<int> pulp::test::audio::LatencyEvidence::expected_samples

An optional INTENDED latency, independent of what the processor reports.

The rest of this struct proves self-consistency: the audio is delayed by exactly as much as the processor claims. That is the property a host cares about — a processor that reports 4096 and delays 4096 is compensated correctly and sounds right.

But it is not the only thing that can regress. Someone doubles an FFT size, the true delay doubles, latency_samples() dutifully reports the new value, and self-consistency still holds — while your plugin quietly grew 43 ms of latency. Set this to pin the value itself and catch that.

final_reported_samples

std::optional<int> pulp::test::audio::LatencyEvidence::final_reported_samples

The report at the end of the render, when observable.

measured_samples

std::optional<std::int64_t> pulp::test::audio::LatencyEvidence::measured_samples

The delay actually observed in the audio, in samples.

measurement_status

LatencyMeasurementStatus pulp::test::audio::LatencyEvidence::measurement_status = LatencyMeasurementStatus::not_requested

null_depth_db

std::optional<double> pulp::test::audio::LatencyEvidence::null_depth_db

Residual level at the winning delay, relative to the input, in dB.

How completely the delayed input explains the output. A pure delay line nulls to the float noise floor; DSP that reconstructs the signal (an STFT, an oversampler) leaves a real residual and nulls less deeply.

observation_mode

LatencyObservationMode pulp::test::audio::LatencyEvidence::observation_mode = LatencyObservationMode::none

policy

LatencyPolicy pulp::test::audio::LatencyEvidence::policy = LatencyPolicy::none

reason

std::string pulp::test::audio::LatencyEvidence::reason

Why the outcome is inconclusive, or why the measurement was not possible.

Empty when the outcome is satisfied. This is the field a developer reads.

report_observation

LatencyReportObservation pulp::test::audio::LatencyEvidence::report_observation = LatencyReportObservation::unobservable

report_status

LatencyReportStatus pulp::test::audio::LatencyEvidence::report_status = LatencyReportStatus::unsupported

reported_samples

std::optional<int> pulp::test::audio::LatencyEvidence::reported_samples

The report at the start of the render.

Null unless report_status is available. A present zero means "reports zero", not "unknown".

tolerance_samples

std::int64_t pulp::test::audio::LatencyEvidence::tolerance_samples = 0

How far |delta| may stray and still count as a match.

---

The documentation for this struct was generated from the following file:

• /home/runner/work/pulp/pulp/tools/audio/analysis/include/pulp/audio/analysis/latency_evidence.hpp