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, figsize=None, dpi=300, ax=None)[source]#

This function plots a LilyPond object.

Parameters:

  • lp – A LilyPond string.

  • filepath (PathLike | str, 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.Figure.show().

  • title (Optional[str], default: None) – Title of the plot.

  • figsize (Optional[tuple[float, float]], 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: 300) – The resolution of the plot in dots per inch.

  • ax (Optional[Axes], default: None) – If provided, the plot will be drawn on this axes.

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 (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 (UnionType[list[float], ndarray[Any, dtype[float]], 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.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.Axes object is supplied, this function returns the original matplotlib.figure.Figure and matplotlib.axes.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:
Return type:

tuple[Figure, Axes]

thebeat.helpers.read_wav(filepath, new_fs)[source]#

Internal function used to read a wave file. Returns the wave file’s samples and the sampling frequency. If dtype is different from np.float64, it converts the samples to that.

thebeat.helpers.resample(samples, input_fs, output_fs)[source]#

Internal function used to resample sounds. Uses scipy.signal.resample

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, dtype=<class 'numpy.int16'>, metronome=False, 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