chord-progressions 0.34.0__py3-none-any.whl

chord_progressions/__init__.py

@@ -0,0 +1,19 @@
+import logging
+import os
+
+__version__ = "0.34.0"  # updated by bumpversion, do not change
+
+THIS_DIR = os.path.dirname(os.path.realpath(__file__))
+
+OUTPUT_DIR = os.path.join(THIS_DIR, "../assets/output")
+
+# a copy of /usr/share/dict/web2 from a macbook air (early 2014)
+WORDS_FILEPATH = os.path.join(THIS_DIR, "..", "words")
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("chord-progressions")
+
+# Config
+# TODO: move to config
+DEFAULT_BPM = 120
+DEFAULT_MIDI_TICKS_PER_BEAT = 480

chord_progressions/chord.py

@@ -0,0 +1,88 @@
+from uuid import uuid4
+
+from chord_progressions import logger
+from chord_progressions.evaluate import evaluate_notes
+from chord_progressions.io.audio import mk_chord_buffer, save_audio_buffer
+from chord_progressions.io.midi import get_midi_from_chord
+from chord_progressions.pitch import get_midi_num_from_note, get_note_from_midi_num
+from chord_progressions.type_templates import (
+    get_template_from_notes,
+    get_type_from_midi_nums,
+    get_type_num_from_type,
+)
+
+NoteList = list[str]
+MidiNumList = list[int]
+
+
+class Chord:
+    """A set of unique notes.
+
+    Parameters
+    ----------
+    notes: list[Chord], default []
+        The set of notes in the chord. Can be specified as a list of midi numbers or as a list of note names.
+            e.g. Chord([60, 64, 67])
+            e.g. Chord(["C4", "E4", "G4"])
+    """
+
+    def __init__(self, notes: list = [], id: str = None):
+        if isinstance(notes, list) and len(notes) > 0 and isinstance(notes[0], str):
+            notes = [get_midi_num_from_note(n) for n in notes]
+
+        self.init_from_midi_nums(midi_nums=notes, id=id)
+
+    def init_from_midi_nums(self, midi_nums: MidiNumList = [], id: str = None):
+        if any([i < 0 or i > 128 for i in midi_nums]):
+            raise ValueError("The valid range of midi numbers is 0 to 128")
+
+        midi_nums = sorted(list(set(midi_nums)))
+        self.midi_nums = [int(i) for i in midi_nums]
+
+        chord_type = get_type_from_midi_nums(midi_nums)
+        self.type = chord_type
+        self.typeId = get_type_num_from_type(chord_type)
+
+        notes = [get_note_from_midi_num(n) for n in midi_nums]
+        self.notes = notes
+        self.metrics = evaluate_notes(notes)
+        self.template = get_template_from_notes(notes)
+
+        if not id:
+            id = str(uuid4())
+        self.id = id
+
+    def __repr__(self):
+        return "Chord " + self.to_string()
+
+    def to_string(self):
+        return str(self.to_json())
+
+    def to_json(self):
+        return {
+            "id": self.id,
+            "midi_nums": self.midi_nums,
+            "type": self.type,
+            "typeId": self.typeId,
+            "notes": self.notes,
+            "metrics": self.metrics,
+        }
+
+    def to_audio(self, outpath=None, n_overtones=4):
+        audio = mk_chord_buffer(self.notes, 1, n_overtones)
+
+        if outpath:
+            save_audio_buffer(audio, outpath)
+            logger.info(f"Audio saved to {outpath}")
+        else:
+            return audio
+
+    def to_midi(self, outpath=None):
+        mid = get_midi_from_chord(self.chords, 1, 120, "-".join(self.notes))
+
+        if outpath:
+            mid.filename = outpath
+            mid.save(outpath)
+            logger.info(f"Midi saved to {outpath}")
+        else:
+            return mid

chord_progressions/evaluate.py

