Timing

Full module path: melody_features.feature_definitions.timing.

Also importable via import melody_features as mf (for example mf.pitch_range).

Timing feature definitions.

durdist1(starts, ends, tempo=120.0)[source]

Note duration distribution in nine log-spaced beat bins.

Bin centers (in beats): 1/4, √2/4, 1/2, √2/2, 1, √2, 2, 2√2, 4.

Parameters:

  • starts (list[float]) – Note onset times in seconds

  • ends (list[float]) – Note offset times in seconds

  • tempo (float) – Tempo in BPM (default 120)

Returns:

Map from bin index (1–9) to proportion

Return type:

dict[int, float]

durdist2(starts, ends, tempo=120.0)[source]

Second-order duration transition distribution (MIDI Toolbox durdist2.m).

Returns a 9×9 matrix of transition probabilities between log-spaced duration bins (same bin centres as durdist1). Keys are (from_bin, to_bin) with bin indices 1–9.

Parameters:

  • starts (list[float]) – Note onset times in seconds

  • ends (list[float]) – Note offset times in seconds

  • tempo (float) – Tempo in BPM (default 120)

Returns:

Map from duration-bin transition to proportion

Return type:

dict[tuple[int, int], float]

initial_tempo(melody)[source]

The first tempo of the melody.

Parameters:

melody (Melody) – The melody to analyze

Returns:

Tempo of melody in bpm

Return type:

float

mean_tempo(melody)[source]

The mean tempo of the melody.

Parameters:

melody (Melody) – The melody to analyze

Returns:

Mean tempo of melody in bpm

Return type:

float

tempo_variability(melody)[source]

The duration-weighted variability of tempo across the melody.

Parameters:

melody (Melody) – The melody to analyze

Returns:

Weighted population standard deviation (BPM) of tempo segments.

Return type:

float

duration_range(starts, ends, tempo=120.0)[source]

The range between the longest and shortest note duration in quarter notes.

Parameters:
Returns:

Range between longest and shortest duration

Return type:

float

mean_duration(starts, ends, tempo=120.0)[source]

The mean note duration in quarter notes, computed from the raw durations.

Parameters:

  • starts (list[float]) – List of note start times (in seconds)

  • ends (list[float]) – List of note end times (in seconds)

  • tempo (float) – Tempo in BPM (beats per minute), default 120.0

Returns:

Mean raw note duration in quarter notes

Return type:

float

Note

We use raw durations here (in the style of FANTASTIC), rather than jSymbolic’s quantized rhythmic-value bins.

average_note_duration(starts, ends)[source]

The average note duration in seconds.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

Returns:

Average note duration in seconds

Return type:

float

Note

This feature reports duration in seconds, unlike quarter-note duration means such as mean_duration and mean_rhythmic_value.

duration_standard_deviation(starts, ends, tempo=120.0)[source]

The standard deviation of note durations in quarter notes.

Parameters:
Returns:

Standard deviation of note durations

Return type:

float

variability_of_note_durations(starts, ends)[source]

The standard deviation of note durations in seconds.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

Returns:

Standard deviation of note durations

Return type:

float

modal_duration(starts, ends, tempo=120.0)[source]

The modal raw note duration in quarter notes.

Parameters:

  • starts (list[float]) – List of note start times (in seconds)

  • ends (list[float]) – List of note end times (in seconds)

  • tempo (float) – Tempo in BPM (beats per minute), default 120.0

Returns:

Most frequent raw note duration in quarter notes

Return type:

float

Note

This computes the mode of raw quarter-note durations, so differs from jSymbolic most_common_rhythmic_value, which uses the modal bin in a 12-bin rhythmic-value histogram.

length(starts)[source]

The total number of notes.

Parameters:

starts (list[float]) – List of note start times

Returns:

Total number of notes

Return type:

int

number_of_unique_durations(starts, ends, tempo=120.0)[source]

The number of unique note durations, measured in quarter notes.

Parameters:
Returns:

Number of unique note durations

Return type:

int

global_duration(melody)[source]

The total duration in seconds of the melody.

Parameters:

melody (Melody) – Melody object containing MIDI data

Returns:

Total duration of the MIDI sequence in seconds

Return type:

float

note_density(melody)[source]

The average number of notes per second.

Parameters:

