Downward expander with ratio control, hysteresis, and sidechain. More...

#include <Expander.h>

Collaboration diagram for dspark::Expander< T >:

Public Types
enum class	State { Closed , Open , Hold }

Public Member Functions
	~Expander ()=default

void	prepare (double sampleRate) noexcept
	Initializes the expander with a specific sample rate.

void	prepare (const AudioSpec &spec) noexcept
	Initializes the expander using an AudioSpec struct.

void	processBlock (AudioBufferView< T > buffer) noexcept
	Processes an audio block in place (internal detector key).

void	processBlock (AudioBufferView< T > buffer, AudioBufferView< T > sidechain) noexcept
	Processes an audio block in place, keyed by an external sidechain.

void	setThreshold (T dB) noexcept
	Sets the threshold in decibels.

void	setRatio (T ratio) noexcept
	Sets the expansion ratio (e.g., 4.0 for 4:1).

void	setHysteresis (T dB) noexcept
	Sets the hysteresis gap in decibels to prevent chattering.

void	setRange (T dB) noexcept
	Sets the maximum gain reduction limit in decibels (<= 0).

void	setAttack (T ms) noexcept
	Sets the attack time in milliseconds.

void	setHold (T ms) noexcept
	Sets the hold time in milliseconds before release begins.

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

void	setSidechainHPF (bool enabled, double cutoffHz=80.0) noexcept
	Enables and configures the sidechain high-pass filter.

State	getGateState () const noexcept

T	getCurrentGainDb () const noexcept

void	reset () noexcept
	Resets all internal DSP states to prevent clicks on playback start.

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
void	cacheParams () noexcept

template<bool UseHPF, bool UseSc>
void	processBlockInternal (AudioBufferView< T > buffer, const AudioBufferView< T > *sidechain) noexcept
	Internal processing loop templated on HPF/sidechain to avoid branching.

void	updateStateMachine (T levelDb) noexcept

T	computeGain (T levelDb) noexcept

void	updateCoefficients () noexcept

Protected Attributes
double	sampleRate_ = 48000.0

bool	prepared_ = false

std::atomic< T >	threshold_ { T(-40) }

std::atomic< T >	ratio_ { T(4) }

std::atomic< T >	hysteresis_ { T(4) }

std::atomic< T >	attackMs_ { T(0.5) }

std::atomic< T >	holdMs_ { T(50) }

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

std::atomic< T >	rangeDb_ { T(-80) }

std::atomic< T >	rangeLinear_ { T(0.0001) }

std::atomic< bool >	scHpfEnabled_ { false }

std::atomic< T >	scHpfFreqHz_ { T(80) }

std::atomic< T >	scHpfCoeff_ { T(0.995) }

std::atomic< T >	scHpfA0_ { T(0.9975) }

std::array< T, MAX_CHANNELS >	scHpfState_ {}

std::array< T, MAX_CHANNELS >	scHpfPrev_ {}

std::atomic< T >	attackCoeff_ { T(0) }

std::atomic< T >	releaseCoeff_ { T(0) }

std::atomic< T >	detAttCoeff_ { T(0.01) }

std::atomic< T >	detRelCoeff_ { T(0.001) }

std::atomic< int >	holdSamples_ { 0 }

T	cachedThreshold_ = T(-40)

T	cachedRatio_ = T(4)

T	cachedHysteresis_ = T(4)

T	cachedRangeLinear_ = T(0.0001)

T	cachedAttackCoeff_ = T(0)

T	cachedReleaseCoeff_ = T(0)

T	cachedDetAttCoeff_ = T(0.01)

T	cachedDetRelCoeff_ = T(0.001)

T	cachedScHpfCoeff_ = T(0.995)

T	cachedScHpfA0_ = T(0.9975)

int	cachedHoldSamples_ = 0

bool	cachedScHpfEnabled_ = false

State	state_ = State::Closed

T	gateGain_ = T(0)

T	envelope_ = T(0)

int	holdCounter_ = 0

Static Protected Attributes
static constexpr int	MAX_CHANNELS = 16

Detailed Description

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

Downward expander with ratio control, hysteresis, and sidechain.

Template Parameters

T	Sample type (float or double).

Definition at line 59 of file Expander.h.

Member Enumeration Documentation

◆ State

template<FloatType T>

enum class dspark::Expander::State

strong

Enumerator
Closed
Open
Hold

Definition at line 64 of file Expander.h.

Constructor & Destructor Documentation

◆ ~Expander()

template<FloatType T>

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

default

Member Function Documentation

◆ cacheParams()

