High-performance brickwall lookahead limiter. More...

#include <Limiter.h>

Collaboration diagram for dspark::Limiter< T >:

[legend]

Public Member Functions
	~Limiter ()=default

void	prepare (double sampleRate, int numChannels=2, double initialLookaheadMs=-1.0)
	Allocates memory and prepares the limiter for processing.

void	prepare (const AudioSpec &spec)
	Prepares from AudioSpec (unified API).

void	processBlock (AudioBufferView< T > buffer) noexcept
	Processes an AudioBufferView in-place.

T	processSample (T input, int channel) noexcept
	Processes a single sample of one channel.

void	reset () noexcept
	Resets the internal state (delays, gain reduction). RT-Safe.

void	setCeiling (T dB) noexcept
	Sets the absolute output ceiling.

void	setRelease (T ms) noexcept
	Sets the base release time.

void	setLookahead (T ms) noexcept
	Sets the lookahead time dynamically.

void	setTruePeak (bool enabled) noexcept
	Enables 4x oversampled ISP true-peak detection. RT-Safe.

void	setAdaptiveRelease (bool enabled) noexcept
	Enables program-dependent adaptive release. RT-Safe.

void	setSafetyClip (bool enabled) noexcept
	Enables the post-limiter soft-knee safety clipper. RT-Safe.

bool	isTruePeakEnabled () const noexcept

bool	isAdaptiveReleaseEnabled () const noexcept

bool	isSafetyClipEnabled () const noexcept

T	getLookahead () const noexcept

int	getLatency () const noexcept
	Reports the processing latency (the lookahead) in samples.

T	getGainReductionDb () const noexcept
	Current gain reduction in dB (metering; unsynchronized read).

std::vector< uint8_t >	getState () const
	Serializes the parameter state (setup/UI threads; allocates).

bool	setState (const uint8_t *data, size_t size)
	Restores parameters from a blob (tolerant; rejects foreign ids).

Protected Member Functions
int	lookaheadSamplesFor (T ms) const noexcept

void	applyLookaheadTarget () noexcept

void	syncParameters () noexcept

void	updateReleaseCoefficient () noexcept

void	smoothGain (T targetGain, bool adaptive, T relMs) noexcept

T	applySafetyClipper (T out, T clipCeil) const noexcept

Protected Attributes
TruePeakDetector< T, kMaxChannels >	truePeak_

bool	prepared_ = false

double	sampleRate_ = 48000.0

T	invSampleRate_ = T(1.0 / 48000.0)

int	numChannels_ = 2

int	lookaheadSamples_ = 96
	Audio-side lookahead (consumed from lookaheadMs_).

int	maxLimitSamples_ = 96000
	Adaptive-release duration cap (2 s).

std::atomic< T >	ceilingDb_ { T(-0.3) }

std::atomic< T >	releaseMs_ { T(100) }

std::atomic< T >	lookaheadMs_ { T(2) }

std::atomic< bool >	lookaheadDirty_ { false }

std::atomic< bool >	truePeakEnabled_ { false }

std::atomic< bool >	adaptiveRelease_ { false }

std::atomic< bool >	safetyClipEnabled_ { false }

SmoothedValue< T >	ceilingSmooth_

T	lastCeilingDb_ = T(-0.3)
	Change detector for the ceiling pow skip.

T	releaseCoeff_ = T(0)

T	attackCoeff_ = T(1)

T	lastReleaseMs_ = T(-1)

T	currentGain_ = T(1)

int	limitingDuration_ = 0

T	lookaheadCurrent_ = T(96)
	Smoothed read offset (glides on live changes).

T	heldPeak_ = T(0)

int	peakHoldCounter_ = 0

T	sampleCeiling_ = T(0.96605)

int	sampleLookNow_ = 96

std::vector< RingBuffer< T > >	delayLines_

Static Protected Attributes
static constexpr int	kMaxChannels = 16

static constexpr double	kMaxLookaheadMs = 10.0