melody (Melody) – Melody object containing MIDI data

Returns:

Note density (notes per unit time)

Return type:

float

note_density_variability(melody)[source]

The standard deviation of note density across 5-second windows.

Parameters:

melody (Melody) – Melody object containing MIDI data

Returns:

Standard deviation of note density using 5-second windows

Return type:

float

Note

Our tests indicate a certain discrepancy between our outputs and JSymbolic’s outputs, which may be a consequence of JSymbolic’s tick-based approach, or perhaps its idiosyncratic windowing approach.

note_density_per_quarter_note(melody)[source]

The average number of note onsets per unit of time corresponding to an idealized quarter note duration based on the tempo.

Parameters:

melody (Melody) – Melody object containing MIDI data

Returns:

Average number of notes per quarter note duration

Return type:

float

note_density_per_quarter_note_variability(melody)[source]

The standard deviation of note density per quarter note.

Divides the melody into 8-quarter-note windows and calculates the standard deviation of note density across these windows.

Parameters:

melody (Melody) – Melody object containing MIDI data

Returns:

Standard deviation of note density across windows

Return type:

float

Note

Our tests indicate a certain discrepancy between our outputs and JSymbolic’s outputs, which may be a consequence of JSymbolic’s tick-based approach, or perhaps its idiosyncratic windowing approach.

duration_histogram(starts, ends, tempo=120.0)[source]

A histogram of note durations in quarter notes.

Parameters:
Returns:

Histogram of note durations

Return type:

dict

range_of_rhythmic_values(starts, ends, tempo=120.0)[source]

The range of rhythmic values located within the 12-bin PPQN-based histogram. Durations are converted to quarter notes and mapped to 12 fixed rhythmic bins using midpoints. The returned value is the difference between the highest and lowest non-empty bins.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Range in bins (int cast to float), 0 if no durations present

Return type:

float

number_of_different_rhythmic_values_present(starts, ends, tempo=120.0)[source]

The number of distinct rhythmic value bins that are present in the melody (non-zero).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Count of non-zero bins as a float (0.0 if no durations)

Return type:

float

number_of_common_rhythmic_values_present(starts, ends, tempo=120.0)[source]

The number of rhythmic value bins with normalized proportion >= 0.15.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Count of bins with mass >= 0.15 as a float (0.0 if no durations)

Return type:

float

prevalence_of_very_short_rhythmic_values(starts, ends, tempo=120.0)[source]

The sum of the two shortest rhythmic bins (indexes 0 and 1).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Proportion in [0, 1] for bins 0 and 1 combined (0.0 if no durations)

Return type:

float

prevalence_of_short_rhythmic_values(starts, ends, tempo=120.0)[source]

The sum of the three shortest rhythmic bins (indexes 0, 1, and 2).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Proportion in [0, 1] for bins 0, 1 and 2 combined (0.0 if no durations)

Return type:

float

Note

Rhythmic-bin families overlap by construction in jSymbolic (e.g., short/medium/long), so these prevalence values are not mutually exclusive and can sum to more than 1.0.

prevalence_of_medium_rhythmic_values(starts, ends, tempo=120.0)[source]

The sum of rhythmic bins 2 to 6 (8th notes to half notes).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Proportion in [0, 1] for bins 2..6 combined (0.0 if no durations)

Return type:

float

Note

Rhythmic-bin families overlap by construction in jSymbolic (e.g., short/medium/long), so these prevalence values are not mutually exclusive and can sum to more than 1.0.

prevalence_of_long_rhythmic_values(starts, ends, tempo=120.0)[source]

The sum of rhythmic bins 6 to 11 (half notes to dotted double whole notes or more).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Proportion in [0, 1] for bins 6 to 11 combined (0.0 if no durations)

Return type:

float

Note

Rhythmic-bin families overlap by construction in jSymbolic (e.g., short/medium/long), so these prevalence values are not mutually exclusive and can sum to more than 1.0.

prevalence_of_very_long_rhythmic_values(starts, ends, tempo=120.0)[source]

The sum of rhythmic bins 9 to 11 (dotted whole notes to dotted double whole notes or more).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Proportion in [0, 1] for bins 9..11 combined (0.0 if no durations)

Return type:

float

prevalence_of_dotted_notes(starts, ends, tempo=120.0)[source]

