Run-Time Control Helper Functions#

Most DSP Stages have fixed point control parameters. To aid conversion from typical tuning units (e.g. decibels) to the correct fixed point format, the helper functions below have been provided.

Biquad helpers#

Functions

void adsp_design_biquad_bypass(q2_30 coeffs[5])#

Design biquad filter bypass This function creeates a bypass biquad filter. Only the b0 coefficient is set.

Parameters:

coeffs – Bypass filter coefficients

void adsp_design_biquad_mute(q2_30 coeffs[5])#

Design mute biquad filter This function creates a mute biquad filter. All the coefficients are 0.

Parameters:

coeffs – Mute filter coefficients

left_shift_t adsp_design_biquad_gain(q2_30 coeffs[5], const float gain_db)#

Design gain biquad filter This function creates a biquad filter with a specified gain.

Parameters:

coeffs – Gain filter coefficients
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

void adsp_design_biquad_lowpass(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)#

Design lowpass biquad filter This function creates a biquad filter with a lowpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Lowpass filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q

void adsp_design_biquad_highpass(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)#

Design highpass biquad filter This function creates a biquad filter with a highpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Highpass filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q

void adsp_design_biquad_bandpass(q2_30 coeffs[5], const float fc, const float fs, const float bandwidth)#

Design bandpass biquad filter This function creates a biquad filter with a bandpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Bandpass filter coefficients
fc – Central frequency
fs – Sampling frequency
bandwidth – Bandwidth

void adsp_design_biquad_bandstop(q2_30 coeffs[5], const float fc, const float fs, const float bandwidth)#

Design bandstop biquad filter This function creates a biquad filter with a bandstop response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Bandstop filter coefficients
fc – Central frequency
fs – Sampling frequency
bandwidth – Bandwidth

void adsp_design_biquad_notch(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)#

Design notch biquad filter This function creates a biquad filter with an notch response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Notch filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q

void adsp_design_biquad_allpass(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q)#

Design allpass biquad filter This function creates a biquad filter with an allpass response fc must be less than fs/2, otherwise it will be saturated to fs/2.

Parameters:

coeffs – Allpass filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q

left_shift_t adsp_design_biquad_peaking(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)#

Design peaking biquad filter This function creates a biquad filter with a peaking response fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 18 dB, otherwise the coefficients may overflow. If the gain is greater than 18 dB, it is saturated to that value.

Parameters:

coeffs – Peaking filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

left_shift_t adsp_design_biquad_const_q(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)#

Design constant Q peaking biquad filter This function creates a biquad filter with a constant Q peaking response.

Constant Q means that the bandwidth of the filter remains constant as the gain varies. It is commonly used for graphic equalisers. fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 18 dB, otherwise the coefficients may overflow. If the gain is greater than 18 dB, it is saturated to that value.

Parameters:

coeffs – Constant Q filter coefficients
fc – Central frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

left_shift_t adsp_design_biquad_lowshelf(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)#

Design lowshelf biquad filter This function creates a biquad filter with a lowshelf response.

The Q factor is defined in a similar way to standard low pass, i.e. Q > 0.707 will yield peakiness (where the shelf response does not monotonically change). The level change at f will be boost_db/2. fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 12 dB, otherwise the coefficients may overflow. If the gain is greater than 12 dB, it is saturated to that value.

Parameters:

coeffs – Lowshelf filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

left_shift_t adsp_design_biquad_highshelf(q2_30 coeffs[5], const float fc, const float fs, const float filter_Q, const float gain_db)#

Design highshelf biquad filter This function creates a biquad filter with a highshelf response.

The Q factor is defined in a similar way to standard high pass, i.e. Q > 0.707 will yield peakiness. The level change at f will be boost_db/2. fc must be less than fs/2, otherwise it will be saturated to fs/2.

The gain must be less than 12 dB, otherwise the coefficients may overflow. If the gain is greater than 12 dB, it is saturated to that value.

