klotho-cac 2.1.0__py3-none-any.whl

klotho/__init__.py

@@ -0,0 +1,35 @@
+"""
+Klotho: A graph-oriented Python package for computational composition.
+
+This package provides tools for working with musical structures across multiple domains:
+- Topos: Abstract structures and relationships
+- Chronos: Time and rhythm
+- Tonos: Pitch and harmony
+- Aikous: Expression and parameters
+- Skora: Visualization and notation
+"""
+from . import topos
+from . import chronos
+from . import tonos
+from . import aikous
+from . import skora
+from . import utils
+
+from .topos.collections import patterns, sequences, sets, Pattern, CombinationSet, PartitionSet
+from .topos.graphs import trees, networks, fields, Tree, Network, Field, Graph
+
+from .chronos import RhythmPair, RhythmTree, TemporalUnit, TemporalUnitSequence, TemporalBlock
+
+from .tonos import Pitch, Scale, Chord, AddressedScale, AddressedChord
+
+from .types import frequency, cent, midicent, midi, amplitude, decibel, onset, duration
+
+__all__ = [
+    'topos', 'chronos', 'tonos', 'aikous', 'skora',
+    'Pitch', 'Scale', 'Chord', 
+    'AddressedScale', 'AddressedChord',
+    'frequency', 'cent', 'midicent', 'midi',
+    'amplitude', 'decibel', 'onset', 'duration'
+]
+
+__version__ = '2.1.0'

klotho/aikous/__init__.py

@@ -0,0 +1,42 @@
+"""
+Aikous: A specialized module for working with expression and parameters in music.
+
+From the Greek "ακούω" (akoúō) meaning "to hear" or "to listen," this module
+deals with the expressive aspects of music that affect how we perceive sound.
+"""
+
+from . import expression
+from . import parameters
+from . import instruments
+
+# Import classes
+from .expression import Dynamic, DynamicRange
+from .parameters import ParameterTree
+from .instruments import Instrument
+
+# Import expression utility functions 
+from .expression import dbamp, ampdb, freq_amp_scale
+from .expression import line, arch, map_curve
+
+__all__ = [
+    # Modules
+    'expression',
+    'parameters',
+    'instruments',
+    
+    # Classes
+    'DynamicRange',
+    'Dynamic',
+    'ParameterTree',
+    'Instrument',
+    
+    # Expression functions
+    'dbamp', 
+    'ampdb', 
+    'freq_amp_scale',
+    'line', 
+    'arch', 
+    'map_curve',
+]
+
+__version__ = '2.0.0'

klotho/aikous/expression/__init__.py

@@ -0,0 +1,29 @@
+'''
+--------------------------------------------------------------------------------------
+General psychoacoustic tools for working with music synthesis.
+
+`Aikous` is a specialized module for working with psychoacoustics in the context of music.
+
+see: https://en.wikipedia.org/wiki/Psychoacoustics
+
+The word "aikous" is a portmanteau derived from Ancient Greek, blending the elements of 
+"αἰσθάνομαι" (aisthanomai), meaning "to perceive" or "to feel," and "ἀκούω" (akouo), 
+meaning "to hear."
+
+The `aikous` module contains tools for translating physics phenomena, as perceived by
+humans, into algebraic musical representations.
+--------------------------------------------------------------------------------------
+'''
+from .dynamics import Dynamic, DynamicRange, dbamp, ampdb, freq_amp_scale
+from .enevelopes import line, arch, map_curve
+
+__all__ = [
+    'Dynamic',
+    'DynamicRange',
+    'dbamp',
+    'ampdb',
+    'freq_amp_scale',
+    'line',
+    'arch',
+    'map_curve'
+]

klotho/aikous/expression/dynamics.py

