pytakt.pitch module

This module defines the Pitch class, the Interval class, the Key class, and utility functions for note numbers.

chroma(note_number) → int

Given a MIDI note number, this function returns the chroma value (aka pitch class), which is an integer between 0 and 11 where C is 0, C# is 1, D is 2, …, and B is 11.

Parameters:

note_number (int or float) – MIDI note number; if it is a float, it is first rounded to an integer before calculation.

octave(note_number) → int

Given a MIDI note number, this function returns the octave number (an integer where 4 represents the octave starting from the middle C).

Parameters:

note_number (int or float) – MIDI note number; if it is a float, it is first rounded to an integer before calculation.

chroma_profile(pitches) → List[int]

Given a list of MIDI note numbers or a score by pitches, it returns a list of 12 integers, with the frequency of occurrence recorded for each chroma value (pitch class).

Parameters:

pitches (iterable of Pitch or int, or Score) – Either an iterable of integers representing MIDI note numbers or a acore object.

Examples

>>> chroma_profile([C4, Bb5])
[1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0]
>>> chroma_profile(readsmf('menuet.mid'))
[20, 5, 33, 0, 14, 0, 19, 48, 0, 30, 0, 35]
class Pitch(value, sf=None, key=0, octave=4)

Bases: int

A class for objects that represent note pitches. It is inherited from the ‘int’ class, and therefore the objects can behave as integers representing MIDI note numbers, but differ in that they have the ‘sf’ attribute, which is additional information about enharmonics.

Attributes

sf

Enharmonics information (sharp-flat), indicating the number of sharps/flats, including those due to key signatures in the score. It is one of 2, -1, 0, 1, and 2, where a positive value indicates the number of sharps and a negative value indicates the number of flats. For example, if the object has 61 as an integer value (i.e., the MIDI note number is 61), it represents the C#4 note pitch if sf is 1, and represents Db4 if sf is -1.

Type:

int

Constructor

Parameters:

  • value (int, str, or Pitch) –

    Either an integer, a Pitch object, or a string representing the pitch. If it is an integer, its value is the MIDI note number; if it is a Pitch, its integer value is the MIDI note number. The pitch can also be specified by a string consisting of the following characters.

    • ’A’ to ‘G’ for pitch name (lowercase letters are also acceptable; B represents an 11 semitones higher pitch than C)

    • ’#’, ‘s’, or ‘+’ for sharps (two at most, to be placed after the pitch name)

    • ’b’, ‘f’, or ‘-’ for flats (two at most, after the ptich name)

    • ’%’ or ‘n’ for natural (after the pitch name)

    • ’0’ to ‘9’ for octave number (optional, after the note name; ‘4’ for the octave starting from the middle C)

    • ’^’ or a single quote for octave up

    • ’_’ or ‘,’ for octave down

    The value of the key argument is taken into account when converting strings to note numbers.

  • sf (int, optional) –

    The value of the sf attribute. If specified, the value becomes the sf attribute value. If not specified, it is determined by the following rules.

    • If value is a Pitch, its sf information is copied.

    • If value is int, it is guessed considering the value of the key argument.

    • If value is str, it is determined from the accidental symbols in the string and the value of the key argument.

  • key (Key, int, or str, optional) – Information about the key referred to when value is int or str. It should be a Key object or the first argument of the Key() constructor. Default is C major.

  • octave (int, optional) – Octave value when value is str and the string does not contain an octave number.

Examples

>>> Pitch(61)   # MIDI note number 61
Cs4             # Equivalent to Pitch(61, 1)
>>> Pitch(61, -1)
Db4
>>> Pitch(61, key='Db major')
Db4
>>> Pitch(C4, 1)
Bs3
>>> Pitch('C#4')
Cs4
>>> Pitch('_C', key='e major')
Cs3
>>> Pitch('Cn', key=3, octave=5)
C5
>>> Db4 + 2
63

Pitch Constants

Constants with Pitch object values are predefined from ‘C0’ to ‘B9’, each optionaly with s (sharp), ss (double sharp), b (flat), and bb (double flat) (e.g., Ds5, Bbb6). These values are equal to those where the constant names are passed as strings to the Pitch() constructor.

