bw_satur

Antialiased tanh-based saturation with parametric bias and gain (compensation) and output bias removal.

In other words this implements (approximately)

y(n) = tanh(gain * x(n) + bias) - tanh(bias)

with antialiasing and optionally dividing the output by gain.

As a side effect, antialiasing causes attenuation at higher frequencies (about 3 dB at 0.5 × Nyquist frequency and rapidly increasing at higher frequencies).

The antialiasing technique used here is described in

J. D. Parker, V. Zavalishin, and E. Le Bivic, "Reducing the Aliasing of Nonlinear Waveshaping Using Continuous-Time Convolution", Proc. 19th Intl. Conf. Digital Audio Effects (DAFx-16), pp. 137-144, Brno, Czech Republic, September 2016.

Version: 1.2.2

License:

GPLv3 for free software/open source projects, or
proprietary license for all other products.

Source code accessible here

Requires:

Included in Brickworks, which is:

FREE for free software/open source projects (GPLv3), or
3,000 € for all other products (proprietary license).

Details

Examples

Here you can download one or more example VST3 plugins for Windows, macOS and Linux. Source code of the audio engine(s) is included in the archive(s).

Description	Link
Saturation	Download

VST® is a trademark of Steinberg Media Technologies GmbH, registered in Europe and other countries.

API

Module type: DSP

bw_satur_coeffs

typedef struct bw_satur_coeffs bw_satur_coeffs;

Coefficients and related.

bw_satur_state

typedef struct bw_satur_state bw_satur_state;

Internal state and related.

bw_satur_init()

static inline void bw_satur_init(
	bw_satur_coeffs * BW_RESTRICT coeffs);

Initializes input parameter values in coeffs.

bw_satur_set_sample_rate()

static inline void bw_satur_set_sample_rate(
	bw_satur_coeffs * BW_RESTRICT coeffs,
	float                         sample_rate);

Sets the sample_rate (Hz) value in coeffs.

bw_satur_reset_coeffs()

static inline void bw_satur_reset_coeffs(
	bw_satur_coeffs * BW_RESTRICT coeffs);

Resets coefficients in coeffs to assume their target values.

bw_satur_reset_state()

static inline float bw_satur_reset_state(
	const bw_satur_coeffs * BW_RESTRICT coeffs,
	bw_satur_state * BW_RESTRICT        state,
	float                               x_0);

Resets the given state to its initial values using the given coeffs and the initial input value x_0.

Returns the corresponding initial output value.

bw_satur_reset_state_multi()

static inline void bw_satur_reset_state_multi(
	const bw_satur_coeffs * BW_RESTRICT              coeffs,
	bw_satur_state * BW_RESTRICT const * BW_RESTRICT state,
	const float *                                    x_0,
	float *                                          y_0,
	size_t                                           n_channels);

Resets each of the n_channels states to its initial values using the given coeffs and the corresponding initial input value in the x_0 array.

The corresponding initial output values are written into the y_0 array, if not BW_NULL.

bw_satur_update_coeffs_ctrl()

static inline void bw_satur_update_coeffs_ctrl(
	bw_satur_coeffs * BW_RESTRICT coeffs);

Triggers control-rate update of coefficients in coeffs.

bw_satur_update_coeffs_audio()

static inline void bw_satur_update_coeffs_audio(
	bw_satur_coeffs * BW_RESTRICT coeffs);

Triggers audio-rate update of coefficients in coeffs.

bw_satur_process1()

static inline float bw_satur_process1(
	const bw_satur_coeffs * BW_RESTRICT coeffs,
	bw_satur_state * BW_RESTRICT        state,
	float                               x);

static inline float bw_satur_process1_comp(
	const bw_satur_coeffs * BW_RESTRICT coeffs,
	bw_satur_state * BW_RESTRICT        state,
	float                               x);

These function process one input sample x using coeffs, while using and updating state. They return the corresponding output sample.

In particular:

bw_satur_process1() assumes that gain compensation is disabled;
bw_satur_process1_comp() assumes that gain compensation is enabled.

The actual gain compensation parameter value is ignored.

bw_satur_process()

static inline void bw_satur_process(
	bw_satur_coeffs * BW_RESTRICT coeffs,
	bw_satur_state * BW_RESTRICT  state,
	const float *                 x,
	float *                       y,
	size_t                        n_samples);

Processes the first n_samples of the input buffer x and fills the first n_samples of the output buffer y, while using and updating both coeffs and state (control and audio rate).

bw_satur_process_multi()

static inline void bw_satur_process_multi(
	bw_satur_coeffs * BW_RESTRICT                    coeffs,
	bw_satur_state * BW_RESTRICT const * BW_RESTRICT state,
	const float * const *                            x,
	float * const *                                  y,
	size_t                                           n_channels,
	size_t                                           n_samples);