@@ -0,0 +1,177 @@
+"""
+    Defines the metrics computed for every progression.
+
+    TODO:
+        - A common heuristic is that an interval is consonant when the ratio between the frequencies is simple.
+        - Resonance
+        - Brilliance: "for maximum brilliance let the lower tones [be somehow equally spaced out as] their overtones"
+            - Vincent Persechetti, Twentieth-Century Harmony
+        - something like https://en.xen.wiki/w/Harmonic_Entropy
+"""
+
+import itertools
+
+import numpy as np
+from chord_progressions.pitch import (
+    get_freq_from_note,
+    get_midi_num_from_note,
+    get_n_overtones_harmonic,
+    get_pitch_class_from_note,
+)
+from chord_progressions.type_templates import get_template_from_notes
+
+
+def get_interval_class_vector(notes):
+    """
+    Returns a vector of interval classes.
+        0: minor second / major seventh (1 or 11 semitones)
+        1: major second / minor seventh (2 or 10 semitones)
+        2: minor third / major sixth (3 or 9 semitones)
+        3: major third / minor sixth (4 or 8 semitones)
+        4: perfect fourth / perfect fifth (5 or 7 semitones)
+        5: tritone (6 semitones)
+    """
+    vec = [0] * 6
+
+    template = get_template_from_notes(notes)
+    one_indices = [ix for ix, i in enumerate(template) if i == 1]
+    pairs = list(itertools.combinations(one_indices, 2))
+
+    intervals = [p[1] - p[0] for p in pairs]
+
+    modded = [12 - i if i > 6 else i for i in intervals]
+
+    for i in range(6):
+        vec[i] = modded.count(i + 1)
+
+    return vec
+
+
+def get_evenness(interval_class_vector):
+    """
+    A rough measure of acoustic consonance. Highly consonant chords divide the octave nearly evenly.
+    Note that acoustic consonance implies near-evenness, but not the reverse.
+    For background on the equation see https://www.researchgate.net/profile/Jack_Douthett/publication/249881698_Vector_Products_and_Intervallic_Weighting/links/575061d708ae1c34b39aaa1b.pdf
+    """
+    weight_vector = [0] * 6
+
+    for i in range(6):
+
+        k = i + 1
+
+        weight_vector[i] += 2 * np.sin(k * np.pi / 12)
+
+    weight = np.dot(weight_vector, interval_class_vector)
+
+    return weight
+
+
+def get_relative_evenness(evenness, cardinality):
+    """
+    Calculate the evenness of a pitch class set relative to its possible range.
+    A relative value is useful because highly-even dyads will have a lower evenness than highly uneven hexachords.
+    The result is a value between 0 and 1.
+    """
+    # TODO: replace this table with a formula
+    MIN_MAX_EVENNESS_BY_CARDINALITY = [
+        [0.0, 0.0],
+        [0.5176380902050415, 2.0],
+        [2.035276180410083, 5.196152422706632],
+        [6.1815405503520555, 9.65685424949238],
+        [9.631030293135233, 15.287884542627612],
+        [16.226784405860382, 22.392304845413264],
+        [24.822538518585535, 30.479392768077915],
+        [35.350144283888824, 40.03987070039298],
+        [47.609800856760984, 50.77067709905754],
+        [61.28367099200624, 62.7660329018012],
+        [75.9575411272515, 75.9575411272515],
+        [91.14904935270181, 91.14904935270181],
+    ]
+
+    emin, emax = MIN_MAX_EVENNESS_BY_CARDINALITY[cardinality - 1]
+    return (evenness - emin) / (emax - emin)
+
+
+def get_overtone_agreement(notes):
+
+    freqs = [get_freq_from_note(n) for n in notes]
+
+    all_partials = []
+
+    n_overtones = 10
+    for f in freqs:
+        all_partials.extend(get_n_overtones_harmonic(f, n_overtones))
+
+    sorted_partials = sorted(all_partials)
+
+    sum_of_differences = 0
+
+    for i in range(1, len(sorted_partials)):
+        diff = sorted_partials[i] - sorted_partials[i - 1]
+        sum_of_differences += diff
+
+    return sum_of_differences
+
+
+def evaluate_notes(notes):
+    """list of notes, e.g. ["C4", "E4", "G4"]"""
+
+    metrics = {}
+
+    interval_class_vector = get_interval_class_vector(notes)
+
+    # evenness = get_evenness(interval_class_vector)
+
+    pc_cardinality = len(set([get_pitch_class_from_note(n) for n in notes]))
+    assert pc_cardinality <= 12, "Pitch class cardinality > 12"
+
+    metrics["num_notes"] = len(notes)
+    metrics["num_pitches"] = len(set(notes))
+    # metrics["pc_cardinality"] = pc_cardinality
+    metrics["interval_class_vector"] = interval_class_vector
+    # metrics["ambitus"] = get_ambitus(notes)
+    # metrics["evenness"] = evenness
+    # metrics["relative_evenness"] = get_relative_evenness(evenness, pc_cardinality)
+    # metrics["overtone_agreement"] = get_overtone_agreement(notes)
+
+    return metrics
+
+
+def get_macroharmony(progression):
+    """The total collection of notes"""
+
+    collection = set()
+
+    for notes in progression:
+        for note in notes:
+            collection.add(note)
+
+    return collection
+
+
+def get_ambitus(macroharmony):
+    """Ambitus, int, # semitones between the lowest and highest note"""
+    midi_notes = [get_midi_num_from_note(n) for n in macroharmony]
+
+    return max(midi_notes) - min(midi_notes)
+
+
+def evaluate_progression(progression):
+    metrics = {}
+
+    # macroharmony = get_macroharmony(notes_list)
+
+    # metrics["ambitus"] = get_ambitus(macroharmony)
+
+    # metrics["density"] = len(macroharmony) / len(notes_list)
+
+    return metrics
+
+
+def get_n_overtones_for_notes(notes, n):
+    """Calculates `n` overtone frequencies for each note in `notes`"""
+
+    freqs = [get_freq_from_note(n) for n in notes]
+    ofreqs = [get_n_overtones_harmonic(f, n) for f in freqs]
+
+    return ofreqs