static constexpr T	kSafetyClipCeiling = T(0.96605)
	-0.3 dBFS

Detailed Description

template<FloatType T>
class dspark::Limiter< T >

High-performance brickwall lookahead limiter.

Template Parameters

T	Sample type (float or double).

Definition at line 70 of file Limiter.h.

Constructor & Destructor Documentation

◆ ~Limiter()

template<FloatType T>

dspark::Limiter< T >::~Limiter ( )

default

Member Function Documentation

◆ applyLookaheadTarget()

template<FloatType T>

void dspark::Limiter< T >::applyLookaheadTarget ( )

inlineprotectednoexcept

Consumes the published lookahead parameter (audio/setup thread).

Definition at line 462 of file Limiter.h.

◆ applySafetyClipper()

template<FloatType T>

T dspark::Limiter< T >::applySafetyClipper	(	T	out,
		T	clipCeil
	)		const

inlineprotectednoexcept

Symmetric soft-knee clipper for the region above the clip threshold, with a hard backstop at 1.05x the threshold.

Definition at line 537 of file Limiter.h.

◆ getGainReductionDb()

template<FloatType T>

T dspark::Limiter< T >::getGainReductionDb ( ) const

inlinenoexcept

Current gain reduction in dB (metering; unsynchronized read).

Definition at line 413 of file Limiter.h.

◆ getLatency()

template<FloatType T>

int dspark::Limiter< T >::getLatency ( ) const

inlinenoexcept

Reports the processing latency (the lookahead) in samples.

Derived from the published lookahead parameter, so it is correct immediately after setLookahead() from any thread (the audio thread may consume the change one block later; the glide covers the transition).

Definition at line 407 of file Limiter.h.

◆ getLookahead()

template<FloatType T>

T dspark::Limiter< T >::getLookahead ( ) const

inlinenoexcept

Definition at line 398 of file Limiter.h.

◆ getState()

template<FloatType T>

std::vector< uint8_t > dspark::Limiter< T >::getState ( ) const

inline

Serializes the parameter state (setup/UI threads; allocates).

Definition at line 417 of file Limiter.h.

◆ isAdaptiveReleaseEnabled()

template<FloatType T>

bool dspark::Limiter< T >::isAdaptiveReleaseEnabled ( ) const

inlinenoexcept

Definition at line 396 of file Limiter.h.

◆ isSafetyClipEnabled()

template<FloatType T>

bool dspark::Limiter< T >::isSafetyClipEnabled ( ) const

inlinenoexcept

Definition at line 397 of file Limiter.h.

◆ isTruePeakEnabled()

template<FloatType T>

bool dspark::Limiter< T >::isTruePeakEnabled ( ) const

inlinenoexcept

Definition at line 395 of file Limiter.h.

◆ lookaheadSamplesFor()

template<FloatType T>

int dspark::Limiter< T >::lookaheadSamplesFor ( T ms ) const

inlineprotectednoexcept

Lookahead in samples for a given ms parameter (shared by the audio-side recompute and getLatency() so both always agree exactly). The product is capped in double before the int cast (out-of-range casts are UB).

Definition at line 454 of file Limiter.h.

◆ prepare() [1/2]

template<FloatType T>

void dspark::Limiter< T >::prepare ( const AudioSpec & spec )

inline

Prepares from AudioSpec (unified API).

Preserves the configured lookahead parameter (it does NOT reset it to the constructor default), so a host re-activation keeps the latency the user dialled in.

Definition at line 151 of file Limiter.h.

◆ prepare() [2/2]

template<FloatType T>

void dspark::Limiter< T >::prepare	(	double	sampleRate,
		int	numChannels = `2`,
		double	initialLookaheadMs = `-1.0`
	)

inline

Allocates memory and prepares the limiter for processing.

Invalid arguments are release-safe: a non-positive or non-finite sample rate makes this call a no-op (the previous state, if any, is kept). Configured parameters (ceiling, release, lookahead, toggles) survive re-preparation.

