# Utilities¶

This section documents various helper functions included in the aubio library.

## Note name conversion¶

aubio.note2midi(note)[source]

Convert note name to midi note number.

Input string note should be composed of one note root and one octave, with optionally one modifier in between.

List of valid components:

• note roots: C, D, E, F, G, A, B,
• modifiers: b, #, as well as unicode characters 𝄫, , , and 𝄪,
• octave numbers: -1 -> 11.
Parameters: note (str) – note name corresponding midi note number int

Examples

>>> aubio.note2midi('C#4')
61
>>> aubio.note2midi('B♭5')
82

Raises: TypeError – If note was not a string. ValueError – If an error was found while converting note.
aubio.midi2note(midi)[source]

Convert midi note number to note name.

Parameters: midi (int [0, 128]) – input midi note number note name str

Examples

>>> aubio.midi2note(70)
'A#4'
>>> aubio.midi2note(59)
'B3'

Raises: TypeError – If midi was not an integer. ValueError – If midi is out of the range [0, 128].
aubio.freq2note(freq)[source]

Convert frequency in Hz to nearest note name.

Parameters: freq (float [0, 23000[) – input frequency, in Hz name of the nearest note str

Example

>>> aubio.freq2note(440)
'A4'
>>> aubio.freq2note(220.1)
'A3'

aubio.note2freq(note)[source]

Convert note name to corresponding frequency, in Hz.

Parameters: note (str) – input note name freq – frequency, in Hz float [0, 23000[

Example

>>> aubio.note2freq('A4')
440
>>> aubio.note2freq('A3')
220.1


## Frequency conversion¶

aubio.freqtomidi(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])

Convert frequency [0; 23000[ to midi [0; 128[.

Parameters: x (numpy.ndarray) – Array of frequencies, in Hz. Converted frequencies, in midi note. numpy.ndarray
aubio.miditofreq(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])

Convert midi [0; 128[ to frequency [0, 23000].

Parameters: x (numpy.ndarray) – Array of frequencies, in midi note. Converted frequencies, in Hz numpy.ndarray
aubio.meltohz(m, htk=False)

Convert a scalar from mel scale to frequency.

Parameters: m (float) – input mel htk (bool) – if True, use Htk mel scale instead of Slaney. output frequency, in Hz float
aubio.hztomel(f, htk=False)

Convert a scalar from frequency to mel scale.

Parameters: m (float) – input frequency, in Hz htk (bool) – if True, use Htk mel scale instead of Slaney. output mel float
aubio.bintomidi(fftbin, samplerate, fftsize)

Convert FFT bin to frequency in midi note, given the sampling rate and the size of the FFT.

Parameters: fftbin (float) – input frequency bin samplerate (float) – sampling rate of the signal fftsize (float) – size of the FFT Frequency converted to midi note. float

Example

>>> aubio.bintomidi(10, 44100, 1024)
68.62871551513672

aubio.miditobin(midi, samplerate, fftsize)

Convert frequency in midi note to FFT bin, given the sampling rate and the size of the FFT.

Parameters: midi (float) – input frequency, in midi note samplerate (float) – sampling rate of the signal fftsize (float) – size of the FFT Frequency converted to FFT bin. float

Examples

>>> aubio.miditobin(69, 44100, 1024)
10.216779708862305
>>> aubio.miditobin(75.08, 32000, 512)
10.002175331115723

aubio.bintofreq(fftbin, samplerate, fftsize)

Convert FFT bin to frequency in Hz, given the sampling rate and the size of the FFT.

Parameters: fftbin (float) – input frequency bin samplerate (float) – sampling rate of the signal fftsize (float) – size of the FFT Frequency converted to Hz. float

Example

>>> aubio.bintofreq(10, 44100, 1024)
430.6640625

aubio.freqtobin(freq, samplerate, fftsize)

Convert frequency in Hz to FFT bin, given the sampling rate and the size of the FFT.

Parameters: midi (float) – input frequency, in midi note samplerate (float) – sampling rate of the signal fftsize (float) – size of the FFT Frequency converted to FFT bin. float

Examples

>>> aubio.freqtobin(440, 44100, 1024)
10.216779708862305


## Audio file slicing¶

aubio.slice_source_at_stamps(source_file, timestamps, timestamps_end=None, output_dir=None, samplerate=0, hopsize=256, create_first=False)[source]

Slice a sound file at given timestamps.

This function reads source_file and creates slices, new smaller files each starting at t in timestamps, a list of integer corresponding to time locations in source_file, in samples.

If timestamps_end is unspecified, the slices will end at timestamps_end[n] = timestamps[n+1]-1, or the end of file. Otherwise, timestamps_end should be a list with the same length as timestamps containing the locations of the end of each slice.

If output_dir is unspecified, the new slices will be written in the current directory. If output_dir is a string, new slices will be written in output_dir, after creating the directory if required.

The default samplerate is 0, meaning the original sampling rate of source_file will be used. When using a sampling rate different to the one of the original files, timestamps and timestamps_end should be expressed in the re-sampled signal.

The hopsize parameter simply tells source to use this hopsize and does not change the output slices.

If create_first is True and timestamps does not start with 0, the first slice from 0 to timestamps[0] - 1 will be automatically added.

Parameters: source_file (str) – path of the resource to slice timestamps (list of int) – time stamps at which to slice, in samples timestamps_end (list of int (optional)) – time stamps at which to end the slices output_dir (str (optional)) – output directory to write the slices to samplerate (int (optional)) – samplerate to read the file at hopsize (int (optional)) – number of samples read from source per iteration create_first (bool (optional)) – always create the slice at the start of the file

Examples

Create two slices: the first slice starts at the beginning of the input file loop.wav and lasts exactly one second, starting at sample 0 and ending at sample 44099; the second slice starts at sample 44100 and lasts until the end of the input file:

>>> aubio.slice_source_at_stamps('loop.wav', [0, 44100])


Create one slice, from 1 second to 2 seconds:

>>> aubio.slice_source_at_stamps('loop.wav', [44100], [44100 * 2 - 1])


Notes

Slices may be overlapping. If timestamps_end is 1 element shorter than timestamps, the last slice will end at the end of the file.

## Windowing¶

aubio.window(window_type, size)

Create a window of length size. window_type should be one of the following:

• default (same as hanningz).
• ones
• rectangle
• hamming
• hanning
• hanningz [1]
• blackman
• blackman_harris
• gaussian
• welch
• parzen
Parameters: window_type (str) – Type of window. size (int) – Length of window. Array of shape (length,) containing the new window. fvec

Examples

Compute a zero-phase Hann window on 1024 points:

>>> aubio.window('hanningz', 1024)
array([  0.00000000e+00,   9.41753387e-06,   3.76403332e-05, ...,
8.46982002e-05,   3.76403332e-05,   9.41753387e-06], dtype=float32)


Plot different window types with matplotlib:

>>> import matplotlib.pyplot as plt
>>> modes = ['default', 'ones', 'rectangle', 'hamming', 'hanning',
...          'hanningz', 'blackman', 'blackman_harris', 'gaussian',
...          'welch', 'parzen']; n = 2048
>>> for m in modes: plt.plot(aubio.window(m, n), label=m)
...
>>> plt.legend(); plt.show()


Note

The following examples contain the equivalent source code to compute each type of window with NumPy:

>>> n = 1024; x = np.arange(n, dtype=aubio.float_type)
>>> ones = np.ones(n).astype(aubio.float_type)
>>> rectangle = 0.5 * ones
>>> hanning = 0.5 - 0.5 * np.cos(2 * np.pi * x / n)
>>> hanningz = 0.5 * (1 - np.cos(2 * np.pi * x / n))
>>> hamming = 0.54 - 0.46 * np.cos(2.*np.pi * x / (n - 1))
>>> blackman = 0.42 \
...          - 0.50 * np.cos(2 * np.pi * x / (n - 1)) \
...          + 0.08 * np.cos(4 * np.pi * x / (n - 1))
>>> blackman_harris = 0.35875 \
...       - 0.48829 * np.cos(2 * np.pi * x / (n - 1)) \
...       + 0.14128 * np.cos(4 * np.pi * x / (n - 1)) \
...       + 0.01168 * np.cos(6 * np.pi * x / (n - 1))
>>> gaussian = np.exp( - 0.5 * ((x - 0.5 * (n - 1)) \
...                            / (0.25 * (n - 1)) )**2 )
>>> welch = 1 - ((2 * x - n) / (n + 1))**2
>>> parzen = 1 - np.abs((2 * x - n) / (n + 1))
>>> default = hanningz


References

 [1] Amalia de Götzen, Nicolas Bernardini, and Daniel Arfib. Traditional (?) implementations of a phase vocoder: the tricks of the trade. In Proceedings of the International Conference on Digital Audio Effects (DAFx-00), pages 37–44, University of Verona, Italy, 2000. (online version).

## Audio level detection¶

aubio.level_lin(x)

Compute sound pressure level of x, on a linear scale.

Parameters: x (fvec) – input vector Linear level of x. float

Example

>>> aubio.level_lin(aubio.fvec(numpy.ones(1024)))
1.0


Note

Computed as the average of the squared amplitudes:

$L = \frac {\sum_{n=0}^{N-1} {x_n}^2} {N}$
aubio.db_spl(x)

Compute Sound Pressure Level (SPL) of x, in dB.

Parameters: x (fvec) – input vector Level of x, in dB SPL. float

Example

>>> aubio.db_spl(aubio.fvec(np.ones(1024)))
1.0
>>> aubio.db_spl(0.7*aubio.fvec(np.ones(32)))
-3.098040819168091


Note

Computed as log10 of level_lin():

${SPL}_{dB} = log10{\frac {\sum_{n=0}^{N-1}{x_n}^2} {N}}$

This quantity is often incorrectly called ‘loudness’.

aubio.silence_detection(vec, level)

Check if level of vec, in dB SPL, is under a given threshold.

Parameters: vec (fvec) – input vector level (float) – level threshold, in dB SPL 1 if level of vec, in dB SPL, is under level, 0 otherwise. int

Examples

>>> aubio.silence_detection(aubio.fvec(32), -100.)
1
>>> aubio.silence_detection(aubio.fvec(np.ones(32)), 0.)
0

aubio.level_detection(vec, level)

Check if vec is above threshold level, in dB SPL.

Parameters: vec (fvec) – input vector level (float) – level threshold, in dB SPL 1.0 if level of vec in dB SPL is under level, db_spl(vec) otherwise. float

Example

>>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -3.)
1.0
>>> aubio.level_detection(0.7*aubio.fvec(np.ones(1024)), -4.)
-3.0980708599090576


## Vector utilities¶

aubio.alpha_norm(vec, alpha)

Compute alpha normalisation factor of vector vec.

Parameters: vec (fvec) – input vector alpha (float) – norm factor p-norm of the input vector, where p=alpha float

Example

>>> a = aubio.fvec(np.arange(10)); alpha = 2
>>> aubio.alpha_norm(a, alpha), (sum(a**alpha)/len(a))**(1./alpha)
(5.338539123535156, 5.338539126015656)


Note

Computed as:

$l_{\alpha} = \|\frac{\sum_{n=0}^{N-1}{{x_n}^{\alpha}}}{N}\|^{1/\alpha}$
aubio.zero_crossing_rate(vec)

Compute zero-crossing rate of vec.

Parameters: vec (fvec) – input vector Zero-crossing rate. float

Example

>>> a = np.linspace(-1., 1., 1000, dtype=aubio.float_type)
>>> aubio.zero_crossing_rate(a), 1/1000
(0.0010000000474974513, 0.001)

aubio.min_removal(vec)

Remove the minimum value of a vector to each of its element.

Modifies the input vector in-place and returns a reference to it.

Parameters: vec (fvec) – input vector modified input vector fvec

Example

>>> aubio.min_removal(aubio.fvec(np.arange(1,4)))
array([0., 1., 2.], dtype=float32)

aubio.shift(vec)

Swap left and right partitions of a vector, in-place.

Parameters: vec (fvec) – input vector to shift The swapped vector. fvec

Notes

The input vector is also modified.

For a vector of length N, the partition is split at index N - N//2.

Example

>>> aubio.shift(aubio.fvec(np.arange(3)))
array([2., 0., 1.], dtype=float32)

aubio.ishift(vec)

Swap right and left partitions of a vector, in-place.

Parameters: vec (fvec) – input vector to shift The swapped vector. fvec

Notes

The input vector is also modified.

Unlike with shift(), the partition is split at index N//2.

Example

>>> aubio.ishift(aubio.fvec(np.arange(3)))
array([1., 2., 0.], dtype=float32)

aubio.unwrap2pi(x, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj])

Map angle to unit circle $$[-\pi, \pi[$$.

Parameters: x (numpy.ndarray) – input array values clamped to the unit circle $$[-\pi, \pi[$$ numpy.ndarray