Basics (libfmp.b)¶

The FMP notebooks provide detailed textbook-like explanations of central techniques and algorithms implemented in the libfmp. The part of FMP related to this module is available at the following URL:

https://www.audiolabs-erlangen.de/resources/MIR/FMP/B/B.html

libfmp.b.b_annotation.cut_audio(fn_in, fn_out, start_sec, end_sec, normalize=True, write=True, Fs=22050)[source]¶

Cut an audio file using specificed start and end time positions and writes the result to a new audio file.

Parameters

fn_in (str) – Filename and path for input audio file
fn_out (str) – Filename and path for input audio file
start_sec (float) – Start time position (in seconds) of cut
end_sec (float) – End time position (in seconds) of cut
normalize (bool) – If True, then normalize audio (with max norm) (Default value = True)
write (bool) – If True, then write audio (Default value = True)
Fs (scalar) – Sampling rate of audio (Default value = 22050)

Returns

x_cut (np.ndarray) – Cut audio

libfmp.b.b_annotation.cut_csv_file(fn_in, fn_out, start_sec, end_sec, write=True)[source]¶

Cut a annotation CSV file (where each row corresponds to the four variables start, end, pitch, and label) using specificed start and end time positions and writes the result to a new CSV file.

Parameters

fn_in (str) – Filename and path for input audio file
fn_out (str) – Filename and path for input audio file
start_sec (float) – Start time position (in seconds) of cut
end_sec (float) – End time position (in seconds) of cut
write (bool) – If True, then write csv file (Default value = True)

Returns

ann_cut (list) – Cut annotation file

libfmp.b.b_annotation.read_csv(fn, header=True, add_label=False)[source]¶

Read a CSV file in table format and creates a pd.DataFrame from it, with observations in the rows and variables in the columns.

Parameters

fn (str) – Filename
header (bool) – Boolean (Default value = True)
add_label (bool) – Add column with constant value of add_label (Default value = False)

Returns

df (pd.DataFrame) – Pandas DataFrame

libfmp.b.b_annotation.write_csv(df, fn, header=True)[source]¶

Write a pd.DataFrame to a CSV file, with observations in the rows and variables in the columns.

Parameters

df (pd.DataFrame) – Pandas DataFrame
fn (str) – Filename
header (bool) – Boolean (Default value = True)

libfmp.b.b_audio.audio_player_list(signals, rates, width=270, height=40, columns=None, column_align='center')[source]¶

Generate a list of HTML audio players tags for a given list of audio signals.

Notebook: B/B_PythonAudio.ipynb

Parameters

signals (list) – List of audio signals
rates (list) – List of sample rates
width (int) – Width of player (either number or list) (Default value = 270)
height (int) – Height of player (either number or list) (Default value = 40)
columns (list) – Column headings (Default value = None)
column_align (str) – Left, center, right (Default value = ‘center’)

libfmp.b.b_audio.read_audio(path, Fs=None, mono=False)[source]¶

Read an audio file into a np.ndarray.

Parameters

path (str) – Path to audio file
Fs (scalar) – Resample audio to given sampling rate. Use native sampling rate if None. (Default value = None)
mono (bool) – Convert multi-channel file to mono. (Default value = False)

Returns

x (np.ndarray) – Waveform signal
Fs (scalar) – Sampling rate

libfmp.b.b_audio.write_audio(path, x, Fs)[source]¶

Write a signal (as np.ndarray) to an audio file.

Parameters

path (str) – Path to audio file
x (np.ndarray) – Waveform signal
Fs (scalar) – Sampling rate

class libfmp.b.b_layout.FloatingBox(align='middle')[source]¶

Floating box for matplotlib plots. The added figures are part of a floating box.

Inspired by https://stackoverflow.com/a/49566213/2812618

Attributes: html – The HTML string

add_fig(fig)[source]¶

Saves a PNG representation of a matplotlib figure.

Parameters: fig – A matplotlib figure

add_html(html)[source]¶

Add HTML to floating box.

Parameters: html – HTML string

show()[source]¶: Display the accumulated HTML

class libfmp.b.b_plot.MultiplePlotsWithColorbar(num_plots, figsize=(8, 4), dpi=72, cbar_ratio=0.1, height_ratios=None)[source]¶

Two-column layout plot, where the first column is for user-given plots and the second column is for colorbars if the corresponding row needs a colorbar.

Attributes

axes – A list of axes for the first column.
cbar_axes – A list of axes for the second column.
num_plots – Number of rows, as given to init method.

