Pitch interval

Full module path: melody_features.feature_definitions.pitch_interval.

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

Pitch interval feature definitions.

pitch_interval(pitches)

The intervals (in semitones) between consecutive pitches in the melody.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

List of intervals between consecutive pitches in semitones

Return type:

list[int]

absolute_interval_range(pitches)

The range between the largest and smallest absolute interval size.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Range between largest and smallest absolute interval in semitones

Return type:

int

mean_absolute_interval(pitches)

The arithmetic mean of the absolute intervals in the melody.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Mean absolute interval size in semitones

Return type:

float

standard_deviation_absolute_interval(pitches)

The standard deviation of the absolute intervals in the melody.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Standard deviation of absolute interval sizes in semitones

Return type:

float

modal_interval(pitches)

The most common interval size in the melody.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Most frequent interval size in semitones

Return type:

int

ivdist1(pitches, starts, ends, tempo=120.0, channels=None)

Interval distribution weighted by duration accent.

Parameters:

• pitches (list[int]) – List of MIDI pitch values

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

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

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

• channels (list[int] | None)

Returns:

Map from interval in semitones (-12..12) to proportion

Return type:

dict

ivdist2(pitches, starts, ends, tempo=120.0)

Second-order interval transition distribution (MIDI Toolbox ivdist2.m).

Each note is assigned an interval class (incoming interval modulo octave, with 0 for the first note). Transition weights use the sum of Parncutt duration accents of the two notes. Keys are (from_interval, to_interval) in semitones (approximately -11 to 11).

Parameters:

• pitches (list[int]) – List of MIDI pitch values

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

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

• tempo (float) – Unused; kept for API consistency with other distribution features

Returns:

Map from interval-class transition to proportion

Return type:

dict

ivdirdist1(pitches, starts, ends, tempo=120.0, channels=None)

Directional interval bias for each interval size (1-12 semitones).

Derived from duration-accent-weighted ivdist1 (MIDI Toolbox ivdirdist1.m).

Parameters:

• pitches (list[int])

• starts (list[float])

• ends (list[float])

• tempo (float)

• channels (list[int] | None)

Return type:

dict[int, float]

ivsizedist1(pitches, starts, ends, tempo=120.0, channels=None)

Interval-size distribution (0-12 semitones) from ivdist1.

Derived from duration-accent-weighted ivdist1 (MIDI Toolbox ivsizedist1.m).

Parameters:

• pitches (list[int])

• starts (list[float])

• ends (list[float])

• tempo (float)

• channels (list[int] | None)

Return type:

dict[int, float]

interval_direction(pitches)

The sequence of interval directions in the melody, where 1 represents upward motion, 0 represents no motion, and -1 represents downward motion.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Sequence of interval directions, where: 1 represents upward motion 0 represents same pitch -1 represents downward motion

Return type:

list[int]

interval_direction_mean(pitches)

The mean of the direction of each interval in the melody.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Mean of interval directions

Return type:

float

Note

Unisons contribute 0 to both numerator and denominator because the mean is taken over the full direction sequence {-1, 0, 1}.

interval_direction_std(pitches)

The standard deviation of the direction of each interval in the melody.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Population standard deviation of interval directions

Return type:

float

Note

Uses population variance (divide by N)

average_length_of_melodic_arcs(pitches)

The average number of notes that separate peaks and troughs in melodic arcs.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Average number of notes that separate peaks and troughs in melodic arcs

Return type:

float

average_interval_span_by_melodic_arcs(pitches)

The average interval span of melodic arcs.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Average interval span of melodic arcs, or 0.0 if no arcs found

Return type:

float

distance_between_most_prevalent_melodic_intervals(pitches)

The absolute difference between the two most common interval sizes.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Absolute difference between two most common intervals, or 0.0 if fewer than 2 intervals

Return type:

float

melodic_interval_histogram(pitches)

Histogram of absolute melodic interval sizes in semitones.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Mapping from interval size (0–127 semitones) to count. Only sizes with count > 0 are included.

Return type:

dict[int, int]

Note

We only return bins for intervals that have a count > 0. An implementation that is truer to the original jSymbolic implementation would return 128 bins (0-127) regardless of how any different intervals are present.

melodic_large_intervals(pitches)

The proportion of intervals >= 13 semitones.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of large intervals, or -1.0 if no intervals

Return type:

float

variable_melodic_intervals(pitches, interval_level)

The proportion of intervals >= specified size.

Parameters:

• pitches (list[int]) – List of MIDI pitch values

• interval_level (Union[int, list[int]]) – Minimum interval size in semitones

Returns:

Proportion of intervals == interval_level, or -1.0 if no intervals

Return type:

float

melodic_thirds(pitches)

The proportion of intervals that are thirds (3 or 4 semitones).

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are thirds (3 or 4 semitones)

Return type:

float

melodic_perfect_fourths(pitches)

The proportion of intervals that are perfect fourths (5 semitones).

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are perfect fourths (5 semitones)

Return type:

float

melodic_tritones(pitches)

The proportion of intervals that are tritones (6 semitones).

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are tritones (6 semitones)

Return type:

float

melodic_perfect_fifths(pitches)

The proportion of intervals that are perfect fifths (7 semitones).

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are perfect fifths (7 semitones)

Return type:

float

melodic_sixths(pitches)

The proportion of intervals that are sixths (8 or 9 semitones).

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are sixths (8 or 9 semitones)

Return type:

float

melodic_sevenths(pitches)

The proportion of intervals that are sevenths (10 or 11 semitones).

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are sevenths (10 or 11 semitones)

Return type:

float

melodic_octaves(pitches)

The proportion of intervals that are octaves (12 semitones).

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are octaves (12 semitones)

Return type:

float

minor_major_third_ratio(pitches)

The ratio of minor thirds to major thirds.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Ratio of minor thirds to major thirds, or NaN if no major thirds exist

Return type:

float

Note

Instead of matching jSymbolic behavior (returning 0.0 when there are no major thirds), this returns NaN when there are no major thirds (including cases where minor thirds are present).

direction_of_melodic_motion(pitches)

The proportion of upward melodic motions with regards to the total number of melodic motions.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of upward melodic motion (0.0 to 1.0), or -1.0 if no intervals

Return type:

float

Note

This feature excludes unisons from its denominator and maps only to [0, 1].

number_of_common_melodic_intervals(pitches)

The number of intervals that appear in at least 9% of melodic transitions.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Number of significant intervals

Return type:

int

prevalence_of_most_common_melodic_interval(pitches)

The proportion of intervals that are the most common interval.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are the most common interval, or 0 if no intervals

Return type:

float

relative_prevalence_of_most_common_melodic_intervals(pitches)

The ratio of the frequency of the second most common interval to the frequency of the most common interval.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Ratio of second most common interval frequency to most common interval frequency. Returns 0.0 if fewer than 2 intervals or only one unique interval.

Return type:

float

amount_of_arpeggiation(pitches)

The proportion of pitch intervals in the melody that constitute triadic movements.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that match arpeggio patterns (0.0-1.0). Returns -1.0 if input is None, 0.0 if input is empty or has only one value.

Return type:

float

chromatic_motion(pitches)

The proportion of chromatic motion in the melody. Chromatic motion is defined as a melodic interval of 1 semitone.

Parameters:

pitches (list[int]) – List of MIDI pitch values

Returns:

Proportion of intervals that are chromatic (0.0-1.0). Returns -1.0 if input is None, 0.0 if input is empty or has only one value.

Return type:

float