@@ -0,0 +1,174 @@
+# ------------------------------------------------------------------------------------
+# Klotho/klotho/aikous/dynamics.py
+# ------------------------------------------------------------------------------------
+'''
+--------------------------------------------------------------------------------------
+Classes and functions for working with musical dynamics.
+--------------------------------------------------------------------------------------
+'''
+
+import numpy as np
+from numpy.polynomial import Polynomial
+from scipy import interpolate
+
+__all__ = [
+    'DynamicRange',
+    'ampdb',
+    'dbamp',
+    # 'amp_freq_scale',
+    'freq_amp_scale',
+]
+
+DYNAMIC_MARKINGS = ('ppp', 'pp', 'p', 'mp', 'mf', 'f', 'ff', 'fff')
+
+class Dynamic:
+    def __init__(self, db_value):
+        self._db_value = db_value
+    
+    @property
+    def db(self):
+        return self._db_value
+        
+    @property
+    def amp(self):
+        return dbamp(self._db_value)
+    
+    def __float__(self):
+        return float(self._db_value)
+    
+    def __repr__(self):
+        return f"Dynamic(db={self._db_value:.2f}, amp={self.amp:.4f})"
+
+
+class DynamicRange:
+  '''
+  Musical dynamics mapped to decibels.
+
+  Note: the decibel level for the loudest 
+  dynamic (ffff) is 0 dB as this translates 
+  to an amplitude of 1.0.
+
+  ----------------|---------|----------------
+  Name            | Letters	| Level
+  ----------------|---------|----------------
+  fortississimo	  | fff	    | very very loud  
+  fortissimo	    | ff	    | very loud
+  forte	          | f	      | loud
+  mezzo-forte	    | mf	    | moderately loud
+  mezzo-piano	    | mp	    | moderately quiet
+  piano	          | p	      | quiet
+  pianissimo	    | pp	    | very quiet
+  pianississimo	  | ppp	    | very very quiet
+  ----------------|---------|----------------
+
+  see https://en.wikipedia.org/wiki/Dynamics_(music)#
+  '''
+  def __init__(self, min_dynamic=-60, max_dynamic=0, curve=0, dynamics=DYNAMIC_MARKINGS):
+    self._min_dynamic = min_dynamic if isinstance(min_dynamic, Dynamic) else Dynamic(min_dynamic)
+    self._max_dynamic = max_dynamic if isinstance(max_dynamic, Dynamic) else Dynamic(max_dynamic)
+    self._curve = curve
+    self._dynamics = dynamics
+    self._range = self._calculate_range()
+    
+  @property
+  def min_dynamic(self):
+    return self._min_dynamic
+  
+  @property
+  def max_dynamic(self):
+    return self._max_dynamic
+  
+  @property
+  def curve(self):
+    return self._curve
+  
+  @property
+  def ranges(self):
+    return self._range
+
+  def _calculate_range(self):
+    min_db = float(self._min_dynamic.db)
+    max_db = float(self._max_dynamic.db)
+    num_dynamics = len(self._dynamics)
+    
+    result = {}
+    for i, dyn in enumerate(self._dynamics):
+        normalized_pos = i / (num_dynamics - 1)
+        
+        if self._curve == 0:
+            curved_pos = normalized_pos
+        elif self._curve > 0:
+            curved_pos = normalized_pos ** (1 + self._curve)
+        else:
+            curved_pos = 1 - ((1 - normalized_pos) ** (1 - self._curve))
+            
+        db_value = min_db + curved_pos * (max_db - min_db)
+        result[dyn] = Dynamic(db_value)
+        
+    return result
+
+  def __getitem__(self, dynamic):
+    return self._range[dynamic]
+
+def ampdb(amp: float) -> float:
+  '''
+  Convert amplitude to decibels (dB).
+
+  Args:
+  amp (float): The amplitude to convert.
+
+  Returns:
+  float: The amplitude in decibels.
+  '''
+  return 20 * np.log10(amp)
+
+def dbamp(db: float) -> float:
+  '''
+  Convert decibels (dB) to amplitude.
+
+  Args:
+  db (float): The decibels to convert.
+
+  Returns:
+  float: The amplitude.
+  '''
+  return 10 ** (db / 20)
+
+# def amp_freq_scale(freq: float,
+#     freqs: list = [20,  100, 250, 500, 1000, 2000, 3000, 4000, 6000, 10000, 20000],
+#     amps: list  = [0.3, 0.5, 0.7, 0.8, 0.5,  0.6,  0.5,  0.6,  0.7,  0.5,   0.3],
+#     deg: int = 4) -> float:
+#   frequencies_sample = np.array(freqs, dtype=float)
+#   loudness_sample    = np.array(amps, dtype=float)
+#   p = Polynomial.fit(frequencies_sample, loudness_sample, deg=deg)
+#   return p(freq)
+
+def freq_amp_scale(freq: float, db_level: float, min_db: float = -60) -> float:
+    """
+    Scale amplitude based on frequency and loudness according to psychoacoustic principles.
+    
+    Args:
+        freq (float): The frequency in Hz
+        db_level (float): The input level in dB
+        min_db (float): The minimum dB level in the dynamic range (default -60)
+        
+    Returns:
+        float: The perceptually scaled amplitude (linear scale)
+    """
+    range_db = abs(min_db)
+    phon_level = 40 + ((db_level - min_db) / range_db) * 60
+    
+    frequencies = np.array([20, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000], dtype=float)
+    
+    if phon_level <= 40:
+        scaling_curve = np.array([0.2, 0.3, 0.5, 0.7, 0.9, 1.0, 1.0, 0.9, 0.7, 0.4], dtype=float)
+    elif phon_level <= 70:
+        scaling_curve = np.array([0.3, 0.45, 0.6, 0.8, 0.95, 1.0, 1.0, 0.95, 0.8, 0.5], dtype=float)
+    else:
+        scaling_curve = np.array([0.5, 0.6, 0.7, 0.85, 0.95, 1.0, 1.0, 0.95, 0.85, 0.6], dtype=float)
+    
+    spline = interpolate.CubicSpline(frequencies, scaling_curve, extrapolate=True)
+    scaling_factor = max(0.01, float(spline(freq)))
+    
+    raw_amp = dbamp(db_level)
+    return raw_amp * scaling_factor