The sum of dotted rhythmic bins: 3, 5, 7, 9, 11.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Proportion in [0, 1] for dotted bins combined (0.0 if no durations)

Return type:

float

shortest_rhythmic_value(starts, ends, tempo=120.0)[source]

The shortest quantized (non-zero) rhythmic-bin value (in quarter notes).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Shortest quantized rhythmic-bin ideal value in quarter notes (0.0 if empty)

Return type:

float

Note

This returns the ideal value of the shortest occupied histogram bin, not the raw minimum note duration.

longest_rhythmic_value(starts, ends, tempo=120.0)[source]

The longest quantized rhythmic-bin value (in quarter notes).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Longest quantized rhythmic-bin ideal value in quarter notes (0.0 if empty)

Return type:

float

Note

This returns the ideal value of the longest occupied histogram bin, not the raw maximum note duration.

mean_rhythmic_value(starts, ends, tempo=120.0)[source]

The mean quantized rhythmic value in quarter notes.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Weighted mean rhythmic-bin ideal value in quarter notes (0.0 if empty)

Return type:

float

Note

Uses histogram-bin ideal values rather than raw note durations.

most_common_rhythmic_value(starts, ends, tempo=120.0)[source]

The modal quantized rhythmic value (in quarter notes).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Modal rhythmic-bin ideal value in quarter notes (0.0 if empty or all-zero)

Return type:

float

Note

Uses rhythmic-value mode from a 12-bin histogram. Differs from modal_duration, which computes a raw-duration mode in quarter-note units.

prevalence_of_most_common_rhythmic_value(starts, ends, tempo=120.0)[source]

The proportion (0.0 - 1.0) of the modal rhythmic bin.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Proportion (0.0 - 1.0) of the modal rhythmic bin (0.0 if empty)

Return type:

float

relative_prevalence_of_most_common_rhythmic_values(starts, ends, tempo=120.0)[source]

The ratio of the second-most-common rhythmic bin to the most common bin.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Ratio of the second-most-common rhythmic bin to the most common bin (0.0 if empty)

Return type:

float

difference_between_most_common_rhythmic_values(starts, ends, tempo=120.0)[source]

The absolute difference in bins between most and second most common rhythmic values.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Absolute difference in bins between most and second most common rhythmic values (0.0 if empty)

Return type:

float

mean_rhythmic_value_run_length(starts, ends, tempo=120.0)[source]

The mean run length of identical rhythmic values across the melody. Run length is the number of consecutive notes with the same rhythmic value.

Returns 0.0 if there are fewer than 1 notes.

Parameters:
Return type:

float

median_rhythmic_value_run_length(starts, ends, tempo=120.0)[source]

The median run length of identical rhythmic values across the melody. Run length is the number of consecutive notes with the same rhythmic value.

Parameters:
Return type:

float

variability_in_rhythmic_value_run_lengths(starts, ends, tempo=120.0)[source]

The standard deviation of rhythmic value run lengths. Run length is the number of consecutive notes with the same rhythmic value.

Parameters:
Return type:

float

mean_rhythmic_value_offset(starts, ends, tempo=120.0)[source]

The mean quantized offset from the nearest ideal rhythmic value (in quarter notes).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Mean quantized offset from the nearest ideal rhythmic value (in quarter notes) (0.0 if no durations)

Return type:

float

median_rhythmic_value_offset(starts, ends, tempo=120.0)[source]

The median quantized offset from the nearest ideal rhythmic value (in quarter notes).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Median quantized offset from the nearest ideal rhythmic value (in quarter notes) (0.0 if no durations)

Return type:

float

variability_of_rhythmic_value_offsets(starts, ends, tempo=120.0)[source]

The standard deviation of rhythmic value offsets (in quarter notes).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

Returns:

Standard deviation of rhythmic value offsets (in quarter notes) (0.0 if no durations)

Return type:

float

complete_rests_fraction(starts, ends, tempo=120.0, ppqn=480)[source]

The fraction of the total duration during which no pitched notes are sounding.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Fraction of total duration during which no pitched notes are sounding (0.0 if no durations)

Return type:

float

Note

This feature includes all complete silent runs (including those shorter than 0.1 quarter notes), whereas other complete-rest summary statistics apply a minimum 0.1 quarter-note threshold.