Parameters:

coeffs – Highshelf filter coefficients
fc – Cutoff frequency
fs – Sampling frequency
filter_Q – Filter Q
gain_db – Gain in dB

Returns:

left_shift_t Left shift compensation value

void adsp_design_biquad_linkwitz(q2_30 coeffs[5], const float f0, const float fs, const float q0, const float fp, const float qp)#

Design Linkwitz transform biquad filter This function creates a biquad filter with a Linkwitz transform response.

The Linkwitz Transform is commonly used to change the low frequency roll off slope of a loudspeaker. When applied to a loudspeaker, it will change the cutoff frequency from f0 to fp, and the quality factor from q0 to qp. f0 and fp must be less than fs/2, otherwise they will be saturated to fs/2.

Parameters:

coeffs – Linkwitz filter coefficients
f0 – Original cutoff frequency
fs – Sampling frequency
q0 – Original quality factor at f0
fp – Target cutoff frequency
qp – Target quality factor of the filter

DRC helpers#

static inline int32_t calc_alpha(float fs, float time)#

Convert an attack or release time in seconds to an EWM alpha value as a fixed point int32 number in Q_alpha format. If the desired time is too large or small to be represented in the fixed point format, it is saturated.

Parameters:

fs – sampling frequency in Hz
time – attack/release time in seconds

Returns:

int32_t attack/release alpha as an int32_t

static inline int32_t calculate_peak_threshold(float level_db)#

Convert a peak compressor/limiter/expander threshold in decibels to an int32 fixed point gain in Q_SIG Q format. If the threshold is higher than representable in the fixed point format, it is saturated. The minimum threshold returned by this function is 1.

Parameters:

level_db – the desired threshold in decibels

Returns:

int32_t the threshold as a fixed point integer.

static inline int32_t calculate_rms_threshold(float level_db)#

Convert an RMS² compressor/limiter/expander threshold in decibels to an int32 fixed point gain in Q_SIG Q format. If the threshold is higher than representable in the fixed point format, it is saturated. The minimum threshold returned by this function is 1.

Parameters:

level_db – the desired threshold in decibels

Returns:

int32_t the threshold as a fixed point integer.

static inline float rms_compressor_slope_from_ratio(float ratio)#

Convert a compressor ratio to the slope, where the slope is defined as (1 - 1 / ratio) / 2.0. The division by 2 compensates for the RMS envelope detector returning the RMS². The ratio must be greater than 1, if it is not the ratio is set to 1.

Parameters:

ratio – the desired compressor ratio

Returns:

float slope of the compressor

static inline float peak_expander_slope_from_ratio(float ratio)#

Convert an expander ratio to the slope, where the slope is defined as (1 - ratio). The ratio must be greater than 1, if it is not the ratio is set to 1.

Parameters:

ratio – the desired expander ratio

Returns:

float slope of the expander

Reverb helpers#

Functions

static inline int32_t adsp_reverb_float2int(float x)#

Convert a floating point value to the Q_RVR format, saturate out of range values. Accepted range is 0 to 1.

Parameters:

x – A floating point number, will be capped to [0, 1]

Returns:

Q_RVR int32_t value

static inline int32_t adsp_reverb_db2int(float db)#

Convert a floating point gain in decibels into a linear Q_RVR value for use in controlling the reverb gains.

Parameters:

db – Floating point value in dB, values above 0 will be clipped.

Returns:

Q_RVR fixed point linear gain.

static inline int32_t adsp_reverb_calculate_damping(float damping)#

Convert a user damping value into a Q_RVR fixed point value suitable for passing to a reverb.

Parameters:

damping – The chose value of damping.

Returns:

Damping as a Q_RVR fixed point integer, clipped to the accepted range.

static inline int32_t adsp_reverb_calculate_feedback(float decay)#

Calculate a Q_RVR feedback value for a given decay. Use to calculate the feedback parameter in reverb_room.

