add frequency_to_note_cents function; update docs

Author: CedarGroveStudios

cedargrove_midi_tools.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2022 JG for Cedar Grove Maker Studios
+# SPDX-FileCopyrightText: Copyright (c) 2023 JG for Cedar Grove Maker Studios
 #
 # SPDX-License-Identifier: MIT
 """
@@ -31,15 +31,14 @@
 
 def note_or_name(value):
     """Bidirectionally translates a MIDI sequential note value to a note name
-    or a note name to a MIDI sequential note value. Note values are
-    of integer type in the range of 0 to 127 (inclusive). Note names are
-    character strings expressed in the format NoteOctave, such as
-    'C4' or 'G#7'. Note names can range from 'C-1' (note value 0) to
-    'F#9' (note value 127). If the input value is outside of the note
-    value or name range, the value of None is returned.
+    or a note name to a MIDI sequential note value. Note values are integers in
+    the range of 0 to 127 (inclusive). Note names are character strings
+    expressed in the format NoteOctave such as 'C4' or 'G#7'. Note names range
+    from 'C-1' (note value 0) to 'F#9' (note value 127). If the input value is
+    outside the note value or name range, the value of `None` is returned.
 
     :param union(int, str) value: The note name or note value input. Note value
-    is an integer; note name is a string. No default value.
+    is an integer Note name is a string. No default value.
     """
     if isinstance(value, str):
         # Input is a string, so it's a note name
@@ -52,11 +51,10 @@ def note_or_name(value):
 
 def note_to_name(note):
     """Translates a MIDI sequential note value to a note name. Note values are
-    of integer type in the range of 0 to 127 (inclusive). Note names are
-    character strings expressed in the format NoteOctave, such as
-    'C4' or 'G#7'. Note names can range from 'C-1' (note value 0) to
-    'F#9' (note value 127). If the input value is outside of that range,
-    the value of None is returned.
+    integers in the range of 0 to 127 (inclusive). Note names are character
+    strings expressed in the format NoteOctave such as 'C4' or 'G#7'. Note
+    names range from 'C-1' (note value 0) to 'F#9' (note value 127). If the
+    input value is outside that range, the value of `None` is returned.
 
     :param int note: The note value input in the range of 0 to 127 (inclusive).
     No default value.
@@ -68,11 +66,10 @@ def note_to_name(note):
 
 def name_to_note(name):
     """Translates a note name to a MIDI sequential note value. Note names are
-    character strings expressed in the NoteOctave format, such as
-    'C4' or 'G#7'. Note names can range from 'C-1' (note value 0) to
-    'F#9' (note value 127). Note values are of integer type in the range
-    of 0 to 127 (inclusive). If the input value is outside of that range,
-    the value of None is returned.
+    character strings expressed in the NoteOctave format such as 'C4' or 'G#7'.
+    Note names range from 'C-1' (note value 0) to 'F#9' (note value 127). Note
+    values are of integer type in the range of 0 to 127 (inclusive). If the
+    input value is outside that range, the value of `None` is returned.
 
     :param str name: The note name input in NoteOctave format. No default value.
     """
@@ -92,12 +89,12 @@ def name_to_note(name):
 
 
 def note_to_frequency(note):
-    """Translates a MIDI sequential note value to its corresponding frequency
-    in Hertz (Hz). Note values are of integer type in the range of 0 to
-    127 (inclusive). Frequency values are floating point. If the input
-    note value is less than 0 or greater than 127, the input is
-    invalid and the value of None is returned. Ref: MIDI Tuning Standard
-    formula: https://en.wikipedia.org/wiki/MIDI_tuning_standard
+    """Translates a MIDI sequential note value to a corresponding frequency in
+    Hertz (Hz). Note values are integers in the range of 0 to 127 (inclusive).
+    Frequency values are floating point. If the input note value is less than
+    0 or greater than 127, the input is invalid and the value of `None` is
+    returned. Ref: MIDI Tuning Standard formula:
+    https://en.wikipedia.org/wiki/MIDI_tuning_standard
 
     :param int note: The MIDI note value input in the range of 0 to 127
     (inclusive). No default.
@@ -108,152 +105,172 @@ def note_to_frequency(note):
 
 
 def frequency_to_note(frequency):