longest_complete_rest(starts, ends, tempo=120.0, ppqn=480)[source]

The longest uninterrupted complete rest in quarter-note units (ignoring rests shorter than 0.1 QN).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Longest uninterrupted complete rest in quarter-note units (0.0 if no durations)

Return type:

float

mean_complete_rest_duration(starts, ends, tempo=120.0, ppqn=480)[source]

The mean duration of complete rests in quarter-note units (ignoring rests shorter than 0.1 QN).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Mean duration of complete rests in quarter-note units (0.0 if no durations)

Return type:

float

median_complete_rest_duration(starts, ends, tempo=120.0, ppqn=480)[source]

The median duration of complete rests in quarter-note units (ignoring rests shorter than 0.1 QN).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Median duration of complete rests in quarter-note units (0.0 if no durations)

Return type:

float

variability_of_complete_rest_durations(starts, ends, tempo=120.0, ppqn=480)[source]

The standard deviation of complete rest durations in quarter notes (ignoring rests shorter than 0.1 QN).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Standard deviation of complete rest durations in quarter notes (0.0 if no durations)

Return type:

float

strongest_rhythmic_pulse(starts, ends, tempo=120.0, ppqn=480)[source]

The bin index (BPM) of the maximum beat histogram magnitude.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Bin index (BPM) of the maximum beat histogram magnitude (0.0 if no durations)

Return type:

float

strongest_rhythmic_pulse_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The bin index (BPM) of the maximum in the 120-BPM standardized beat histogram.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Bin index (BPM) of the maximum beat histogram magnitude (0.0 if no durations)

Return type:

float

second_strongest_rhythmic_pulse(starts, ends, tempo=120.0, ppqn=480)[source]

The bin index (BPM) of the second-highest magnitude in the beat histogram.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Bin index (BPM) of the second-highest magnitude in the beat histogram (0.0 if no durations)

Return type:

float

second_strongest_rhythmic_pulse_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The bin index (BPM) of the second-highest magnitude in the 120-BPM standardized beat histogram.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Bin index (BPM) of the second-highest magnitude in the 120-BPM standardized beat histogram (0.0 if no durations)

Return type:

float

harmonicity_of_two_strongest_rhythmic_pulses(starts, ends, tempo=120.0, ppqn=480)[source]

The ratio of higher to lower bin index of the two strongest rhythmic pulses.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Ratio of higher to lower bin index of the two strongest rhythmic pulses (0.0 if no durations).

Return type:

float

Note

The first peak is selected from the raw beat histogram and the second peak is selected from the thresholded peak table (column 1), excluding the first peak bin.

harmonicity_of_two_strongest_rhythmic_pulses_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The ratio of higher to lower bin index of the two strongest rhythmic pulses (120-BPM standardized histogram).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Ratio of higher to lower bin index of the two strongest rhythmic pulses (120-BPM standardized histogram) (0.0 if no durations).

Return type:

float

Note

The first peak is selected from the standardized histogram values from the standardized histogram values and the second peak is selected from the standardized thresholded peak table (column 1), excluding the first peak bin.

strength_of_strongest_rhythmic_pulse(starts, ends, tempo=120.0, ppqn=480)[source]

The magnitude of the beat histogram bin with the highest magnitude.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Magnitude of the beat histogram bin with the highest magnitude (0.0 if no durations)

Return type:

float

strength_of_strongest_rhythmic_pulse_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The magnitude of the tempo-standardized beat histogram bin with the highest magnitude.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Magnitude of the tempo-standardized beat histogram bin with the highest magnitude (0.0 if no durations)

Return type:

float

strength_of_second_strongest_rhythmic_pulse(starts, ends, tempo=120.0, ppqn=480)[source]

The magnitude of the beat histogram bin with the second-highest magnitude.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Magnitude of the beat histogram bin with the second-highest magnitude (0.0 if no durations)

Return type:

float

strength_of_second_strongest_rhythmic_pulse_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The magnitude of the tempo-standardized beat histogram bin with the second-highest magnitude.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Magnitude of the tempo-standardized beat histogram bin with the second-highest magnitude (0.0 if no durations)

Return type:

float

strength_ratio_of_two_strongest_rhythmic_pulses(starts, ends, tempo=120.0, ppqn=480)[source]