Parameters:

decay – The desired decay value.

Returns:

Calculated feedback as a Q_RVR fixed point integer.

static inline int32_t adsp_reverb_room_calc_gain(float gain_db)#

Calculate the reverb gain in linear scale.

Will convert a gain in dB to a linear scale in Q_RVR format. To be used for converting wet and dry gains for the room_reverb.

Parameters:

gain_db – Gain in dB

Returns:

int32_t Linear gain in a Q_RVR format

void adsp_reverb_wet_dry_mix(int32_t gains[2], float mix)#

Calculate the wet and dry gains according to the mix amount.

When the mix is set to 0, only the dry signal will be output. The wet gain will be 0 and the dry gain will be max. When the mix is set to 1, only they wet signal will be output. The wet gain is max, the dry gain will be 0. In order to maintain a consistent signal level across all mix values, the signals are panned with a -4.5 dB panning law.

Parameters:

gains – Output gains: [0] - Dry; [1] - Wet
mix – Mix applied from 0 to 1

reverb_room_t adsp_reverb_room_init(float fs, float max_room_size, float room_size, float decay, float damping, float wet_gain, float dry_gain, float pregain, float max_predelay, float predelay, void *reverb_heap)#

Initialise a reverb room object A room reverb effect based on Freeverb by Jezar at Dreampoint.

Parameters:

fs – Sampling frequency
max_room_size – Maximum room size of delay filters
room_size – Room size compared to the maximum room size [0, 1]
decay – Length of the reverb tail [0, 1]
damping – High frequency attenuation
wet_gain – Wet gain in dB
dry_gain – Dry gain in dB
pregain – Linear pre-gain
max_predelay – Maximum size of the predelay buffer in ms
predelay – Initial predelay in ms
reverb_heap – Pointer to heap to allocate reverb memory

Returns:

reverb_room_t Initialised reverb room object

void adsp_reverb_room_st_calc_wet_gains(int32_t wet_gains[2], float wet_gain, float width)#

Calculate the stereo wet gains of the stereo reverb room.

Parameters:

wet_gains – Output linear wet_1 and wet_2 gains in Q_RVR
wet_gain – Input wet gain in dB
width – Stereo separation of the room [0, 1]

void adsp_reverb_st_wet_dry_mix(int32_t gains[3], float mix, float width)#

Calculate the stereo wet and dry gains according to the mix amount.

Parameters:

gains – Output gains: [0] - Dry; [1] - Wet_1; [2] - Wet_2
mix – Mix applied from 0 to 1
width – Stereo separation of the room [0, 1]

reverb_room_st_t adsp_reverb_room_st_init(float fs, float max_room_size, float room_size, float decay, float damping, float width, float wet_gain, float dry_gain, float pregain, float max_predelay, float predelay, void *reverb_heap)#

Initialise a stereo reverb room object A room reverb effect based on Freeverb by Jezar at Dreampoint.

Parameters:

fs – Sampling frequency
max_room_size – Maximum room size of delay filters
room_size – Room size compared to the maximum room size [0, 1]
decay – Length of the reverb tail [0, 1]
damping – High frequency attenuation
width – Stereo separation of the room [0, 1]
wet_gain – Wet gain in dB
dry_gain – Dry gain in dB
pregain – Linear pre-gain
max_predelay – Maximum size of the predelay buffer in ms
predelay – Initial predelay in ms
reverb_heap – Pointer to heap to allocate reverb memory

Returns:

reverb_room_st_t Initialised stereo reverb room object

Signal chain helpers#

uint32_t time_to_samples(float fs, float time, time_units_t units)#

Convert a time in seconds/milliseconds/samples to samples for a given sampling frequency.

Parameters:

fs – Sampling frequency
time – New delay time in specified units
units – Time units (SAMPLES, MILLISECONDS, SECONDS) . If an invalid unit is passed, SAMPLES is used.

Returns:

uint32_t Time in samples