Audio Effects (dsptoolbox.effects)

Effects

This module is a collection of basic audio effects implemented for offline processing. The effects can be applied to the signal as a whole (with possibly anti-causal operations) or in a block-processing manner.

class dsptoolbox.effects.Chorus(depths_ms: float | ndarray[tuple[Any, ...], dtype[float64]] = 5, base_delays_ms: float | ndarray[tuple[Any, ...], dtype[float64]] = 15, modulators: LFO | list | tuple | ndarray[tuple[Any, ...], dtype[float64]] | None = None, mix_percent: float = 100)

Bases: AudioEffect

Basic chorus effect.

Methods

apply(signal)

Apply audio effect on a given signal.

set_parameters([depths_ms, base_delays_ms, ...])

Sets the advanced parameters for the chorus effect.
set_parameters(depths_ms: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None, base_delays_ms: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None, modulators: LFO | list | tuple | ndarray[tuple[Any, ...], dtype[float64]] | None = None, mix_percent: float | None = None)

Sets the advanced parameters for the chorus effect. By passing multiple base delays, depths and LFOs, the effect can be fine-tuned. The number of voices is always extracted from the maximal length of the arrays. Pass None to leave a parameter unchanged.

Parameters:
depths_msfloat, optional

Depth of the delay variation in ms. This must be a positive value. Default: None.

modulatorsLFO or list or tuple or NDArray[np.float64], optional

This defines the modulators signal. It can be a single LFO object or a list containing an LFO for each voice. Alternatively, a numpy.ndarray with shape (time samples, voice) can be passed. If the length in the time axis does not match, it is zero-padded or trimmed in the end. Default: None.

number_of_voicesint, optional

Number of voices to use in the chorus effect. Default: None.

class dsptoolbox.effects.Compressor(threshold_dbfs: float = -10, attack_time_ms: float = 0.5, release_time_ms: float = 20, ratio: float = 3, relative_to_peak_level: bool = True)

Bases: AudioEffect

This is a standard compressor that can also function as a multi-band compressor if the input is a MultiBandSignal.

Methods

apply(signal)

Apply audio effect on a given signal.

set_advanced_parameters([knee_factor_db, ...])

The advanced parameters of the compressor.

set_parameters([threshold_dbfs, ...])

This effect compresses the dynamic range of a signal based on a threshold in dBFS.

show_compression()

Plot the compressor with the actual settings.
set_advanced_parameters(knee_factor_db: float = 0, pre_gain_db: float = 0, post_gain_db: float = 0, mix_percent: float = 100, automatic_make_up_gain: bool = True, downward_compression: bool = True)

The advanced parameters of the compressor.

Parameters:
knee_factor_dbfloat, optional

The knee factor in dB changes the triggering of the compressor. A value of 0 is a hard knee while increasing it produces a smoother knee. Default: 0.

pre_gain_dbfloat, optional

Pre-compression gain in dB. Default: 0.

post_gain_dbfloat, optional

Post-compression gain in dB. Default: 0.

mix_percentfloat, optional

Mix percent is the amount of the compressed signal that is mixed with the clean signal at the output. 100 means for instance that only compressed signal is returned. Values near 100 are advisable. Default: 100.

automatic_make_up_gainbool, optional

When True, the RMS value of the signal is kept after compression. Default: True.

downward_compressionbool, optional

When True, the compressor acts as a downward compressor where signal above the threshold level gets attenuated. If False, it acts as an upward compressor (expander) where the signal below the threshold gets amplified. Default: True.

Notes

  • The compression function with its threshold, ratio and knee can be plotted with the method show_compression().

set_parameters(threshold_dbfs: float | None = None, attack_time_ms: float | None = None, release_time_ms: float | None = None, ratio: float | None = None, relative_to_peak_level: bool | None = None)

This effect compresses the dynamic range of a signal based on a threshold in dBFS. Pass None to leave the previoulsy selected values unchanged.

Parameters:
threshold_dbfsfloat

Threshold in dB above which compression is triggered.

attack_time_msfloat

Attack time in milliseconds.

release_time_msfloat

Release time in milliseconds.

ratiofloat