Ratio of the magnitude of the strongest to second-strongest rhythmic pulse.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Ratio of the magnitude of the strongest to second-strongest rhythmic pulse (0.0 if no durations)

Return type:

float

strength_ratio_of_two_strongest_rhythmic_pulses_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

Ratio of the magnitude of the strongest to second-strongest rhythmic pulse (120-BPM standardized histogram).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Ratio of the magnitude of the strongest to second-strongest rhythmic pulse (120-BPM standardized histogram) (0.0 if no durations)

Return type:

float

combined_strength_of_two_strongest_rhythmic_pulses(starts, ends, tempo=120.0, ppqn=480)[source]

Sum of the magnitudes of the two strongest rhythmic pulses.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Sum of the magnitudes of the two strongest rhythmic pulses (0.0 if no durations)

Return type:

float

combined_strength_of_two_strongest_rhythmic_pulses_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

Sum of the magnitudes of the two strongest rhythmic pulses using tempo-standardized histogram.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Sum of the magnitudes of the two strongest rhythmic pulses using tempo-standardized histogram (0.0 if no durations)

Return type:

float

rhythmic_variability(starts, ends, tempo=120.0, ppqn=480)[source]

The standard deviation of the beat histogram bin magnitudes, excluding the first 40 bins.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Standard deviation of the beat histogram bin magnitudes, excluding the first 40 bins (0.0 if no durations)

Return type:

float

rhythmic_variability_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The standard deviation of the tempo-standardized beat histogram bin magnitudes, excluding the first 40 bins.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Standard deviation of the tempo-standardized beat histogram bin magnitudes, excluding the first 40 bins (0.0 if no durations)

Return type:

float

rhythmic_looseness(starts, ends, tempo=120.0, ppqn=480)[source]

The average width of beat histogram peaks. Width is defined as the distance between points at 30% of the peak height.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Average width of beat histogram peaks (0.0 if no durations)

Return type:

float

rhythmic_looseness_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The average width of beat histogram peaks using tempo-standardized histogram. Width is defined as the distance between points at 30% of the peak height.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Average width of beat histogram peaks using tempo-standardized histogram (0.0 if no durations)

Return type:

float

polyrhythms(starts, ends, tempo=120.0, ppqn=480)[source]

The fraction of strong beat-histogram peaks related to the strongest peak.

Among peaks at least 30% as tall as the maximum, returns the proportion whose bin is an integer multiple/factor of the strongest (multipliers 1, 2, 3, 4, 6, 8; ±3 bins).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

hits / n_peaks, or 0.0 if there are no qualifying peaks.

Return type:

float

polyrhythms_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The fraction of strong beat-histogram peaks related to the strongest peak using the tempo-standardized beat histogram.

Among peaks at least 30% as tall as the maximum, returns the proportion whose bin is an integer multiple/factor of the strongest (multipliers 1, 2, 3, 4, 6, 8; ±3 bins).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

hits / n_peaks, or 0.0 if there are no qualifying peaks.

Return type:

float

number_of_strong_rhythmic_pulses(starts, ends, tempo=120.0, ppqn=480)[source]

The count of BPM bins with strong rhythmic pulses (> 0.1 in the underlying beat histogram).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Count of BPM bins 40-200 with a thresholded strong-pulse value (> 0.1 in the underlying beat histogram), or 0.0 if no durations.

Return type:

float

number_of_strong_rhythmic_pulses_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The count of BPM bins with strong pulses (> 0.1 in the underlying standardized beat histogram).

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Count of BPM bins 40-200 with a thresholded strong-pulse value (> 0.1 in the underlying standardized histogram), or 0.0 if no durations.

Return type:

float

number_of_moderate_rhythmic_pulses(starts, ends, tempo=120.0, ppqn=480)[source]

The number of beat histogram peaks with normalized magnitudes over 0.01.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Number of beat histogram peaks with normalized magnitudes over 0.01 (0.0 if no durations)

Return type:

float

number_of_moderate_rhythmic_pulses_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The number of tempo-standardized beat histogram peaks with normalized magnitudes over 0.01.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Number of tempo-standardized beat histogram peaks with normalized magnitudes over 0.01 (0.0 if no durations)

Return type:

float

number_of_relatively_strong_rhythmic_pulses(starts, ends, tempo=120.0, ppqn=480)[source]