Arithmetic Rules

  • Comparison between Pitch objects (equality and order comparison) is performed only by the note number. The value of sf has no effect on the result of the comparison. For example, Cs4 == Db4 is true.

  • The result of (Pitch - Pitch) will be an Interval.

  • The result of (Pitch + Interval), (Interval + Pitch), or (Pitch - Interval) will be a Pitch, and sf will be calculated correctly as long as it is within the range +-2.

  • All other operations will be performed as ‘int’ type.


natural() → Pitch

Returns a Pitch object of the natural note (note where sharps and flats are removed).

tostr(*, lossless=False, octave=True, pitch_strings='CDEFGAB', sfn='sbn') → str

Returns a string representing the pitch (‘C4’, ‘Gbb6’, etc.).

Parameters:

  • lossless (bool) – If False (default), a string created with pitch_strings and sfn is always returned. When True, it returns a string in the form of a constructor call like ‘Pitch(Cs4, 0)’ if necessary, so that when the eval function is applied, it reproduces the original Pitch object exactly.

  • octave (bool, optional) – If False, returns a string without an octave number. Available only when lossless is False.

  • pitch_strings (sequence of str) – A collection of strings indexable from 0 to 6 used for pitch names. pitch_strings[0], …, pitch_strings[6] correspond to the strings for the C, …, B, respectively.

  • sfn (sequence of str) – A collection of strings indexable from 0 to 2 (or 1) that are used for accidentals. sfn[0] is the string for a sharp, sfn[1] is the string for a flat, and sfn[2] is currently unused.

Returns:

Result string

fixsf(key, set_sf_for_naturals=False, enh='heuristic') → Pitch

Returns a new Pitch object with the value of the sf attribute modified as appropriate for the key key. The original sf value behaves as a hint if it is non-zero.

Parameters:

  • key (Key, int, or str) – a key (an object of the Key class, or the first argument of the Key() constructor)

  • set_sf_for_naturals (bool) – If true, sets sf to 1 or -1 (opposite to signs in the key signature) for cases that need a natural sign when notated (e.g., D for the Db major key).

  • enh (str) – undocumented

Returns:

a new Pitch object

Examples

>>> Dbb4.fixsf('C major')
C4
>>> Ds4.fixsf('Eb major')
Eb4
>>> Pitch(Fs4, 0).fixsf('C major')
Fs4
>>> Pitch(D4, -1).fixsf('Db major')  # -1 is a hint
Ebb4
freq(afreq=440.0) → float

Returns the frequency assuming equal temperament.

Parameters:

  • self (Pitch, int, or float) – A Pitch object or a (fractional) MIDI note number

  • afreq (float, optional) – Specifies the frequency (Hz) of the A4 pitch

static from_freq(freq, sf=None, key=0, afreq=440.0, fractional=False) → Union[Pitch, float]

Constructs a Pitch object that is closest to the frequency freq assuming equal temperament.

Parameters:

  • freq (float) – frequency

  • sf (int, optional) – Has the same meaning as the sf argument of the Pitch() constructor.

  • key (Key, int, or str, optional) – Has the same meaning as the key argument of the Pitch() constructor.

  • afreq (float, optional) – Specifies the frequency (Hz) of the A4 pitch

  • fractional (bool, optional) – If True, a fractional MIDI note number is returned instead of a Pitch object.

class Interval(value, ds=None)

Bases: int

A class for objects representing intervals (difference between two pitches). It is inherited from the ‘int’ class and therefore the objects can behave as integers representing semitones. It is signed, i.e., it also represents negative intervals.

Attributes

ds

Signed distance on the staff. This is one less than the number of degrees, e.g., 2 for third intervals. Negative for negative intervals.

Type:

int

Constructor

