Helper functions#

These are helper functions that are used throughout the package.

thebeat.helpers.all_possibilities(numbers, target)[source]#

Use a deep-first search to find all possible combinations of ‘numbers’ that sum to ‘target’. Returns a NumPy array of NumPy arrays (with dtype=object to allow nested array).

Return type: ndarray

thebeat.helpers.all_rhythmic_ratios(allowed_note_values, time_signature)[source]#

thebeat.helpers.check_for_overlap(sounds_durations, onsets)[source]#

thebeat.helpers.check_sound_properties_sameness(objects)[source]#: This helper function checks whether the objects in the passed iterable have the same sound properties. Raises errors if properties are not the same.

thebeat.helpers.get_sound_with_metronome(samples, fs, metronome_ioi, metronome_amplitude)[source]#

This helper function adds a metronome sound to a NumPy array of sound samples. It works for both mono and stereo sounds.

Return type: ndarray

thebeat.helpers.join_rhythms(iterator)[source]#: This function can join multiple Rhythm objects.

thebeat.helpers.make_ramps(samples, fs, onramp_ms, offramp_ms, ramp_type)[source]#: Internal function used to create on- and offramps. Supports ‘linear’ and ‘raised-cosine’ ramps.

thebeat.helpers.normalize_audio(samples)[source]#

This helper function normalizes audio based on the absolute max amplitude from the provided sound samples.

Return type: ndarray

thebeat.helpers.overlay_samples(samples_arrays)[source]#

Overlay all the samples in the iterable

Return type: ndarray

thebeat.helpers.play_samples(samples, fs, mean_ioi, loop, metronome, metronome_amplitude)[source]#

This helper function uses the sounddevice library to play a sound, either with or without metronome.

Return type: None

thebeat.helpers.plot_lp(lp, filepath=None, suppress_display=False, title=None, dpi=300, ax=None)[source]#

This function plots a LilyPond object.

Parameters

lp – A LilyPond string.
filepath (Union[PathLike, str, None], default: None) – If provided, the plot will be saved to this path. Has to end with either .png or .pdf.
suppress_display (bool, default: False) – If True, the plot will not be displayed using matplotlib.Figure.show().
title (Optional[str], default: None) – Title of the plot.
dpi (int, default: 300) – The resolution of the plot in dots per inch.
ax (Optional[Axes], default: None) – If provided, the plot will be drawn on this axis.

Return type

tuple[Figure, Axes]

thebeat.helpers.plot_single_sequence(onsets, end_with_interval, final_ioi=None, style='seaborn-v0_8', title=None, x_axis_label='Time', linewidths=None, figsize=None, dpi=100, suppress_display=False, ax=None)[source]#

This function plots the onsets of a Sequence or SoundSequence object in an event plot.

Parameters

onsets (Union[list, ndarray]) – The onsets (i.e. t values) of the sequence.
end_with_interval (bool) – Indicates whether sequence ends with an interval (True) or event (False).
final_ioi (Optional[float], default: None) – The final inter-onset interval of the sequence. This is only used if the sequence ends with an interval.
linewidths (Union[float, list[float], ndarray[Any, dtype[float]], None], default: None) – The desired width of the bars (events). Defaults to 1/10th of the smallest inter-onset interval (IOI). Can be a single value that will be used for each onset, or a list or array of values (i.e with a value for each respective onsets).
style (str, default: 'seaborn-v0_8') – Matplotlib style to use for the plot. Defaults to ‘seaborn’. See matplotlib style sheets reference.
title (Optional[str], default: None) – If desired, one can provide a title for the plot. This takes precedence over using the name of the object as the title of the plot (if the object has one).
x_axis_label (str, default: 'Time') – A label for the x axis.
figsize (Optional[tuple], default: None) – A tuple containing the desired output size of the plot in inches, e.g. (4, 1). This refers to the figsize parameter in matplotlib.pyplot.subplots().
dpi (int, default: 100) – The number of dots per inch. This refers to the dpi parameter in matplotlib.figure.Figure.
suppress_display (bool, default: False) – If True, the plot is only returned, and not displayed via matplotlib.pyplot.show().
ax (Optional[Axes], default: None) – If desired, you can provide an existing matplotlib.Axes object onto which to plot. See the Examples of the different plotting functions to see how to do this (e.g. plot_sequence() ). If an existing matplotlib.Axes object is supplied, this function returns the original matplotlib.Figure and matplotlib.Axes objects.

Return type

tuple[Figure, Axes]

thebeat.helpers.plot_waveform(samples, fs, n_channels, style='seaborn-v0_8', title=None, figsize=None, dpi=100, suppress_display=False, ax=None)[source]#

This helper function plots a waveform of a sound using matplotlib.

Parameters

samples (ndarray) – The array containing the sound samples.
fs (int) – Sampling frequency in hertz (e.g. 48000).
n_channels (int) – Number of channels (1 for mono, 2 for stereo).
style (str, default: 'seaborn-v0_8') –
Style used by matplotlib. See matplotlib style sheets reference.
title (Optional[str], default: None) – If desired, one can provide a title for the plot.
figsize (Optional[tuple], default: None) – A tuple containing the desired output size of the plot in inches, e.g. (4, 1). This refers to the figsize parameter in matplotlib.pyplot.figure().
dpi (int, default: 100) – The resolution of the plot in dots per inch. This refers to the dpi parameter in matplotlib.pyplot.figure().
suppress_display (bool, default: False) – If True, matplotlib.pyplot.Figure.show() is not run.
ax (Optional[Axes], default: None) – If desired, you can provide an existing matplotlib.Axes object onto which to plot. See the Examples of the different plotting functions to see how to do this (e.g. plot_sequence() ). If an existing matplotlib.Axes object is supplied, this function returns the original matplotlib.Figure and matplotlib.Axes objects.

Return type

tuple[Figure, Axes]

thebeat.helpers.rhythm_to_binary(rhythm, smallest_note_value=16)[source]#: This helper function converts a rhythm to a binary representation.

thebeat.helpers.sequence_to_binary(sequence, resolution)[source]#: Converts a sequence of millisecond onsets to a series of zeros and ones. Ones for the onsets.

thebeat.helpers.synthesize_sound(duration_ms, fs, freq, n_channels, amplitude, oscillator)[source]#

Return type: ndarray

thebeat.helpers.write_wav(samples, fs, filepath, metronome, metronome_ioi=None, metronome_amplitude=None)[source]#

This helper function writes the provided sound samples to disk as a wave file. See https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.wavfile.write.html for more info.

Return type: None