Welcome to pitchtools’s documentation!

pitchtools Package

Set of routines to work with musical pitches, convert to and from frequencies, notenames, etc. Microtones are fully supported, both as fractional midinotes and as notenames.

Features

  • convert between frequencies, midinotes and notenames

  • microtones are fully supported

  • split a pitch into its multiple components (pitch class, octave, microtonal deviation, etc.)

  • transpose a pitch taking its spelling into consideration

  • create custom pitch converters to work with custom reference frequencies, or modify the reference frequency globally

Microtonal notation

Some shortcuts are used for round microtones:

Symbol

Cents

+

+50

-

-50

>

+25

<

-25

There is some flexibility regarding notenames: the octave can be placed before the note or after, and the pitch-class is case-insensitive.

Some example notenames

Midinote

Notename

Alternative notation

60.25

4C+25 / 4C>

c4+25 / c>4

60.45

4C+45

C4+45

60.5

4C

c4

60.75

4Db-25

Db4-25 / db4-25

61.5

4D-

d4-

61.80

4D-20

D4

63

4D#

d#4

63.5

4D#+

d#+4

63.7

4E-30

E4-30

Global settings vs Converter objects

To convert to and from frequencies a reference frequency (A4) is needed. In pitchtools there are set of global functions (m2f(), f2m(), n2f(), etc) which rely on a global reference. This reference can be modified via set_reference_freq().

It is also possible to create an ad-hoc converter (PitchConverter). This makes it possible to customize the reference frequency without any side-effects

Example

# Set the value globally
>>> set_reference_freq(443)
>>> n2f("A4")
443.0

# Create a Converter object
>>> cnv = PitchConverter(a4=435)
>>> print(cnv.n2f("4C"))
258.7

Functions

accidental_name(alteration_cents[, ...])

The name of the accidental corresponding to the given cents

alteration_to_cents(alteration)

Convert an alteration to its corresponding cents deviation

amp2db(amp)

convert amp (0, 1) to dB

as_midinotes(x)

Tries to interpret x as a list of pitches, returns these as midinotes

cents2pitchbend(cents[, maxcents])

Convert a deviation in cents to the corresponding value as pitchbend.

cents_repr(cents[, eighthToneShortcuts])

Return the string representation of cents

construct_notename(octave, letter, alter, cents)

Utility function to construct a valid notename

db2amp(db)

convert dB to amplitude (0, 1)

enharmonic(notename)

Returns the enharmonic variant of notename

enharmonic_variations(notes[, fixedslots, force])

Generates all enharmonic variations of the given notes

f2m(freq)

Convert a frequency in Hz to a midi-note

f2n(freq)

Return the notename corresponding to the given freq

freq2mel(freq)

Convert a frequency to its place in the mel-scale :rtype: float

freq_round(freq[, semitone_divisions])

Round the freq.

get_reference_freq()

Get the reference frequency for this converter

i2r(interval)

Convert a semitone interval to a ratio between 2 freqs.

interval2ratio(interval)

Convert a semitone interval to a ratio between 2 freqs.

is_valid_notename(notename[, minpitch])

Returns true if notename is valid

m2f(midinote)

Convert a midi-note to a frequency

m2n(midinote)

Convert midinote to notename

mel2freq(mel)

Convert a position in the mel-scale to its corresponding frequency

midi_to_note_parts(midinote)

Convert a midinote into its parts as a note

n2f(note)

Convert a notename to its corresponding frequency

n2m(note)

Convert a notename to a midinote

normalize_notename(notename)

Convert notename to its canonical form

notated_interval(n0, n1)

Gives information regarding the notated interval between n0 and n1

notated_pitch(pitch[, semitone_divisions])

Convert a note or a (fractional) midinote to a NotatedPitch

notename_upper(notename)

Convert from 4eb to 4Eb or from eb4 to Eb4

notes2ratio(n1, n2[, maxdenominator])

Find the ratio between n1 and n2

pitch_round(midinote[, semitone_divisions])

Round midinote to the next (possibly microtonal) note

pitchbend2cents(pitchbend[, maxcents])

Convert a MIDI pitchbend to its corresponding deviation in cents

pitchclass(notename[, semitone_divisions])

Returns the pitchclass of a given note, rounded to the nearest semitone division

quantize_midinote(midinote, ...[, method])

Quantize midinote to the next semitone division

quantize_notename(notename, ...)

Quantize notename to the next semitone divisions

r2i(ratio)

Convert the ratio between 2 freqs.

ratio2interval(ratio)

Convert the ratio between 2 freqs.

set_reference_freq(a4)

Set the reference freq.

split_cents(notename)

Split a notename into the chromatic note and the cents deviation.

split_frequency_deviation(pitch)

For a pitch given as 4Eb-14hz, returns ('4Eb', -14)

split_notename(notename)

Splits a notename into octave, letter, alteration and cents

str2midi(s)

Accepts all that n2m accepts but with the addition of frequencies

transpose(notename, interval[, white_enharmonic])

Transpose a note by an interval taking spelling into account

vertical_position(note)

Return the vertical notated position of a note

vertical_position_to_note(pos)

Given a vertical position as an integer, returns the corresponding (diatonic) note

Classes

NotatedPitch(octave, diatonic_index, ...)

A parsed notename to be queried in relation to its musical notation

NoteParts(octave, diatonic_name, alteration, ...)

Represents the parts of a notename

PitchConverter([a4, eightnote_symbol])

Convert between midinote, frequency and notename.