F0 (libsoni.core.f0)

libsoni.core.f0.sonify_f0(time_f0: ndarray, gains: ndarray = None, partials: ndarray = array([1]), partials_amplitudes: ndarray = array([1]), partials_phase_offsets: ndarray = None, sonification_duration: int = None, crossfade_duration=0.01, normalize: bool = True, fs: int = 22050, ignore_zero_freq_samples: int = 1000, freq_change_threshold_cents: float = 50) → ndarray[source]

Sonifies an F0 trajectory given as a 2D NumPy array.

The 2D array must contain time positions and associated F0 values. The sonification is based on phase accumulation by summing the instantaneous frequencies. The parameters partials, partials_amplitudes, and partials_phase_offsets can be used to modify the timbre.

Parameters:

  • time_f0 (np.ndarray (np.float32 / np.float64) [shape=(N, 2)]) – 2D array containing time positions and associated F0 values.

  • gains (np.ndarray (np.float32 / np.float64) [shape=(N, )], default = None) – Array containing gain values for F0 values.

  • partials (np.ndarray (np.float32 / np.float64) [shape=(N, )], default = [1]) – Array specifying the desired partials of the fundamental frequency for sonification. An array [1] results in sonification using only the fundamental frequency, while [1, 2] includes both the fundamental frequency and its second harmonic (twice the fundamental frequency).

  • partials_amplitudes (np.ndarray (np.float32 / np.float64) [shape=(N, )], default = None) – Array specifying the amplitudes of the partials. For example, [1, 0.5] sets the first partial’s amplitude to 1 and the second partial’s amplitude to 0.5. If None, all partial amplitudes default to 1.

  • partials_phase_offsets (np.ndarray (np.float32 / np.float64) [shape=(N, )], default = None) – Array specifying phase offsets for partials. If None, all partials have a phase offset of 0.

  • sonification_duration (int, default = None) – Duration of the sonification in samples.

  • crossfade_duration (float, default = 0.01) – Duration of fade in/out at the beginning/end of the signal, as well as between discrete notes (see freq_change_threshold_cents), in seconds.

  • normalize (bool, default = True) – Whether to normalize the output signal to the range [-1, 1].

  • fs (int, default = 22050) – Sampling rate in samples per second.

  • ignore_zero_freq_samples (int, default = 1000) – Number of consecutive samples with frequency 0 that will be ignored in the sonification (e.g., to compensate for poor F0 estimation). Must be greater than 2; otherwise, this parameter is ignored.

  • freq_change_threshold_cents (float, default = 50) – If the frequency change between successive frames exceeds this threshold (in cents), the sonification will apply crossfading instead of linear interpolation of the instantaneous frequency.

Returns:

f0_sonification (np.ndarray (np.float32 / np.float64) [shape=(M, )]) – The sonified F0 trajectory.