make_colorbars()[source]¶: Create colorbars if the corresponding row needs a colorbar, or hides the axis in other cases.

libfmp.b.b_plot.check_line_annotations(annot, default_label='')[source]¶

Check a list of annotations with time positions and labels. If label is missing, adds an default label.

Parameters

annot – A List of the form of [(time_position, label), ...], or [(time_position, ), ...], or [time_position, ...]
default_label – The default label used if label is missing

Returns

annot – A List of tuples in the form of [(time_position, label), ...]

libfmp.b.b_plot.check_segment_annotations(annot, default_label='')[source]¶

Check a list of segment annotations. If label is missing, adds an default label.

Parameters

annot – A List of the form of [(start_position, end_position, label), ...], or [(start_position, end_position), ...]
default_label – The default label used if label is missing

Returns

annot – A List of tuples in the form of [(start_position, end_position, label), ...]

libfmp.b.b_plot.color_argument_to_dict(colors, labels_set, default='gray')[source]¶

Create a dictionary that maps labels to colors.

Parameters

colors – Several options: 1. string of FMP_COLORMAPS, 2. string of matplotlib colormap, 3. list or np.ndarray of matplotlib color specifications, 4. dict that assigns labels to colors
labels_set – List of all labels
default – Default color, used for labels that are in labels_set, but not in colors

Returns

color_dict – Dictionary that maps labels to colors

libfmp.b.b_plot.compressed_gray_cmap(alpha=5, N=256, reverse=False)[source]¶

Create a logarithmically or exponentially compressed grayscale colormap.

Parameters

alpha (float) – The compression factor. If alpha > 0, it performs log compression (enhancing black colors). If alpha < 0, it performs exp compression (enhancing white colors). Raises an error if alpha = 0. (Default value = 5)
N (int) – The number of rgb quantization levels (usually 256 in matplotlib) (Default value = 256)
reverse (bool) – If False then “white to black”, if True then “black to white” (Default value = False)

Returns

color_wb (mpl.colors.LinearSegmentedColormap) – The colormap

libfmp.b.b_plot.plot_annotation_line(annot, ax=None, label_keys=None, colors='FMP_1', figsize=(6, 1), direction='horizontal', time_min=None, time_max=None, time_axis=True, nontime_axis=False, swap_time_ticks=False, axis_off=False, dpi=72)[source]¶

Create a line plot visualization for a list of annotations with time positions and labels.

Parameters