Processes the first n_samples of the n_channels input buffers x and fills the first n_samples of the n_channels output buffers y, while using and updating both the common coeffs and each of the n_channels states (control and audio rate).

bw_satur_set_bias()

static inline void bw_satur_set_bias(
	bw_satur_coeffs * BW_RESTRICT coeffs,
	float                         value);

Sets the input bias value in coeffs.

Valid range: [-1e12f, 1e12f].

Default value: 0.f.

bw_satur_set_gain()

static inline void bw_satur_set_gain(
	bw_satur_coeffs * BW_RESTRICT coeffs,
	float                         value);

Sets the gain value in coeffs.

Valid range: [1e-12f, 1e12f].

Default value: 1.f.

bw_satur_set_gain_compensation()

static inline void bw_satur_set_gain_compensation(
	bw_satur_coeffs * BW_RESTRICT coeffs,
	char                          value);

Sets whether the output should be divided by gain (value non-0) or not (0).

Default value: 0 (off).

bw_satur_coeffs_is_valid()

static inline char bw_satur_coeffs_is_valid(
	const bw_satur_coeffs * BW_RESTRICT coeffs);

Tries to determine whether coeffs is valid and returns non-0 if it seems to be the case and 0 if it is certainly not. False positives are possible, false negatives are not.

coeffs must at least point to a readable memory block of size greater than or equal to that of bw_satur_coeffs.

bw_satur_state_is_valid()

static inline char bw_satur_state_is_valid(
	const bw_satur_coeffs * BW_RESTRICT coeffs,
	const bw_satur_state * BW_RESTRICT  state);

Tries to determine whether state is valid and returns non-0 if it seems to be the case and 0 if it is certainly not. False positives are possible, false negatives are not.

If coeffs is not BW_NULL extra cross-checks might be performed (state is supposed to be associated to coeffs).

state must at least point to a readable memory block of size greater than or equal to that of bw_satur_state.

C++ wrapper

Brickworks::Satur

template<size_t N_CHANNELS = 1>
class Satur {
public:
	Satur();

	void setSampleRate(
		float sampleRate);

	void reset(
		float               x0 = 0.f,
		float * BW_RESTRICT y0 = BW_NULL);

# ifndef BW_CXX_NO_ARRAY
	void reset(
		float                                       x0,
		std::array<float, N_CHANNELS> * BW_RESTRICT y0);
# endif

	void reset(
		const float * x0,
		float *       y0 = BW_NULL);

# ifndef BW_CXX_NO_ARRAY
	void reset(
		std::array<float, N_CHANNELS>               x0,
		std::array<float, N_CHANNELS> * BW_RESTRICT y0 = BW_NULL);
# endif

	void process(
		const float * const * x,
		float * const *       y,
		size_t                nSamples);

# ifndef BW_CXX_NO_ARRAY
	void process(
		std::array<const float *, N_CHANNELS> x,
		std::array<float *, N_CHANNELS>       y,
		size_t                                nSamples);
# endif

	void setBias(
		float value);

	void setGain(
		float value);

	void setGainCompensation(
		bool value);
...
}

Changelog

Version 1.2.2:
- Added default value for N_CHANNELS in C++ API.
- Updated dependencies.
Version 1.2.1:
- Now using BW_NULL in the C++ API and implementation.
Version 1.2.0:
- Added support for BW_INCLUDE_WITH_QUOTES, BW_NO_CXX, and BW_CXX_NO_EXTERN_C.
- Added debugging checks from bw_satur_process() to bw_satur_process_multi().
- Added debugging checks in bw_satur_process_multi() to ensure that buffers used for both input and output appear at the same channel indices.
Version 1.1.0:
- Fixed gain compensation in bw_satur_process_multi().
- Now using BW_NULL and BW_CXX_NO_ARRAY.
Version 1.0.0:
- Changed default value for gain compensation to off.
- Added initial input value to bw_satur_reset_state().
- Added bw_satur_reset_state_multi() and updated C++ API in this regard.
- Now bw_satur_reset_state() returns the initial output value.
- Added overloaded C++ reset() functions taking arrays as arguments.
- bw_satur_process() and bw_satur_process_multi() now use size_t to count samples and channels.
- Added more const and BW_RESTRICT specifiers to input arguments and implementation.
- Moved C++ code to C header.
- Added overloaded C++ process() function taking C-style arrays as arguments.
- Removed usage of reserved identifiers.
- Clearly specified parameter validity ranges.
- Added debugging code.
Version 0.6.0:
- Removed dependency on bw_config.
Version 0.5.0:
- Added bw_satur_process_multi().
- Fixed gain coefficient reset bug.
- Fixed initial state bug.
- Added C++ wrapper.
Version 0.4.0:
- Fixed unused parameter warnings.
Version 0.2.0:
- First release.