Standard functions (dsptoolbox.*)¶

Standard functions¶

This module contains a general collection of DSP functions that do not fall under a same category. These functions act on the custom classes of dsptoolbox and not on primitive data types such as arrays.

Access to these functions should be done via dsptoolbox.* (without reference to standard).

class dsptoolbox.standard.BiquadEqType(*values)¶

Bases: Enum

Available types:

Lowpass
Highpass
Peaking
Lowshelf
Highshelf
BandpassSkirt
BandpassPeak
LowpassFirstOrder
HighpassFirstOrder
AllpassFirstOrder
Allpass
Notch
Inverter

Allpass = 11¶

AllpassFirstOrder = 10¶

BandpassPeak = 7¶

BandpassSkirt = 6¶

Highpass = 2¶

HighpassFirstOrder = 9¶

Highshelf = 5¶

Inverter = 13¶

Lowpass = 1¶

LowpassFirstOrder = 8¶

Lowshelf = 4¶

Notch = 12¶

Peaking = 3¶

class dsptoolbox.standard.FadeType(*values)¶

Bases: Enum

Exponential = 2¶

Linear = 1¶

Logarithmic = 3¶

NoFade = 4¶

class dsptoolbox.standard.FilterBankMode(*values)¶

Bases: Enum

Ways to apply a filter bank to a signal: - Parallel: returns a MultiBandSignal where each band is the output of

each filter.

Sequential: applies each filter to the given Signal in a sequential manner and returns output with same dimension.
Summed: applies every filter as parallel and then sums the outputs returning same dimensional output as input.

Parallel = 1¶

Sequential = 2¶

Summed = 3¶

class dsptoolbox.standard.FilterCoefficientsType(*values)¶

Bases: Enum

Coefficients accepted by scipy.

Zpk: zero, poles, gain.
Sos: second-order sections.
Ba: feed-forward and feed-backward coefficients.

Ba = 3¶

Sos = 2¶

Zpk = 1¶

class dsptoolbox.standard.FilterPassType(*values)¶

Bases: Enum

Bandpass = 3¶

Bandstop = 4¶

Highpass = 2¶

Lowpass = 1¶

to_str()¶

class dsptoolbox.standard.FrequencySpacing(*values)¶

Bases: Enum

Linear = 2¶

Logarithmic = 1¶

Other = 3¶

class dsptoolbox.standard.IirDesignMethod(*values)¶

Bases: Enum

Methods for IIR filter design:

Butterworth: maximally flat in the passband. Good for general use.
Bessel: mild rolloff but with approximately linear phase response in the passband.
Chebyshev1: ripples in the passband, monotonically decreasing in the stopband. Steep Rolloff.
Chebyshev2: flat in the passband, ripples in the stopband.
Elliptic: ripples in passband and stopband. Very steep rolloff.

Bessel = 1¶

Butterworth = 2¶

Chebyshev1 = 3¶

Chebyshev2 = 4¶

Elliptic = 5¶

to_scipy_str() → str¶: Return the scipy string variant.

class dsptoolbox.standard.InterpolationDomain(*values)¶

Bases: Enum

For Complex and MagnitudePhase domains, the underlying data must be complex.

Complex = 3¶

Magnitude = 1¶

MagnitudePhase = 4¶

Power = 2¶

is_complex() → bool¶

is_linear() → bool¶

class dsptoolbox.standard.InterpolationEdgeHandling(*values)¶

Bases: Enum

Handling of edges during interpolation:

ZeroPad: fills with 0 values the frequency bins outside the range.
OnePad: fills with 1 values the frequency bins outside the range.
Extend: uses the values at the edges of the spectrum.
Error: raises an assertion error if frequency bins outside the saved range are requested.

Error = 4¶

Extend = 3¶

OnePad = 2¶

ZeroPad = 1¶

class dsptoolbox.standard.InterpolationScheme(*values)¶

Bases: Enum

The interpolation schemes are:

