Real-time audio clipper with analog modeling and anti-aliasing features. More...

#include <Clipper.h>

Collaboration diagram for dspark::Clipper< T >:

[legend]

Public Types
enum class	Mode { Hard , Soft , Analog , GoldenRatio }
	Defines the harmonic waveshaping algorithm used for clipping. More...

Public Member Functions
void	prepare (const AudioSpec &spec)
	Prepares the clipper for processing, allocating any necessary internal buffers.

void	reset () noexcept
	Resets the internal state of the clipper.

void	processBlock (AudioBufferView< T > buffer) noexcept
	Processes an audio buffer in-place through the clipping algorithm.

void	setMode (Mode mode) noexcept
	Sets the clipping algorithm.

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

void	setInputGain (T dB) noexcept
	Sets the input drive/gain before clipping.

void	setStages (int count) noexcept
	Sets the number of cascaded clipping stages.

void	setMix (T amount) noexcept
	Sets the dry/wet ratio of the processor.

void	setSlewLimit (T ms) noexcept
	Enables slew limiting to soften clipping edges.

void	setOversampling (int factor) noexcept
	Sets the oversampling multiplier to mitigate aliasing.

Mode	getMode () const noexcept

T	getCeiling () const noexcept

T	getInputGain () const noexcept

int	getStages () const noexcept

T	getMix () const noexcept

T	getSlewLimit () const noexcept

int	getOversampling () const noexcept
	Returns the published oversampling factor (applied on the next prepare()).

int	getLatency () const noexcept
	Returns latency in samples introduced by oversampling filters.

T	getGainReductionDb () const noexcept
	Retrieves the maximum gain reduction applied during the last block (for UI metering).

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. Oversampling factor applies on the next prepare() as usual.

Protected Member Functions
void	processInternal (AudioBufferView< T > &buffer, double currentSampleRate) noexcept
	Core DSP routing. Resolves atomics and branches to the per-mode template.

template<Mode M>
void	dispatchClipping (AudioBufferView< T > &buffer, T totalGainLin, T stageGain, int numStages, T ceiling, T maxSlewDelta) noexcept
	Per-mode processing loop (waveshaper inlined at compile time; the slew state and peak metering keep the loop serial per channel).

Static Protected Member Functions
template<Mode M>
static T	processSample (T sample, T ceiling) noexcept
	Compile-time resolution of the waveshaping math.

static T	dbToLinear (T dB) noexcept

static T	gainToDecibels (T linear, T minusInfinityDb) noexcept

Protected Attributes
AudioSpec	spec_ {}

std::atomic< bool >	prepared_ { false }

DryWetMixer< T >	mixer_

std::unique_ptr< Oversampling< T > >	oversampler_

std::atomic< Mode >	mode_ { Mode::Hard }

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

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

std::atomic< int >	stages_ { 1 }

std::atomic< T >	mix_ { T(1) }

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

std::atomic< int >	osFactor_ { 1 }

T	slewPrev_ [kMaxChannels] {}

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

Static Protected Attributes
static constexpr int	kMaxStages = 4

static constexpr int	kMaxChannels = 16

static constexpr T	kPhi = static_cast<T>(1.6180339887498948482)
	Mathematical Golden Ratio used for the GoldenRatio soft-knee transition.

Detailed Description

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

Real-time audio clipper with analog modeling and anti-aliasing features.

Template Parameters

T	Sample type (must satisfy dspark::FloatType, typically float or double).

Definition at line 66 of file Clipper.h.

Member Enumeration Documentation

◆ Mode

template<FloatType T>

enum class dspark::Clipper::Mode

strong

Defines the harmonic waveshaping algorithm used for clipping.

Enumerator
Hard	Brickwall digital clipping. High odd harmonics.
Soft	Tanh soft clipping. Even/odd blend, tape-like.
Analog	Sine-based soft clipping. Transformer-like saturation.
GoldenRatio	Mathematical soft-knee using phi. Extremely transparent until heavy drive.

