#music #music-theory #pitch #scoring


Tonal pitch classes with enharmonic distinction

5 releases

0.1.1 May 19, 2020
0.1.0 May 18, 2020
0.0.3 May 16, 2020
0.0.2 May 15, 2020
0.0.1 May 15, 2020

#25 in Multimedia

21 downloads per month


377 lines


crate documentation build

A library for handling tonal pitch classes, keys, intervals, accidentals and alterations. A tonal pitch class (Tpc) does not distinguish pitches in different octaves, but it does distinguish different enharmonic spellings of notes, intervals, and keys. This is done based on the "line of fifths" concept.

Distinguishing enharmonic spellings is desirable in several applications:

  • In musical notation, where using an incorrect enharmonic spelling harms legibility
  • When using other tunings than twelve tone equal temperament (12TET), in which case notes normally considered enharmonic should actually be played at different pitches.

Another important type is the Step, which represents the fact that G sharp and G flat are written on the same line of the staff. A Step combined with a Key or Accidental gives a Tpc.

Using the Step type also helps you handle octaves. If you want the F above A flat, for instance, you would compare their Steps, see that F has a lower step than A flat, and therefore should be raised an octave.

Arithmetic operations with Tpcs and Intervals return optional values, because they may result in alterations beyond the domain of the library. Triple sharps/flats or double diminished/augmented intervals are not supported.


You can find the tonal pitch classes of the notes in a chord by specifying the chord as a collection of Intervals.

use tonality::{Tpc, Interval};

type Chord = Vec<Interval>;

let dom7: Chord = vec![Interval::Unison, Interval::Maj3, Interval::P5, Interval::Min7];
let root = Tpc::Fs;
let chord_tones: Vec<Tpc> = dom7
    // `Tpc` + `Interval` returns `Option<Tpc>`
    .filter_map(|&interval| root + interval)

let expected = vec![Tpc::Fs, Tpc::As, Tpc::Cs, Tpc::E];
assert_eq!(expected, chord_tones);


Types and operations, in particular the Tpc type, are influenced by Musescore's internal library.

Related crates

pitch_calc lets you convert between a number of different pitch representations, including the frequency domain.

rust-music-theory supports procedurally utilizing music theory notions like Note, Chord, Scale, Interval and more.

This crate might support conversion to and from types in the above mentioned crates in the future.


~22K SLoC