Linear: linear interpolation. It is the fastest and most stable.
Cubic: CubicSplines. It delivers smoother results, but can lead to overshooting and other interpolation artifacts.
Pchip: PchipInterpolator. It is a polynomial interpolator that avoids overshooting between interpolation points.

Cubic = 2¶

Linear = 1¶

Pchip = 3¶

class dsptoolbox.standard.MagnitudeNormalization(*values)¶

Bases: Enum

Normalization for magnitude responses:

NoNormalization.
OneKhz: @ 1 kHz for each channel.
Max: @ peak.
Energy: use average energy (per frequency) as normalization value.

All variants exist either for the first channel, thus taking the same normalization value for all channels, or for each channel independently.

Energy = 6¶

EnergyFirstChannel = 7¶

Max = 4¶

MaxFirstChannel = 5¶

NoNormalization = 1¶

OneKhz = 2¶

OneKhzFirstChannel = 3¶

class dsptoolbox.standard.SpectrumMethod(*values)¶

Bases: Enum

Methods to compute a spectrum. - Welch: produces a spectrum that is averaged over time. If it is the

autospectrum, it is always real-valued (magnitude or power). If it is a cross-spectrum, it is complex.

FFT: produces the spectrum of a deterministic signal or an impulse response using a DFT directly on the time signal.

FFT = 2¶

WelchPeriodogram = 1¶

class dsptoolbox.standard.SpectrumScaling(*values)¶

Bases: Enum

Amplitude scalings are: - AmplitudeSpectrum - AmplitudeSpectralDensity - FFTBackward - FFTForward - FFTOrthogonal

Power scalings are: - PowerSpectrum - PowerSpectralDensity

Notes

FFT scalings just normalized by the length of the data but have no direct physical units, since they do not regard windows or sampling rates.
Power (magnitude-squared) scalings usually deliver real data, i.e., no complex spectra. This is not the case for cross-spectral matrices (CSM), where the power scalings do deliver complex cross-spectra.
Amplitude scalings can deliver complex or real (magnitude) spectra depending on the applied method to compute the spectrum.

AmplitudeSpectralDensity = 2¶

AmplitudeSpectrum = 1¶

FFTBackward = 5¶

FFTForward = 6¶

FFTOrthogonal = 7¶

PowerSpectralDensity = 4¶

PowerSpectrum = 3¶

conversion_factor(output: SpectrumScaling, length_time_data_samples: int, sampling_rate_hz: int, window: ndarray[tuple[Any, ...], dtype[float64]] | None) → ndarray[tuple[Any, ...], dtype[float64]]¶

Obtain the conversion factor from the current scaling to another one. If the input and output do not match on whether scaling is linear or squared, the conversion factor is always computed to be multiplied with the squared data.

Parameters:

outputSpectrumScaling: Scaling output.
length_time_data_samplesint
sampling_rate_hzint
windowNDArray[np.float64], None

Returns:

NDArray[np.float64]

fft_norm() → str¶

Return the expected FFT normalization to use for the given scaling.

Returns:

str: FFT normalization as expected by numpy or scipy FFT.

get_scaling_factor(length_time_data_samples: int, sampling_rate_hz: int, window: ndarray[tuple[Any, ...], dtype[float64]] | None) → ndarray[tuple[Any, ...], dtype[float64]]¶

Obtain the scaling factor for the given spectrum scaling and parameters. This factor is always valid for applying on the linear or squared data directly. This factor applies for the forward transform and a one-sided spectrum. Correction for DC and Nyquist must be done manually.

Parameters:

outputSpectrumScaling: Scaling output.
length_time_data_samplesint
sampling_rate_hzint
windowNDArray[np.float64], None

has_physical_units() → bool¶

When True, the spectrum scaling has a physical unit. Otherwise, it is just an FFT normalization scheme.

Returns:

bool

is_amplitude_scaling() → bool¶

When True, it is an amplitude scaling of spectrum. False should then be regarded as a power scaling.

Returns:

bool

is_spectral_density() → bool¶