template<FloatType T>

void dspark::Expander< T >::cacheParams ( )

inlineprotectednoexcept

Definition at line 292 of file Expander.h.

◆ computeGain()

template<FloatType T>

T dspark::Expander< T >::computeGain ( T levelDb )

inlineprotectednoexcept

Definition at line 395 of file Expander.h.

◆ getCurrentGainDb()

template<FloatType T>

T dspark::Expander< T >::getCurrentGainDb ( ) const

inlinenoexcept

Returns: The current actual gain being applied, in decibels (approximate cross-thread metering read).

Definition at line 241 of file Expander.h.

◆ getGateState()

template<FloatType T>

State dspark::Expander< T >::getGateState ( ) const

inlinenoexcept

Returns: The current state of the expander's logic gate (approximate cross-thread metering read). (Renamed from getState(), which now follows the framework-wide preset serialization convention.)

Definition at line 237 of file Expander.h.

◆ getState()

template<FloatType T>

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

inline

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

Definition at line 257 of file Expander.h.

◆ prepare() [1/2]

template<FloatType T>

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

inlinenoexcept

Initializes the expander using an AudioSpec struct.

Parameters

spec	Framework audio specification object (invalid specs are ignored).

Definition at line 91 of file Expander.h.

◆ prepare() [2/2]

template<FloatType T>

void dspark::Expander< T >::prepare ( double sampleRate )

inlinenoexcept

Initializes the expander with a specific sample rate.

Parameters

sampleRate The sample rate in Hz. Non-finite or non-positive rates are ignored (previous state is kept).

Definition at line 73 of file Expander.h.

◆ processBlock() [1/2]

template<FloatType T>

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

inlinenoexcept

Processes an audio block in place (internal detector key).

Parameters

buffer View of the audio buffer to process.

Definition at line 101 of file Expander.h.

◆ processBlock() [2/2]

template<FloatType T>

void dspark::Expander< T >::processBlock	(	AudioBufferView< T >	buffer,
		AudioBufferView< T >	sidechain
	)

inlinenoexcept

Processes an audio block in place, keyed by an external sidechain.

The detector (and its optional HPF) runs on the sidechain channels; the resulting gain is applied to the audio buffer. If the sidechain is empty or shorter than the audio block, the internal key is used instead.

Parameters

buffer	Audio to process in place.
sidechain	Detector key signal (not modified).

Definition at line 123 of file Expander.h.

◆ processBlockInternal()

template<FloatType T>

template<bool UseHPF, bool UseSc>

void dspark::Expander< T >::processBlockInternal	(	AudioBufferView< T >	buffer,
		const AudioBufferView< T > *	sidechain
	)

inlineprotectednoexcept

Internal processing loop templated on HPF/sidechain to avoid branching.

Template Parameters

UseHPF	Compile-time flag to include HPF processing.
UseSc	Compile-time flag: detector keyed by the external sidechain.

Parameters

buffer	View of the audio buffer (gain target).
sidechain	Detector key when UseSc (guaranteed >= buffer length).

Definition at line 316 of file Expander.h.

◆ reset()

template<FloatType T>

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

inlinenoexcept

Resets all internal DSP states to prevent clicks on playback start.

Definition at line 244 of file Expander.h.

◆ setAttack()

template<FloatType T>

void dspark::Expander< T >::setAttack ( T ms )

inlinenoexcept

Sets the attack time in milliseconds.

Definition at line 181 of file Expander.h.

◆ setHold()

template<FloatType T>

void dspark::Expander< T >::setHold ( T ms )

inlinenoexcept

Sets the hold time in milliseconds before release begins.

Definition at line 189 of file Expander.h.

◆ setHysteresis()

template<FloatType T>

void dspark::Expander< T >::setHysteresis ( T dB )

inlinenoexcept

Sets the hysteresis gap in decibels to prevent chattering.

Definition at line 165 of file Expander.h.

◆ setRange()

template<FloatType T>

void dspark::Expander< T >::setRange ( T dB )

inlinenoexcept

Sets the maximum gain reduction limit in decibels (<= 0).

Definition at line 172 of file Expander.h.

◆ setRatio()

template<FloatType T>

void dspark::Expander< T >::setRatio ( T ratio )

inlinenoexcept

Sets the expansion ratio (e.g., 4.0 for 4:1).

Definition at line 158 of file Expander.h.

◆ setRelease()

template<FloatType T>

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

inlinenoexcept

Sets the release time in milliseconds.

Definition at line 205 of file Expander.h.

◆ setSidechainHPF()