Warning: Must be called from the main/setup thread, NEVER from the audio thread.

Parameters

sampleRate	Sample rate in Hz (must be > 0).
numChannels	Number of channels to process (clamped to [1, 16]).
initialLookaheadMs	Optional lookahead override in ms; any non-positive or non-finite value (the default) keeps the current lookahead parameter.

Definition at line 93 of file Limiter.h.

◆ processBlock()

template<FloatType T>

void dspark::Limiter< T >::processBlock ( AudioBufferView< T > buffer )

inlinenoexcept

Processes an AudioBufferView in-place.

RT-Safe: Yes. Lock-free and allocation-free.

The gain envelope is linked: the loudest channel drives the reduction applied to all channels. Channels beyond the prepared count pass through untouched (and undelayed).

Parameters

buffer Audio buffer view.

Definition at line 167 of file Limiter.h.

◆ processSample()

template<FloatType T>

T dspark::Limiter< T >::processSample	(	T	input,
		int	channel
	)

inlinenoexcept

Processes a single sample of one channel.

The shared state (ceiling smoother, lookahead glide, peak hold decay and gain envelope) advances on channel 0, so call channel 0 first within each sample frame. For mono streams (channel 0 only) this path is bit-identical to processBlock(). Any channel's peak can raise the shared peak hold, but only channel 0 detects into the envelope; for properly linked multi-channel limiting prefer processBlock().

Note: No DenormalGuard here (per-sample hot path); per-sample callers are expected to guard their own processing loop.

Definition at line 262 of file Limiter.h.

◆ reset()

template<FloatType T>

void dspark::Limiter< T >::reset ( )

inlinenoexcept

Resets the internal state (delays, gain reduction). RT-Safe.

Definition at line 319 of file Limiter.h.

◆ setAdaptiveRelease()

template<FloatType T>

void dspark::Limiter< T >::setAdaptiveRelease ( bool enabled )

inlinenoexcept

Enables program-dependent adaptive release. RT-Safe.

Definition at line 383 of file Limiter.h.

◆ setCeiling()

template<FloatType T>

void dspark::Limiter< T >::setCeiling ( T dB )

inlinenoexcept

Sets the absolute output ceiling.

Parameters

dB	Ceiling in dBFS (e.g., -1.0 for streaming). RT-Safe. Non-finite values are ignored.

Definition at line 340 of file Limiter.h.

◆ setLookahead()

template<FloatType T>

void dspark::Limiter< T >::setLookahead ( T ms )

inlinenoexcept

Sets the lookahead time dynamically.

Note: RT-Safe (atomic publication from any thread). It only adjusts read pointers up to the max memory allocated during prepare(); the read offset glides to the new value at one sample per sample. Non-finite values are ignored. getLatency() reflects the new value immediately.

Parameters

ms	Lookahead in milliseconds (clamped to 0.5 to 10.0 ms).

Definition at line 369 of file Limiter.h.

◆ setRelease()

template<FloatType T>

void dspark::Limiter< T >::setRelease ( T ms )

inlinenoexcept

Sets the base release time.

Parameters

ms	Release time in milliseconds (floored to 1 ms). RT-Safe. Non-finite values are ignored.

Definition at line 353 of file Limiter.h.

◆ setSafetyClip()

template<FloatType T>

void dspark::Limiter< T >::setSafetyClip ( bool enabled )

inlinenoexcept

Enables the post-limiter soft-knee safety clipper. RT-Safe.

Softens the region above -0.3 dBFS up to the ceiling; it only has an effect when the ceiling is set above -0.3 dBFS (below that, the brickwall clamp already keeps the output under the clipper threshold).

Definition at line 392 of file Limiter.h.

◆ setState()

template<FloatType T>

bool dspark::Limiter< T >::setState	(	const uint8_t *	data,
		size_t	size
	)

inline

Restores parameters from a blob (tolerant; rejects foreign ids).