annot – A List of tuples in the form of [(time_position, label), ...]
ax – The Axes instance to plot on. If None, will create a figure and axes. (Default value = None)
label_keys – A dict, where the keys are the labels used in annot. The values are dicts, which are used as keyword arguments for matplotlib.pyplot.axvline or matplotlib.pyplot.axhline. (Default value = None)
colors – Several options: 1. string of FMP_COLORMAPS, 2. string of matplotlib colormap, 3. list or np.ndarray of matplotlib color specifications, 4. dict that assigns labels to colors (Default value = ‘FMP_1’)
figsize – Width, height in inches (Default value = (6, 1)
direction – ‘vertical’ or ‘horizontal’ (Default value = ‘horizontal’)
time_min – Minimal limit for time axis. If None, will be min annotation. (Default value = None)
time_max – Maximal limit for time axis. If None, will be max from annotation. (Default value = None)
time_axis – Display time axis ticks or not (Default value = True)
nontime_axis – Display non-time axis ticks or not (Default value = False)
swap_time_ticks – For horizontal: xticks up; for vertical: yticks left (Default value = False)
axis_off – Calls ax.axis(‘off’) (Default value = False)
dpi – Dots per inch (Default value = 72)

Returns

fig – The created matplotlib figure or None if ax was given.
ax – The used axes.

libfmp.b.b_plot.plot_annotation_line_overlay(*args, **kwargs)[source]¶

Plot segment annotations as overlay.

See libfmp.b.b_plot.plot_annotation_line() for parameters and return values.

libfmp.b.b_plot.plot_annotation_multiline(annot, ax=None, label_keys=None, colors='FMP_1', figsize=(6, 1.5), direction='horizontal', sort_labels=None, time_min=None, time_max=None, time_axis=True, swap_time_ticks=False, axis_off=False, dpi=72)[source]¶

Create a multi-line plot visualization for a list of annotations with time positions and labels. The multi-line plot visualization comprises a separate line plot visualization for each label category stacked horizontally or vertically (depending on the direction keyword).

Parameters

annot – A List of tuples in the form of [(time_position, label), ...]
ax – The Axes instance to plot on. If None, will create a figure and axes. (Default value = None)
label_keys – A dict, where the keys are the labels used in annot. The values are dicts, which are used as keyword arguments for matplotlib.pyplot.axvline or matplotlib.pyplot.axhline. (Default value = None)
colors – Several options: 1. string of FMP_COLORMAPS, 2. string of matplotlib colormap, 3. list or np.ndarray of matplotlib color specifications, 4. dict that assigns labels to colors (Default value = ‘FMP_1’)
figsize – Width, height in inches (Default value = (6, 1.5)
direction – ‘vertical’ or ‘horizontal’ (Default value = ‘horizontal’)
sort_labels – List of labels used for sorting the line plots (Default value = None)
time_min – Minimal limit for time axis. If None, will be min annotation. (Default value = None)
time_max – Maximal limit for time axis. If None, will be max from annotation. (Default value = None)
time_axis – Display time axis ticks or not (Default value = True)
swap_time_ticks – For horizontal: xticks up; for vertical: yticks left (Default value = False)
axis_off – Calls ax.axis(‘off’) (Default value = False)
dpi – Dots per inch (Default value = 72)

Returns

fig – The created matplotlib figure or None if ax was given.
ax – The used axes.

libfmp.b.b_plot.plot_chromagram(*args, chroma_yticks=np.arange(12), **kwargs)[source]¶

Call libfmp.b.plot_matrix and sets chroma labels.

See libfmp.b.b_plot.plot_matrix() for parameters and return values.

libfmp.b.b_plot.plot_matrix(X, Fs=1, Fs_F=1, T_coef=None, F_coef=None, xlabel='Time (seconds)', ylabel='Frequency (Hz)', xlim=None, ylim=None, clim=None, title='', dpi=72, colorbar=True, colorbar_aspect=20.0, cbar_label='', ax=None, figsize=(6, 3), **kwargs)[source]¶

2D raster visualization of a matrix, e.g. a spectrogram or a tempogram.

Parameters

X – The matrix
Fs – Sample rate for axis 1 (Default value = 1)
Fs_F – Sample rate for axis 0 (Default value = 1)
T_coef – Time coeffients. If None, will be computed, based on Fs. (Default value = None)
F_coef – Frequency coeffients. If None, will be computed, based on Fs_F. (Default value = None)
xlabel – Label for x-axis (Default value = ‘Time (seconds)’)
ylabel – Label for y-axis (Default value = ‘Frequency (Hz)’)
xlim – Limits for x-axis (Default value = None)
ylim – Limits for y-axis (Default value = None)
clim – Color limits (Default value = None)
title – Title for plot (Default value = ‘’)
dpi – Dots per inch (Default value = 72)
colorbar – Create a colorbar. (Default value = True)
colorbar_aspect – Aspect used for colorbar, in case only a single axes is used. (Default value = 20.0)
cbar_label – Label for colorbar (Default value = ‘’)
ax – Either (1.) a list of two axes (first used for matrix, second for colorbar), or (2.) a list with a single axes (used for matrix), or (3.) None (an axes will be created). (Default value = None)
figsize – Width, height in inches (Default value = (6, 3))
**kwargs – Keyword arguments for matplotlib.pyplot.imshow

Returns

fig – The created matplotlib figure or None if ax was given.
ax – The used axes.
im – The image plot

libfmp.b.b_plot.plot_segments(annot, ax=None, figsize=(6, 1), direction='horizontal', colors='FMP_1', time_min=None, time_max=None, nontime_min=0, nontime_max=1, time_axis=True, nontime_axis=False, time_label=None, swap_time_ticks=False, edgecolor='k', axis_off=False, dpi=72, adjust_time_axislim=True, adjust_nontime_axislim=True, alpha=None, print_labels=True, label_ticks=False, **kwargs)[source]¶

Create a segment plot visualization for a list of annotations with start time positions, end time positions, and labels. The segment plot visualization shows a colored box for each segment.

Parameters

annot – A List of tuples in the form of [(start_position, end_position, label), ...]
ax – The Axes instance to plot on. If None, will create a figure and axes. (Default value = None)
figsize – Width, height in inches (Default value = (6, 1)
direction – ‘vertical’ or ‘horizontal’ (Default value = ‘horizontal’)
colors – Several options: 1. string of FMP_COLORMAPS, 2. string of matplotlib colormap, 3. list or np.ndarray of matplotlib color specifications, 4. dict that assigns labels to colors (Default value = ‘FMP_1’)
time_min – Minimal limit for time axis. If None, will be min annotation. (Default value = None)
time_max – Maximal limit for time axis. If None, will be max from annotation. (Default value = None)
nontime_min – Minimal limit for non-time axis. (Default value = 0)
nontime_max – Maximal limit for non-time axis. (Default value = 1)
time_axis – Display time axis ticks or not (Default value = True)
nontime_axis – Display non-time axis ticks or not (Default value = False)
time_label – Label for time axes (Default value = None)
swap_time_ticks – For horizontal: xticks up; for vertical: yticks left (Default value = False)
edgecolor – Color for edgelines of segment box (Default value = ‘k’)
axis_off – Calls ax.axis(‘off’) (Default value = False)
dpi – Dots per inch (Default value = 72)
adjust_time_axislim – Adjust time-axis. Usually True for plotting on standalone axes and False for overlay plotting (Default value = True)
adjust_nontime_axislim – Adjust non-time-axis. Usually True for plotting on standalone axes and False for overlay plotting (Default value = True)
alpha – Alpha value for rectangle (Default value = None)
print_labels – Print labels inside Rectangles (Default value = True)
label_ticks – Print labels as ticks (Default value = False)
**kwargs –

Returns

fig – The created matplotlib figure or None if ax was given.
ax – The used axes.

libfmp.b.b_plot.plot_segments_overlay(*args, **kwargs)[source]¶

Plot segment annotations as overlay.

See libfmp.b.b_plot.plot_segments() for parameters and return values.

libfmp.b.b_plot.plot_signal(x, Fs=1, T_coef=None, ax=None, figsize=(6, 2), xlabel='Time (seconds)', ylabel='', title='', dpi=72, ylim=True, **kwargs)[source]¶

Line plot visualization of a signal, e.g. a waveform or a novelty function.

Parameters

x – Input signal
Fs – Sample rate (Default value = 1)
T_coef – Time coeffients. If None, will be computed, based on Fs. (Default value = None)
ax – The Axes instance to plot on. If None, will create a figure and axes. (Default value = None)
figsize – Width, height in inches (Default value = (6, 2))
xlabel – Label for x axis (Default value = ‘Time (seconds)’)
ylabel – Label for y axis (Default value = ‘’)
title – Title for plot (Default value = ‘’)
dpi – Dots per inch (Default value = 72)
ylim – True or False (auto adjust ylim or nnot) or tuple with actual ylim (Default value = True)
**kwargs – Keyword arguments for matplotlib.pyplot.plot

Returns

fig – The created matplotlib figure or None if ax was given.
ax – The used axes.
line – The line plot

libfmp.b.b_sonification.generate_shepard_tone(chromaNum, Fs, N, weight=1, Fc=440, sigma=15, phase=0)[source]¶

Generate a shepard tone signal as np.ndarray.

Parameters

chromaNum (int) – 1=C,…
Fs (scalar) – Sampling frequency
N (int) – Desired length (in samples)
weight (float) – Scaling factor [0:1] (Default value = 1)
Fc (float) – Frequency for A4 (Default value = 440)
sigma (float) – Parameter for envelope of Shepard tone (Default value = 15)
phase (float) – Phase of sine (Default value = 0)

Returns

tone (np.ndarray) – Shepard tone

libfmp.b.b_sonification.list_to_chromagram(note_list, num_frames, frame_rate)[source]¶

Create a chromagram matrix as np.ndarray from a list of note events.

Parameters

note_list (list) – A list of note events (e.g. gathered from a CSV file by libfmp.c1.c1s2_symbolic_rep.csv_to_list())
num_frames (int) – Desired number of frames for the matrix
frame_rate (float) – Frame rate for C (in Hz)

Returns

C (np.ndarray) – Chromagram matrix

libfmp.b.b_sonification.list_to_pitch_activations(note_list, num_frames, frame_rate)[source]¶

Create a pitch activation matrix from a list of note events.

Parameters

note_list (list) – A list of note events (e.g., gathered from a CSV file by libfmp.c1.c1s2_symbolic_rep.csv_to_list())
num_frames (int) – Desired number of frames for the matrix
frame_rate (float) – Frame rate for P (in Hz)

Returns

P (np.ndarray) – Pitch activation matrix (first axis: Indexed by [0:127], encoding MIDI pitches [1:128])
F_coef_MIDI (np.ndarray) – MIDI pitch axis

libfmp.b.b_sonification.sonify_chromagram(chroma_data, N, frame_rate, Fs, fading_msec=5)[source]¶

Generate a sonification of the chroma features from a chromagram matrix using shepard tones.

Parameters

chroma_data (np.ndarray) – A chromagram (e.g., gathered from a list of note events by libfmp.b.b_sonification.list_to_chromagram())
N (int) – Length of the sonification (in samples)
frame_rate (float) – Frame rate for P (in Hz)
Fs (float) – Sampling frequency (in Hz)
fading_msec (float) – The length of the fade in and fade out for sonified tones (in msec) (Default value = 5)

Returns

chroma_son (np.ndarray) – Sonification of the chromagram

libfmp.b.b_sonification.sonify_chromagram_with_signal(chroma_data, x, frame_rate, Fs, fading_msec=5, stereo=True)[source]¶

Sonifiy the chroma features from a chromagram matrix (using libfmp.b.b_sonification.sonify_chromagram()) together with a corresponding signal.

Parameters

chroma_data (np.ndarray) – A chromagram (e.g., gathered from a list of note events by libfmp.b.b_sonification.list_to_chromagram())
x (np.ndarray) – Original signal
frame_rate (float) – Frame rate for P (in Hz)
Fs (float) – Sampling frequency (in Hz)
fading_msec (float) – The length of the fade in and fade out for sonified tones (in msec) (Default value = 5)
stereo (bool) – Decision between stereo and mono sonification (Default value = True)

Returns

chroma_son (np.ndarray) – Sonification of the chromagram
out (np.ndarray) – Sonification combined with the original signal

libfmp.b.b_sonification.sonify_pitch_activations(P, N, frame_rate, Fs, min_pitch=1, Fc=440, harmonics_weights=[1], fading_msec=5)[source]¶

Sonify the pitches from a pitch activation matrix using sinusoidals.

Parameters

P (np.ndarray) – A pitch activation matrix (e.g., gathered from a list of note events by libfmp.b.b_sonification.list_to_pitch_activations()). First axis: Indexed by [0:127], encoding MIDI pitches [1:128]
N (int) – Length of the sonification (in samples)
frame_rate (float) – Frame rate for P (in Hz)
Fs (float) – Sampling frequency (in Hz)
min_pitch (int) – Lowest MIDI pitch in P (Default value = 1)
Fc (float) – Tuning frequency (in Hz) (Default value = 440)
harmonics_weights (list) – A list of weights for the harmonics of the tones to be sonified (Default value = [1])
fading_msec (float) – The length of the fade in and fade out for sonified tones (in msec) (Default value = 5)

Returns

pitch_son (np.ndarray) – Sonification of the pitch activation matrix

libfmp.b.b_sonification.sonify_pitch_activations_with_signal(P, x, frame_rate, Fs, min_pitch=1, Fc=440, harmonics_weights=[1], fading_msec=5, stereo=True)[source]¶

Sonify the pitches from a pitch activation matrix (using libfmp.b.b_sonification.sonify_pitch_activations()) together with a corresponding signal.

Parameters

P (np.ndarray) – A pitch activation matrix (e.g., gathered from a list of note events by libfmp.b.b_sonification.list_to_pitch_activations())
x (np.ndarray) – Original signal
frame_rate (float) – Frame rate for P (in Hz)
Fs (float) – Sampling frequency (in Hz)
min_pitch (int) – Lowest MIDI pitch in P (Default value = 1)
Fc (float) – Tuning frequency (in Hz) (Default value = 440)
harmonics_weights (list) – A list of weights for the harmonics of the tones to be sonified (Default value = [1])
fading_msec (float) – The length of the fade in and fade out for sonified tones (in msec) (Default value = 5)
stereo (bool) – Decision between stereo and mono sonification (Default value = True)

Returns

pitch_son (np.ndarray) – Sonification of the pitch activation matrix
out (np.ndarray) – Sonification combined with the original signal

libfmp.b.b_test_module.add(a, b=0, c=0)[source]¶

Function to add three numbers

Notebook: B/B_libfmp.ipynb and

Notebook: B/B_PythonBasics.ipynb

Parameters

a (float) – First number
b (float) – Second number (default: 0)
c (float) – Third number (default: 0)

Returns

d (float) – Sum