When True, the scaling is a spectral density and its power representation can be integrated over frequency to get the signal’s energy (Parserval’s theorem applies). False means it is either a spectrum or it has no physical units.

Returns:

bool

outputs_complex_spectrum(method: SpectrumMethod) → bool¶

True means that the output spectrum should be complex, otherwise it will real-valued.

Parameters:

methodSpectrumMethod: Method for computing the spectrum.

class dsptoolbox.standard.SpectrumType(*values)¶

Bases: Enum

Spectrum representations.

Complex = 3¶

Db = 4¶

Magnitude = 2¶

Power = 1¶

class dsptoolbox.standard.Window(*values)¶

Bases: Enum

Different window types. They are computed via scipy.signal.windows.get_window().

Methods

Barthann
Bartlett
Blackman
Blackmanharris
Bohman
Boxcar
Chebwin
Cosine
Dpss
Exponential
Flattop
Gaussian
GeneralCosine
GeneralGaussian
GeneralHamming
Hamming
Hann
Kaiser
KaiserBesselDerived
Lanczos
Nuttall
Parzen
Taylor
Triang
Tukey

Barthann = 12¶

Bartlett = 6¶

Blackman = 3¶

Blackmanharris = 10¶

Bohman = 9¶

Boxcar = 1¶

Chebwin = 25¶

Cosine = 13¶

Dpss = 24¶

Exponential = 14¶

Flattop = 7¶

Gaussian = 20¶

GeneralCosine = 21¶

GeneralGaussian = 22¶

GeneralHamming = 23¶

Hamming = 4¶

Hann = 5¶

Kaiser = 18¶

KaiserBesselDerived = 19¶

Lanczos = 17¶

Nuttall = 11¶

Parzen = 8¶

Taylor = 16¶

Triang = 2¶

Tukey = 15¶

property extra_parameter¶

needs_extra_parameter() → bool¶: When True, window type requires a new parameter.

to_scipy_format()¶: Parse to format for passing to scipy.signal.windows.get_window().

with_extra_parameter(extra_parameter: float | tuple[float, float])¶

Add the extra parameter parameter to the window. Windows that require an extra parameter are: - Kaiser - KaiserBesselDerived - Gaussian - GeneralCosine - GeneralGaussian (two parameters) - GeneralHamming - Dpss - Chebwin

Refer to scipy.signal.windows for more information.

dsptoolbox.standard.activity_detector(signal: Signal, threshold_dbfs: float = -20, channel: int = 0, relative_to_peak: bool = True, pre_filter: Filter | None = None, attack_time_ms: float = 1, release_time_ms: float = 25) → tuple[Signal, dict]¶

This is a simple signal activity detector that uses a power threshold. It can be used relative to the signal’s peak value or absolute. It is only applicable to one channel of the signal. This function returns the signal and a dictionary containing noise (as a signal) and the time indices corresponding to the bins that were found to surpass the threshold according to attack and release times.

Prefiltering (for example with a bandpass filter) is possible when a pre_filter is passed.

See Returns to gain insight into the returned dictionary and its keys.

Parameters:

signalSignal: Signal in which to detect activity.
threshold_dbfsfloat: Threshold in dBFS to separate noise from activity.
channelint, optional: Channel in which to perform the detection. Default: 0.
relative_to_peakbool, optional: When True, the threshold value is relative to the signal’s peak value. Otherwise, it is regarded as an absolute threshold. Default: True.
pre_filterFilter, optional: Filter used for prefiltering the signal. It can be for instance a bandpass filter selecting the relevant frequencies in which the activity might be. Pass None to avoid any pre filtering. The filter is applied using zero-phase filtering. Default: None.
attack_time_msfloat, optional: Attack time (in ms). It corresponds to a lag time for detecting activity after surpassing the threshold. Default: 1.
release_time_msfloat, optional: Release time (in ms) for activity detector after signal has fallen below power threshold. Pass 0 to release immediately. Default: 25.

Returns:

detected_sigSignal

Detected signal.

othersdict