Compression ratio. When setting the compression to a value larger than 10, the compressor will start acting as a limiter. Values below 1 are not permitted since it would amplify the signal.

relative_to_peak_levelbool

When True, the threshold is relative to the signal’s peak level. Otherwise, it is an absolute value.

show_compression()

Plot the compressor with the actual settings.

Returns:
figmatplotlib.figure.Figure

Figure.

axmatplotlib.axes.Axes

Axes.

class dsptoolbox.effects.DigitalDelay(delay_time_ms: float = 300, feedback: float = 0.1)

Bases: AudioEffect

This applies a basic digital delay to a signal.

Methods

apply(signal)

Apply audio effect on a given signal.

plot_delay()

Plots the delay decay with the selected parameters.

set_advanced_parameters([saturation])

This function sets the advanced parameters for the delay effect.

set_parameters([delay_time_ms, feedback])

Set the parameters for the tremolo effect.
plot_delay()

Plots the delay decay with the selected parameters.

Returns:
figmatplotlib.figure.Figure

Figure.

axmatplotlib.axes.Axes

Axes.

set_advanced_parameters(saturation: str | None = None)

This function sets the advanced parameters for the delay effect.

Parameters:
saturationstr, optional

If None, a linear digital delay line is applied. If ‘arctan’, some arctan saturation is added to the delayed signal. Pass a callable if a custom saturation should be applied. It must take in 1 float and return 1 float in order to be valid. Default: None.

set_parameters(delay_time_ms: float | None = None, feedback: float | None = None)

Set the parameters for the tremolo effect. Passing None in this function leaves them unchanged.

Parameters:
delay_time_msfloat, optional

Delay time in milliseconds.

feedbackfloat, optional