Definition at line 70 of file Clipper.h.

Member Function Documentation

◆ dbToLinear()

template<FloatType T>

static T dspark::Clipper< T >::dbToLinear ( T dB )

inlinestaticprotectednoexcept

Definition at line 446 of file Clipper.h.

◆ dispatchClipping()

template<FloatType T>

template<Mode M>

void dspark::Clipper< T >::dispatchClipping	(	AudioBufferView< T > &	buffer,
		T	totalGainLin,
		T	stageGain,
		int	numStages,
		T	ceiling,
		T	maxSlewDelta
	)

inlineprotectednoexcept

Per-mode processing loop (waveshaper inlined at compile time; the slew state and peak metering keep the loop serial per channel).

Definition at line 355 of file Clipper.h.

◆ gainToDecibels()

template<FloatType T>

static T dspark::Clipper< T >::gainToDecibels	(	T	linear,
		T	minusInfinityDb
	)

inlinestaticprotectednoexcept

Definition at line 447 of file Clipper.h.

◆ getCeiling()

template<FloatType T>

T dspark::Clipper< T >::getCeiling ( ) const

inlinenoexcept

Definition at line 261 of file Clipper.h.

◆ getGainReductionDb()

template<FloatType T>

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

inlinenoexcept

Retrieves the maximum gain reduction applied during the last block (for UI metering).

Definition at line 274 of file Clipper.h.

◆ getInputGain()

template<FloatType T>

T dspark::Clipper< T >::getInputGain ( ) const

inlinenoexcept

Definition at line 262 of file Clipper.h.

◆ getLatency()

template<FloatType T>

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

inlinenoexcept

Returns latency in samples introduced by oversampling filters.

Definition at line 271 of file Clipper.h.

◆ getMix()

template<FloatType T>

T dspark::Clipper< T >::getMix ( ) const

inlinenoexcept

Definition at line 264 of file Clipper.h.

◆ getMode()

template<FloatType T>

Mode dspark::Clipper< T >::getMode ( ) const

inlinenoexcept

Definition at line 260 of file Clipper.h.

◆ getOversampling()

template<FloatType T>

int dspark::Clipper< T >::getOversampling ( ) const

inlinenoexcept

Returns the published oversampling factor (applied on the next prepare()).

Definition at line 268 of file Clipper.h.

◆ getSlewLimit()

template<FloatType T>

T dspark::Clipper< T >::getSlewLimit ( ) const

inlinenoexcept

Definition at line 265 of file Clipper.h.

◆ getStages()

template<FloatType T>

int dspark::Clipper< T >::getStages ( ) const

inlinenoexcept

Definition at line 263 of file Clipper.h.

◆ getState()

template<FloatType T>

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

inline

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

Definition at line 278 of file Clipper.h.

◆ prepare()

template<FloatType T>

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

inline

Prepares the clipper for processing, allocating any necessary internal buffers.

If oversampling is configured > 1x, this method allocates the oversampling filters. Call it from the main/setup thread before playback begins (never concurrently with processBlock), and again whenever the sample rate changes.

Invalid specs (non-positive/non-finite rate, block size or channel count) are ignored: the previous state is kept and an unprepared instance stays pass-through.

Parameters

spec	The current audio environment specifications (sample rate, max block size).

Definition at line 93 of file Clipper.h.

◆ processBlock()

template<FloatType T>

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

inlinenoexcept

Processes an audio buffer in-place through the clipping algorithm.

Handles dry/wet mixing, upsampling, processing, and downsampling transparently. Pass-through until prepare() succeeds.

Parameters

buffer View of the audio data to process.

Definition at line 146 of file Clipper.h.

◆ processInternal()

template<FloatType T>

void dspark::Clipper< T >::processInternal	(	AudioBufferView< T > &	buffer,
		double	currentSampleRate
	)

