Interval

class music_embedding.interval.interval(interval_order: int = 1, interval_type: int = 0, octave_offset: int = 0, is_descending: int = 0, semitones: int = 0)[source]

Bases: object

A class representing musical intervals, offering functionality to handle interval characteristics, conversions, and descriptions within music theory.

Notes

The class provides both numerical and one-hot-encoded methods for representing interval characteristics, and it includes methods for converting between semitone distances and interval qualities.

Attributes:

interval_orderint: The ordinal number of the interval, ranging from 1 (unison) to 7 (seventh).
interval_typeint: The quality of the interval, represented by integers: -2 (diminished), -1 (minor), 0 (perfect), 1 (major), 2 (augmented).
octave_offsetint: The octave offset for compound intervals; 0 if the interval is within a single octave.
is_descendingint: Indicates the direction of the interval: 0 for ascending, 1 for descending.
semitonesint: The number of semitones in the interval.

Methods

`get_name`([semitones])	Generates the interval's name from its internal representation.
`get_one_hot_specs_list`()	Provides a one-hot encoding of the interval's order and type, and represents the descending status and octave offset as an integer and boolean, respectively.
`get_silence_specs_list`()	Provides a representation of silence in the interval format.
`get_specs_list`()	Returns the interval's characteristics as a list of integers.
`interval2semitone`([specs])	Returns the distance between the two notes of the interval in semitones.
`is_silence`()	Determines if the interval represents silence, based on its specifications.
`semitone2interval`([semitones])	Calculates the interval characteristics based on their semitone distance.
`set_one_hot_specs_list`(interval_order, ...)	Sets the interval's characteristics based on one-hot encoded representations and integer values.
`set_specs_list`(specs)	Sets the interval's characteristics from a list or dictionary.

feature_dimensions = 4

get_name(semitones: int | None = None) → str[source]

Generates the interval’s name from its internal representation. If semitones is provided, the interval characteristics are updated accordingly before generating the name.

Parameters:

semitonesint | None, default=None: If provided, the number of semitones is used to update the interval characteristics.

Returns:

str: The name of the interval, including its quality, ordinal number, and direction (ascending/descending).

Notes

Returns “Silence” if the interval represents silence. The name includes the interval’s quality (diminished, minor, perfect, major, augmented), its ordinal number (1st, 2nd, etc.), and its direction (ascending or descending) if applicable.

get_one_hot_specs_list() → Dict[str, List[int] | int | bool][source]

Provides a one-hot encoding of the interval’s order and type, and represents the descending status and octave offset as an integer and boolean, respectively.

Returns:

Dict[str, List[int] | int, bool]]: A dictionary containing one-hot encoded representations of the interval order and type, the descending status as a boolean, and the octave offset as an integer. Keys are ‘interval_order’, ‘interval_type’, ‘is_descending’, and ‘octave_offset’.

static get_silence_specs_list() → List[int][source]

Provides a representation of silence in the interval format.

Silence is represented as a list of zeros with a length equal to the number of feature dimensions of the interval class.

Returns:

List[int]: A list of integers representing silence, with all elements set to zero.

get_specs_list() → List[int][source]

Returns the interval’s characteristics as a list of integers.

Returns:

List[int]: A list containing the interval’s characteristics in the following order: [interval_order, interval_type, is_descending, octave_offset]

interval2semitone(specs: List[int] | None = None) → int[source]

Returns the distance between the two notes of the interval in semitones.

Parameters:

specsList[int] | None, optional: A list containing the interval characteristics in the following order: - interval_order (first to seventh) - interval_type (-2: dim, -1: min, 0: perfect, 1: Maj, 2: Aug) - is_descending (0 for ascending, 1 for descending) - octave_offset (octave offset of the interval, 0 if not compound) If None, uses the current interval’s properties.

Returns:

int: Number of semitones in the interval.

Notes

Updates interval parameters if specs is passed.
Faulty interval representation handling:
- If the interval is 1st, 4th, or 5th and the interval type is set to minor (m) or Major (M),
calculates the perfect (P) interval. * If the interval is 2nd, 3rd, 6th, or 7th and the interval type is set to perfect (P), calculates the Major (M) interval.

is_silence() → bool[source]

Determines if the interval represents silence, based on its specifications.

Silence is represented by an interval with all attributes set to zero values.

Returns:

bool: True if the interval represents silence, False otherwise.

semitone2interval(semitones: int | None = None) → Dict[str, int][source]

Calculates the interval characteristics based on their semitone distance. If the ‘semitones’ argument is provided, it updates the instance’s ‘semitones’ attribute before calculating the interval.

Semitone-interval Q-Table

Semitones	Interval
0	Perfect 1st
1	minor 2nd
2	Major 2nd
3	minor 3rd
4	Major 3rd
5	Perfect 4th
6	diminished 5th
7	Perfect 5th
8	minor 6th
9	Major 6th
10	minor 7th
11	Major 7th

Parameters:

semitonesint | None, default=None: The number of semitones in the interval. If provided, updates the instance’s ‘semitones’ attribute.

Returns:

dict: A dictionary with the updated interval characteristics: ‘interval_order’, ‘interval_type’, ‘octave_offset’, and ‘is_descending’.

set_one_hot_specs_list(interval_order: List[int], interval_type: List[int], is_descending: int, octave_offset: int) → None[source]

Sets the interval’s characteristics based on one-hot encoded representations and integer values.

Parameters:

interval_orderList[int]: One-hot encoding representation of the interval’s order: 1st to 7th. A list of 7 integers, where exactly one element is 1, and the others are 0, indicating the order of the interval.
interval_typeList[int]: One-hot encoding representation of the interval’s type: -2 (diminished) to 2 (augmented). A list of 5 integers, where exactly one element is 1, and the others are 0, indicating the type of the interval.
is_descendingint: Indicates the direction of the interval: 0 for ascending, 1 for descending.
octave_offsetint: The octave offset for compound intervals; 0 if the interval is within a single octave.

set_specs_list(specs: List[int] | Dict[str, int] | None) → None[source]

Sets the interval’s characteristics from a list or dictionary.

Parameters:

specsList[int] | Dict[str, int] | None: A list or dictionary containing the interval’s characteristics, or None. The list or dictionary should contain the following elements in order: interval_order (int), interval_type (int), is_descending (int), and octave_offset (int).

Raises:

ValueError: If any of the provided values for interval_order, interval_type, is_descending, or octave_offset are out of their valid ranges.

Notes

The valid ranges for the attributes are as follows: - interval_order: between 0 and 7 (inclusive) - interval_type: between -2 and 2 (inclusive) - is_descending: either 0 or 1 - octave_offset: between 0 and 9 (inclusive)