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

Returns

corresponding midi note number

Return type

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

Returns

note name

Return type

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

Returns

name of the nearest note

Return type

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

Returns

freq – frequency, in Hz

Return type

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.

Returns

Converted frequencies, in midi note.

Return type

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.

Returns

Converted frequencies, in Hz

Return type

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.

Returns

output frequency, in Hz

Return type

float

See also

hztomel()

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.

Returns

output mel

Return type

float

See also

meltohz()

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

Returns

Frequency converted to midi note.

Return type

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

Returns

Frequency converted to FFT bin.

Return type

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

Returns

Frequency converted to Hz.

Return type

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

Returns

Frequency converted to FFT bin.

Return type

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.

Returns

Array of shape (length,) containing the new window.

Return type

fvec

See also

pvoc(), fft()

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

Returns

Linear level of x.

Return type

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

Returns

Level of x, in dB SPL.

Return type

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

Returns

1 if level of vec, in dB SPL, is under level, 0 otherwise.

Return type

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

Returns

1.0 if level of vec in dB SPL is under level, db_spl(vec) otherwise.

Return type

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

Returns

p-norm of the input vector, where p=alpha

Return type

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

Returns

Zero-crossing rate.

Return type

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

Returns

modified input vector

Return type

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

Returns

The swapped vector.

Return type

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)

See also

ishift()

aubio.ishift(vec)

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

Parameters

vec (fvec) – input vector to shift

Returns

The swapped vector.

Return type

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)

See also

shift()

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

Returns

values clamped to the unit circle \([-\pi, \pi[\)

Return type

numpy.ndarray