Dictionary containing following keys: - ‘noise’: left-out noise in original signal (below threshold) as

Signal object.

‘signal_indices’: array of boolean that describes which indices of the original time series belong to signal and which to noise. True at index n means index n was passed to signal.
‘noise_indices’: the inverse array to ‘signal_indices’.

dsptoolbox.standard.append_filterbanks(fbs: list[FilterBank]) → FilterBank¶

Merges filterbanks by concatenating all of its filters.

Parameters:

fbslist[FilterBank]: List of FilterBanks.

Returns:

new_fbFilterBank: New filterbank with all filters.

dsptoolbox.standard.append_signals(signals: list[Signal] | list[MultiBandSignal], allow_padding_trimming: bool = True, at_end: bool = True) → Signal | MultiBandSignal¶

Append all channels of the signals in the list. If their lengths are not the same trimming or padding can be applied to match the length of the first signal.

Parameters:

signalslist[Signal] or list[MultiBandSignal]: First signal.
allow_padding_trimmingbool, optional: If the signals do not have the same length, all are trimmed or zero-padded to match the first signal’s length, when this is True. Otherwise, an error will be raised if the lengths do not match. Default: True.
at_endbool, optional: When True and allow_padding_trimming=True, padding or trimming is done at the end of the signals. Otherwise, it is done in the beginning. Default: True.

Returns:

new_sigSignal or MultiBandSignal: Signal with all channels.

dsptoolbox.standard.append_spectra(spectra: list[Spectrum], complex_if_available: bool = True) → Spectrum¶

Join all spectra by appending their channels.

Parameters:

spectralist[Spectrum]: Spectra to be appended. All spectra will be interpolated to the frequency vector of the first one.
complex_if_availablebool, optional: If the first spectrum is complex and this is set to True, all other spectra are expected to be complex as well and will be appended. In any other case, only magnitude spectra will be appended. Default: True.

Returns:

Spectrum: New spectrum with all channels.

Apply some gain to a signal or filters.

If it is a Signal or MultiBandSignal, it can be done to the signal as a whole or per channel.

If it is a Filter or a FilterBank, it can be applied to the different filters. When passing a single gain value to a FilterBank, this will be applied to all filters. See notes for details.

Parameters:

targetSignal, MultiBandSignal, Filter, FilterBank: Target to apply gain to.
gain_dbfloat, NDArray[np.float64]: Gain in dB to be applied. If it is an array, it should have as many elements as there are channels in the signal or filters in the filter bank.

Returns:

Signal, MultiBandSignal, Filter, FilterBank: Signal or filter with new gain.

Notes

If constrain_amplitude=True in the signal, the resulting time data might get rescaled after applying the gain.
When applying gain to a FilterBank, it should be regarded how it will be used. If the intended mode is “parallel”, then a single gain value will modify each band. If “sequential”, the gain value will be applied to the output signal for each filter. In the latter case, a single filter should get the gain modification.

dsptoolbox.standard.crest_factor(sig: Signal | MultiBandSignal, in_db: bool = True, use_true_peak: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]¶

Compute the crest factor of a signal, which is defined as the level difference between its peak and RMS value.

Parameters:

sigSignal, MultiBandSignal: Input signal.
in_dbbool, optional: When True, the output is given in dB. Otherwise, it is given in the amplitude form. Default: True.
use_true_peakbool, optional: When True, the true peak value is used for computing the crest factor. Default: False.

Returns:

NDArray[np.float64]: Crest factors for each channel. If it the input is a MultiBandSignal, the shape is (band, channel).

dsptoolbox.standard.delay(sig: Signal | MultiBandSignal, delay_samples: int, channels=None, keep_length: bool = False) → Signal | MultiBandSignal¶

Apply a time delay to a signal. This function is faster than fractional_delay because it only applies integer delay by zero-padding.

Parameters:

