chord-progressions 0.34.0__tar.gz

chord_progressions-0.34.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Patricio Ovalle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chord_progressions-0.34.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: chord-progressions
+Version: 0.34.0
+Summary: A Python package for extracting, analyzing, and generating chord progressions 
+Author-email: p3zo <p3zo@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2024 Patricio Ovalle
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/p3zo/chord-progressions
+Project-URL: Issues, https://github.com/p3zo/chord-progressions/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib~=3.5.1
+Requires-Dist: mido~=1.2.10
+Requires-Dist: networkx~=2.8
+Requires-Dist: numpy~=1.22.3
+Requires-Dist: pandas~=1.4.2
+Requires-Dist: pretty_midi~=0.2.10
+Requires-Dist: scipy~=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: ipdb; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: bump-my-version; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+
+# Chord progressions
+
+## Usage
+
+See the [Makefile](Makefile) for available actions.
+
+## Docs
+
+The documentation uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to build a static site from
+Markdown files. Use `mkdocs serve` to start a live preview server of the site that automatically rebuilds upon saving.
+Use `mkdocs build` to build the site.
+
+## TODO
+
+Analysis
+
+- [feature] get key for progression
+- [feature] get functional names for chords given key
+- [feature] extend interval class vectors to "polychord content" vectors
+
+I/O
+
+- [feature] add `from_audio` and `from_midi` constructors to Progression class
+- [maintainability] use a singular method of counting in `extract_harman.py`
+    - `get_segment_label` uses counter
+    - `get_segment_pc_weights` uses defaultdict
+    - `MinimalSegment.get_pitch_class_weights` uses list.count()
+- [performance] `extract.midi_harman.segment_and_label()` gets really slow for many consecutive segments. test that a
+  maximum of six segment evaluations occur per note
+
+Generation
+
+- [feature] VAE solver
+- [feature] use variable chord durations
+- [feature] consider lower and upper structures in select_voicing
+- [feature] add the possibility of repeated notes in different octaves
+- [feature] ability to constrain key
+
+Misc
+
+- [feature] Host docs site
+- [feature] Generalize `noteNumberToFrequency` to use any periodic
+  tuning (see https://github.com/soul-lang/SOUL/pull/26/files)
+- [feature] implement `is_partial_circular_match`, `chord_contained_in_type`, and `get_possible_types_of_chord`
+- [maintainability] mk `pitch_class` refer to "C" and call 0 `pitch_class_ix`
+- [maintainability] pass midi note numbers everywhere as "notes" and include note names as "noteNames"
+- [maintainability] test the merging of chord types

chord_progressions-0.34.0/README.md

@@ -0,0 +1,47 @@
+# Chord progressions
+
+## Usage
+
+See the [Makefile](Makefile) for available actions.
+
+## Docs
+
+The documentation uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to build a static site from
+Markdown files. Use `mkdocs serve` to start a live preview server of the site that automatically rebuilds upon saving.
+Use `mkdocs build` to build the site.
+
+## TODO
+
+Analysis
+
+- [feature] get key for progression
+- [feature] get functional names for chords given key
+- [feature] extend interval class vectors to "polychord content" vectors
+
+I/O
+
+- [feature] add `from_audio` and `from_midi` constructors to Progression class
+- [maintainability] use a singular method of counting in `extract_harman.py`
+    - `get_segment_label` uses counter
+    - `get_segment_pc_weights` uses defaultdict
+    - `MinimalSegment.get_pitch_class_weights` uses list.count()
+- [performance] `extract.midi_harman.segment_and_label()` gets really slow for many consecutive segments. test that a
+  maximum of six segment evaluations occur per note
+
+Generation
+
+- [feature] VAE solver
+- [feature] use variable chord durations
+- [feature] consider lower and upper structures in select_voicing
+- [feature] add the possibility of repeated notes in different octaves
+- [feature] ability to constrain key
+
+Misc
+
+- [feature] Host docs site
+- [feature] Generalize `noteNumberToFrequency` to use any periodic
+  tuning (see https://github.com/soul-lang/SOUL/pull/26/files)
+- [feature] implement `is_partial_circular_match`, `chord_contained_in_type`, and `get_possible_types_of_chord`
+- [maintainability] mk `pitch_class` refer to "C" and call 0 `pitch_class_ix`
+- [maintainability] pass midi note numbers everywhere as "notes" and include note names as "noteNames"
+- [maintainability] test the merging of chord types

chord_progressions-0.34.0/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-0.34.0/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-0.34.0/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-0.34.0/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)