Overview

The idea behind this library is that the central object is the interval. Pitches are derived from intervals by interpreting them with respect to a reference point. This is much like the relation between vectors (= intervals) and points (= pitches). For example, the pitch E♭4 can be represented as an interval (e.g. a minor third, m3:0) above a reference pitch such as Middle C (C4). Intervals and Pitches come in families of four variants:

• *Interval represents a normal interval

• *Pitch represents a normal pitch

• *IntervalClass represents an interval with octave equivalence

• *PitchClass represents a pitch with octave equivalence

Similar to vectors and points, intervals and pitches support a number of operations such as addition and scalar multiplication.

The following representations of intervals and pitches are implemented so far:

• spelled: based on Western notation

• spelled: based on Western notation

• enharmonic: based on the chromatic 12-tone system (*)

• frequency: based on the frequencies and frequency ratios (*)

• harmonic: based prime-factorized just intervals (*)

(*): The interfaces for these types are not yet standardized/synchronized with the implementations in other languages and lack detailed documentation. They implement the basic pitch/interval interface, but type-specific details (notation etc.) might change in the future.

Generic Operations

The operations of the generic interface are based on intervals as the fundamental elements. Intervals can be thought of as vectors in a vector space (or more precisely: a module over integers). They can be added, subtracted, negated, and multiplied with integers. Pitches, on the other hand, can be seen as points in this space and are represented as intervals in relation to an (implicit) origin.

Intervals. (here denoted as i) support the following operations:

• i + i

• i - i

• -i

• i * int

• int * i

• i.direction()

• i.abs()

i.direction() indicates the logical direction of the interval by musical convention (upward = positive, downward = negative), even if the interval space is multi-dimensional. Consequently, i.abs() ensures that an interval is neutral or upward-directed. For interval classes (which are generally undirected), the sign indicates the direction of the “shortest” class member:

>>> SpelledIntervalClass("P4").direction()
1
>>> SpelledIntervalClass("P5").direction() # == -"P4"
-1

In addition to arithmetic operations, some special intervals are defined:

• I.unison()

• I.octave()

• I.chromatic_semitone() (a chromatic semitone, optional)

• i.is_step() (optional, a predicate that test whether the interval is considered a “step”)

Finally, some operations specify the relationship between intervals and interval classes:

• i.ic(): Returns the corresponding interval class.

• i.embed(): Returns a canonical embedding of an interval class into interval space.

Pitch operations generally interact with intervals (and can be derived from the interval operations):

• p + i -> p

• i + p -> p

• p - i -> p

• p - p -> i

• p.pc() -> pc

• pc.embed() -> p

Besides the specific functions of the interface, pitch and interval types generally implement basic functions such as

• equality

• comparison

• hashing

• printing in standard notation

Note that the ordering of pitches is generally not unique, so comparison uses an appropriate convention for each interval type. If you need musically valid comparisons, use semantic methods such as direction() as appropriate to your use case.

Reference

Intervals

class pitchtypes.Interval

The basic interface implemented by every interval (and interval class) type.

abs()

For downward intervals, return their upward counterpart, otherwise just return the interval itself.

Returns:

the absolute interval

abstract direction()

Determines the direction of the interval: 1 for up, -1 for down and 0 for neutral. Different types may have different conventions for the direction of an interval.

Returns:

the interval’s direction (-1 / 0 / 1, integer)

abstract embed()

For interval classes, return an embedding into the interval space in a (type-dependent) default octave. For non-class intervals, return the interval itself.

Returns:

a non-class version of this interval

abstract ic()

Return the interval class that corresponds to this interval. If the interval is already an interval class, it is returned itself.

Returns:

the interval’s corresponding interval class

abstract classmethod octave()

Create the octave interval of this type.

Returns:

an octave interval

abstract semitones()

Return the number of semitones corresponding to the interval.

abstract steps()

Return the number of diatonic steps corresponding to the interval.

to_class()

Alias for ic(), but also supported by pitch types.

Returns:

the interval’s corresponding interval class

abstract classmethod unison()

Create the unison interval of this type.

Returns:

a unison interval

class pitchtypes.Chromatic

Some intervals have the notion of a chromatic semitone and implement this interface.

abstract classmethod chromatic_semitone()

Return a chromatic semitone (augmented unison) of this type.

Returns:

a chromatic semitone interval

class pitchtypes.Diatonic

Some intervals have a notion of a diatonic step and implement this interface.

abstract is_step()

Return True if the interval is considered a step, False otherwise.

Returns:

the stepness of the interval (boolean)

Pitches

class pitchtypes.Pitch

The basic interface that is implemented by every pitch (and pitch class) type.

abstract embed()

For a pitch class, returns the corresponding pitch in a (type-dependent) default octave. For non-class pitches, returns the pitch itself.

Returns:

a non-class version of this pitch

abstract interval_from(other)

Computes the interval from another pitch to this pitch.

Parameters:

other – another pitch

Returns:

the interval from other to self

interval_to(other)

Computes the interval from this pitch to another pitch.

Parameters:

other – another pitch

Returns:

the interval from self to other

abstract midi()

Return the MIDI number corresponding to the pitch.

abstract pc()

Returns the pitch class corresponding to the pitch. For pitch classes, it returns the pitch class itself.

Returns:

the pitch class that corresponds to this pitch

abstract semitones()

Return the number of chromatic semitones corresponding to the pitch.

abstract steps()

Return the number of diatonic steps corresponding to the pitch.

to_class()

Alias for pc(), but also supported by interval types.

Returns:

the pitch class that corresponds to this pitch