sigSignal or MultiBandSignal: Signal to be delayed.
delay_samplesint: Delay in samples.
channelsint or array-like, optional: Channels to be delayed. Pass None to delay all channels. Default: None.
keep_lengthbool, optional: When True, the signal retains its original length and loses information for the latest samples. If only specific channels are to be delayed, and keep_length is set to False, the remaining channels are zero-padded in the end. Default: False.

Returns:

out_sigSignal or MultiBandSignal: Delayed signal.

dsptoolbox.standard.detrend(sig: Signal | MultiBandSignal, polynomial_order: int = 0) → Signal | MultiBandSignal¶

Returns the detrended signal.

Parameters:

sigSignal: Signal to detrend.
polynomial_orderint, optional: Polynomial order of the fitted polynomial that will be removed from time data. 0 is equal to mean removal. Default: 0.

Returns:

Signal: Detrended signal.

dsptoolbox.standard.dither(s: Signal, triangular_distribution: bool = True, epsilon: float = 5.960464477539063e-08, noise_shaping_filterbank: FilterBank | None = None, truncate: bool = False) → Signal¶

This function applies dither to the signal and, optionally, truncates the time samples to 16-bits floating point representation.

Parameters:

sSignal: Signal to apply dither to.
triangular_distributionbool, optional: Type of probability distribution to acquire noise from. When True, a rectangular distribution is used, otherwise it is uniform. Default: True.
epsilonfloat, optional: Value that represents the quantization step. The default value supposes quantization to 16-bit floating point. It is obtained through numpy’s smallest subnormal for np.float16. See notes for the value concerning the 24-bit case. Default: 6e-08.
noise_shaping_filterbankFilterBank, None, optional: Noise can be arbitrarily shaped using a filter bank (in sequential mode). Pass None to avoid any noise-shaping. Default: None.
truncatebool, optional: When True, the time samples are truncated to np.float16 resolution. False only applies dither noise to the signal without truncating. Default: False.

Returns:

new_sSignal: Signal with dither.

Notes

The output signal has time samples with 16-bit precision, but the data type of the array is np.float64 for consistency.
Rectangular distribution applies noise with samples coming from a uniform distribution [-epsilon/2, epsilon/2]. Triangular has a triangle shape for the noise distribution with values between [-epsilon, epsilon]. See [1] for more details.
Dither might be only necessary when lowering the bit-depth down to 16 bits, though the 24-bit case might be relevant if the there are signal components with very low volumes.
24-bit signed integers range from -8388608 to 8388607. The quantization step is therefore 1/8388608=1.1920928955078125e-07.

References

[1]: Lerch, Weinzierl. Handbuch der Audiotechnik: Chapter 14.

dsptoolbox.standard.envelope(signal: Signal | MultiBandSignal, analytic: bool = True, window_length_samples: int | None = None)¶

This function computes the envelope of a given signal by means of its hilbert transformation. It can also compute the RMS value over a certain window length (boxcar). The time signal is always detrended with a linear polynomial.

Parameters:

signalSignal or MultiBandSignal: Time series for which to find the envelope. If it is a MultiBandSignal, it must have the same sampling rate for all bands.
analyticbool, optional: When True, the hilbert transform is used to obtain the envelope of the analytic signal. Otherwise, a RMS envelope is computed with a boxcar window. Default: True.
window_length_samplesint, optional: Window length (boxcar) to average the RMS values. Cannot be None if mode = ‘rms’. Default: None.

Returns:

NDArray[np.float64]: Signal envelope. It has the shape (time sample, channel) or (time sample, band, channel) in case of MultiBandSignal.

dsptoolbox.standard.fade(sig: Signal, fade_type: FadeType, length_fade_seconds: float | None = None, at_start: bool = True, at_end: bool = True) → Signal¶

Applies fading to signal.

Parameters:

sigSignal: Signal to apply fade to.
fade_typeFadeType: Type of fading to be applied.
length_fade_secondsfloat, optional: Fade length in seconds. If None, 2.5% of the signal’s length is used for the fade. Default: None.
at_startbool, optional: When True, the start of signal is faded. Default: True.
at_endbool, optional: When True, the ending of signal is faded. Default: True.