inlineprotectednoexcept

Core DSP routing. Resolves atomics and branches to the per-mode template.

Definition at line 317 of file Clipper.h.

◆ processSample()

template<FloatType T>

template<Mode M>

static T dspark::Clipper< T >::processSample	(	T	sample,
		T	ceiling
	)

inlinestaticprotectednoexcept

Compile-time resolution of the waveshaping math.

Definition at line 407 of file Clipper.h.

◆ reset()

template<FloatType T>

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

inlinenoexcept

Resets the internal state of the clipper.

Clears history buffers, slew limiter states, and oversampling memory. Useful when stopping/starting transport or flushing tails.

Definition at line 127 of file Clipper.h.

◆ setCeiling()

template<FloatType T>

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

inlinenoexcept

Sets the absolute maximum output level.

Parameters

dB	Ceiling level in decibels Full Scale (dBFS). Clamped between -60 and 0; non-finite values are ignored.

Definition at line 186 of file Clipper.h.

◆ setInputGain()

template<FloatType T>

void dspark::Clipper< T >::setInputGain ( T dB )

inlinenoexcept

Sets the input drive/gain before clipping.

Parameters

dB	Gain applied to the input signal in dB. Clamped between 0 and 48; non-finite values are ignored.

Definition at line 197 of file Clipper.h.

◆ setMix()

template<FloatType T>

void dspark::Clipper< T >::setMix ( T amount )

inlinenoexcept

Sets the dry/wet ratio of the processor.

Parameters

amount Linear ratio where 0.0 is entirely dry and 1.0 is fully processed. Non-finite values are ignored.

Definition at line 222 of file Clipper.h.

◆ setMode()

template<FloatType T>

void dspark::Clipper< T >::setMode ( Mode mode )

inlinenoexcept

Sets the clipping algorithm.

Parameters

mode	The desired waveshaping Mode (out-of-range values are clamped).

Definition at line 174 of file Clipper.h.

◆ setOversampling()

template<FloatType T>

void dspark::Clipper< T >::setOversampling ( int factor )

inlinenoexcept

Sets the oversampling multiplier to mitigate aliasing.

Values are rounded UP to the next power of two and capped at 16.

Note: Changing this requires a subsequent call to prepare() to allocate filters.

Parameters

factor Oversampling ratio (1 = off, 2, 4, 8, 16).

Definition at line 254 of file Clipper.h.

◆ setSlewLimit()

template<FloatType T>

void dspark::Clipper< T >::setSlewLimit ( T ms )

inlinenoexcept

Enables slew limiting to soften clipping edges.

Limits how fast the output can change over time. Defined in milliseconds, so the effect stays consistent regardless of the sample rate or oversampling factor. Note that a slew limiter is itself nonlinear: it darkens the transient edges and top octave rather than strictly removing aliasing (use oversampling for that).

Parameters

ms	Rise time in milliseconds to reach the ceiling from zero. 0 = off; non-finite values are ignored.

Definition at line 240 of file Clipper.h.

◆ setStages()

template<FloatType T>

void dspark::Clipper< T >::setStages ( int count )

inlinenoexcept

Sets the number of cascaded clipping stages.

Multi-stage clipping distributes the input gain logarithmically across multiple clipping algorithms. This alters the harmonic profile, making heavy distortion sound smoother compared to a single aggressive stage.

Parameters

count Number of stages. Clamped between 1 and 4.

Definition at line 212 of file Clipper.h.

◆ setState()

template<FloatType T>

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

inline

Restores parameters from a blob. Oversampling factor applies on the next prepare() as usual.

Definition at line 293 of file Clipper.h.

Member Data Documentation

◆ ceilingDb_

template<FloatType T>

std::atomic<T> dspark::Clipper< T >::ceilingDb_ { T(0) }

protected

Definition at line 459 of file Clipper.h.

◆ gainReductionDb_