template<FloatType T>

void dspark::Expander< T >::setSidechainHPF	(	bool	enabled,
		double	cutoffHz = `80.0`
	)

inlinenoexcept

Enables and configures the sidechain high-pass filter.

Invalid cutoffs (non-finite or <= 0) keep the previous frequency and only apply the toggle; the design clamp is [1, 0.45 * sampleRate]. A negative cutoff used to flip the one-pole into an unstable growth filter, blowing up the detector and pinning the expander open.

Parameters

enabled	True to engage the HPF.
cutoffHz	Cutoff frequency in Hz.

Definition at line 223 of file Expander.h.

◆ setState()

template<FloatType T>

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

inline

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

Definition at line 275 of file Expander.h.

◆ setThreshold()

template<FloatType T>

void dspark::Expander< T >::setThreshold ( T dB )

inlinenoexcept

Sets the threshold in decibels.

Definition at line 151 of file Expander.h.

◆ updateCoefficients()

template<FloatType T>

void dspark::Expander< T >::updateCoefficients ( )

inlineprotectednoexcept

Definition at line 427 of file Expander.h.

◆ updateStateMachine()

template<FloatType T>

void dspark::Expander< T >::updateStateMachine ( T levelDb )

inlineprotectednoexcept

Definition at line 369 of file Expander.h.

Member Data Documentation

◆ attackCoeff_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::attackCoeff_ { T(0) }

protected

Definition at line 474 of file Expander.h.

◆ attackMs_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::attackMs_ { T(0.5) }

protected

Definition at line 458 of file Expander.h.

◆ cachedAttackCoeff_

template<FloatType T>

T dspark::Expander< T >::cachedAttackCoeff_ = T(0)

protected

Definition at line 485 of file Expander.h.

◆ cachedDetAttCoeff_

template<FloatType T>

T dspark::Expander< T >::cachedDetAttCoeff_ = T(0.01)

protected

Definition at line 487 of file Expander.h.

◆ cachedDetRelCoeff_

template<FloatType T>

T dspark::Expander< T >::cachedDetRelCoeff_ = T(0.001)

protected

Definition at line 488 of file Expander.h.

◆ cachedHoldSamples_

template<FloatType T>

int dspark::Expander< T >::cachedHoldSamples_ = 0

protected

Definition at line 491 of file Expander.h.

◆ cachedHysteresis_

template<FloatType T>

T dspark::Expander< T >::cachedHysteresis_ = T(4)

protected

Definition at line 483 of file Expander.h.

◆ cachedRangeLinear_

template<FloatType T>

T dspark::Expander< T >::cachedRangeLinear_ = T(0.0001)

protected

Definition at line 484 of file Expander.h.

◆ cachedRatio_

template<FloatType T>

T dspark::Expander< T >::cachedRatio_ = T(4)

protected

Definition at line 482 of file Expander.h.

◆ cachedReleaseCoeff_

template<FloatType T>

T dspark::Expander< T >::cachedReleaseCoeff_ = T(0)

protected

Definition at line 486 of file Expander.h.

◆ cachedScHpfA0_

template<FloatType T>

T dspark::Expander< T >::cachedScHpfA0_ = T(0.9975)

protected

Definition at line 490 of file Expander.h.

◆ cachedScHpfCoeff_

template<FloatType T>

T dspark::Expander< T >::cachedScHpfCoeff_ = T(0.995)

protected

Definition at line 489 of file Expander.h.

◆ cachedScHpfEnabled_

template<FloatType T>

bool dspark::Expander< T >::cachedScHpfEnabled_ = false

protected

Definition at line 492 of file Expander.h.

◆ cachedThreshold_

template<FloatType T>

T dspark::Expander< T >::cachedThreshold_ = T(-40)

protected

Definition at line 481 of file Expander.h.

◆ detAttCoeff_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::detAttCoeff_ { T(0.01) }

protected

Definition at line 476 of file Expander.h.

◆ detRelCoeff_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::detRelCoeff_ { T(0.001) }

protected

Definition at line 477 of file Expander.h.

◆ envelope_

template<FloatType T>

T dspark::Expander< T >::envelope_ = T(0)

protected

Definition at line 496 of file Expander.h.

◆ gateGain_

template<FloatType T>

T dspark::Expander< T >::gateGain_ = T(0)

protected

Definition at line 495 of file Expander.h.

◆ holdCounter_

template<FloatType T>

int dspark::Expander< T >::holdCounter_ = 0

protected

Definition at line 497 of file Expander.h.

◆ holdMs_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::holdMs_ { T(50) }