klotho/aikous/expression/enevelopes.py

@@ -0,0 +1,89 @@
+# --------------------------------------------------
+#  Klotho/klotho/aikous/envelopes.py
+# --------------------------------------------------
+'''
+--------------------------------------------------------------------------------------
+Envelopes for shaping the dynamics of a sequence of discrete values.
+--------------------------------------------------------------------------------------
+'''
+
+import numpy as np
+
+__all__ = [
+    'line',
+    'arch',
+    'map_curve',
+]
+
+def line(start=0.0, end=1.0, steps=100, curve=0.0):
+    '''
+    Generate a curved line from start to end value over n steps.
+    
+    Args:
+        start: Starting value
+        end: Ending value
+        steps: Number of steps
+        curve: Shape of the curve. Negative for exponential, positive for logarithmic, 0 for linear
+        
+    Returns:
+        numpy.ndarray: Array of values following the specified curve
+    '''
+    if curve == 0:
+        return np.linspace(start, end, steps)
+    
+    t = np.linspace(0, 1, steps)
+    curved_t = np.exp(curve * t) - 1
+    curved_t = curved_t / (np.exp(curve) - 1)
+    
+    return start + (end - start) * curved_t
+
+def arch(base=0.0, peak=1.0, steps=100, curve=0.0, axis=0):
+    '''
+    Generate a swelling curve that rises and falls, starting and ending at base value, peaking at peak value.
+    
+    Args:
+        base: Starting and ending value
+        peak: Peak value
+        steps: Number of steps
+        curve: Shape of the curve. Can be:
+               - A single number: Same curve applied to both sides (negative for exponential, positive for logarithmic)
+               - A tuple/list of two values: First value for ascending curve, second for descending
+        axis: Position of the peak (-1 to 1). 0 centers the peak, negative shifts earlier, positive shifts later
+        
+    Returns:
+        numpy.ndarray: Array of values following a swell curve
+    '''
+    axis = np.clip(axis, -1, 1)
+    split_point = int((0.5 + axis * 0.4) * steps)
+    
+    if isinstance(curve, (list, tuple)) and len(curve) == 2:
+        up_curve, down_curve = curve
+    else:
+        up_curve = down_curve = curve
+    
+    up = line(base, peak, split_point + 1, up_curve)
+    down = line(peak, base, steps - split_point, down_curve)
+    
+    return np.concatenate([up[:-1], down])
+
+def map_curve(value, in_range, out_range, curve=0.0):
+    '''
+    Map a value from an input range to an output range with optional curve shaping.
+    
+    Args:
+        value: Input value to map
+        in_range: Tuple of (min, max) for input range
+        out_range: Tuple of (min, max) for output range
+        curve: Shape of the curve. Negative for exponential, positive for logarithmic, 0 for linear
+        
+    Returns:
+        float: Mapped value with curve applied
+    '''
+    normalized = np.interp(value, in_range, (0, 1))
+    
+    if curve != 0:
+        normalized = np.exp(curve * normalized) - 1
+        normalized = normalized / (np.exp(curve) - 1)
+    
+    return np.interp(normalized, (0, 1), out_range)
+