template<FloatType T>

std::atomic<T> dspark::Clipper< T >::gainReductionDb_ { T(0) }

protected

Definition at line 470 of file Clipper.h.

◆ inputGainDb_

template<FloatType T>

std::atomic<T> dspark::Clipper< T >::inputGainDb_ { T(0) }

protected

Definition at line 460 of file Clipper.h.

◆ kMaxChannels

template<FloatType T>

constexpr int dspark::Clipper< T >::kMaxChannels = 16

staticconstexprprotected

Definition at line 309 of file Clipper.h.

◆ kMaxStages

template<FloatType T>

constexpr int dspark::Clipper< T >::kMaxStages = 4

staticconstexprprotected

Definition at line 308 of file Clipper.h.

◆ kPhi

template<FloatType T>

constexpr T dspark::Clipper< T >::kPhi = static_cast<T>(1.6180339887498948482)

staticconstexprprotected

Mathematical Golden Ratio used for the GoldenRatio soft-knee transition.

Definition at line 312 of file Clipper.h.

◆ mix_

template<FloatType T>

std::atomic<T> dspark::Clipper< T >::mix_ { T(1) }

protected

Definition at line 462 of file Clipper.h.

◆ mixer_

template<FloatType T>

DryWetMixer<T> dspark::Clipper< T >::mixer_

protected

Definition at line 454 of file Clipper.h.

◆ mode_

template<FloatType T>

std::atomic<Mode> dspark::Clipper< T >::mode_ { Mode::Hard }

protected

Definition at line 458 of file Clipper.h.

◆ osFactor_

template<FloatType T>

std::atomic<int> dspark::Clipper< T >::osFactor_ { 1 }

protected

Definition at line 464 of file Clipper.h.

◆ oversampler_

template<FloatType T>

std::unique_ptr<Oversampling<T> > dspark::Clipper< T >::oversampler_

protected

Definition at line 455 of file Clipper.h.

◆ prepared_

template<FloatType T>

std::atomic<bool> dspark::Clipper< T >::prepared_ { false }

protected

Definition at line 453 of file Clipper.h.

◆ slewLimitMs_

template<FloatType T>

std::atomic<T> dspark::Clipper< T >::slewLimitMs_ { T(0) }

protected

Definition at line 463 of file Clipper.h.

◆ slewPrev_

template<FloatType T>

T dspark::Clipper< T >::slewPrev_[kMaxChannels] {}

protected

Definition at line 467 of file Clipper.h.

◆ spec_

template<FloatType T>

AudioSpec dspark::Clipper< T >::spec_ {}

protected

Definition at line 452 of file Clipper.h.

◆ stages_

template<FloatType T>

std::atomic<int> dspark::Clipper< T >::stages_ { 1 }

protected

Definition at line 461 of file Clipper.h.

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

Effects/Clipper.h

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Mode

Member Function Documentation

◆ dbToLinear()

◆ dispatchClipping()

◆ gainToDecibels()

◆ getCeiling()

◆ getGainReductionDb()

◆ getInputGain()

◆ getLatency()

◆ getMix()

◆ getMode()

◆ getOversampling()

◆ getSlewLimit()

◆ getStages()

◆ getState()

◆ prepare()

◆ processBlock()

◆ processInternal()

◆ processSample()

◆ reset()

◆ setCeiling()

◆ setInputGain()

◆ setMix()

◆ setMode()

◆ setOversampling()

◆ setSlewLimit()

◆ setStages()

◆ setState()

Member Data Documentation

◆ ceilingDb_

◆ gainReductionDb_

◆ inputGainDb_

◆ kMaxChannels

◆ kMaxStages

◆ kPhi

◆ mix_

◆ mixer_

◆ mode_

◆ osFactor_

◆ oversampler_

◆ prepared_

◆ slewLimitMs_

◆ slewPrev_

◆ spec_

◆ stages_