Function Based API

The function based interface provides most of the functions that are availible as methods of the Signal() and also some that are not directly availible through the Signal() class.

audiotoolbox.crest_factor(signal, axis=0)

Calculate crest factor

Calculates the crest factor of the input signal. The crest factor is defined as:

\[C = \frac{|x_{peak}|}{x_{rms}}\]

where \(x_{peak}\) is the maximum of the absolute value and \(x_{rms}\) is the effective value of the signal.

Parameters:

• signal (ndarray) – The input signal

• axis (int) – The axis for which to calculate the crest factor (default = 0)

Returns:

The crest factor

Return type:

scalar

See also

audiotoolbox.Signal.calc_crest_factor

audiotoolbox.crossfade(sig1: Signal, sig2: Signal, fade_duration: float, fade_type: Literal['linear', 'cos'] = 'linear') → Signal

Crossfade two Signals

Apply a crossfade between the end of the first and the beginning of the second signal.

Parameters:

• sig1 (Signal) – First signal

• sig2 (Signal) – Second signal

• fade_duration (float) – duration of the fade in seconds

• fade_type (Literal["linear", "cos"]) – Type of the crossfade

Returns:

The resulting signal.

Return type:

Signal

audiotoolbox.dbspl_to_phon(frequency, l_dbspl, interpolate=False, limit=True)

loudness levels from sound pressure level (following DIN ISO 226:2006-04)

Calulates the loudness level at a given frequency from the sound pressure level following DIN ISO 226:2006-04

The normed values are tabulated for the following frequencies and sound pressure levels:

1. 20phon to 90phon

• 20, 25, 31.5, 40, 50, 63, 80, 100, 125, 160, 200, 250, 315,

• 400, 500, 630, 800, 1000, 1250, 1600, 2000, 2500, 3150, 4000

2. 20phon to 80phon

*5000, 6300, 8000, 10000, 12500

Values for other frequencies can be interpolated (cubic spline) by setting the parameter interpolate to True. The check for correct sound pressure levels can be switched off by setting limit=False. In poth cases, the results are not covered by the DIN ISO norm

Parameters:

• frequency (scalar) – The frequency in Hz. must be one of the tabulated values above if interpolate = False

• l_dbspl (scalar) – sound pressure level that should be converted

• interpolate (bool, optional) – Defines whether the tabulated values from the norm should be interpolated. If set to True, the tabulated values will be interpolated using a cubic spline (default = False)

• limit (bool, optional) – Defines whether the limits of the norm should be checked (default = True)

Returns:

scalar

Return type:

The loudnes level level in dB SPL

audiotoolbox.from_file(filename: str, start: int = 0, stop: int | None = None) → Signal

Read signal from an audio file.

This function reads a signal from an audio file and returns it as a Signal object. The signal can be read from a specific start point and up to a specific stop point. The function supports all audio file formats supported by libsndfile, such as WAV, FLAC, AIFF, and more.

Parameters:

• filename (str) – The path to the audio file to read.

• start (int, optional) – The starting sample index from which to read the signal. Default is 0.

• stop (int, optional) – The stopping sample index up to which to read the signal. If None, the signal is read until the end of the file. Default is None.

Returns:

The Signal object containing the audio data read from the file.

Return type:

Signal

Raises:

ValueError – If the audio file cannot be read or if the file format is not supported.

Examples

Read a signal from a file starting at the beginning:

>>> sig = from_file("example.wav")

Read a signal from a file starting at sample index 1000 and stopping at sample index 5000:

>>> sig = from_file("example.wav", start=1000, stop=5000)

See also

audiotoolbox.Signal.from_file

Method to load a signal into an existing Signal object.

audiotoolbox.nsamples(duration, fs=None)

Number of samples in a signal with a given duration.

This function calculates the number of samples that will be returned when generating a signal with a certain duration and sampling rates. The number is determined by multiplying the sampling rate with the duration and rounding to the next integer.

Parameters:

• duration (scalar) – The signals duration in seconds. Or Signal class

• fs (scalar (optional)) – The sampling rate for the tone. Is ignored when Signal class is passed