The number of peaks at least 30% of the max magnitude.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Number of peaks at least 30% of the max magnitude (0.0 if no durations)

Return type:

float

number_of_relatively_strong_rhythmic_pulses_tempo_standardized(starts, ends, tempo=120.0, ppqn=480)[source]

The number of tempo-standardized peaks at least 30% of the max magnitude.

Parameters:

  • starts (list[float]) – Note start times (seconds)

  • ends (list[float]) – Note end times (seconds)

  • tempo (float, optional) – Tempo in BPM (only used to convert seconds to quarter notes)

  • ppqn (int, optional) – Pulses per quarter note (MIDI resolution), default 480

Returns:

Number of tempo-standardized peaks at least 30% of the max magnitude (0.0 if no durations)

Return type:

float

minimum_note_duration(starts, ends)[source]

The minimum note duration in seconds.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

Returns:

Minimum note duration in seconds (0.0 if there are no notes)

Return type:

float

maximum_note_duration(starts, ends)[source]

The maximum note duration in seconds.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

Returns:

Maximum note duration in seconds

Return type:

float

equal_duration_transitions(starts, ends, tempo=120.0)[source]

The proportion of duration transitions that are equal in length.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

  • tempo (float, optional) – Included for API consistency; not used in this calculation.

Returns:

  • float – Proportion of equal duration transitions (0.0 to 1.0)

  • Citation

  • ——–

  • Steinbeck (1982)

Return type:

float

half_duration_transitions(starts, ends, tempo=120.0)[source]

The proportion of duration transitions that are halved or doubled.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

  • tempo (float, optional) – Included for API consistency; not used in this calculation.

Returns:

  • float – Proportion of half/double duration transitions (0.0 to 1.0)

  • Citation

  • ——–

  • Steinbeck (1982)

Return type:

float

dotted_duration_transitions(starts, ends, tempo=120.0)[source]

The proportion of duration transitions that are dotted.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

  • tempo (float, optional) – Included for API consistency; not used in this calculation.

Returns:

  • float – Proportion of dotted duration transitions (0.0 to 1.0)

  • Citation

  • ——–

  • Steinbeck (1982)

Return type:

float

amount_of_staccato(starts, ends)[source]

The proportion of notes with a duration shorter than 0.1 seconds.

Parameters:

  • starts (list[float]) – List of note start times

  • ends (list[float]) – List of note end times

Returns:

Fraction of notes shorter than 0.1 seconds

Return type:

float

Note

Though this feature is named Amount Of Staccato, it is a fixed-duration cutoff statistic rather than symbolic articulation parsing.

npvi(starts, ends, tempo=120.0)[source]

The normalized Pairwise Variability Index (nPVI) of note durations in quarter notes. The nPVI measures the durational variability of events, originally developed for language research to distinguish stress-timed vs. syllable-timed languages. Applied to music by Patel & Daniele (2003) to study the prosodic influences on musical rhythm.

Parameters:
Returns:

  • float – nPVI index value (higher values indicate greater durational variability)

  • Citation

  • ——–

  • Patel & Daniele (2003)

Return type:

float

onset_autocorrelation(starts, ends, divisions_per_quarter=4, max_lag_quarters=8, tempo=120.0, tempo_changes=None)[source]

The autocorrelation function of onset times weighted by duration accents. This is calculated by weighting the onset times by the duration accents, as defined by Parncutt (1994).

Onsets are converted to quarter-note beats using tempo before grid quantization.

Parameters:

  • starts (list[float]) – Note onset times in seconds

  • ends (list[float]) – Note offset times in seconds

  • divisions_per_quarter (int, optional) – Grid divisions per quarter note (default 4)

  • max_lag_quarters (int, optional) – Maximum lag in quarter notes (default 8)

  • tempo (float, optional) – Tempo in BPM (default 120)

  • tempo_changes (list[tuple[float, float]] | None)

Returns:

  • list[float] – Normalized autocorrelation from lag 0 through max_lag_quarters quarters

  • Citation

  • ——–

  • Parncutt (1994)

Return type:

list[float]

onset_autocorr_peak(starts, ends, divisions_per_quarter=4, max_lag_quarters=8, tempo=120.0, tempo_changes=None)[source]

Maximum onset autocorrelation excluding lag 0.

Parameters:
Return type:

float