klotho/aikous/instruments/__init__.py

@@ -0,0 +1 @@
+from .instrument import Instrument

klotho/aikous/instruments/instrument.py

@@ -0,0 +1,76 @@
+from abc import ABC, abstractmethod
+from klotho.aikous.expression.dynamics import Dynamic, DynamicRange
+from klotho.tonos.pitch import Pitch
+from klotho.utils.data_structures.dictionaries import SafeDict
+from typing import List, Dict, TypeVar, Union
+
+class Instrument(ABC):
+    
+    def __init__(self, name, freq_range=None, dynamic_range=None, pfields=None):
+        """
+        Initialize an Instrument.
+        
+        Args:
+            name (str): The name of the instrument
+            freq_range (tuple): A tuple of (min, max) frequency values or Pitch instances
+            dynamic_range: A DynamicRange instance or a tuple of (min, max) dB values
+            pfields (dict or SafeDict): Parameter fields with default values
+        """
+        self._name = name
+        
+        if freq_range is None:
+            freq_range = (20.0, 20000.0)
+        self._freq_range = self._process_freq_range(freq_range)
+        
+        if dynamic_range is None:
+            dynamic_range = (-60, 0)
+        self._dynamic_range = self._process_dynamic_range(dynamic_range)
+        
+        if pfields is None:
+            pfields = {}
+        self._pfields = pfields if isinstance(pfields, SafeDict) else SafeDict(pfields)
+    
+    def _process_freq_range(self, freq_range):
+        min_freq, max_freq = freq_range
+        
+        if not isinstance(min_freq, Pitch):
+            min_freq = Pitch.from_freq(float(min_freq))
+        
+        if not isinstance(max_freq, Pitch):
+            max_freq = Pitch.from_freq(float(max_freq))
+            
+        return (min_freq, max_freq)
+    
+    def _process_dynamic_range(self, dynamic_range):
+        if isinstance(dynamic_range, DynamicRange):
+            return dynamic_range
+        
+        min_dyn, max_dyn = dynamic_range
+        
+        if isinstance(min_dyn, Dynamic):
+            min_dyn = min_dyn.db
+            
+        if isinstance(max_dyn, Dynamic):
+            max_dyn = max_dyn.db
+            
+        return DynamicRange(min_dynamic=min_dyn, max_dynamic=max_dyn)
+    
+    @property
+    def name(self):
+        return self._name
+    
+    @property
+    def freq_range(self):
+        return self._freq_range
+    
+    @property
+    def dynamic_range(self):
+        return self._dynamic_range
+    
+    @property
+    def pfields(self):
+        return self._pfields
+    
+    def __repr__(self):
+        # return f"Instrument(name='{self._name}', freq_range={self._freq_range}, dynamic_range={self._dynamic_range}, pfields={dict(self._pfields)})"
+        return f"Instrument(name='{self._name}', pfields={dict(self._pfields)})"