Returns:

new_sigSignal: New Signal

dsptoolbox.standard.fractional_delay(sig: Signal | MultiBandSignal, delay_seconds: float, channels=None, keep_length: bool = False, order: int = 30, side_lobe_suppression_db: float = 60) → Signal | MultiBandSignal¶

Apply fractional time delay to a signal.

Parameters:

sigSignal or MultiBandSignal: Signal to be delayed.
delay_secondsfloat: Delay in seconds.
channelsint or array-like, optional: Channels to be delayed. Pass None to delay all channels. Default: None.
keep_lengthbool, optional: When True, the signal retains its original length and loses information for the latest samples. If only specific channels are to be delayed, and keep_length is set to False, the remaining channels are zero-padded in the end. Default: False.
orderint, optional: Order of the sinc filter, higher order yields better results at the expense of computation time. Default: 30.
side_lobe_suppression_dbfloat, optional: Side lobe suppresion in dB for the Kaiser window. Default: 60.

Returns:

out_sigSignal or MultiBandSignal: Delayed signal.

dsptoolbox.standard.latency(in1: Signal | MultiBandSignal, in2: Signal | MultiBandSignal | None = None, polynomial_points: int = 0) → tuple[ndarray[tuple[Any, ...], dtype[_ScalarT]], ndarray[tuple[Any, ...], dtype[float64]]]¶

Computes latency between two signals using the correlation method. If there is no second signal, the latency between the first and the other channels is computed. in1 is to be understood as a delayed version of in2 for the latency to be positive. The other way around will give the same result but negative.

This function can compute the sub-sample latency between two signals using Zero-Crossing of the analytic (hilbert transformed) correlation function. See [1] for more details. The number of polynomial points taken around the correlation maximum can be arbitrarily set, although some polynomial orders might fail to compute the root. In that case, integer latency will be returned for the respective channel. To avoid fractional latency, use polynomial_points = 0.

The quality of the estimation is assessed by computing the pearson correlation coefficient between the two time series after compensating the delay. See notes for details.

Parameters:

in1Signal or MultiBandSignal: First signal.
in2Signal or MultiBandSignal, optional: Second signal. If it is None, the first channel of in1 will be taken as in2, i.e., the “undelayed” version. Default: None.
polynomial_pointsint, optional: This corresponds to the number of points taken around the root in order to fit a polynomial for the fractional latency. Accuracy might improve with higher orders but it could also lead to ill-conditioned polynomials. In case root finding is not successful, integer latency values are returned. Default: 0.

Returns:

lagsNDArray[np.float64]: Delays in samples. For Signal, the output shape is (channel). In case in2 is None, the length is channels - 1. In the case of MultiBandSignal, output shape is (band, channel).
correlationsNDArray[np.float64]: Correlation for computed delays with the same shape as lags.

Notes

The correlation coefficients have values between [-1, 1]. The closer the absolute value is to 1, the better the latency estimation. This is always computed using the integer latency for performance.

References

[1]: N. S. M. Tamim and F. Ghani, “Hilbert transform of FFT pruned cross correlation function for optimization in time delay estimation,” 2009 IEEE 9th Malaysia International Conference on Communications (MICC), Kuala Lumpur, Malaysia, 2009, pp. 809-814, doi: 10.1109/MICC.2009.5431382.

dsptoolbox.standard.load_pkl_object(path: str)¶

WARNING: This is not secure. Only unpickle data you know! Loads an object with all its attributes and methods.

Parameters:

pathstr: Path to the pickle object.

Returns:

objobject: Unpacked pickle object.

dsptoolbox.standard.lufs_integrated(s: Signal) → float¶

Compute integrated loudness using Loudness Units relative to Full Scale (LUFS or LKFS) of the signal. The computation is done according to [1].

Parameters:

sdsp.Signal: Signal from which to compute the loudness. The signal can have up to 5 channels where the following order is always assumed: (Left, Right, Center, Left Surround, Right Surround). This is relevant for the channel-specific gain compensation.