Definition at line 430 of file Limiter.h.

◆ setTruePeak()

template<FloatType T>

void dspark::Limiter< T >::setTruePeak ( bool enabled )

inlinenoexcept

Enables 4x oversampled ISP true-peak detection. RT-Safe.

Definition at line 380 of file Limiter.h.

◆ smoothGain()

template<FloatType T>

void dspark::Limiter< T >::smoothGain	(	T	targetGain,
		bool	adaptive,
		T	relMs
	)

inlineprotectednoexcept

Definition at line 497 of file Limiter.h.

◆ syncParameters()

template<FloatType T>

void dspark::Limiter< T >::syncParameters ( )

inlineprotectednoexcept

Definition at line 474 of file Limiter.h.

◆ updateReleaseCoefficient()

template<FloatType T>

template<FloatType T>

constexpr double dspark::Limiter< T >::kMaxLookaheadMs = 10.0

staticconstexprprotected

Definition at line 445 of file Limiter.h.

◆ kSafetyClipCeiling

template<FloatType T>

constexpr T dspark::Limiter< T >::kSafetyClipCeiling = T(0.96605)

staticconstexprprotected

-0.3 dBFS

Definition at line 446 of file Limiter.h.

◆ lastCeilingDb_

template<FloatType T>

T dspark::Limiter< T >::lastCeilingDb_ = T(-0.3)

protected

Change detector for the ceiling pow skip.

Definition at line 567 of file Limiter.h.

◆ lastReleaseMs_

template<FloatType T>

T dspark::Limiter< T >::lastReleaseMs_ = T(-1)

protected

Definition at line 571 of file Limiter.h.

◆ limitingDuration_

template<FloatType T>

int dspark::Limiter< T >::limitingDuration_ = 0

protected

Definition at line 574 of file Limiter.h.

◆ lookaheadCurrent_

template<FloatType T>

T dspark::Limiter< T >::lookaheadCurrent_ = T(96)

protected

Smoothed read offset (glides on live changes).

Definition at line 575 of file Limiter.h.

◆ lookaheadDirty_

template<FloatType T>

std::atomic<bool> dspark::Limiter< T >::lookaheadDirty_ { false }

protected

Definition at line 561 of file Limiter.h.

Effects/Limiter.h

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Limiter()

Member Function Documentation

◆ applyLookaheadTarget()

◆ applySafetyClipper()

◆ getGainReductionDb()

◆ getLatency()

◆ getLookahead()

◆ getState()

◆ isAdaptiveReleaseEnabled()

◆ isSafetyClipEnabled()

◆ isTruePeakEnabled()

◆ lookaheadSamplesFor()

◆ prepare() [1/2]

◆ prepare() [2/2]

◆ processBlock()

◆ processSample()

◆ reset()

◆ setAdaptiveRelease()

◆ setCeiling()

◆ setLookahead()

◆ setRelease()

◆ setSafetyClip()

◆ setState()

◆ setTruePeak()

◆ smoothGain()

◆ syncParameters()

◆ updateReleaseCoefficient()

Member Data Documentation

◆ adaptiveRelease_

◆ attackCoeff_

◆ ceilingDb_

◆ ceilingSmooth_

◆ currentGain_

◆ delayLines_

◆ heldPeak_

◆ invSampleRate_

◆ kMaxChannels

◆ kMaxLookaheadMs

◆ kSafetyClipCeiling

◆ lastCeilingDb_

◆ lastReleaseMs_

◆ limitingDuration_

◆ lookaheadCurrent_

◆ lookaheadDirty_

◆ lookaheadMs_

◆ lookaheadSamples_

◆ maxLimitSamples_

◆ numChannels_

◆ peakHoldCounter_

◆ prepared_

◆ releaseCoeff_

◆ releaseMs_

◆ safetyClipEnabled_

◆ sampleCeiling_

◆ sampleLookNow_

◆ sampleRate_

◆ truePeak_

◆ truePeakEnabled_