Tones

class pytheory.tones.Interval

Bases: object

Named constants for common musical intervals (in semitones).

UNISON = 0

MINOR_SECOND = 1

MAJOR_SECOND = 2

MINOR_THIRD = 3

MAJOR_THIRD = 4

PERFECT_FOURTH = 5

TRITONE = 6

PERFECT_FIFTH = 7

MINOR_SIXTH = 8

MAJOR_SIXTH = 9

MINOR_SEVENTH = 10

MAJOR_SEVENTH = 11

OCTAVE = 12

class pytheory.tones.Tone(name: str, *, alt_names: list[str] | None = None, octave: int | None = None, system: str | object = 'western')

Bases: object

__init__(name: str, *, alt_names: list[str] | None = None, octave: int | None = None, system: str | object = 'western') → None

Initialize a Tone with a name, optional octave, and musical system.

Parameters:

• name – The note name (e.g. "C", "C#4"). If the name contains a digit, it is parsed as the octave.

• alt_names – Alternate spellings for this tone (e.g. enharmonics).

• octave – The octave number. Overrides any octave parsed from name.

• system – The tuning system, either as a string key ("western") or a ToneSystem instance.

property exists: bool

True if this tone’s name is found in the associated system.

property system: object

The ToneSystem associated with this tone.

Lazily resolved from system_name on first access and cached.

property full_name: str

The tone name with octave appended, e.g. 'C4' or 'C'.

names() → list[str]

Return a list containing the primary name and all alternate names.

property is_natural: bool

True if this is a natural note (no sharp or flat).

property is_sharp: bool

True if this tone has a sharp (#).

property is_flat: bool

True if this tone has a flat (b after the first character).

property letter: str

The letter name without any accidental.

Example:

>>> Tone.from_string("C#4").letter
'C'
>>> Tone.from_string("Bb4").letter
'B'
>>> Tone.from_string("G4").letter
'G'

property enharmonic: str | None

The enharmonic equivalent of this tone, or None if there isn’t one.

Returns the alternate spelling: C# → Db, Db → C#, etc. Natural notes (C, D, E, F, G, A, B) have no enharmonic.

Example:

>>> Tone.from_string("C#4").enharmonic
'Db'

__repr__() → str

Return repr(self).

__str__() → str

Return str(self).

__add__(interval: int) → Tone

__sub__(other: int | Tone) → Tone | int

__lt__(other: Tone) → bool

Return self<value.

__le__(other: Tone) → bool

Return self<=value.

__gt__(other: Tone) → bool

Return self>value.

__ge__(other: Tone) → bool

Return self>=value.

__eq__(other: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

classmethod from_string(s: str, system: str | object | None = None) → Tone

Create a Tone by parsing a string like 'C#4' or 'Bb'.

Parameters:

• s – A note string, optionally including an octave number.

• system – The tuning system to associate with the tone.

Returns:

A new Tone instance.

classmethod from_tuple(t: tuple[str, ...]) → Tone

Create a Tone from a tuple of (name, *alt_names).

Parameters:

t – A tuple where the first element is the primary name and any remaining elements are alternate names (enharmonics).

Returns:

A new Tone instance.

classmethod from_frequency(hz: float, system: str | object = 'western') → Tone

Create a Tone from a frequency in Hz.

Finds the nearest note in 12-TET tuning (A4=440Hz).

Example:

>>> Tone.from_frequency(440)
<Tone A4>
>>> Tone.from_frequency(261.63)
<Tone C4>

classmethod from_midi(note_number: int, system: str | object = 'western') → Tone

Create a Tone from a MIDI note number.

MIDI note 60 = C4 (middle C), 69 = A4 (440 Hz).

Example:

>>> Tone.from_midi(60)
<Tone C4>
>>> Tone.from_midi(69)
<Tone A4>

classmethod from_index(i: int, *, octave: int, system: object) → Tone

Create a Tone from its index within a tuning system.

Parameters:

• i – The index of the tone in the system’s tone list.

• octave – The octave number.

• system – The ToneSystem instance.

Returns:

A new Tone instance.

add(interval: int) → Tone

Return a new Tone that is interval semitones above this one.

Parameters:

interval – Number of semitones to add (positive = up).

Returns:

A new Tone instance.

subtract(interval: int) → Tone

Return a new Tone that is interval semitones below this one.

Parameters:

interval – Number of semitones to subtract (positive = down).

Returns:

A new Tone instance.

interval_to(other: Tone) → str

Name the interval between this tone and another.

Returns a string like "perfect 5th", "major 3rd", or "octave". For intervals larger than an octave, returns the compound form (e.g. "minor 2nd + 1 octave").

Example:

>>> C4.interval_to(G4)
'perfect 5th'
>>> C4.interval_to(C5)
'octave'

property midi: int | None

MIDI note number (C4 = 60, A4 = 69).

The MIDI standard assigns integer note numbers from 0–127. Middle C (C4) is 60, and each semitone increments by 1.

Returns:

the MIDI note number, or None if no octave is set.

Return type:

int

transpose(semitones: int) → Tone

Return a new Tone transposed by the given number of semitones.

Alias for tone + semitones / tone - semitones. Positive values transpose up, negative values transpose down.

circle_of_fifths() → list[Tone]

The 12 tones of the circle of fifths starting from this tone.

Each step ascends by a perfect fifth (7 semitones). After 12 steps you return to the starting tone. The circle of fifths is the backbone of Western harmony — it determines key signatures, chord relationships, and modulation paths.

Clockwise = add sharps: C → G → D → A → E → B → F# → … Counter-clockwise = add flats (see circle_of_fourths).

Returns:

A list of 12 Tones.

circle_of_fourths() → list[Tone]

The 12 tones of the circle of fourths starting from this tone.

Each step ascends by a perfect fourth (5 semitones) — the reverse direction of the circle of fifths.

Clockwise = add flats: C → F → Bb → Eb → Ab → …

Returns:

A list of 12 Tones.

property frequency: float

The frequency of this tone in Hz (equal temperament, A4=440).

The result is cached after the first computation.

overtones(n: int = 8) → list[float]

The first n overtones (harmonic series) of this tone.

The harmonic series is the foundation of timbre and consonance. When a string or air column vibrates, it produces not just the fundamental frequency but also integer multiples: 2f, 3f, 4f…

The intervals between consecutive harmonics form the basis of Western harmony:

Harmonic  Ratio  Interval from fundamental
1         1:1    Unison (the fundamental)
2         2:1    Octave
3         3:1    Octave + perfect 5th
4         4:1    Two octaves
5         5:1    Two octaves + major 3rd
6         6:1    Two octaves + perfect 5th
7         7:1    Two octaves + minor 7th (slightly flat)
8         8:1    Three octaves

The reason a perfect fifth sounds consonant is that the 3rd harmonic of the lower note aligns with the 2nd harmonic of the upper note (when the upper note is a fifth above). More shared harmonics = more consonance.

Parameters:

n – Number of harmonics to return (default 8).

Returns:

List of frequencies in Hz.

pitch(*, reference_pitch: float = 440, temperament: str = 'equal', symbolic: bool = False, precision: int | None = None) → float