Returns:

float: Loudness in LUFS-i

Notes

[1] provides exact filter coefficients for a sampling rate of 48 kHz. In this implementation, the corresponding biquad filter parameters were extracted and can be used for any sampling rate provided it is not too low (frequency warping).

References

[1]: Recommendation ITU-R BS.1770-5 (11/2023). Algorithms to measure audio programme loudness and true-peak audio level

dsptoolbox.standard.merge_filters(filters: list[Filter] | FilterBank) → Filter¶

This returns a filter that concatenates all passed filters passed. For FIR filters, it is the result of convolving all passed FIR filters. For IIR, their SOS are concatenated. Mixed lists will raise an error.

Parameters:

filterslist[Filter] or FilterBank: List or FilterBank containing all filters to combine.

Returns:

Filter: Combined filter.

dsptoolbox.standard.modify_signal_length(signal: Signal | MultiBandSignal, start_seconds: float | None, end_seconds: float | None) → Signal | MultiBandSignal¶

This function returns a copy of the signal with added silence at the beginning or the end of the signal. Time samples can also be trimmed when using negative time values.

Parameters:

signalSignal, MultiBandSignal: Signal to apply the length change to.
start_secondsfloat, None: Seconds to add or remove from the start. Positive values append samples while negative ones remove them. Pass None to avoid any modification.
end_secondsfloat, None: Seconds to add or remove from the end. Positive values append samples while negative ones remove them. Pass None to avoid any modification.

Returns:

Signal or MultiBandSignal: Copy of the signal with new length.

dsptoolbox.standard.normalize(sig: Signal | MultiBandSignal, norm_dbfs: float, peak_normalization: bool = True, each_channel: bool = False) → Signal | MultiBandSignal¶

Normalizes a signal to a given dBFS value. It either normalizes each channel or the signal as a whole.

Parameters:

sigSignal or MultiBandSignal: Signal to be normalized.
norm_dbfsfloat: Value in dBFS to reach after normalization.
peak_normalizationbool, optional: When True, signal is normalized at peak. False uses RMS value. See notes. Default: True.
each_channelbool, optional: When True, each channel on its own is normalized. When False, the peak or rms value across all channels is regarded. Default: False.

Returns:

new_sigSignal or MultiBandSignal: Normalized signal.

Notes

Normalization can be done for peak or RMS. The latter might generate a signal with samples above 0 dBFS if signal.constrain_amplitude=False.

dsptoolbox.standard.pad_trim(signal: Signal | MultiBandSignal, desired_length_samples: int, in_the_end: bool = True) → Signal | MultiBandSignal¶

Returns a copy of the signal with padded or trimmed time data. If signal is MultiBandSignal, only same_sampling_rate=True is valid.

Parameters:

signalSignal or MultiBandSignal: Signal to be padded or trimmed.
desired_length_samplesint: Length of resulting signal.
in_the_endbool, optional: Defines if padding or trimming should be done in the beginning or in the end of the signal. Default: True.

Returns:

new_signalSignal or MultiBandSignal: New padded signal.

dsptoolbox.standard.resample(sig: Signal, desired_sampling_rate_hz: int, rescaling: bool = False) → Signal¶

Resamples signal to the desired sampling rate using scipy.signal.resample_poly with an efficient polyphase representation.

Parameters:

sigSignal: Signal to be resampled.
desired_sampling_rate_hzint: Sampling rate to convert the signal to.
rescalingbool, optional: When True, the data is rescaled by dividing by the resampling factor. This retains the magnitude scaling when regarding the unscaled spectrum. Default: False.

Returns:

new_sigSignal: Resampled signal. It is rescaled by the resampling factor.

dsptoolbox.standard.resample_filter(filter: Filter, new_sampling_rate_hz: int) → Filter¶

This function resamples a filter by mapping its zpk representation to the s-plane and reapplying the bilinear transform to the new sampling rate. This approach can deliver satisfactory results for filters whose poles and zeros correspond to low normalized frequencies (~0.1), but higher frequencies will get significantly distorted due to the bilinear mapping.

