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.

See also

midi2note(), freqtomidi(), miditofreq()

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].

See also

note2midi(), miditofreq(), freqtomidi()

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}\]

See also

db_spl(), silence_detection(), level_detection()

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’.

See also

level_lin(), silence_detection(), level_detection()

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

See also

level_detection(), db_spl(), level_lin()

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

See also

silence_detection(), db_spl(), level_lin()

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