pulp::test::audio::AliasOptions Struct Reference

Options for measure_aliasing. More...

#include <audio_spectrum.hpp>

Public Attributes
double	max_alias_frequency_hz = 20000.0
	── THE MOST IMPORTANT FIELD IN THIS HEADER.
int	num_harmonics = 64
	Harmonics of the ideal series to account for, from the fundamental up.
int	analysis_offset = 0
	Samples skipped (settling / plugin latency).
int	analysis_length = 0
	Samples analyzed; 0 means "to the end of the buffer".
int	channel = 0
double	min_separation_bins = 2.0
	Minimum separation between two fitted landing sites, in units of 1 / analysis-duration (the natural resolution of a fit this long).

Detailed Description

Options for measure_aliasing.

Member Data Documentation

analysis_length

int pulp::test::audio::AliasOptions::analysis_length = 0

Samples analyzed; 0 means "to the end of the buffer".

Longer is strictly better here — the detection floor improves as 1/√length, and closely-spaced components separate as 1/length.

analysis_offset

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

Samples skipped (settling / plugin latency).

channel

int pulp::test::audio::AliasOptions::channel = 0

max_alias_frequency_hz

double pulp::test::audio::AliasOptions::max_alias_frequency_hz = 20000.0

── THE MOST IMPORTANT FIELD IN THIS HEADER.

READ THIS BEFORE GATING. ──

Aliases landing ABOVE this frequency are measured and reported, but are excluded from worst_alias_db / worst_alias_hz.

A full-band "no alias above −100 dB" gate is physically impossible for any finite method, and a caller who removes this qualifier has written a gate that no correct implementation can pass. Two independent reasons:

1. Fold-back is continuous across Nyquist. A component at Nyquist + ε lands at Nyquist − ε. As ε → 0 the alias approaches the band edge and no filter can act on it, because "reject at Nyquist, pass at Nyquist" is not a specification.
2. Every realizable kernel has a transition band. An anti-alias response cannot step from 0 dB to −100 dB at a point; it needs finite width, and that width straddles Nyquist with near-zero attenuation. At 48 kHz a 100 dB-stopband 64-tap Kaiser design costs ≈4.8 kHz of transition, so content in ≈24–25 kHz folds to 23–24 kHz essentially unattenuated — tens of dB above −100.

The physics is not a defect, it is why the default is 20 kHz: an alias that lands at 23.4 kHz is above hearing and unavoidable; one that lands at 7 kHz is audible and is the bug. Band-qualifying is what makes the gate measure the oscillator instead of the sample rate.

Raise it only to characterize (full_band_worst_alias_db already reports the unqualified number for exactly that). Lower it for a content-specific audibility argument. Setting it at or above Nyquist makes the qualifier a no-op and is the misuse described above.

min_separation_bins

double pulp::test::audio::AliasOptions::min_separation_bins = 2.0

Minimum separation between two fitted landing sites, in units of 1 / analysis-duration (the natural resolution of a fit this long).

Sites closer than this — to each other, to DC, or to Nyquist — are not linearly independent over the segment, so they are marked resolved = false rather than fitted to an ill-conditioned answer.

num_harmonics

int pulp::test::audio::AliasOptions::num_harmonics = 64

Harmonics of the ideal series to account for, from the fundamental up.

Every one above Nyquist contributes a fold site. Too few and real aliases are missed (they fall through to noise_db); too many and the fit spends conditioning on sites with nothing at them. For a saw or pulse, go high enough that num_harmonics · f0 is several times the sample rate.

A series with NO harmonic at or above Nyquist is rejected outright (measure_aliasing throws): it models no fold site, so its report would read as clean on ANY signal, however aliased. Note the default hits that wall for a low fundamental — 64 harmonics of anything below 375 Hz at 48 kHz never reach Nyquist — so size this from the sample rate, not from habit.

---

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