Parameters:

filterFilter: Filter to resample.
new_sampling_rate_hzint: Target sampling rate in Hz.

Returns:

Filter: Filter with new sampling rate.

dsptoolbox.standard.rms(sig: Signal | MultiBandSignal, in_dbfs: bool = True) → ndarray[tuple[Any, ...], dtype[float64]]¶

Returns Root Mean Squared (RMS) value for each channel.

Parameters:

sigSignal or MultiBandSignal: Signal for which to compute the RMS values. It can be a MultiBandSignal as well.
in_dbfsbool, optional: When True, RMS values are returned in dBFS. Default: True.

Returns:

rms_valuesNDArray[np.float64]: Array with RMS values. If a Signal is passed, it has shape (channel). If a MultiBandSignal is passed, its shape is (bands, channel).

dsptoolbox.standard.spectral_difference(input_1: Signal | Spectrum, input_2: Signal | Spectrum, octave_fraction_smoothing: float = 0.0, energy_normalization: bool = True, complex: bool = False, dynamic_range_db: float | None = 100.0) → Spectrum¶

Compute the spectral difference between two signals or spectra. Their number of channels must match. It is computed as input_1 / input_2.

Parameters:

input_1Signal, Spectrum
input_2Signal, Spectrum
octave_fraction_smoothingfloat, optional: Smoothing can be applied prior to computing the difference. Default: 0 (no smoothing).
energy_normalizationbool, optional: When True, each channel is energy normalized before computing the difference. Default: True.
complexbool, optional: When True, the output will be complex. This is only supported if the inputs are complex (for signals, the saved spectrum parameters must deliver a complex spectrum). Default: False.
dynamic_range_dbfloat, None, optional: Dynamic range in dB to regard when building the difference. Pass None to avoid limiting the range. Default: 100.

Returns:

Spectrum: Difference spectrum.

dsptoolbox.standard.trim_with_level_threshold(signal: Signal, threshold_db: float, at_start: bool = True, at_end: bool = True) → tuple[Signal, int, int]¶

Trim a signal by discarding the edge samples below a certain threshold.

Parameters:

signalSignal: Signal to be trimmed. If it is multichannel, it is trimmed to the minimum index at start and the maximum at end across all channels.
threshold_dbfloat: (Inclusive) Threshold for trimming. Generally in dBFS, but it can be in dBSPL if the signal has been calibrated.
at_startbool, optional: Activate trimming in the beginning. Default: True.
at_endbool, optional: Activate trimming in the end. Default: True.

Returns:

Signal: Copy of input signal with trimmed time series.
int: Start index in the original array.
int: Stop index in the original array.

dsptoolbox.standard.trim_with_time_selection(signal: Signal | MultiBandSignal, start_time_s: float | None, end_time_s: float | None, inclusive: bool = True)¶

Return a trimmed version of the input signal with a selected time window.

Parameters:

signalSignal: Input signal.
start_time_sfloat, None: Start time for the window. Pass None to start the time window at the beginning of the signal.
end_time_sfloat, None: End time for the window. Pass None to place the end of the time window at the end of the signal.
inclusivebool, optional: When True, the bounds are inclusive. Default: True.

Returns:

Signal: Trimmed copy.

dsptoolbox.standard.true_peak_level(signal: Signal | MultiBandSignal) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]¶

Computes true-peak level of a signal using the standardized method by the Rec. ITU-R BS.1770-4. See references.

Parameters:

signalSignal or MultiBandSignal: Signal for which to compute the true-peak level.

Returns:

true_peak_levelsNDArray[np.float64]: True-peak levels (in dBTP) as an array with shape (channels) or (band, channels) in case that the input signal is MultiBandSignal.
peak_levelsNDArray[np.float64]: Peak levels (in dBFS) as an array with shape (channels) or (band, channels) in case that the input signal is MultiBandSignal.

References

https://www.itu.int/rec/R-REC-BS.1770