Parameters:

  • value (str or int) –

    When it is a string, it specifies the interval like the following:

    • ’P1’ – perfect 1st degree, ‘m2’ – minor 2nd degree, ‘M2’ – major 2nd degree, ‘m3’ – minor 3rd degree, ‘M3’ – major 3rd degree, ‘P4’ – perfect 4th degree, ‘P5’ – perfect 5th degree, …

    • ’A1’ – augmented 1st degree, ‘A2’ – augmented 2nd degree, ‘A3’ – augmented 3rd degree, …

    • ’d2’ – diminished 2nd degree, ‘d3’ – diminished 3rd degree, …

    • ’AA1’ – double-argmented 1st degree, …

    • ’dd3’ – double-diminished 3rd degree, …

    • ’A’ and ‘d’ can be further increased.

    When it is an integer, it specifies the interval by semitones.

  • ds (int, optional) – When value is an integer, the value of the ds attribute must be specified by this argument.

Arithmetic Rules

  • Comparison between Interval objects (equality and order comparisons) is performed only be semitones. The value of the ds attribute has no effect on the result of the comparison. For example, Interval(‘A4’) == Interval(‘d5’) is true.

  • Sign inversion of an Interval inverts the signs of both the semitone and ds values.

  • The result of adding two Interval objects will be an Interval where the two intervals are stacked together (the semitones and ds values are added to each).

  • The subtraction (x-y) between Interval objects is equivalent to x+(-y).

  • Multiplication of an Interval and an integer results in an Interval where each of the semitone and ds values is multiplied by the integer.

  • The result of a remainder operation (x % y) between Interval objects is an Interval, which is equivalent to x - (int(x) // int(y)) * y.

  • For operations between Interval and Pitch, see the operation rules of the Pitch class.

  • All other operations will be performed as ‘int’ type.

Examples

>>> B4 - F4
Interval('A4')
>>> C4 + Interval('d5')
Gb4
>> Interval('A4') + Interval('d5')
Interval('P8')
>> Interval('P8') - Interval('M3')
Interval('m6')
>>> G5 - C4
Interval('P12')
>>> Interval('P12') % Interval('P8')
Interval('P5')
>>> int(Interval('A4'))
6
>>> Interval('A4') + 1
7

class Key(keydesc, minor=0, extended=False)

Bases: object

A class for objects that represent keys.

Attributes

signs

Its absolute value represents the number of signs in the key signature (usually 0-7, up to 11 when extended), and it is positive for sharps and negative for flats.

Type:

int

minor

0 for major keys, 1 for minor keys

Type:

int

Constructor

Parameters:

  • keydesc (int, str, or Key) –

    If it is an integer, it directly specifies the value of the signs attribute. If it is a string, the key is specified by a string matched by the regular expression below. It is case-insensitive.

    [A-G][#bsf]?[- ]*(major|minor)

    If it is a Key object, the constructor acts as a copy constructor.

  • minor (int, optional) – If keydesc is an integer, it specifies the value of the ‘minor’ attribute. Ignored if keydesc is any other type.

  • extended (bool, optional) – If True, then uncommon keys such as ‘G# major’ are allowed.

Examples

Key('C major')  Key('Eb-minor')  Key(-3)  Key(3,1)


tostr() → str

Returns a string representing the key (‘C major’, etc.).

getsf(note_number) → int

Given a note number, returns the number of sharps/flats implied by the key signature.

Parameters:

note_number (int) – MIDI note number

Returns:

An integer that, if it is positive, means the number of sharps, and if it is negative, its absolute value means the number of flats.

Examples

>>> Key('G-major').getsf(F4)
1
>>> Key('G-major').getsf(Fs4)
0
is_scale_tone(note_number) → bool

Given a note number, checks whether the note is on the scale implied by the key (major scale for major keys, natural minor scale for minor keys).

Parameters:

note_number (int) – MIDI note number

Returns:

True if the note is on the scale, or False otherwise.

gettonic(octave=4) → Pitch

Returns the tonic (principal pitch) of the key.

Parameters:

octave (int) – Octave number of the tonic to be returned.

static from_tonic(tonic, minor=0, extended=False) → Key

Creates a Key object from the pitch of its tonic.

Parameters:

  • tonic (Pitch or int) – Pitch of the tonic

  • minor (int, optional) – 0 for major, 1 for minor

  • extended (bool, optional) – If True, uncommon keys are allowed.