klotho/aikous/parameters/__init__.py

@@ -0,0 +1 @@
+from .parameter_tree import *

klotho/aikous/parameters/instruments.py

@@ -0,0 +1,142 @@
+from enum import Enum
+from klotho.utils.data_structures.dictionaries import SafeDict
+
+class PFIELDS(Enum):
+    def __call__(self):
+        # return SafeDict(self.value.copy())
+        return self.value.copy()
+
+    SineEnv = SafeDict({
+        'start'      : 0,
+        'dur'        : 1,
+        'synthName'  : 'SineEnv',
+        'amplitude'  : 0.45,
+        'frequency'  : 440,
+        'attackTime' : 0.01,
+        'releaseTime': 0.1,
+        'pan'        : 0.0,
+    })
+
+    Vib = SafeDict({
+        'start'      : 0,
+        'dur'        : 1,
+        'synthName'  : 'Vib',
+        'amplitude'  : 0.45,
+        'frequency'  : 440,
+        'attackTime' : 0.01,
+        'releaseTime': 0.1,
+        'sustain'    : 0.5,
+        'curve'      : 4.0,
+        'pan'        : 0.0,
+        'table'      : 0,
+        'vibRate1'   : 3.5,
+        'vibRate2'   : 5.8,
+        'vibRise'    : 0.5,
+        'vibDepth'   : 0.005,     
+    })
+
+    FMWT = SafeDict({
+        'start'        : 0,
+        'dur'          : 1,
+        'synthName'    : 'FMWT',
+        'frequency'    : 440,
+        'amplitude'    : 0.45,
+        'attackTime'   : 0.01,
+        'releaseTime'  : 0.1,
+        'sustain'      : 0.5,
+        'idx1'         : 0.01,
+        'idx2'         : 7,
+        'idx3'         : 5,
+        'carMul'       : 1,
+        'modMul'       : 1.0007,
+        'vibRate1'     : 0.01,
+        'vibRate2'     : 0.5,
+        'vibRise'      : 0,
+        'vibDepth'     : 0,
+        'pan'          : 0.0,
+        'table'        : 0,
+        'reverberation': 0.0,
+    })
+
+    OscTrm = SafeDict({
+        'start'      : 0,
+        'dur'        : 1,
+        'synthName'  : 'OscTrm',
+        'amplitude'  : 0.45,
+        'frequency'  : 440,
+        'attackTime' : 0.01,
+        'releaseTime': 0.1,
+        'sustain'    : 0.5,
+        'curve'      : 4.0,
+        'pan'        : 0.0,
+        'table'      : 0,
+        'trm1'       : 3.5,
+        'trm2'       : 5.8,
+        'trmRise'    : 0.5,
+        'trmDepth'   : 0.1,
+    })
+
+    OscAM = SafeDict({
+        'start'        : 0,
+        'dur'          : 1,
+        'synthName'    : 'OscAM',
+        'amplitude'    : 0.45,
+        'frequency'    : 440,
+        'attackTime'   : 0.01,
+        'releaseTime'  : 0.1,
+        'sustain'      : 0.5,
+        'pan'          : 0.0,
+        'amFunc'       : 0.0,
+        'am1'          : 0.75,
+        'am2'          : 0.75,
+        'amRise'       : 0.75,
+        'amRatio'      : 0.75,
+        'reverberation': 0.0,
+        'visualMode'   : 0.0,
+    })
+
+    AddSyn = SafeDict({
+        'start'        : 0,
+        'dur'          : 1,
+        'synthName'    : 'AddSyn',
+        'amp'          : 0.45,
+        'frequency'    : 440,
+        'ampStri'      : 0.5,
+        'attackStri'   : 0.1,
+        'releaseStri'  : 0.1,
+        'sustainStri'  : 0.8,
+        'ampLow'       : 0.5,
+        'attackLow'    : 0.001,
+        'releaseLow'   : 0.1,
+        'sustainLow'   : 0.8,
+        'ampUp'        : 0.6,
+        'attackUp'     : 0.01,
+        'releaseUp'    : 0.075,
+        'sustainUp'    : 0.9,
+        'freqStri1'    : 1.0,
+        'freqStri2'    : 2.001,
+        'freqStri3'    : 3.0,
+        'freqLow1'     : 4.009,
+        'freqLow2'     : 5.002,
+        'freqUp1'      : 6.0,
+        'freqUp2'      : 7.0,
+        'freqUp3'      : 8.0,
+        'freqUp4'      : 9.0,
+        'pan'          : 0.0,
+        'reverberation': 0.0,
+    })
+
+    PluckedString = SafeDict({
+        'start'      : 0,
+        'dur'        : 1,
+        'synthName'  : 'PluckedString',
+        'amplitude'  : 0.45,
+        'frequency'  : 440,
+        'attackTime' : 0.01,
+        'releaseTime': 0.1,
+        'sustain'    : 0.5,
+        'Pan1'       : 0.0,
+        'Pan2'       : 0.0,
+        'PanRise'    : 0.0,
+    })
+    

