pulp::test::audio::PhaseCurve Struct Reference

Phase / group-delay curve of a transfer function. More...

#include <audio_spectrum.hpp>

Public Member Functions
bool	defined_at (double hz) const
	True when the bin nearest hz carries enough energy for its group delay to be a measurement.
bool	phase_defined_at (double hz) const
	True when the bin nearest hz is defined_at AND the unwrap reached it over an unbroken run of defined bins from DC, so its phase sits on the right 2π branch.
double	group_delay_samples_at (double hz) const
	Group delay in samples at the bin nearest hz.
double	group_delay_seconds_at (double hz) const
	Group delay in seconds at hz (samples / sample_rate). NaN when undefined.
double	phase_radians_at (double hz) const
	Unwrapped transfer phase in radians at hz.
double	magnitude_db_rel_peak_at (double hz) const
	Transfer magnitude at hz in dB relative to this curve's own peak transfer magnitude — always defined (it IS the gate input).

Public Attributes
std::string	analyzer = "group_delay"
std::string	stimulus
Window	window = Window::rectangular
int	fft_length = 0
int	analysis_offset = 0
double	sample_rate = 0.0
double	bin_hz = 0.0
double	magnitude_floor_db = 0.0
	Magnitude gate, in dB relative to the curve's peak transfer magnitude.
std::vector< PhasePoint >	full
	Bin 0..N/2, monotonic in hz.
std::vector< PhasePoint >	checkpoints
	Requested frequencies only.

Detailed Description

Phase / group-delay curve of a transfer function.

Determinism contract (echoed into the artifact):

• stimulus: a unit impulse (or caller-supplied reference) driven through the processor, same as the magnitude response;
• window/length: stated window over an fft_length-sample segment beginning at analysis_offset. rectangular is the default and the only window for which the estimator below returns the segment's true group delay (see measure_group_delay);
• reference: phase and group delay are those of the transfer function H = output/input, so a delay common to both cancels and the absolute FFT scale is irrelevant (both facts are ratios) — backend-stable;
• resolution: one bin every sample_rate / fft_length Hz; checkpoints read the nearest bin (no interpolation).

Sign convention: group delay is positive for a causal delay — a filter that delays by k samples reports +k, matching -dφ/dω.

Member Function Documentation

defined_at()

bool pulp::test::audio::PhaseCurve::defined_at

(

double

hz

)

const

True when the bin nearest hz carries enough energy for its group delay to be a measurement.

False for an empty curve. This does NOT qualify phase_radians_at — see phase_defined_at.

group_delay_samples_at()

double pulp::test::audio::PhaseCurve::group_delay_samples_at

(

double

hz

)

const

Group delay in samples at the bin nearest hz.

NaN when defined_at(hz) is false — the caller must not treat a stopband as a measurement. NaN propagates loudly through arithmetic and fails any comparison, which is the intended failure mode.

group_delay_seconds_at()

double pulp::test::audio::PhaseCurve::group_delay_seconds_at

(

double

hz

)

const

Group delay in seconds at hz (samples / sample_rate). NaN when undefined.

magnitude_db_rel_peak_at()

double pulp::test::audio::PhaseCurve::magnitude_db_rel_peak_at

(

double

hz

)

const

Transfer magnitude at hz in dB relative to this curve's own peak transfer magnitude — always defined (it IS the gate input).

NOT the absolute out/in ratio that ResponseCurve::magnitude_db_at returns; see PhasePoint::magnitude_db_rel_peak. Returns kSilenceFloorDb for an empty curve.

phase_defined_at()

bool pulp::test::audio::PhaseCurve::phase_defined_at

(

double

hz

)

const

True when the bin nearest hz is defined_at AND the unwrap reached it over an unbroken run of defined bins from DC, so its phase sits on the right 2π branch.

False for an empty curve.

phase_radians_at()

double pulp::test::audio::PhaseCurve::phase_radians_at

(

double

hz

)

const

Unwrapped transfer phase in radians at hz.

NaN when phase_defined_at(hz) is false — which includes bins that are defined_at but sit above a gap the unwrap could not carry a branch across. See measure_group_delay.

Member Data Documentation

analysis_offset

int pulp::test::audio::PhaseCurve::analysis_offset = 0

analyzer

std::string pulp::test::audio::PhaseCurve::analyzer = "group_delay"

bin_hz

double pulp::test::audio::PhaseCurve::bin_hz = 0.0

checkpoints

std::vector<PhasePoint> pulp::test::audio::PhaseCurve::checkpoints

Requested frequencies only.

fft_length

int pulp::test::audio::PhaseCurve::fft_length = 0

full

std::vector<PhasePoint> pulp::test::audio::PhaseCurve::full

Bin 0..N/2, monotonic in hz.

magnitude_floor_db

double pulp::test::audio::PhaseCurve::magnitude_floor_db = 0.0

Magnitude gate, in dB relative to the curve's peak transfer magnitude.

Bins below it are reported defined = false. Necessary, not sufficient: clearing it does not by itself make a bin defined — the reference- and output-energy gates apply too (see measure_group_delay).

sample_rate

double pulp::test::audio::PhaseCurve::sample_rate = 0.0

stimulus

std::string pulp::test::audio::PhaseCurve::stimulus

window

Window pulp::test::audio::PhaseCurve::window = Window::rectangular

---

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

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