This controls the amount of repetitions to be generated. The bigger the feedback, the more extreme the effect. It is constrained to the range [0, 1[. Default: 0.1.

class dsptoolbox.effects.Distortion(distortion_level: float = 20, post_gain_db: float = 0, type_of_distortion: DistortionType = DistortionType.Arctan)

Bases: AudioEffect

This implements a basic distortion effect that can be expanded by the user by passing a non-linear functions that can be applied to the waveform. Multiple distortions can be linearly combined.

Methods

apply(signal)

Apply audio effect on a given signal.

set_advanced_parameters([...])

This sets the parameters of the distortion.
set_advanced_parameters(type_of_distortion: DistortionType | list[DistortionType] = DistortionType.Arctan, distortion_levels_db: ndarray[tuple[Any, ...], dtype[float64]] = 20, mix_percent: ndarray[tuple[Any, ...], dtype[float64]] = 100, offset_db: ndarray[tuple[Any, ...], dtype[float64]] = -inf, post_gain_db: float = 0)

This sets the parameters of the distortion. Multiple non-linear distortions can be combined with the clean signal and among each other. In that case, distortion_levels, mix_percent and offset_db must be arrays. Furthermore, the original peak levels of each channel in the signal are kept after applying the distortion.

Parameters:
type_of_distortionDistortionType, list[DistortionType], optional

Type of distortion to be applied. If it is a single DistortionType, it is applied to the signal and mixed with the clean signal according to the mixed parameter. If a list is passed, each entry must be either a string corresponding to the supported modes. Default: Arctan.

distortion_levelsNDArray[np.float64], optional

This defines how strong the distortion effect is applied. It can vary according to the non-linear function. Usually, a range between 0 and 50 should be reasonable, though any value is possible. If multiple types of distortion are being used, this should be an array corresponding to each distortion. Default: 20.

mix_percentNDArray[np.float64], optional

This defines how much of each distortion is used in the final mix. If type_of_distortion is only one string or callable, mix_percent is its amount in the final mix with the clean signal. This means that 100 leads to only using the distorted signal while 40 leads to 40% distorted, 60% clean. If multiple types of distortion are being used, this should be an array corresponding to each distortion and its sum must be 100. Default: 100.

offset_dbNDArray[np.float64], optional

This offset corresponds to the offset shown in [1]. It must be a value between -np.inf and 0. The bigger this value, the more even harmonics are caused by the distortion. Pass -np.inf to avoid any offset If multiple types of distortion are being used, this should be an array corresponding to each distortion. Default: -np.inf.

post_gain_dbfloat, optional

This is an additional gain stage in dB after the distortion has been applied. Peak values of the original clean signal are always maintained after distortion. Default: 0.

Returns:
distorted_signalSignal

Distorted signal.

References

class dsptoolbox.effects.DistortionType(*values)

Bases: Enum

Arctan = 1
HardClip = 2
NoDistortion = 4
SoftClip = 3
class dsptoolbox.effects.LFO(frequency_hz: float | tuple, waveform: str = 'harmonic', random_phase: bool = False, smooth: float = 0)

Bases: object

Low-frequency oscillator.

Methods

get_waveform(sampling_rate_hz[, length_samples])

Get the waveform of the oscillator for a sampling frequency and a specified duration.

plot_waveform()

Plot the waveform (2 periods).

set_parameters([frequency_hz, waveform, ...])

Set the parameters of the LFO.
get_waveform(sampling_rate_hz: int, length_samples: int | None = None)

Get the waveform of the oscillator for a sampling frequency and a specified duration. If length_samples is None, only one oscillation is returned.

plot_waveform()

Plot the waveform (2 periods).

Returns:
figmatplotlib.figure.Figure

Figure.

axmatplotlib.axes.Axes

Axes.

set_parameters(frequency_hz: float | tuple | None = None, waveform: str | None = None, random_phase: bool | None = None, smooth: float | None = None)

Set the parameters of the LFO.

class dsptoolbox.effects.SpectralSubtractor(adaptive_mode: bool = True, threshold_rms_dbfs: float = -40, block_length_s: float = 0.1, spectrum_to_subtract: ndarray[tuple[Any, ...], dtype[float64]] | bool = False)

Bases: AudioEffect

This class implements a classical spectral subtraction for denoising or other purposes that can act adaptively (in adaptive mode) or globally (static mode). It is possible to pass either a Signal or a MultiBandSignal to denoise in different frequency bands.

Methods

apply(signal)

Apply audio effect on a given signal.

set_advanced_parameters([overlap_percent, ...])

This allows for setting up the advanced parameters of the spectral subtraction.

set_parameters([adaptive_mode, ...])

Sets the audio effects parameters.
set_advanced_parameters(overlap_percent: int = 50, window_type: Window = Window.Hann, noise_forgetting_factor: float = 0.9, subtraction_factor: float = 2, subtraction_exponent: float = 2, ad_attack_time_ms: float = 0.5, ad_release_time_ms: float = 30)

This allows for setting up the advanced parameters of the spectral subtraction.

Parameters:
overlap_percentint, optional

Window overlap in percent. Default: 50.

window_typeWindow, optional

Window type to use. Default: Hann.

noise_forgetting_factorfloat, optional

This factor is used to average the noise spectrum in order to reduce distortions at the expense of responsiveness. It should be between 0 and 1. The lower this value, the faster the algorithm responds to changes in the noise. Default: 0.5.

subtraction_factorfloat, optional

The subtraction factor defines how strongly noise is subtracted from the signal. It can take values larger than one leading to a strong noise subtraction with possibly more distortion. Default: 2.

subtraction_exponentfloat, optional

The subtraction exponent defines the exponent to which the spectral are scaled during the subtraction. 2 means it is a power subtraction and 1 is an amplitude subtraction. Other values are also possible. Default: 2.

ad_attack_time_msfloat, optional

Attack time in ms for the activity detector (static mode). Default: 0.9.

ad_release_time_msfloat, optional

Release time for the activity detector (static mode). Default: 30.

maximum_amplification_dbfloat, optional

Maximum sample amplification in dB. During signal reconstruction, some samples in the signal might be amplified by large values (depending on window and overlap). This parameter sets the maximum value to which this amplification is allowed. Pass None to ignore it. This might reconstruct the signal better but can lead sometimes to instabilities. Default: 60.

It is also advisable to zero-pad a signal in the beginning to avoid instabilities due to a lack of window overlap on the edges.

Notes

Parameters in use according to mode:

  • Adaptive mode:

    • overlap_percent

    • window_type

    • noise_forgetting_factor

    • subtraction_factor

    • subtraction_exponent

    • maximum_amplification_db

  • Static Mode:

    • overlap_percent

    • window_type

    • subtraction_factor

    • subtraction_exponent

    • maximum_amplification_db

    • ad_attack_time_ms

    • ad_release_time_ms

set_parameters(adaptive_mode: bool | None = None, threshold_rms_dbfs: float | None = None, block_length_s: float | None = None, spectrum_to_subtract: ndarray[tuple[Any, ...], dtype[float64]] = False)

Sets the audio effects parameters. Pass None to leave the previously selected value for each parameter unchanged.

Parameters:
adaptive_modebool, optional

When True, the subtracted spectrum is dynamic and gets updated during the signal’s passing. Otherwise, the spectrum of the noise in the whole signal is computed and applied statically. This could be advantageous when the noise in the signal is thought to be stationary and the least possible audible distortions are expected. In order to separate signal from noise, dsptoolbox.activity_detector is used. Default: True.

threshold_rms_dbfsfloat, optional

Threshold for the RMS value of a signal segment in dBFS that has to separates signal from noise. This means, when below the threshold, the signal segment is regarded as noise. Default: -40.

block_length_sfloat, optional

Block length in seconds. The spectral subtraction is done over blocks of the signal. The real block length in samples is always clipped to the closest power of 2 for efficiency of the FFT. Default: 0.1.

spectrum_to_subtractNDArray[np.float64], optional

If a spectrum is passed, it is used as the one to subtract and all other parameters are ignored. This should be the result of the squared magnitude of the FFT without any scaling in order to avoid scaling discrepancies. It should be only the spectrum corresponding to the positive frequencies (including 0). Pass False to ignore. Default: False.

class dsptoolbox.effects.Tremolo(depth: float = 0.5, modulator: LFO | ndarray[tuple[Any, ...], dtype[float64]] | None = None)

Bases: AudioEffect

Tremolo effect that varies the amplitude of a signal according to a low-frequency oscillator or another modulation signal.

Methods

apply(signal)

Apply audio effect on a given signal.

set_parameters([depth, modulator])

Set the parameters for the tremolo effect.
set_parameters(depth: float | None = None, modulator: LFO | ndarray[tuple[Any, ...], dtype[float64]] | None = None)

Set the parameters for the tremolo effect. Passing None in this function leaves them unchanged.

Parameters:
depthfloat, optional

Depth of the amplitude variation. This must be a positive value. Default: None.

modulatorLFO or NDArray[np.float64], optional

This is the modulator signal that modifies the amplitude of the carrier signal. It can either be a LFO or a numpy array. If the length of the numpy array is different to that of the carrier signal, it is zero-padded or trimmed in the end to match the length. Default: None.

dsptoolbox.effects.get_frequency_from_musical_rhythm(note, bpm)

Method to compute frequency from a musical rhythm notation. The time signature is always assumed to be 4/4. Choose from:

  • ‘quarter’, ‘half’, ‘whole’, ‘eighth’, ‘sixteenth’,

    ‘32th’, ‘quintuplet’.

  • ‘eighth 3’ means eight note triplets. It can be used for getting

    triplets of any other duration.

  • ‘half dotted’ refers to a dotted duration. It can be added to a

    string of any duration.

Parameters:
notestr

String

bpmfloat

Beats per minute to define rhythm.

Returns:
float

Frequency in Hz corresponding to the musical rhythm.

dsptoolbox.effects.get_time_period_from_musical_rhythm(note, bpm)

Method to compute time period from a musical rhythm notation. The time signature is always assumed to be 4/4. Choose from:

  • ‘quarter’, ‘half’, ‘whole’, ‘eighth’, ‘sixteenth’,

    ‘32th’, ‘quintuplet’.

  • ‘eighth 3’ means eight note triplets. It can be used for getting

    triplets of any other duration.

  • ‘half dotted’ refers to a dotted duration. It can be added to a

    string of any duration.

Parameters:
notestr

String

bpmfloat

Beats per minute to define rhythm.

Returns:
float

Time period in s corresponding to the musical rhythm.