-    """Translates a frequency in Hertz (Hz) to the closest MIDI sequential
-    note value. Frequency values are floating point. Note values are of
-    integer type in the range of 0 to 127 (inclusive). If the input
-    frequency is less than the corresponding frequency for note 0 or
-    greater than note 127, the input is invalid and the value of None
-    is returned. Ref: MIDI Tuning Standard formula:
+    """Translates a frequency in Hertz (Hz) to a MIDI sequential note value.
+    Frequency values are floating point. Note values are integers in the range
+    of 0 to 127 (inclusive). If the input frequency is less than the
+    corresponding frequency for note 0 or greater than note 127, the note value
+    cannot be determined and `None` is returned. Ref: MIDI Tuning Standard
+    formula:
     https://en.wikipedia.org/wiki/MIDI_tuning_standard
 
     :param float frequency: The frequency value input in Hz. No default.
     """
-    if (pow(2, (0 - 69) / 12) * 440) <= frequency <= (pow(2, (127 - 69) / 12) * 440):
+    if (pow(2, (0 - 69) / 12) * 440) <= frequency <= (pow(2, (128 - 69) / 12) * 440):
         return int(69 + (12 * log(frequency / 440, 2)))
     return None  # Frequency outside valid range
 
 
+def frequency_to_note_cents(frequency):
+    """Translates a frequency in Hertz (Hz) to a MIDI sequential note value and
+    positive offset in cents. Frequency values are floating point. Note values
+    are integers in the range of 0 to 127 (inclusive). Cent values range from
+    0 to +100 cents. If the input frequency is less than the corresponding
+    frequency for note 0 or greater than note 127, the note value cannot be
+    determined and `None` is returned. Ref: MIDI Tuning Standard and cent
+    formulae:
+    https://en.wikipedia.org/wiki/MIDI_tuning_standard
+    https://en.wikipedia.org/wiki/Cent_(music)
+
+    :param float frequency: The frequency value input in Hz. No default.
+    """
+    if (pow(2, (0 - 69) / 12) * 440) <= frequency <= (pow(2, (128 - 69) / 12) * 440):
+        note = int(69 + (12 * log(frequency / 440, 2)))
+        note_freq = pow(2, (note - 69) / 12) * 440
+        return note, int(1200 * log(frequency / note_freq))
+    return None, None  # Frequency outside valid range
+
+
 # Controller descriptions -- no list offset
 #   0-63 continuous, 64-121 switch, 122-127 channel mode
 CONTROLLERS = [
-    ("Bank_Select"),
-    ("Modulation"),
-    ("Breath_Ctrl"),
-    ("Ctrl_3"),
-    ("Foot_Ctrl"),
-    ("Portamento_Time"),
-    ("Data_Entry_MSB"),
-    ("Chan_Vol"),
-    ("Balance"),
-    ("Ctrl_9"),
-    ("Pan_Ctrl"),
-    ("Exp_Pedal"),
-    ("FX_Ctrl_1"),
-    ("FX_Ctrl_2"),
-    ("Ctrl_14"),
-    ("Ctrl_15"),
-    ("Gen_Pur_1"),
-    ("Gen_Pur_2"),
-    ("Gen_Pur_3"),
-    ("Gen_Pur_4"),
-    ("Ctrl_20"),
-    ("Ctrl_21"),
-    ("Ctrl_22"),
-    ("Ctrl_23"),
-    ("Ctrl_24"),
-    ("Ctrl_25"),
-    ("Ctrl_26"),
-    ("Ctrl_27"),
-    ("Ctrl_28"),
-    ("Ctrl_29"),
-    ("Ctrl_30"),
-    ("Ctrl_31"),
-    ("Bank_Sel_LSB"),
-    ("Modulation_LSB"),
-    ("Breath_Ctrl_LSB"),
-    ("Ctrl_3_LSB"),
-    ("Foot_Ctrl_LSB"),
-    ("Portamento_Time_LSB"),
-    ("Data_Entry_LSB"),
-    ("Chan_Vol_LSB"),
-    ("Balance_LSB"),
-    ("Ctrl_9_LSB"),
-    ("Pan_Ctrl_LSB"),
-    ("Exp_Pedal_LSB"),
-    ("FX_Ctrl_1_LSB"),
-    ("FX_Ctrl_2_LSB"),
-    ("Ctrl_14_LSB"),
-    ("Ctrl_15_LSB"),
-    ("Gen_Pur_1_LSB"),
-    ("Gen_Pur_2_LSB"),
-    ("Gen_Pur_3_LSB"),
-    ("Gen_Pur_4_LSB"),
-    ("Ctrl_20_LSB"),
-    ("Ctrl_21_LSB"),
-    ("Ctrl_22_LSB"),
-    ("Ctrl_23_LSB"),
-    ("Ctrl_24_LSB"),
-    ("Ctrl_25_LSB"),
-    ("Ctrl_26_LSB"),
-    ("Ctrl_27_LSB"),
-    ("Ctrl_28_LSB"),
-    ("Ctrl_29_LSB"),
-    ("Ctrl_30_LSB"),
-    ("Ctrl_31_LSB"),
-    ("Sus_Damp_Pedal_sw"),
-    ("Portamento_sw"),
-    ("Sostenuto_sw"),
-    ("Soft_Pedal_sw"),
-    ("Legato_Foot_sw"),
-    ("Hold_2_sw"),
-    ("Sound_Ctrl_1_Variation"),
-    ("Sound_Ctrl_2_Tibre"),
-    ("Sound_Ctrl_3_Release"),
-    ("Sound_Ctrl_4_Attack"),
-    ("Sound_Ctrl_5_Bright"),
-    ("Sound_Ctrl_6_Decay"),
-    ("Sound_Ctrl_7_Vib_Rate"),
-    ("Sound_Ctrl_8_Vib_Depth"),
-    ("Sound_Ctrl_9_Vib_Delay"),
-    ("Sound_Ctrl_10"),
-    ("Gen_Pur_5"),
-    ("Gen_Pur_6"),
-    ("Gen_Pur_7"),
-    ("Gen_Pur_8"),
-    ("Portamento_Ctrl"),
-    ("Ctrl_85"),
-    ("Ctrl_86"),
-    ("Ctrl_87"),
-    ("HR_Vel_Prefix"),
-    ("Ctrl_89"),
-    ("Ctrl_90"),
-    ("FX_1_Depth_Reverb"),
-    ("FX_2_Depth"),
-    ("FX_3_Depth"),
-    ("FX_4_Depth"),
-    ("FX_5_Depth"),
-    ("Data_Inc + Value"),
-    ("Data_Dec + Value"),
-    ("NRPN_LSB + Value"),
-    ("NRPN_MSB + Value"),
-    ("RPN_LSB + Value"),
-    ("RPN_MSB + Value"),
-    ("Ctrl_102"),
-    ("Ctrl_103"),
-    ("Ctrl_104"),
-    ("Ctrl_105"),
-    ("Ctrl_106"),
-    ("Ctrl_107"),
-    ("Ctrl_108"),
-    ("Ctrl_109"),
-    ("Ctrl_110"),
-    ("Ctrl_111"),
-    ("Ctrl_112"),
-    ("Ctrl_113"),
-    ("Ctrl_114"),
-    ("Ctrl_115"),
-    ("Ctrl_116"),
-    ("Ctrl_117"),
-    ("Ctrl_118"),
-    ("Ctrl_119"),
-    ("All_Sound_Off"),
-    ("Reset_All_Ctrls"),
-    ("Local_Ctrl_Sw"),
-    ("All_Notes_Off"),
-    ("Omni_Mode_Off"),
-    ("Omni_Mode_On"),
-    ("Mono_Mode_On"),
-    ("Poly_Mode_On"),
+    "Bank_Select",
+    "Modulation",
+    "Breath_Ctrl",
+    "Ctrl_3",
+    "Foot_Ctrl",
+    "Portamento_Time",
+    "Data_Entry_MSB",
+    "Chan_Vol",
+    "Balance",
+    "Ctrl_9",
+    "Pan_Ctrl",
+    "Exp_Pedal",
+    "FX_Ctrl_1",
+    "FX_Ctrl_2",
+    "Ctrl_14",
+    "Ctrl_15",
+    "Gen_Pur_1",
+    "Gen_Pur_2",
+    "Gen_Pur_3",
+    "Gen_Pur_4",
+    "Ctrl_20",
+    "Ctrl_21",
+    "Ctrl_22",
+    "Ctrl_23",
+    "Ctrl_24",
+    "Ctrl_25",
+    "Ctrl_26",
+    "Ctrl_27",
+    "Ctrl_28",
+    "Ctrl_29",
+    "Ctrl_30",
+    "Ctrl_31",
+    "Bank_Sel_LSB",
+    "Modulation_LSB",
+    "Breath_Ctrl_LSB",
+    "Ctrl_3_LSB",
+    "Foot_Ctrl_LSB",
+    "Portamento_Time_LSB",
+    "Data_Entry_LSB",
+    "Chan_Vol_LSB",
+    "Balance_LSB",
+    "Ctrl_9_LSB",
+    "Pan_Ctrl_LSB",
+    "Exp_Pedal_LSB",
+    "FX_Ctrl_1_LSB",
+    "FX_Ctrl_2_LSB",
+    "Ctrl_14_LSB",
+    "Ctrl_15_LSB",
+    "Gen_Pur_1_LSB",
+    "Gen_Pur_2_LSB",
+    "Gen_Pur_3_LSB",
+    "Gen_Pur_4_LSB",
+    "Ctrl_20_LSB",
+    "Ctrl_21_LSB",
+    "Ctrl_22_LSB",
+    "Ctrl_23_LSB",
+    "Ctrl_24_LSB",
+    "Ctrl_25_LSB",
+    "Ctrl_26_LSB",
+    "Ctrl_27_LSB",
+    "Ctrl_28_LSB",
+    "Ctrl_29_LSB",
+    "Ctrl_30_LSB",
+    "Ctrl_31_LSB",
+    "Sus_Damp_Pedal_sw",
+    "Portamento_sw",
+    "Sostenuto_sw",
+    "Soft_Pedal_sw",
+    "Legato_Foot_sw",
+    "Hold_2_sw",
+    "Sound_Ctrl_1_Variation",
+    "Sound_Ctrl_2_Timbre",
+    "Sound_Ctrl_3_Release",
+    "Sound_Ctrl_4_Attack",
+    "Sound_Ctrl_5_Bright",
+    "Sound_Ctrl_6_Decay",
+    "Sound_Ctrl_7_Vib_Rate",
+    "Sound_Ctrl_8_Vib_Depth",
+    "Sound_Ctrl_9_Vib_Delay",
+    "Sound_Ctrl_10",
+    "Gen_Pur_5",
+    "Gen_Pur_6",
+    "Gen_Pur_7",
+    "Gen_Pur_8",
+    "Portamento_Ctrl",
+    "Ctrl_85",
+    "Ctrl_86",
+    "Ctrl_87",
+    "HR_Vel_Prefix",
+    "Ctrl_89",
+    "Ctrl_90",
+    "FX_1_Depth_Reverb",
+    "FX_2_Depth",
+    "FX_3_Depth",
+    "FX_4_Depth",
+    "FX_5_Depth",
+    "Data_Inc + Value",
+    "Data_Dec + Value",
+    "NRPN_LSB + Value",
+    "NRPN_MSB + Value",
+    "RPN_LSB + Value",
+    "RPN_MSB + Value",
+    "Ctrl_102",
+    "Ctrl_103",
+    "Ctrl_104",
+    "Ctrl_105",
+    "Ctrl_106",
+    "Ctrl_107",
+    "Ctrl_108",
+    "Ctrl_109",
+    "Ctrl_110",
+    "Ctrl_111",
+    "Ctrl_112",
+    "Ctrl_113",
+    "Ctrl_114",
+    "Ctrl_115",
+    "Ctrl_116",
+    "Ctrl_117",
+    "Ctrl_118",
+    "Ctrl_119",
+    "All_Sound_Off",
+    "Reset_All_Ctrls",
+    "Local_Ctrl_Sw",
+    "All_Notes_Off",
+    "Omni_Mode_Off",
+    "Omni_Mode_On",
+    "Mono_Mode_On",
+    "Poly_Mode_On",
 ]