klotho/aikous/parameters/parameter_tree.py

@@ -0,0 +1,69 @@
+from ...topos.graphs.trees import Tree
+import pandas as pd
+
+class ParameterTree(Tree):
+    def __init__(self, root, children:tuple):
+        super().__init__(root, children)
+        self._meta['pfields'] = pd.Series([set()], index=[''])
+    
+    def __getitem__(self, node):
+        return ParameterNode(self, node)
+    
+    @property
+    def pfields(self):
+        return sorted(self._meta.loc['', 'pfields'])
+    
+    def set(self, node, **kwargs):
+        self._meta.loc['', 'pfields'].update(kwargs.keys())
+        
+        for key, value in kwargs.items():
+            self.graph.nodes[node][key] = value
+        
+        for descendant in self.descendants(node):
+            for key, value in kwargs.items():
+                self.graph.nodes[descendant][key] = value
+        
+    def get(self, node, key):
+        if key in self.graph.nodes[node]:
+            return self.graph.nodes[node][key]
+        return None
+    
+    def clear(self, node=None):
+        if node is None:
+            for n in self.graph.nodes:
+                self.graph.nodes[n].clear()
+        else:
+            self.graph.nodes[node].clear()
+            for descendant in self.descendants(node):
+                self.graph.nodes[descendant].clear()
+            
+    def items(self, node):
+        return dict(self.graph.nodes[node])
+
+class ParameterNode:
+    def __init__(self, tree, node):
+        self._tree = tree
+        self._node = node
+        
+    def __getitem__(self, key):
+        if isinstance(key, str):
+            return self._tree.get(self._node, key)
+        raise TypeError("Key must be a string")
+    
+    def __setitem__(self, key, value):
+        self._tree.set(self._node, **{key: value})
+        
+    def clear(self):
+        self._tree.clear(self._node)
+        
+    def items(self):
+        return self._tree.items(self._node)
+    
+    def __dict__(self):
+        return self._tree.items(self._node)
+        
+    def __str__(self):
+        return str(self._tree.items(self._node))
+    
+    def __repr__(self):
+        return repr(self._tree.items(self._node))