Returns:

number of samples in the signal

Return type:

int

audiotoolbox.phase2time(phase, frequency)

Pase to Time for a given frequency

\[t = \frac{\phi}{2 \pi f}\]

Parameters:

phase (ndarray) – The phase values to convert

Returns:

converted time values

Return type:

ndarray

audiotoolbox.phon_to_dbspl(frequency, l_phon, interpolate=False, limit=True)

Sound pressure levels from loudness level (following DIN ISO 226:2006-04)

Calulates the sound pressure level at a given frequency that is necessary to reach a specific loudness level following DIN ISO 226:2006-04

The normed values are tabulated for the following frequencies and sound pressure levels:

1. 20phon to 90phon

• 20 Hz, 25 Hz, 31.5 Hz, 40 Hz, 50 Hz, 63 Hz, 80 Hz, 100 Hz, 125 Hz, 160 Hz, 200 Hz, 250 Hz, 315 Hz, 400 Hz, 500 Hz, 630 Hz, 800 Hz, 1000 Hz, 1250 Hz, 1600 Hz, 2000 Hz, 2500 Hz, 3150 Hz, 4000 Hz

2. 20phon to 80phon

• 5000 Hz, 6300 Hz, 8000 Hz, 10000 Hz, 12500 Hz

Values for other frequencies can be interpolated (cubic spline) by setting the parameter interpolate=True. The check for correct sound pressure levels can be switched off by setting limit=False. In both cases, the results are not covered by the DIN ISO norm

Parameters:

• frequency (scalar) – The frequency in Hz. must be one of the tabulated values above if interpolate = False

• l_phon (scalar) – loudness level that should be converted

• interpolate (bool, optional) – Defines whether the tabulated values from the norm should be interpolated. If set to True, the tabulated values will be interpolated using a cubic spline (default = False)

• limit (bool, optional) – Defines whether the limits of the norm should be checked (default = True)

Returns:

The soundpressure level in dB SPL

Return type:

scalar

audiotoolbox.schroeder_phase(harmonics, amplitudes, phi0=0.0)

Phases for a schroeder phase harmonic complex

This function calculates the phases for a schroeder phase harmonic comlex following eq. 11 of [1]:

\[\phi_n = \phi_l - 2\pi \sum\limits^{n-1}_{l=1}(n - l)p_l\]

\(n\) is the order of the harmonic and p_l is the relative power of the spectral component p_l.

Parameters:

• harmonics (ndarray) – A vector of harmonics for which the schroeder phases should be calculated

• amplitudes (ndarray) – A vector of amplitudes for the given harmonics

• phi0 (scalar) – The starting phase of the first harmonic (default = 0)

Returns:

The phase values for the harmonic compontents

Return type:

ndarray

References

[1] (1,2)

Schroeder, M. (1970). Synthesis of low-peak-factor signals and binary sequences with low autocorrelation (corresp.). IEEE Transactions on Information Theory, 16(1), 85-89

audiotoolbox.shift_signal(signal, nr_samples)

Shift signal by nr_samples samples.

Shift a signal by a given number of samples. The shift happens

cyclically so that the length of the signal does not change.

Parameters:

• signal (array_like) – Input signal

• nr_samples (int) – The number of samples that the signal should be shifted. Must be positive if mode is ‘zeros’.

Returns:

• res (ndarray) – The shifted signal

• See Also

• ———

• delay_signal (A high level delaying / shifting function.)

• fftshift_signal (Shift a signal in frequency space.)

audiotoolbox.time2phase(time, frequency)

Time to phase for a given frequency.

\[\phi = 2 \pi t f\]

Parameters:

time (ndarray) – The time values to convert

Returns:

converted phase values

Return type:

ndarray

audiotoolbox.filter

Individual filter can either be applied by directly calling the respective filter functions such as filter.gammatone() or by using the unified interfaces for filter.bandpass(), filter.lowpass() and filter.highpass() filters. When using the unified interface, all additional arguments are passed to the respective filter functions.

audiotoolbox.filter.a_weighting(signal, fs=None)

