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
- 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
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:
- 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:
- 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
- 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
- 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
sourceto 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 (
listofint) – time stamps at which to slice, in samplestimestamps_end (
listofint(optional)) – time stamps at which to end the slicesoutput_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:
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
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
- 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
- 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
- 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
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.
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.
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
- aubio.ishift(vec)¶
Swap right and left partitions of a vector, in-place.
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
- 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: