alto.theory.scales
Scales, modes, key signatures and chords, built from spelled intervals.
SCALES and CHORDS map a name to the list of intervals above the tonic or root. build turns such a list into notes,
and the other functions work out key signatures, mode tonics and arpeggios from them.
Examples
>>> [str(n) for n in build(Note.parse("D4"), intervals=SCALES["Dorian"])]
['D4', 'E4', 'F4', 'G4', 'A4', 'B4', 'C5']
>>> [str(n) for n in build(Note.parse("C4"), intervals=CHORDS["minor 7th"])]
['C4', 'E♭4', 'G4', 'B♭4']
major_key_tonic
def major_key_tonic(count: int) -> Note
Return the tonic of the major key with a given number of sharps or flats.
Parameters
count(int): Sharps (positive) or flats (negative) in the key signature, from -7 to 7.
Returns
- Note: The tonic, in octave 4.
Raises
- KeyError: If
countis outside -7..7.
Examples
>>> str(major_key_tonic(2)) # two sharps: D major
'D4'
>>> str(major_key_tonic(-3)) # three flats: E♭ major
'E♭4'
mode_tonic
def mode_tonic(
count: int,
*,
mode: str,
) -> Note
Return the note a scale in a given mode starts on, for a given key signature.
The notes of a mode are those of a major scale started from another degree. D Dorian, for example, has the key signature of C major, started from its second note.
Parameters
count(int): Sharps (positive) or flats (negative) in the key signature, from -7 to 7.mode(str): A key ofMODE_DEGREE, such as “Dorian” or “Natural minor (Aeolian)”. Keyword-only.
Returns
- Note: The tonic of that mode, in octave 4 or 5.
Examples
>>> str(mode_tonic(0, mode="Dorian")) # no sharps or flats: D Dorian
'D4'
>>> str(mode_tonic(2, mode="Natural minor (Aeolian)")) # two sharps: B minor
'B4'
arpeggio
def arpeggio(
root: Note,
*,
intervals: list[Interval],
inversion: int = 0,
) -> list[Note]
Return a chord broken and rising from its lowest note, then that note again an octave higher.
Parameters
root(Note): The root of the chord.intervals(list of Interval): The intervals above the root that make the chord, such asCHORDS["major"]. Keyword-only.inversion(int, default 0): How many of the lowest chord tones are moved up an octave first: 0 is root position, 1 puts the third at the bottom, 2 the fifth. Keyword-only.
Returns
- list of Note: The chord tones from the lowest up, ending on the lowest note an octave higher.
Examples
>>> [str(n) for n in arpeggio(Note.parse("C4"), intervals=CHORDS["major"])]
['C4', 'E4', 'G4', 'C5']
>>> [str(n) for n in arpeggio(Note.parse("C4"), intervals=CHORDS["major"], inversion=1)]
['E4', 'G4', 'C5', 'E5']
build
def build(
tonic: Note,
*,
intervals: list[Interval],
) -> list[Note]
Build the notes of a scale or chord above a tonic.
Parameters
tonic(Note): The first note.intervals(list of Interval): The intervals above the tonic, including the unison, such as a value ofSCALESorCHORDS. Keyword-only.
Returns
- list of Note: The tonic transposed by each interval, in order.
Examples
>>> [str(n) for n in build(Note.parse("G4"), intervals=SCALES["Major (Ionian)"])]
['G4', 'A4', 'B4', 'C5', 'D5', 'E5', 'F♯5']
key_signature
def key_signature(
tonic_name: str,
*,
scale: str = 'Major (Ionian)',
) -> int
Return the key signature of a scale as a signed count of accidentals.
Parameters
tonic_name(str): The tonic in plain text without an octave, such as ‘G’, ‘Eb’ or ‘F#’.scale(str, default “Major (Ionian)”): A key ofSCALES. Keyword-only.
Returns
- int: The sum of the accidentals of the scale’s notes: positive for sharps, negative for flats.
Examples
>>> key_signature("G") # G major has one sharp
1
>>> key_signature("Eb") # E♭ major has three flats
-3
>>> key_signature("A", scale="Natural minor (Aeolian)") # A minor has none
0
format_key_signature
def format_key_signature(count: int) -> str
Describe a key signature in words.
Parameters
count(int): Sharps (positive) or flats (negative).
Returns
- str: For example ‘1 sharp’, ‘3 flats’ or ‘no sharps or flats’.
Examples
>>> format_key_signature(0)
'no sharps or flats'
>>> format_key_signature(1)
'1 sharp'
>>> format_key_signature(-3)
'3 flats'
all_tonics
def all_tonics(max_accidentals: int = 1) -> list[Note]
Return every spelled tonic in octave 4, within a limit on accidentals.
Parameters
max_accidentals(int, default 1): The most sharps or flats a tonic may have, so 1 allows C♭ through B♯ but not double sharps.
Returns
- list of Note: Each letter with each accidental from
-max_accidentalstomax_accidentals, letters in the order C to B.
Examples
>>> len(all_tonics())
21
>>> [str(n) for n in all_tonics(0)]
['C4', 'D4', 'E4', 'F4', 'G4', 'A4', 'B4']