Apply A weighting filter to a signal.

Apply an digital A-weighting filter following IEC 61672-1. Take care that the sampling frequency is high enough to prevent steep high frequency drop-off. A sampling frequency of about 48 kHz should be sufficent to result in a Class 1 filter following IEC 61672-1.

Parameters:

signalSignal or np.ndarray

The input signal

fsscalar or None

The signals sampling rate in Hz.

rtype:

The filtered signal.

audiotoolbox.filter.bandpass(signal, fc, bw, filter_type, fs=None, **kwargs)

Apply a bandpass filter to the Signal.

This function provieds a unified interface to all bandpass filters implemented in audiotoolbox.

Parameters:

• signal (ndarray or Signal) – The input signal.

• fc (float) – The center frequency in Hz.

• bw (float) – The bandwidth in Hz

• filter_type (string) – The filter type, ‘gammatone’, ‘butter’, ‘brickwall’

• fs (None or int) – The sampling frequency, must be provided if not using the Signal class.

• **kwargs – Further arguments such as ‘order’ that are passed to the filter functions.

Returns:

Signal

Return type:

The filtered Signal

audiotoolbox.filter.brickwall(signal, low_f, high_f, fs)

Brickwall filter.

Bandpass filters an input signal by setting all frequency outside of the passband [low_f, high_f] to zero.

Parameters:

• signal (ndarray) – The input signal

• low_f (scalar) – low cutoff in Hz

• high_f (scalar or None) – high cutoff in Hz, if None, high_f will be set to fs/2

• fs (scalar) – The signals sampling rate in Hz

Return type:

The filtered signal

audiotoolbox.filter.butterworth(signal, low_f, high_f, fs=None, order=2, return_states=False, states=None)

Apply a butterwoth filter

Applies the cascated second-order sections representation of a butterwoth IIR filter.

To construct a lowpass filter, set low_f to None. For a highpass, set high_f to None.

Parameters:

• low_f (scalar or None) – lower cutoff in Hz

• high_f (scalar or None) – high cutoff in Hz

• fs (scalar) – sampling frequency in Hz

• order (integer, optional) – filter order (default = 2)

• return_states (bool, optional) – Wheather the filter states should be returned. (default=False)

• states (True, None or array_like, optional) – Inital conditions for the filter. if True, the conditions for a step response are constructed. if set to None, the inital rest is assumed (all 0). Otherwise, expects the inital filter delay values.

Returns:

ndarray

Return type:

The filtered signal

audiotoolbox.filter.c_weighting(signal, fs=None)

Apply C weighting filter to a signal.

Apply an digital C-weighting filter following IEC 61672-1. Take care that the sampling frequency is high enough to prevent steep high frequency drop-off. A sampling frequency of about 48 kHz should be sufficent to result in a Class 1 filter following IEC 61672-1.

Parameters:

signalSignal or np.ndarray

The input signal

fsscalar or None

The signals sampling rate in Hz.

rtype:

The filtered signal.

audiotoolbox.filter.gammatone(signal, fc, bw, fs, order=4, attenuation_db='erb', return_complex=True)

Apply a gammatone filter to the signal.

Applys a gammatone filter following [Hohmann2002] to the input signal and returns the filtered signal.

Parameters:

• signal (ndarray) – The input signal

• fs (int) – The sample frequency in Hz

• fc (scalar) – The center frequency of the filter in Hz

• bw (scalar) – The bandwidth of the filter in Hz

• order (int) – The filter order (default = 4)

• attenuation_db (scalar or 'erb') – The attenuation at half bandwidth in dB (default = ‘erb’). If set to ‘erb’, the bandwidth is interpreted as the rectangular equivalent bw.

• return_complex (bool) – Whether the complex filter output or only it’s real part is returned (default = True)

Return type:

The filtered signal.

References

[Hohmann2002]

Hohmann, V., Frequency analysis and synthesis using a Gammatone filterbank, Acta Acustica, Vol 88 (2002), 43 -3442

audiotoolbox.filter.highpass(signal, f_cut, filter_type, fs=None, **kwargs)

Apply a highpass filter to the Signal.

