Utils (libsoni.utils)
- libsoni.utils.fade_signal(signal: ndarray, fading_duration: float = 0, fs: int = 22050, fade_type: str = 'squared_sine') ndarray [source]
Fade in / out audio signal
- Parameters:
signal (np.ndarray (np.float32 / np.float64) [shape=(N, )]) – Signal to be faded
fs (int, default = 22050) – sampling rate
fading_duration (float or tuple of 2 floats, default = 0) – duration of fade-in and fade-out, in seconds if one float is given, fade-in and fade-out have the same length
If the total fading duration is longer than the total signal length, the fades will be scaled proportionally.
fade_type (str) – Define the fading function. Options: “squared_sine” (default), “sine”, “linear”
- Returns:
normalized_signal (np.ndarray (np.float32 / np.float64) [shape=(N, )]) – Normalized signal
- libsoni.utils.mix_sonification_and_original(sonification: ndarray, original_audio: ndarray, gain_lin_sonification: float = 1.0, gain_lin_original_audio: float = 1.0, panning: float = 1.0, duration: int = None)[source]
This function takes a sonification and an original_audio and mixes it to stereo
- Parameters:
sonification (np.ndarray (np.float32 / np.float64) [shape=(N, )]) – Sonification
original_audio (np.ndarray (np.float32 / np.float64) [shape=(N, )]) – Original audio
gain_lin_sonification (float, default = 1.0) – linear gain for sonification
gain_lin_original_audio (float, default = 1.0) – linear gain for original audio
panning (float, default = 1.0) –
- Controls the panning of the mixed output
panning = 1.0 means original audio on left and sonification on right channel panning = 0.5 means same amount of both signals on both channels. panning = 0.0 means sonification on left and original audio on right channel
duration (int, default = None) – Duration of the output waveform, given in samples.
- Returns:
stereo_audio (np.ndarray (np.float32 / np.float64) [shape=(N, 2)]) – Mix of the signals
- libsoni.utils.normalize_signal(signal: ndarray) ndarray [source]
Max-normalize audio signal
- Parameters:
signal (np.ndarray (np.float32 / np.float64) [shape=(N, )]) – Signal to be normalized
- Returns:
normalized_signal (np.ndarray (np.float32 / np.float64) [shape=(N, )]) – Normalized signal
- libsoni.utils.pitch_to_frequency(pitch: int, reference_pitch: int = 69, tuning_frequency: float = 440.0) float [source]
Calculates the corresponding frequency for a given pitch.
- Parameters:
pitch (int) – Pitch to calculate frequency for.
reference_pitch (int, default = 69) – Reference pitch for calculation.
tuning_frequency (float, default = 440.0) – Tuning frequency for calculation, in Hertz.
- Returns:
frequency (float) – Calculated frequency for given pitch, in Hertz.
- libsoni.utils.replace_zeros(x: ndarray, zero_count: int = 1000, replace_with_previous=True, value=0)[source]
Replaces consecutive rows of zeros (up to a specified length) with the previous value or a given value in the array. If a row of zeros is longer than zero_counts, no zeros will be replaced.
- Parameters:
x (np.ndarray) – 1D array of size (N).
zero_counts (int, default = 1000) – Maximum number of consecutive zeros that will be replaced. Must be greater than 2.
replace_with_previous (bool, default = True) – If True, zeros will be replaced with the last non-zero value in the array. If False, zeros will be replaced with the specified value.
value (int | float, optional) – The value used to replace zeros when replace_with_previous = False.
- Returns:
y (np.ndarray) – 1D array of size (N) with specified zero rows replaced.
- libsoni.utils.smooth_weights(weights: ndarray, fading_samples: int = 0) ndarray [source]
Weight smoothing
- Parameters:
weights ((np.float32 / np.float64) [shape=(N, )]) – Input weights
fading_samples (int) – Number of samples for fade-in/out.
- Returns:
weights_smoothed (np.ndarray (np.float32 / np.float64) [shape=(N, )]) – Smoothed weights
- libsoni.utils.split_freq_trajectory(frequencies: ndarray, max_change_cents: float = 50.0)[source]
Splits a frequency array into regions where the change in frequency from frame to frame remains within a specified threshold, e.g., to isolate note events in an F0 trajectory.
- Parameters:
frequencies (np.ndarray) – 1D array of frequencies (Hz) to be split into regions with minimal pitch changes.
max_change_cents (float) – Maximum allowed change (in cents) between successive frames before splitting the trajectory.
- Returns:
splits (np.ndarray) – 1D array containing indices where the input array should be split. Within each resulting region, the change in frequency from frame to frame remains below the specified threshold. Can be used with np.split().
- libsoni.utils.visualize_pianoroll(pianoroll_df: DataFrame, xlabel: str = 'Time (seconds)', ylabel: str = 'Pitch', title: str = None, colors: str = 'FMP_1', velocity_alpha: bool = False, figsize: Tuple[float, float] = (12, 4), ax: Axes = None, dpi: int = 72) Tuple[Figure, Axes] [source]
Visualization function for piano-roll representations, given in a pd.DataFrame format
- Parameters:
pianoroll_df (pd.DataFrame) – Dataframe containing pitch-event information.
xlabel (str, default = ‘Time (seconds)’) – Label text for the x-axis.
ylabel (str, default = ‘Pitch’) – Label text for the y-axis.
title (str, default = None) – Title of the figure.
colors (str, default = ‘FMP_1’) – Colormap, for the default colormap see https://github.com/meinardmueller/libfmp.
velocity_alpha (bool = False) – Set True to weight the visualized rectangular regions for each pitch based on their velocity value.
figsize (Tuple[float, float], default: [12, 4])) – Figure size
ax (matplotlib.axes.Axes) – Axes object
dpi (int) – Resolution of the figure.
- Returns:
fig (matplotlib.figure.Figure) – Figure instance
ax (matplotlib.axes.Axes) – Axes object
- libsoni.utils.warp_sample(sample: ndarray, reference_pitch: int, target_pitch: int, target_duration_sec: float, gain: float = 1.0, fs: int = 22050, fading_duration: float = 0.01)[source]
This function warps a sample. Given the reference pitch of the sample provided as np.ndarray, the warped version of the sample gets pitch-shifted using librosa.effects.pitch_shift(). For the temporal alignment, if the desired duration is shorter than the original sample, the sample gets cropped, else if the desired duration is longer of the provided sample, the returned signal gets zero-padded at the end.
- Parameters:
sample (np.ndarray (np.float32 / np.float64) [shape=(K, )]) – Sample to be warped.
reference_pitch (int) – Reference pitch for the given sample.
target_pitch (int) – Target pitch for the warped sample.
target_duration_sec (float) – Duration, given in seconds, for the returned signal.
gain (float, default = 1.0) – Gain of the generated tone
fs (int, default = 22050) – Sampling rate, in samples per seconds.
fading_duration (float, default = 0.01) – Duration of fade in and fade out (to avoid clicks)
- Returns:
warped_sample (np.ndarray (np.float32 / np.float64) [shape=(M, )]) – Warped sample.