chord_progressions/midi.py

@@ -0,0 +1,31 @@
+import mido
+from chord_progressions import DEFAULT_MIDI_TICKS_PER_BEAT
+
+
+def make_midi_chord(chord, end_tick: int):
+    note_onsets = []
+    note_offsets = []
+
+    first_note = True
+    for midi_num in chord.midi_nums:
+        note_onsets.append(mido.Message("note_on", note=midi_num, time=0))
+
+        if not first_note:
+            end_tick = 0
+
+        note_offsets.append(mido.Message("note_off", note=midi_num, time=end_tick))
+        first_note = False
+
+    return note_onsets + note_offsets
+
+
+def get_midi_ticks_from_seconds(
+    seconds, bpm, ticks_per_beat=DEFAULT_MIDI_TICKS_PER_BEAT
+):
+    midi_tempo = mido.bpm2tempo(bpm)
+    return int(mido.second2tick(seconds, ticks_per_beat, midi_tempo))
+
+
+def get_seconds_from_midi_ticks(ticks, bpm, ticks_per_beat=DEFAULT_MIDI_TICKS_PER_BEAT):
+    midi_tempo = mido.bpm2tempo(bpm)
+    return mido.tick2second(ticks, ticks_per_beat, midi_tempo)

chord_progressions/pitch.py