This function provieds a unified interface to all highpass filters implemented in audiotoolbox.

Parameters:

• signal (ndarray or Signal) – The input signal.

• f_cut (float) – The cutoff frequency in Hz

• filter_type (string) – The filter type, ‘butter’, ‘brickwall’

• **kwargs – Further arguments such as ‘order’ that are passed to the filter functions.

Returns:

Signal

Return type:

The filtered Signal

audiotoolbox.filter.lowpass(signal, f_cut, filter_type, fs=None, **kwargs)

Apply a lowpass filter to the Signal.

This function provieds a unified interface to all lowpass filters implemented in audiotoolbox.

Parameters:

• signal (ndarray or Signal) – The input signal.

• f_cut (float) – The cutoff frequency in Hz

• filter_type (string) – The filter type, ‘butter’, ‘brickwall’

• fs (None or int) – The sampling frequency, must be provided if not using the Signal class.

• **kwargs – Further arguments such as ‘order’ that are passed to the filter functions.

Returns:

Signal

Return type:

The filtered Signal

Filterbanks are created using the create_filterbank() command

audiotoolbox.filter.bank.auditory_gamma_bank(fs, flow=16, fhigh=16000, step=1, **kwargs)

Equivalent Rectangular Bandwidth spaced gammatone filterbank.

Creates a gammatone filterbank with center freequencies equally spaced on the auditory ERB scale as proposed by [1].

..[1] Glasberg, B. R., & Moore, B. C. (1990). Derivation of

auditory filter shapes from notched-noise data. Hearing Research, 47(1-2), 103-138.

Parameters:

• fs (int) – sampling frequency

• flow (scalar (optional)) – Lowest center frequency in Hz. (default = 16 Hz)

• fhigh (scalar (optional)) – Highest center frequency in Hz. (default = 16 kHz)

• step (scalar (optional)) – Stepsize between filters on the ERB scale. Defauls to 1 filter per ERB

• **kwargs – Further paramters such as filter order to pass to the filter.GammaToneBank function. Values can either be an ndarray that matches the length of fc or a single value in which case this value is used for all filters.

Returns:

GammaToneBank

Return type:

The filterbank.

audiotoolbox.filter.bank.create_filterbank(fc: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], bw: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], filter_type: Literal['butter', 'gammatone', 'brickwall'], fs: int, **kwargs) → FilterBank

Creates a filterbank object

Parameters:

• fc (ndarray) – Center frequencies in Hz

• bw (ndarray) – Filter Bandwidths in Hz

• filter_type ('butter', 'gammatone') – Type of Bandpass filter

• fs (int) – Sampling frequency

• **kwargs – Further paramters such as filter order to pass to the Filter function, see filter documenation for details. Value can either be an ndarray that matches the length of fc or a single value in which case this value is used for all filters.

Return type:

FilterBank Object

audiotoolbox.filter.bank.octave_bank(fs: int, flow: float = 24.8, fhigh: float = 20158.0, oct_fraction: int = 3, round_to_band: bool = True, **kwargs) → ButterworthBank

Fractional Octave spaced butterworth filterbank.

Creates a fractional octave filterbank based on butterworth filters. By default, This function will create a 1/3 octave bank. If round_to_band is set to True (default), center frequencies will be adjusted to fit ANSI S1.11-2004.

Parameters:

• fs (int) – sampling frequency

• flow (float (optional)) – Lowest center frequency in Hz. (default = 24.8 Hz)

• fhigh (float (optional)) – Highest center frequency in Hz. (default = 20158 Hz)

• oct_frqction (int (optional)) – The fraction of an octave used to space the filter. e.g. 3 for 1/3 octave spacing. (default = 3)

• round_to_band (bool (optional)) – Indicates if the band numbers should be rounde to the next full integer. If set to True, this will result in center frequencies following ANSI S1.11-2004

• **kwargs – Further paramters such as filter order to pass to the filter.ButterworthBank function. Values can either be an ndarray that matches the length of fc or a single value in which case this value is used for all filters.

Returns:

ButterworthBank

Return type:

The filterbank