pulp::audio::AudioProbe Class Reference

Realtime output-boundary probe. More...

#include <audio_probe.hpp>

Public Types
using	CaptureConfig = AudioProbeCaptureConfig
	Configuration for the optional last-N-frames capture ring.

Public Member Functions
	AudioProbe ()=default
void	prepare (int max_channels, int max_frames, double sample_rate, AudioProbeStage stage=AudioProbeStage::kStandaloneOutputBoundary, CaptureConfig capture={})
	Allocate fixed-capacity storage.
void	analyze_output (const BufferView< const float > &output) noexcept
	Realtime-safe per-block analysis.
AudioProbeSnapshot	latest ()
	Read the latest published snapshot (UI/worker thread).
AudioStats	stats ()
	Release-safe counter subset, derived from the latest snapshot.
int	read_capture (float *dst, int max_frames)
	Copy up to max_frames of the most recent captured channel-0 history into dst (UI/worker thread).
int	read_capture (BufferView< float > dst, int max_frames)
	Copy up to max_frames of the most recent captured multichannel history into dst (UI/worker thread).
void	reset () noexcept
	Reset all cumulative counters and the capture ring.
int	max_channels () const noexcept
int	max_frames () const noexcept
bool	capture_enabled () const noexcept
void	set_silence_threshold (float linear) noexcept
	Silence threshold (linear).
void	set_clip_ceiling (float linear) noexcept
	Clip ceiling (linear). Samples with |x| strictly greater are "clipped".

Detailed Description

Realtime output-boundary probe.

Single-producer (audio thread) / single consumer (UI/worker thread). Sizing and all allocation happen exactly once, in prepare(). After that, analyze_output() is allocation-free.

Lifetime: prepare() must run on a non-audio thread before the audio callback starts calling analyze_output(). Re-preparing while the audio thread is live is a programming error (it reallocates).

Member Typedef Documentation

CaptureConfig

using pulp::audio::AudioProbe::CaptureConfig = AudioProbeCaptureConfig

Configuration for the optional last-N-frames capture ring.

When capture_frames == 0 (default) no ring is allocated and the probe only publishes the latest scalar summary. Defined at namespace scope so it can serve as a default argument to AudioProbe::prepare() (a nested type's default member initializer is not yet usable while the enclosing class is still incomplete).

Constructor & Destructor Documentation

AudioProbe()

pulp::audio::AudioProbe::AudioProbe ( )

default

Member Function Documentation

analyze_output()

void pulp::audio::AudioProbe::analyze_output ( const BufferView< const float > & output )

noexcept

Realtime-safe per-block analysis.

Callable from the audio callback.

Performs only bounded scalar work over output and publishes an updated AudioProbeSnapshot. Allocation-free, lock-free, no FFT. Channels beyond the prepared capacity are ignored (clamped).

capture_enabled()

bool pulp::audio::AudioProbe::capture_enabled ( ) const

inlinenoexcept

latest()

AudioProbeSnapshot pulp::audio::AudioProbe::latest ( )

inline

Read the latest published snapshot (UI/worker thread).

Returns a copy so the reader is not racing the TripleBuffer's front buffer.

max_channels()

int pulp::audio::AudioProbe::max_channels ( ) const

inlinenoexcept

max_frames()

int pulp::audio::AudioProbe::max_frames ( ) const

inlinenoexcept

prepare()

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

Allocate fixed-capacity storage.

THE ONLY place the probe allocates.

Parameters

max_channels	Upper bound on channels per block. Clamped to AudioProbeSnapshot::kMaxChannels.
max_frames	Upper bound on frames per block (informational / used to size the capture ring against). Must be > 0 for capture to function.
sample_rate	Stamped onto every published snapshot.
stage	The boundary this probe observes.
capture	Optional last-N-frames capture configuration.

read_capture() [1/2]

int pulp::audio::AudioProbe::read_capture	(	BufferView< float >	dst,
		int	max_frames )

Copy up to max_frames of the most recent captured multichannel history into dst (UI/worker thread).

Missing source channels are zero-filled. Returns the number of frames written. Single-consumer: this drains the same FIFO as read_capture(float*).

read_capture() [2/2]

int pulp::audio::AudioProbe::read_capture	(	float *	dst,
		int	max_frames )

Copy up to max_frames of the most recent captured channel-0 history into dst (UI/worker thread).

Returns the number of frames written. Only meaningful when capture was enabled at prepare(). Non-RT; intended for the consumer side. This is the single-channel convenience reader over the first channel of the multichannel capture ring.

reset()

void pulp::audio::AudioProbe::reset ( )

noexcept

Reset all cumulative counters and the capture ring.

Not thread-safe against a live audio thread; call when playback is stopped.

set_clip_ceiling()

void pulp::audio::AudioProbe::set_clip_ceiling ( float linear )

inlinenoexcept

Clip ceiling (linear). Samples with |x| strictly greater are "clipped".

set_silence_threshold()

void pulp::audio::AudioProbe::set_silence_threshold ( float linear )

inlinenoexcept

Silence threshold (linear).

A block whose per-channel peak is at or below this is "silent" for the silence-run counter. Default ~ -90 dBFS.

stats()

AudioStats pulp::audio::AudioProbe::stats

(

)

Release-safe counter subset, derived from the latest snapshot.

The device_* mirror fields are left at zero here — the HOST populates them from AudioDeviceManager (ownership boundary, see audio_stats.hpp).

---

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

• /home/runner/work/pulp/pulp/core/audio/include/pulp/audio/audio_probe.hpp