protected

Definition at line 459 of file Expander.h.

◆ holdSamples_

template<FloatType T>

std::atomic<int> dspark::Expander< T >::holdSamples_ { 0 }

protected

Definition at line 478 of file Expander.h.

◆ hysteresis_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::hysteresis_ { T(4) }

protected

Definition at line 457 of file Expander.h.

◆ MAX_CHANNELS

template<FloatType T>

constexpr int dspark::Expander< T >::MAX_CHANNELS = 16

staticconstexprprotected

Definition at line 470 of file Expander.h.

◆ prepared_

template<FloatType T>

bool dspark::Expander< T >::prepared_ = false

protected

Definition at line 453 of file Expander.h.

◆ rangeDb_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::rangeDb_ { T(-80) }

protected

Definition at line 461 of file Expander.h.

◆ rangeLinear_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::rangeLinear_ { T(0.0001) }

protected

Definition at line 462 of file Expander.h.

◆ ratio_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::ratio_ { T(4) }

protected

Definition at line 456 of file Expander.h.

◆ releaseCoeff_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::releaseCoeff_ { T(0) }

protected

Definition at line 475 of file Expander.h.

◆ releaseMs_

template<FloatType T>

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

protected

Definition at line 460 of file Expander.h.

◆ sampleRate_

template<FloatType T>

double dspark::Expander< T >::sampleRate_ = 48000.0

protected

Definition at line 452 of file Expander.h.

◆ scHpfA0_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::scHpfA0_ { T(0.9975) }

protected

Definition at line 467 of file Expander.h.

◆ scHpfCoeff_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::scHpfCoeff_ { T(0.995) }

protected

Definition at line 466 of file Expander.h.

◆ scHpfEnabled_

template<FloatType T>

std::atomic<bool> dspark::Expander< T >::scHpfEnabled_ { false }

protected

Definition at line 464 of file Expander.h.

◆ scHpfFreqHz_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::scHpfFreqHz_ { T(80) }

protected

Definition at line 465 of file Expander.h.

◆ scHpfPrev_

template<FloatType T>

std::array<T, MAX_CHANNELS> dspark::Expander< T >::scHpfPrev_ {}

protected

Definition at line 472 of file Expander.h.

◆ scHpfState_

template<FloatType T>

std::array<T, MAX_CHANNELS> dspark::Expander< T >::scHpfState_ {}

protected

Definition at line 471 of file Expander.h.

◆ state_

template<FloatType T>

State dspark::Expander< T >::state_ = State::Closed

protected

Definition at line 494 of file Expander.h.

◆ threshold_

template<FloatType T>

std::atomic<T> dspark::Expander< T >::threshold_ { T(-40) }

protected

Definition at line 455 of file Expander.h.

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

Effects/Expander.h

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ ~Expander()

Member Function Documentation

◆ cacheParams()

◆ computeGain()

◆ getCurrentGainDb()

◆ getGateState()

◆ getState()

◆ prepare() [1/2]

◆ prepare() [2/2]

◆ processBlock() [1/2]

◆ processBlock() [2/2]

◆ processBlockInternal()

◆ reset()

◆ setAttack()

◆ setHold()

◆ setHysteresis()

◆ setRange()

◆ setRatio()

◆ setRelease()

◆ setSidechainHPF()

◆ setState()

◆ setThreshold()

◆ updateCoefficients()

◆ updateStateMachine()

Member Data Documentation

◆ attackCoeff_

◆ attackMs_

◆ cachedAttackCoeff_

◆ cachedDetAttCoeff_

◆ cachedDetRelCoeff_

◆ cachedHoldSamples_

◆ cachedHysteresis_

◆ cachedRangeLinear_

◆ cachedRatio_

◆ cachedReleaseCoeff_

◆ cachedScHpfA0_

◆ cachedScHpfCoeff_

◆ cachedScHpfEnabled_

◆ cachedThreshold_

◆ detAttCoeff_

◆ detRelCoeff_

◆ envelope_

◆ gateGain_

◆ holdCounter_

◆ holdMs_

◆ holdSamples_

◆ hysteresis_

◆ MAX_CHANNELS

◆ prepared_

◆ rangeDb_

◆ rangeLinear_

◆ ratio_

◆ releaseCoeff_

◆ releaseMs_

◆ sampleRate_

◆ scHpfA0_

◆ scHpfCoeff_

◆ scHpfEnabled_

◆ scHpfFreqHz_

◆ scHpfPrev_

◆ scHpfState_

◆ state_

◆ threshold_