@@ -0,0 +1,393 @@
+A4 = 440
+
+
+NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+
+MIDI_NOTES = [
+    "C-1",
+    "C#-1",
+    "D-1",
+    "D#-1",
+    "E-1",
+    "F-1",
+    "F#-1",
+    "G-1",
+    "G#-1",
+    "A-1",
+    "A#-1",
+    "B-1",
+    "C0",
+    "C#0",
+    "D0",
+    "D#0",
+    "E0",
+    "F0",
+    "F#0",
+    "G0",
+    "G#0",
+    # start piano range
+    "A0",
+    "A#0",
+    "B0",
+    "C1",
+    "C#1",
+    "D1",
+    "D#1",
+    "E1",
+    "F1",
+    "F#1",
+    "G1",
+    "G#1",
+    "A1",
+    "A#1",
+    "B1",
+    "C2",
+    "C#2",
+    "D2",
+    "D#2",
+    "E2",
+    "F2",
+    "F#2",
+    "G2",
+    "G#2",
+    "A2",
+    "A#2",
+    "B2",
+    "C3",
+    "C#3",
+    "D3",
+    "D#3",
+    "E3",
+    "F3",
+    "F#3",
+    "G3",
+    "G#3",
+    "A3",
+    "A#3",
+    "B3",
+    "C4",
+    "C#4",
+    "D4",
+    "D#4",
+    "E4",
+    "F4",
+    "F#4",
+    "G4",
+    "G#4",
+    "A4",
+    "A#4",
+    "B4",
+    "C5",
+    "C#5",
+    "D5",
+    "D#5",
+    "E5",
+    "F5",
+    "F#5",
+    "G5",
+    "G#5",
+    "A5",
+    "A#5",
+    "B5",
+    "C6",
+    "C#6",
+    "D6",
+    "D#6",
+    "E6",
+    "F6",
+    "F#6",
+    "G6",
+    "G#6",
+    "A6",
+    "A#6",
+    "B6",
+    "C7",
+    "C#7",
+    "D7",
+    "D#7",
+    "E7",
+    "F7",
+    "F#7",
+    "G7",
+    "G#7",
+    "A7",
+    "A#7",
+    "B7",
+    "C8",
+    # end piano range
+    "C#8",
+    "D8",
+    "D#8",
+    "E8",
+    "F8",
+    "F#8",
+    "G8",
+    "G#8",
+    "A8",
+    "A#8",
+    "B8",
+    "C9",
+    "C#9",
+    "D9",
+    "D#9",
+    "E9",
+    "F9",
+    "F#9",
+    "G9",
+]
+
+MIDI_NOTE_FREQUENCIES = [
+    8.18,
+    8.66,
+    9.18,
+    9.72,
+    10.3,
+    10.91,
+    11.56,
+    12.25,
+    12.98,
+    13.75,
+    14.57,
+    15.43,
+    16.35,
+    17.32,
+    18.35,
+    19.45,
+    20.6,
+    21.83,
+    23.12,
+    24.5,
+    25.96,
+    # start piano range
+    27.5,
+    29.14,
+    30.87,
+    32.7,
+    34.65,
+    36.71,
+    38.89,
+    41.2,
+    43.65,
+    46.25,
+    49.0,
+    51.91,
+    55.0,
+    58.27,
+    61.74,
+    65.41,
+    69.3,
+    73.42,
+    77.78,
+    82.41,
+    87.31,
+    92.5,
+    98.0,
+    103.83,
+    110.0,
+    116.54,
+    123.47,
+    130.81,
+    138.59,
+    146.83,
+    155.56,
+    164.81,
+    174.61,
+    185.0,
+    196.0,
+    207.65,
+    220.0,
+    233.08,
+    246.94,
+    261.63,
+    277.18,
+    293.66,
+    311.13,
+    329.63,
+    349.23,
+    369.99,
+    392.0,
+    415.3,
+    440.0,
+    466.16,
+    493.88,
+    523.25,
+    554.37,
+    587.33,
+    622.25,
+    659.26,
+    698.46,
+    739.99,
+    783.99,
+    830.61,
+    880.0,
+    932.33,
+    987.77,
+    1046.5,
+    1108.73,
+    1174.66,
+    1244.51,
+    1318.51,
+    1396.91,
+    1479.98,
+    1567.98,
+    1661.22,
+    1760.0,
+    1864.66,
+    1975.53,
+    2093.0,
+    2217.46,
+    2349.32,
+    2489.02,
+    2637.02,
+    2793.83,
+    2959.96,
+    3135.96,
+    3322.44,
+    3520.0,
+    3729.31,
+    3951.07,
+    4186.01,
+    # end piano range
+    4434.92,
+    4698.64,
+    4978.03,
+    5274.04,
+    5587.65,
+    5919.91,
+    6271.93,
+    6644.88,
+    7040.0,
+    7458.62,
+    7902.13,
+    8372.02,
+    8869.84,
+    9397.27,
+    9956.06,
+    10548.08,
+    11175.3,
+    11839.82,
+    12543.85,
+]
+
+
+def get_note_from_midi_num(note_num):
+    try:
+        return MIDI_NOTES[int(note_num)]
+    except IndexError:
+        raise IndexError(f"Invalid midi note number: {note_num}")
+
+
+def get_midi_num_from_note(note):
+    try:
+        return MIDI_NOTES.index(note)
+    except ValueError:
+        raise ValueError(f"Invalid note name: {note}")
+
+
+def get_pitch_class_from_note(note):
+    """Returns the pitch class of a note, e.g. get_pitch_class_from_note(C4) -> 0"""
+    midi_num = get_midi_num_from_note(note)
+    return get_pitch_class_from_midi_num(midi_num)
+
+
+def get_pitch_class_from_midi_num(note_num):
+    """Returns the pitch class of a midi num"""
+    return note_num % 12
+
+
+def get_note_name_from_note(note):
+    """Drops the octave part of the note, e.g. A#4 -> A#"""
+
+    midi_num = get_midi_num_from_note(note) % 12
+    pitch_class = get_pitch_class_from_midi_num(midi_num)
+
+    return NOTE_NAMES[pitch_class]
+
+
+def get_notes_from_midi_nums_str(midi_nums_str):
+    """e.g. "60-48" -> ["C4", "C3"]"""
+    return [get_note_from_midi_num(s) for s in midi_nums_str.split("-")]
+
+
+def get_notes_list_from_midi_nums_str(midi_nums_str):
+    """e.g. "60-48_62-50" -> [["C4", "C3"], ["D4", "E3"]]"""
+    return [get_notes_from_midi_nums_str(s) for s in midi_nums_str.split("_")]
+
+
+def get_midi_nums_list_from_midi_nums_str(midi_nums_str):
+    """e.g. "60-48_62-50" -> [[60, 48], [62, 50]]
+    If any chord in `midi_nums_str` is invalid, returns an empty string for that chord"""
+    midi_nums_list = []
+    for m in midi_nums_str.split("_"):
+        try:
+            midi_nums_list.append([int(i) for i in m.split("-")])
+        except:
+            pass
+
+    return midi_nums_list
+
+
+def get_octave_from_note(note):
+
+    note_name = get_note_name_from_note(note)
+
+    octave = note.split(note_name)[1]
+
+    return int(octave)
+
+
+def get_freq_from_midi_num(n):
+    return round(A4 * 2 ** ((n - 69) / 12), 2)
+
+
+def increment_note(note):
+    """Returns the note a half step above `note`"""
+
+    note_name = get_note_name_from_note(note)
+
+    new_name_ix = NOTE_NAMES.index(note_name) + 1 % 12
+    new_note_name = NOTE_NAMES[new_name_ix % 12]
+
+    octave = get_octave_from_note(note)
+
+    if new_name_ix == 12:
+        octave += 1
+
+    return new_note_name + str(octave)
+
+
+def create_notes_freqs_table():
+    """This is a one-off function that was used to create the MIDI_NOTE_FREQUENCIES constant"""
+
+    from collections import OrderedDict  # # noqa
+
+    notes = OrderedDict()
+
+    current_note = "C-1"
+
+    for i in range(128):
+        notes[current_note] = get_freq_from_midi_num(i)
+        current_note = increment_note(current_note)
+
+    return notes
+
+
+def get_note_list(note_range_low=0, note_range_high=127):
+
+    start_ix = note_range_low
+    end_ix = note_range_high
+
+    return MIDI_NOTES[start_ix : end_ix + 1]
+
+
+def get_freq_from_note(note):
+    """Returns the frequency of a note, e.g. `A4`"""
+
+    ix = get_midi_num_from_note(note)
+
+    return MIDI_NOTE_FREQUENCIES[ix]
+
+
+def get_n_overtones_harmonic(freq, n):
+    """Compute a list of n overtones above a given freq"""
+    return [i * freq for i in range(1, n + 2)]