constraint-synth 0.1.0__py3-none-any.whl

constraint_synth/__init__.py

@@ -0,0 +1,19 @@
+"""Constraint Synthesizer — where waveshape IS lattice geometry."""
+
+from .oscillator import LatticeOscillator
+from .envelope import FunnelEnvelope
+from .constraint_filter import ConsonanceFilter
+from .synth import ConstraintSynth, BiquadLowpass, SchroederReverb
+from .playback import AudioPlayer
+from .midi_renderer import MIDIRenderer
+
+__all__ = [
+    "LatticeOscillator",
+    "FunnelEnvelope",
+    "ConsonanceFilter",
+    "ConstraintSynth",
+    "AudioPlayer",
+    "MIDIRenderer",
+    "BiquadLowpass",
+    "SchroederReverb",
+]

constraint_synth/constraint_filter.py

@@ -0,0 +1,44 @@
+"""Consonance Filter — passes consonant harmonics, attenuates dissonant ones."""
+
+import numpy as np
+
+
+# Harmonic series ratios (consonant with fundamental)
+CONSONANT_RATIOS = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]
+
+
+class ConsonanceFilter:
+    """
+    A filter that passes consonant harmonics and attenuates dissonant ones.
+
+    Unlike a traditional frequency filter, this filters by INTERVAL quality.
+
+    cutoff: 0.0 = only unisons pass, 1.0 = everything passes
+    resonance: constraint tightness (higher = sharper rolloff)
+    """
+    def __init__(self, cutoff: float = 0.5, resonance: float = 1.0):
+        self.cutoff = cutoff
+        self.resonance = resonance
+
+    def apply(self, signal: np.ndarray, fundamental: float, sample_rate: int) -> np.ndarray:
+        """Filter harmonics based on consonance with fundamental."""
+        if fundamental <= 0 or len(signal) == 0:
+            return signal
+
+        spectrum = np.fft.rfft(signal)
+        freqs = np.fft.rfftfreq(len(signal), 1.0 / sample_rate)
+
+        for i, freq in enumerate(freqs):
+            if freq < 20:
+                continue
+            ratio = freq / fundamental
+            # Distance to nearest consonant ratio
+            distances = [abs(ratio - cr) for cr in CONSONANT_RATIOS]
+            min_dist = min(distances)
+            # Consonance score: 1.0 = perfectly consonant, 0.0 = very dissonant
+            consonance = max(0.0, 1.0 - min_dist)
+            if consonance < self.cutoff:
+                attenuation = (consonance / self.cutoff) ** self.resonance
+                spectrum[i] *= attenuation
+
+        return np.fft.irfft(spectrum, len(signal))

constraint_synth/envelope.py

@@ -0,0 +1,73 @@
+"""Funnel Envelope — ADSR as deadband funnel lifecycle."""
+
+import numpy as np
+from dataclasses import dataclass
+
+
+@dataclass
+class FunnelEnvelope:
+    """
+    ADSR envelope as deadband funnel.
+
+    Attack = convergence rate, Sustain = equilibrium epsilon,
+    Release = divergence. Hold = suspension plateau.
+    """
+    attack: float = 0.01   # convergence time (seconds)
+    decay: float = 0.1     # relaxation time
+    sustain: float = 0.7   # equilibrium epsilon (0-1)
+    release: float = 0.3   # divergence time
+    hold: float = 0.0      # suspension plateau
+
+    def apply(self, signal: np.ndarray, sample_rate: int, note_duration: float) -> np.ndarray:
+        """Apply envelope to signal."""
+        n_samples = len(signal)
+        if n_samples == 0:
+            return signal
+
+        envelope = np.zeros(n_samples)
+
+        attack_samples = int(self.attack * sample_rate)
+        decay_samples = int(self.decay * sample_rate)
+        release_samples = int(self.release * sample_rate)
+        hold_samples = int(self.hold * sample_rate)
+
+        sustain_samples = (n_samples
+                           - attack_samples
+                           - decay_samples
+                           - hold_samples
+                           - release_samples)
+        if sustain_samples < 0:
+            sustain_samples = 0
+
+        idx = 0
+
+        # Attack — convergence ramp (0 → 1)
+        if attack_samples > 0:
+            end = min(attack_samples, n_samples)
+            envelope[idx:end] = np.linspace(0, 1, end - idx)
+            idx = end
+
+        # Hold — suspension plateau at peak
+        if hold_samples > 0 and idx < n_samples:
+            end = min(idx + hold_samples, n_samples)
+            envelope[idx:end] = 1.0
+            idx = end
+
+        # Decay — relaxation to pocket (1 → sustain)
+        if decay_samples > 0 and idx < n_samples:
+            end = min(idx + decay_samples, n_samples)
+            envelope[idx:end] = np.linspace(1, self.sustain, end - idx)
+            idx = end
+
+        # Sustain — pocket equilibrium
+        if sustain_samples > 0 and idx < n_samples:
+            end = min(idx + sustain_samples, n_samples)
+            envelope[idx:end] = self.sustain
+            idx = end
+
+        # Release — divergence (sustain → 0)
+        if release_samples > 0 and idx < n_samples:
+            remaining = min(release_samples, n_samples - idx)
+            envelope[idx:idx + remaining] = np.linspace(self.sustain, 0, remaining)
+
+        return signal * envelope

constraint_synth/flux_bridge.py

@@ -0,0 +1,521 @@
+"""flux_bridge — Bridge between flux-tensor-midi and constraint-synth.
+
+Converts flux-tensor-midi MidiEvent streams and FluxVectors into
+constraint-synth audio, enabling direct synthesis without DawDreamer.
+
+This is the synergy: constraint parameters → MIDI (flux) → audio (dawdreamer)
+OR constraint parameters → audio directly (synth). Same source, two renderers.
+
+Usage:
+    from constraint_synth.flux_bridge import FluxBridge
+
+    bridge = FluxBridge(preset="piano_ballad")
+    audio = bridge.render_events(midi_events)
+    bridge.to_wav(audio, "output.wav")
+"""
+
+from __future__ import annotations
+
+import math
+import struct
+import wave
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+from .oscillator import LatticeOscillator
+from .envelope import FunnelEnvelope
+from .constraint_filter import ConsonanceFilter
+from .synth import ConstraintSynth, BiquadLowpass, SchroederReverb
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Channel mapping: FluxVector channels → constraint-synth parameters
+# ──────────────────────────────────────────────────────────────────────────────
+
+CHANNEL_NAMES = (
+    "pitch",
+    "dynamics",
+    "timbre",
+    "brightness",
+    "space",
+    "tension",
+    "noise",
+    "snap",
+    "weight",
+)
+
+# Lattice shape lookup by index (timbre channel)
+LATTICE_SHAPES = ("sine", "saw", "square", "triangle", "eisenstein")
+
+# Default note-to-channel mapping (matches flux-tensor-midi NoteName)
+NOTE_CHANNEL_BASE = 60  # C4
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# MidiEvent shim — works with or without flux-tensor-midi installed
+# ──────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class MidiEventShim:
+    """Lightweight MidiEvent compatible with flux-tensor-midi's MidiEvent.
+
+    If flux_tensor_midi is installed, we accept its MidiEvent directly.
+    Otherwise, this shim provides the same interface.
+    """
+    note: int
+    velocity: int
+    start_ms: float
+    duration_ms: float
+    channel: int = 0
+
+    def __post_init__(self):
+        if not 0 <= self.note <= 127:
+            raise ValueError(f"note must be 0–127, got {self.note}")
+        if not 0 <= self.velocity <= 127:
+            raise ValueError(f"velocity must be 0–127, got {self.velocity}")
+
+
+def _normalize_event(ev: Any) -> MidiEventShim:
+    """Accept any event with note/velocity/start_ms/duration_ms attributes."""
+    if isinstance(ev, MidiEventShim):
+        return ev
+    return MidiEventShim(
+        note=ev.note,
+        velocity=ev.velocity,
+        start_ms=ev.start_ms,
+        duration_ms=ev.duration_ms,
+        channel=getattr(ev, "channel", 0),
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# FluxVector mapper
+# ──────────────────────────────────────────────────────────────────────────────
+
+class FluxVectorMapper:
+    """Maps a 9-channel FluxVector to constraint-synth parameters.
+
+    Channel semantics:
+        0 (pitch)      → oscillator frequency via note offset from C4
+        1 (dynamics)   → envelope sustain (0–1) + velocity scaling
+        2 (timbre)     → lattice_shape index (0–4)
+        3 (brightness) → filter_cutoff (200–8000 Hz)
+        4 (space)      → reverb_wet (0–1)
+        5 (tension)    → lattice_stretch (0.9–1.1)
+        6 (noise)      → noise_floor (0–0.1)
+        7 (snap)       → snap_threshold (0–1)
+        8 (weight)     → attack (0.001–0.5) and decay (0.01–1.0)
+    """
+
+    def __init__(
+        self,
+        base_note: int = 60,
+        velocity_scale: int = 100,
+        sample_rate: int = 44100,
+    ):
+        self.base_note = base_note
+        self.velocity_scale = velocity_scale
+        self.sample_rate = sample_rate
+
+    def map_to_synth_params(
+        self,
+        values: Sequence[float],
+        salience: Sequence[float] | None = None,
+        tolerance: Sequence[float] | None = None,
+    ) -> dict:
+        """Map FluxVector values to a dict of constraint-synth constructor args.
+
+        Returns a dict suitable for building a LatticeOscillator, FunnelEnvelope,
+        and synth config.
+        """
+        if len(values) < 9:
+            raise ValueError(f"Expected 9 channels, got {len(values)}")
+
+        # Channel 0: pitch → semitone offset from base_note
+        pitch_offset = values[0] * 12.0  # 0–12 semitones
+        note = min(127, max(0, int(self.base_note + pitch_offset)))
+        freq = 440.0 * (2 ** ((note - 69) / 12.0))
+
+        # Channel 1: dynamics → sustain level
+        dynamics = max(0.0, min(1.0, values[1]))
+
+        # Channel 2: timbre → lattice shape index
+        shape_idx = max(0, min(len(LATTICE_SHAPES) - 1, int(values[2] * len(LATTICE_SHAPES))))
+        lattice_shape = LATTICE_SHAPES[shape_idx]
+
+        # Channel 3: brightness → filter cutoff
+        brightness = max(0.0, min(1.0, values[3]))
+        filter_cutoff = 200.0 + brightness * 7800.0  # 200–8000 Hz
+
+        # Channel 4: space → reverb wet
+        space = max(0.0, min(1.0, values[4]))
+        reverb_wet = space * 0.8  # cap at 0.8
+
+        # Channel 5: tension → lattice stretch
+        tension = max(0.0, min(1.0, values[5]))
+        lattice_stretch = 0.9 + tension * 0.2  # 0.9–1.1
+
+        # Channel 6: noise → noise floor
+        noise = max(0.0, min(1.0, values[6]))
+        noise_floor = noise * 0.1
+
+        # Channel 7: snap → snap threshold
+        snap = max(0.0, min(1.0, values[7]))
+
+        # Channel 8: weight → attack and decay
+        weight = max(0.0, min(1.0, values[8]))
+        attack = 0.001 + weight * 0.499  # 0.001–0.5
+        decay = 0.01 + weight * 0.99     # 0.01–1.0
+
+        return {
+            "note": note,
+            "freq": freq,
+            "velocity": int(dynamics * self.velocity_scale),
+            "lattice_shape": lattice_shape,
+            "lattice_stretch": lattice_stretch,
+            "noise_floor": noise_floor,
+            "snap_threshold": snap,
+            "filter_cutoff": filter_cutoff,
+            "reverb_wet": reverb_wet,
+            "attack": attack,
+            "decay": decay,
+            "sustain": dynamics,
+            "release": 0.3,
+        }
+
+    def map_to_synth(self, values: Sequence[float], **overrides) -> ConstraintSynth:
+        """Build a complete ConstraintSynth from FluxVector values."""
+        params = self.map_to_synth_params(values)
+        params.update(overrides)
+
+        osc = LatticeOscillator(
+            frequency=params["freq"],
+            lattice_shape=params["lattice_shape"],
+            lattice_stretch=params["lattice_stretch"],
+            noise_floor=params["noise_floor"],
+            snap_threshold=params["snap_threshold"],
+        )
+        env = FunnelEnvelope(
+            attack=params["attack"],
+            decay=params["decay"],
+            sustain=params["sustain"],
+            release=params["release"],
+        )
+        return ConstraintSynth(
+            oscillator=osc,
+            envelope=env,
+            filter_cutoff=params["filter_cutoff"],
+            reverb_wet=params["reverb_wet"],
+        )
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# FluxBridge — main bridge class
+# ──────────────────────────────────────────────────────────────────────────────
+
+class FluxBridge:
+    """Bridge between flux-tensor-midi and constraint-synth.
+
+    Renders MidiEvent streams as direct audio via ConstraintSynth,
+    bypassing DawDreamer entirely while preserving constraint semantics.
+
+    Parameters
+    ----------
+    preset : str, optional
+        ConstraintSynth preset name. If provided, used as default timbre.
+    mapper : FluxVectorMapper, optional
+        Custom mapper. Defaults to standard channel mapping.
+    sample_rate : int
+        Audio sample rate (default 44100).
+    """
+
+    def __init__(
+        self,
+        preset: str | None = None,
+        mapper: FluxVectorMapper | None = None,
+        sample_rate: int = 44100,
+    ):
+        self.sample_rate = sample_rate
+        self.mapper = mapper or FluxVectorMapper(sample_rate=sample_rate)
+
+        if preset is not None:
+            self._default_synth = ConstraintSynth.from_preset(preset)
+        else:
+            self._default_synth = ConstraintSynth()
+
+    @property
+    def synth(self) -> ConstraintSynth:
+        """The default ConstraintSynth instance."""
+        return self._default_synth
+
+    def render_events(
+        self,
+        events: Sequence[Any],
+        spacing_ms: float = 10.0,
+        crossfade_samples: int = 64,
+    ) -> np.ndarray:
+        """Render a list of MidiEvent objects to audio.
+
+        Accepts flux-tensor-midi MidiEvent objects or MidiEventShim objects.
+        Events can be in any order; they are sorted by start time.
+
+        Parameters
+        ----------
+        events : sequence of MidiEvent-like
+            Events with .note, .velocity, .start_ms, .duration_ms attributes.
+        spacing_ms : float
+            Extra silence between overlapping notes (default 10ms).
+        crossfade_samples : int
+            Crossfade length between consecutive note boundaries.
+
+        Returns
+        -------
+        np.ndarray
+            Mono audio signal, float64, [-1, 1].
+        """
+        if not events:
+            return np.array([], dtype=np.float64)
+
+        normalized = [_normalize_event(e) for e in events]
+        normalized.sort(key=lambda e: e.start_ms)
+
+        # Calculate total duration
+        end_ms = max(e.start_ms + e.duration_ms for e in normalized)
+        total_seconds = end_ms / 1000.0 + 1.0  # extra for release tail
+        total_samples = int(total_seconds * self.sample_rate)
+        output = np.zeros(total_samples, dtype=np.float64)
+
+        for ev in normalized:
+            duration_sec = ev.duration_ms / 1000.0
+            if duration_sec <= 0:
+                continue
+
+            # Render note via constraint-synth
+            note_audio = self._default_synth.play_note(
+                ev.note, ev.velocity, duration_sec
+            )
+
+            # Place at correct position
+            start_sample = int(ev.start_ms / 1000.0 * self.sample_rate)
+            end_sample = min(start_sample + len(note_audio), total_samples)
+            length = end_sample - start_sample
+
+            if length > 0:
+                # Additive mixing for overlapping notes
+                output[start_sample:end_sample] += note_audio[:length]
+
+        # Normalize
+        peak = np.max(np.abs(output))
+        if peak > 1.0:
+            output = output / peak * 0.9
+
+        return output
+
+    def render_flux_vector(
+        self,
+        values: Sequence[float],
+        start_ms: float = 0.0,
+        duration_ms: float = 500.0,
+        salience: Sequence[float] | None = None,
+        tolerance: Sequence[float] | None = None,
+    ) -> np.ndarray:
+        """Render a single FluxVector to audio via direct constraint mapping.
+
+        The FluxVector channels control all synth parameters directly —
+        no MIDI involved. This is the pure constraint-synthesis path.
+
+        Parameters
+        ----------
+        values : sequence of float
+            9-channel FluxVector values.
+        start_ms : float
+            Start time offset (for scheduling within a larger buffer).
+        duration_ms : float
+            Note duration in milliseconds.
+        salience : sequence of float, optional
+            Per-channel salience values (0–1).
+        tolerance : sequence of float, optional
+            Per-channel tolerance values (ms).
+
+        Returns
+        -------
+        np.ndarray
+            Mono audio signal.
+        """
+        params = self.mapper.map_to_synth_params(values, salience, tolerance)
+
+        # Build a per-vector synth with the mapped parameters
+        osc = LatticeOscillator(
+            frequency=params["freq"],
+            lattice_shape=params["lattice_shape"],
+            lattice_stretch=params["lattice_stretch"],
+            noise_floor=params["noise_floor"],
+            snap_threshold=params["snap_threshold"],
+        )
+        env = FunnelEnvelope(
+            attack=params["attack"],
+            decay=params["decay"],
+            sustain=params["sustain"],
+            release=params["release"],
+        )
+        synth = ConstraintSynth(
+            oscillator=osc,
+            envelope=env,
+            filter_cutoff=params["filter_cutoff"],
+            reverb_wet=params["reverb_wet"],
+        )
+
+        duration_sec = duration_ms / 1000.0
+        return synth.play_note(params["note"], params["velocity"], duration_sec)
+
+    def render_flux_sequence(
+        self,
+        vectors: Sequence[dict],
+        spacing_ms: float = 50.0,
+    ) -> np.ndarray:
+        """Render a sequence of FluxVectors to audio.
+
+        Parameters
+        ----------
+        vectors : sequence of dict
+            Each dict should have:
+            - "values": 9-channel values
+            - "start_ms": start time (optional, auto-sequenced)
+            - "duration_ms": duration (default 250)
+            - "salience": optional salience values
+            - "tolerance": optional tolerance values
+        spacing_ms : float
+            Default spacing between vectors if start_ms not specified.
+
+        Returns
+        -------
+        np.ndarray
+            Mono audio signal.
+        """
+        buffers = []
+        auto_start = 0.0
+
+        for v in vectors:
+            values = v["values"]
+            duration_ms = v.get("duration_ms", 250.0)
+            start_ms = v.get("start_ms", auto_start)
+
+            audio = self.render_flux_vector(
+                values,
+                start_ms=0.0,  # render relative
+                duration_ms=duration_ms,
+                salience=v.get("salience"),
+                tolerance=v.get("tolerance"),
+            )
+            buffers.append((start_ms, audio))
+            auto_start = start_ms + duration_ms + spacing_ms
+
+        if not buffers:
+            return np.array([], dtype=np.float64)
+
+        # Calculate total length
+        max_end = max(start + len(audio) / self.sample_rate * 1000
+                      for start, audio in buffers)
+        total_samples = int((max_end / 1000.0 + 0.5) * self.sample_rate)
+        output = np.zeros(total_samples, dtype=np.float64)
+
+        for start_ms, audio in buffers:
+            start_sample = int(start_ms / 1000.0 * self.sample_rate)
+            end_sample = min(start_sample + len(audio), total_samples)
+            length = end_sample - start_sample
+            if length > 0:
+                output[start_sample:end_sample] += audio[:length]
+
+        peak = np.max(np.abs(output))
+        if peak > 1.0:
+            output = output / peak * 0.9
+
+        return output
+
+    def events_to_constraints(
+        self,
+        events: Sequence[Any],
+    ) -> List[dict]:
+        """Extract constraint parameters from a MidiEvent stream.
+
+        Reverse-maps MIDI events back into constraint parameter space.
+        This enables round-tripping: constraints → MIDI → constraints.
+
+        Parameters
+        ----------
+        events : sequence of MidiEvent-like
+
+        Returns
+        -------
+        list of dict
+            Each dict contains the inferred constraint parameters per event.
+        """
+        results = []
+        for ev in events:
+            ev = _normalize_event(ev)
+            freq = 440.0 * (2 ** ((ev.note - 69) / 12.0))
+
+            results.append({
+                "note": ev.note,
+                "freq": freq,
+                "velocity": ev.velocity,
+                "start_ms": ev.start_ms,
+                "duration_ms": ev.duration_ms,
+                "channel": ev.channel,
+                "amplitude": ev.velocity / 127.0,
+                "duration_sec": ev.duration_ms / 1000.0,
+            })
+        return results
+
+    @staticmethod
+    def to_wav(
+        signal: np.ndarray,
+        path: str,
+        sample_rate: int = 44100,
+    ) -> None:
+        """Save audio signal as 16-bit WAV."""
+        ConstraintSynth.to_wav(signal, path, sample_rate)
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Comparison utility
+# ──────────────────────────────────────────────────────────────────────────────
+
+def compare_renderers(
+    events: Sequence[Any],
+    preset: str = "piano_ballad",
+    output_dir: str = ".",
+) -> dict:
+    """Render the same events via both paths and compare.
+
+    Returns a dict with:
+    - "direct_path": path to constraint-synth WAV
+    - "direct_duration_ms": render time
+    - "events_count": number of events rendered
+
+    Note: DawDreamer comparison only available if flux-tensor-midi
+    with audio extras is installed.
+    """
+    import time
+    import os
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    bridge = FluxBridge(preset=preset)
+
+    t0 = time.perf_counter()
+    audio = bridge.render_events(events)
+    direct_ms = (time.perf_counter() - t0) * 1000
+
+    direct_path = os.path.join(output_dir, "bridge_direct.wav")
+    bridge.to_wav(audio, direct_path)
+
+    return {
+        "direct_path": direct_path,
+        "direct_duration_ms": round(direct_ms, 2),
+        "events_count": len(events),
+        "audio_samples": len(audio),
+        "audio_duration_sec": len(audio) / bridge.sample_rate,
+    }

constraint_synth/midi_renderer.py

@@ -0,0 +1,170 @@
+"""Render full MIDI files to audio using ConstraintSynth."""
+
+import numpy as np
+
+
+class MIDIRenderer:
+    """Render a complete MIDI file to audio using ConstraintSynth."""
+
+    def __init__(self, synth=None, sample_rate: int = 44100,
+                 use_biquad: bool = False, use_reverb: bool = False,
+                 stereo: bool = False):
+        from .synth import ConstraintSynth, BiquadLowpass, SchroederReverb
+
+        self.synth = synth or ConstraintSynth()
+        self.sample_rate = sample_rate
+        self.use_biquad = use_biquad
+        self.use_reverb = use_reverb
+        self.stereo = stereo
+
+        if use_biquad:
+            self.biquad = BiquadLowpass(cutoff_hz=2000, sample_rate=sample_rate)
+        else:
+            self.biquad = None
+
+        if use_reverb:
+            self.reverb = SchroederReverb(sample_rate=sample_rate)
+        else:
+            self.reverb = None
+
+    def render(self, midi_path: str) -> np.ndarray:
+        """Render MIDI file to audio numpy array."""
+        import mido
+
+        mid = mido.MidiFile(midi_path)
+        ticks_per_beat = mid.ticks_per_beat
+
+        # Find tempo (default 120 BPM)
+        tempo = 500000  # microseconds per beat
+        for track in mid.tracks:
+            for msg in track:
+                if msg.type == "set_tempo":
+                    tempo = msg.tempo
+                    break
+
+        seconds_per_tick = tempo / (ticks_per_beat * 1_000_000)
+
+        # Calculate total duration
+        total_ticks = 0
+        for track in mid.tracks:
+            track_ticks = sum(msg.time for msg in track)
+            total_ticks = max(total_ticks, track_ticks)
+
+        total_seconds = total_ticks * seconds_per_tick + 2.0  # extra for release
+        total_samples = int(total_seconds * self.sample_rate)
+        output = np.zeros(total_samples)
+
+        # Render each track
+        for track in mid.tracks:
+            abs_tick = 0
+            active_notes = {}
+            for msg in track:
+                abs_tick += msg.time
+                abs_time = abs_tick * seconds_per_tick
+                sample_pos = int(abs_time * self.sample_rate)
+
+                if msg.type == "note_on" and msg.velocity > 0:
+                    active_notes[msg.note] = (sample_pos, msg.velocity, msg.channel)
+                elif msg.type == "note_off" or (
+                    msg.type == "note_on" and msg.velocity == 0
+                ):
+                    if msg.note in active_notes:
+                        start, velocity, channel = active_notes.pop(msg.note)
+                        duration_samples = sample_pos - start
+                        duration_sec = duration_samples / self.sample_rate
+
+                        if duration_sec > 0:
+                            note_audio = self.synth.play_note(
+                                msg.note, velocity, duration_sec
+                            )
+                            end = min(start + len(note_audio), total_samples)
+                            output[start:end] += note_audio[: end - start]
+
+        # Apply effects
+        if self.biquad is not None:
+            output = self.biquad.process(output)
+        if self.reverb is not None:
+            output = self.reverb.process(output)
+
+        # Re-normalize after effects
+        peak = np.max(np.abs(output))
+        if peak > 0:
+            output = output / peak * 0.8
+
+        # Stereo: create right channel with slight detune
+        if self.stereo:
+            from .oscillator import LatticeOscillator
+            # Render a detuned version for the right channel
+            detune_factor = 1 + 0.5 / self.synth.oscillator.frequency  # +0.5 Hz
+            original_freq = self.synth.oscillator.frequency
+            # Re-render with detuned oscillator for right channel
+            # We do this by re-processing the original MIDI with detuned freq
+            right = self._render_detuned(midi_path, detune_factor)
+            # Match lengths
+            maxlen = max(len(output), len(right))
+            left = np.zeros(maxlen)
+            right_ch = np.zeros(maxlen)
+            left[:len(output)] = output
+            right_ch[:len(right)] = right
+            output = np.column_stack([left, right_ch])
+
+        return output
+
+    def _render_detuned(self, midi_path: str, detune_factor: float) -> np.ndarray:
+        """Render MIDI with a detuned oscillator for stereo effect."""
+        import mido
+
+        mid = mido.MidiFile(midi_path)
+        ticks_per_beat = mid.ticks_per_beat
+        tempo = 500000
+        for track in mid.tracks:
+            for msg in track:
+                if msg.type == "set_tempo":
+                    tempo = msg.tempo
+                    break
+
+        seconds_per_tick = tempo / (ticks_per_beat * 1_000_000)
+        total_ticks = 0
+        for track in mid.tracks:
+            track_ticks = sum(msg.time for msg in track)
+            total_ticks = max(total_ticks, track_ticks)
+        total_seconds = total_ticks * seconds_per_tick + 2.0
+        total_samples = int(total_seconds * self.sample_rate)
+        output = np.zeros(total_samples)
+
+        original_freq = self.synth.oscillator.frequency
+
+        for track in mid.tracks:
+            abs_tick = 0
+            active_notes = {}
+            for msg in track:
+                abs_tick += msg.time
+                abs_time = abs_tick * seconds_per_tick
+                sample_pos = int(abs_time * self.sample_rate)
+
+                if msg.type == "note_on" and msg.velocity > 0:
+                    active_notes[msg.note] = (sample_pos, msg.velocity, msg.channel)
+                elif msg.type == "note_off" or (
+                    msg.type == "note_on" and msg.velocity == 0
+                ):
+                    if msg.note in active_notes:
+                        start, velocity, channel = active_notes.pop(msg.note)
+                        duration_samples = sample_pos - start
+                        duration_sec = duration_samples / self.sample_rate
+
+                        if duration_sec > 0:
+                            # Apply detune
+                            base_freq = 440.0 * (2 ** ((msg.note - 69) / 12.0))
+                            self.synth.oscillator.frequency = base_freq * detune_factor
+                            note_audio = self.synth.play_note(
+                                msg.note, velocity, duration_sec
+                            )
+                            end = min(start + len(note_audio), total_samples)
+                            output[start:end] += note_audio[: end - start]
+
+        self.synth.oscillator.frequency = original_freq
+
+        peak = np.max(np.abs(output))
+        if peak > 0:
+            output = output / peak * 0.8
+        return output

constraint_synth/oscillator.py

@@ -0,0 +1,127 @@
+"""Lattice Oscillator — waveshape as lattice geometry."""
+
+import numpy as np
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class LatticeOscillator:
+    """
+    An oscillator where waveshape IS lattice geometry.
+
+    sine: continuous, no snapping (epsilon=inf)
+    square: binary snap (Z2 — only 2 directions)
+    saw: ramp through lattice (Z — linear interpolation + snap)
+    triangle: A2 snap (our Eisenstein lattice in 1D)
+    eisenstein: full A2 lattice (hexagonal tiling)
+    """
+    frequency: float = 440.0      # Hz
+    sample_rate: int = 44100
+    lattice_shape: Literal["sine", "square", "saw", "triangle", "eisenstein"] = "sine"
+    lattice_stretch: float = 1.0  # 1.0=harmonic, 1.002=piano, 1.5=bell
+    noise_floor: float = 0.0      # 0-1, jitter that never converges
+    snap_threshold: float = 1.0   # 0=soft snap, 1=hard snap
+    use_polyblep: bool = True     # enable PolyBLEP anti-aliasing
+
+    def _polyblep_correct(self, phase_inc: float, sample_phases: np.ndarray,
+                          direction: Literal["rising", "falling"]) -> np.ndarray:
+        """Apply PolyBLEP correction at phase-wrap discontinuities.
+
+        For each sample, compute how close the phase is to the wrap point (0/1)
+        and apply a 2-point polynomial correction.
+
+        Args:
+            phase_inc: phase increment per sample (= freq / sample_rate)
+            sample_phases: normalised phase in [0, 1) per sample
+            direction: 'rising' for upward discontinuity, 'falling' for downward
+
+        Returns:
+            Correction array (same length as sample_phases)
+        """
+        correction = np.zeros_like(sample_phases)
+        if phase_inc <= 0:
+            return correction
+
+        for i, p in enumerate(sample_phases):
+            # Check samples near the phase-wrap boundary (0 ≡ 1)
+            # t = distance from wrap, measured in samples
+
+            # --- just BEFORE the wrap (phase close to 1, i.e. p close to 1) ---
+            if p >= 1.0 - phase_inc:
+                t = (p - 1.0) / phase_inc  # in (-1, 0]
+                val = t + t + t * t        # = 2t + t^2
+            # --- just AFTER the wrap (phase close to 0) ---
+            elif p < phase_inc:
+                t = p / phase_inc          # in [0, 1)
+                val = t + t - t * t        # = 2t - t^2
+            else:
+                val = 0.0
+
+            if direction == "falling":
+                val = -val
+            correction[i] = val
+
+        return correction
+
+    def generate(self, duration: float) -> np.ndarray:
+        """Generate audio samples."""
+        n_samples = int(self.sample_rate * duration)
+        if n_samples == 0:
+            return np.array([], dtype=np.float64)
+        t = np.linspace(0, duration, n_samples, endpoint=False)
+        phase = 2 * np.pi * self.frequency * t
+        norm_phase = (phase / (2 * np.pi)) % 1.0  # normalised [0, 1)
+        phase_inc = self.frequency / self.sample_rate
+
+        if self.lattice_shape == "sine":
+            signal = np.sin(phase)
+        elif self.lattice_shape == "square":
+            signal = np.sign(np.sin(phase))
+            if self.use_polyblep:
+                # Rising edge at phase wrap (0→1)
+                signal += self._polyblep_correct(phase_inc, norm_phase, "rising")
+                # Falling edge at phase 0.5
+                shifted = (norm_phase - 0.5) % 1.0
+                signal += self._polyblep_correct(phase_inc, shifted, "falling")
+        elif self.lattice_shape == "saw":
+            signal = 2 * norm_phase - 1
+            if self.use_polyblep:
+                signal -= self._polyblep_correct(phase_inc, norm_phase, "rising")
+        elif self.lattice_shape == "triangle":
+            signal = 2 * np.abs(2 * norm_phase - 1) - 1
+        elif self.lattice_shape == "eisenstein":
+            raw = np.sin(phase)
+            signal = self._eisenstein_snap(raw)
+        else:
+            raise ValueError(f"Unknown lattice_shape: {self.lattice_shape}")
+
+        # Apply inharmonicity (lattice stretch)
+        if self.lattice_stretch != 1.0:
+            harmonic = np.sin(phase * 2 * self.lattice_stretch) * 0.3
+            signal = signal + harmonic
+
+        # Apply noise floor (irreducible jitter)
+        if self.noise_floor > 0:
+            noise = np.random.normal(0, self.noise_floor * 0.1, len(signal))
+            signal = signal + noise
+
+        return signal
+
+    def _eisenstein_snap(self, values: np.ndarray) -> np.ndarray:
+        """Snap continuous values to Eisenstein lattice directions.
+
+        Uses the actual A2 lattice snap logic from constraint_theory_core:
+        quantize to nearest of the 6 hex directions in 1D projection.
+        """
+        # Map values through hexagonal quantization
+        # 6 directions at 60° intervals: project onto amplitude axis
+        # This creates a staircase-like wave richer than square
+        snapped = np.zeros_like(values)
+        levels = 6  # hexagonal symmetry
+        for i, v in enumerate(values):
+            # Quantize to nearest hex level
+            level = round(v * levels / 2) / (levels / 2)
+            # Soft/hard snap interpolation
+            snapped[i] = v + (level - v) * self.snap_threshold
+        return snapped

constraint_synth/playback.py

@@ -0,0 +1,55 @@
+"""Real-time audio playback for ConstraintSynth."""
+
+import io
+import wave
+
+import numpy as np
+
+
+class AudioPlayer:
+    """Play numpy arrays as audio. Zero external deps for WAV, optional sounddevice for realtime."""
+
+    @staticmethod
+    def to_wav_bytes(signal: np.ndarray, sample_rate: int = 44100) -> bytes:
+        """Convert numpy float array to WAV bytes (for IPython, web, etc.)"""
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as f:
+            f.setnchannels(1)
+            f.setsampwidth(2)
+            f.setframerate(sample_rate)
+            data = (np.clip(signal, -1, 1) * 32767).astype(np.int16)
+            f.writeframes(data.tobytes())
+        return buf.getvalue()
+
+    @staticmethod
+    def play_ipython(signal: np.ndarray, sample_rate: int = 44100):
+        """Play audio in Jupyter/IPython using IPython.display.Audio"""
+        try:
+            from IPython.display import Audio, display
+
+            wav_bytes = AudioPlayer.to_wav_bytes(signal, sample_rate)
+            display(Audio(wav_bytes, rate=sample_rate))
+        except ImportError:
+            print("IPython not available. Save to WAV instead.")
+
+    @staticmethod
+    def play_sounddevice(signal: np.ndarray, sample_rate: int = 44100):
+        """Play audio through speakers using sounddevice."""
+        try:
+            import sounddevice as sd
+
+            sd.play(signal, sample_rate)
+            sd.wait()
+        except ImportError:
+            raise RuntimeError("sounddevice not installed. pip install sounddevice")
+
+    @staticmethod
+    def play(signal: np.ndarray, sample_rate: int = 44100):
+        """Auto-detect best playback method."""
+        try:
+            AudioPlayer.play_sounddevice(signal, sample_rate)
+        except Exception:
+            try:
+                AudioPlayer.play_ipython(signal, sample_rate)
+            except Exception:
+                print("No audio playback available. Use to_wav_bytes() + save instead.")

constraint_synth/synth.py

@@ -0,0 +1,241 @@
+"""ConstraintSynth — the full constraint-theory synthesizer."""
+
+import struct
+import wave
+
+import numpy as np
+
+from .oscillator import LatticeOscillator
+from .envelope import FunnelEnvelope
+from .constraint_filter import ConsonanceFilter
+
+
+class BiquadLowpass:
+    """Second-order IIR lowpass filter (RBJ Audio EQ Cookbook)."""
+
+    def __init__(self, cutoff_hz: float, sample_rate: int = 44100, Q: float = 0.707):
+        from math import cos, pi, sin
+
+        omega = 2 * pi * cutoff_hz / sample_rate
+        alpha = sin(omega) / (2 * Q)
+        b0 = (1 - cos(omega)) / 2
+        b1 = 1 - cos(omega)
+        b2 = (1 - cos(omega)) / 2
+        a0 = 1 + alpha
+        a1 = -2 * cos(omega)
+        a2 = 1 - alpha
+
+        # Normalize by a0
+        self.b = [b0 / a0, b1 / a0, b2 / a0]
+        self.a = [a1 / a0, a2 / a0]
+        self.w = [0.0, 0.0]  # Direct Form II Transposed state
+
+    def process(self, samples: np.ndarray) -> np.ndarray:
+        """Process a numpy array of samples through the filter."""
+        output = np.zeros_like(samples)
+        for i, x in enumerate(samples):
+            y = self.b[0] * x + self.w[0]
+            self.w[0] = self.b[1] * x - self.a[0] * y + self.w[1]
+            self.w[1] = self.b[2] * x - self.a[1] * y
+            output[i] = y
+        return output
+
+
+class SchroederReverb:
+    """Schroeder reverb: 4 parallel comb filters + 2 series allpass filters."""
+
+    def __init__(self, sample_rate: int = 44100, feedback: float = 0.84, wet: float = 0.3):
+        # Comb filter delay lengths (chosen to be coprime for decorrelation)
+        comb_delays = [1557, 1617, 1491, 1422]
+        # Allpass delay lengths
+        allpass_delays = [225, 556]
+
+        self.combs = [np.zeros(d, dtype=np.float64) for d in comb_delays]
+        self.comb_idx = [0] * 4
+        self.allpasses = [np.zeros(d, dtype=np.float64) for d in allpass_delays]
+        self.ap_idx = [0] * 2
+        self.feedback = feedback
+        self.wet = wet
+        self.ap_gain = 0.5
+
+    def _process_combs(self, samples: np.ndarray) -> np.ndarray:
+        """Run 4 parallel comb filters and sum."""
+        output = np.zeros_like(samples)
+        for k in range(4):
+            buf = self.combs[k]
+            idx = self.comb_idx[k]
+            for i, x in enumerate(samples):
+                delayed = buf[idx]
+                buf[idx] = x + self.feedback * delayed
+                output[i] += delayed
+                idx = (idx + 1) % len(buf)
+            self.comb_idx[k] = idx
+        return output / 4.0
+
+    def _process_allpasses(self, samples: np.ndarray) -> np.ndarray:
+        """Run 2 series allpass filters."""
+        signal = samples
+        for k in range(2):
+            buf = self.allpasses[k]
+            idx = self.ap_idx[k]
+            out = np.zeros_like(signal)
+            for i, x in enumerate(signal):
+                delayed = buf[idx]
+                buf[idx] = x + self.ap_gain * delayed
+                out[i] = delayed - self.ap_gain * x
+                idx = (idx + 1) % len(buf)
+            self.ap_idx[k] = idx
+            signal = out
+        return signal
+
+    def process(self, samples: np.ndarray) -> np.ndarray:
+        """Process samples: parallel combs → series allpasses → dry/wet mix."""
+        comb_out = self._process_combs(samples)
+        reverb = self._process_allpasses(comb_out)
+        return samples * (1.0 - self.wet) + reverb * self.wet
+
+
+class ConstraintSynth:
+    """Lattice oscillator + funnel envelope + consonance filter + lowpass + reverb."""
+
+    def __init__(
+        self,
+        oscillator: LatticeOscillator | None = None,
+        envelope: FunnelEnvelope | None = None,
+        filter: ConsonanceFilter | None = None,
+        filter_cutoff: float = 2000.0,
+        reverb_wet: float = 0.3,
+    ):
+        self.oscillator = oscillator or LatticeOscillator()
+        self.envelope = envelope or FunnelEnvelope()
+        self.filter = filter
+        self._lowpass = BiquadLowpass(filter_cutoff, self.oscillator.sample_rate)
+        self._reverb = SchroederReverb(self.oscillator.sample_rate, wet=reverb_wet)
+        self.filter_cutoff = filter_cutoff
+        self.reverb_wet = reverb_wet
+
+    def play_note(self, pitch: int, velocity: int, duration: float) -> np.ndarray:
+        """Generate a single note from MIDI parameters."""
+        # MIDI pitch → frequency
+        freq = 440.0 * (2 ** ((pitch - 69) / 12.0))
+        self.oscillator.frequency = freq
+
+        signal = self.oscillator.generate(duration)
+        signal = self.envelope.apply(signal, self.oscillator.sample_rate, duration)
+        signal *= velocity / 127.0
+
+        if self.filter is not None:
+            signal = self.filter.apply(signal, freq, self.oscillator.sample_rate)
+
+        # Apply lowpass filter
+        if self.filter_cutoff > 0:
+            signal = self._lowpass.process(signal)
+
+        # Apply reverb
+        if self.reverb_wet > 0:
+            signal = self._reverb.process(signal)
+
+        return signal
+
+    # ------------------------------------------------------------------
+    # Presets
+    # ------------------------------------------------------------------
+    PRESETS = {
+        "bop_sax": dict(
+            oscillator=dict(lattice_shape="saw", lattice_stretch=1.0, use_polyblep=True),
+            envelope=dict(attack=0.005, decay=0.08, sustain=0.75, release=0.15, hold=0.0),
+            consonance_filter=dict(cutoff=0.5, resonance=1.0),
+            filter_cutoff=3500.0,
+            reverb_wet=0.2,
+        ),
+        "blues_guitar": dict(
+            oscillator=dict(lattice_shape="square", lattice_stretch=1.0, noise_floor=0.02),
+            envelope=dict(attack=0.02, decay=0.15, sustain=0.6, release=0.4, hold=0.0),
+            consonance_filter=dict(cutoff=0.4, resonance=1.2),
+            filter_cutoff=1800.0,
+            reverb_wet=0.45,
+        ),
+        "techno_bass": dict(
+            oscillator=dict(lattice_shape="saw", lattice_stretch=1.0),
+            envelope=dict(attack=0.001, decay=0.3, sustain=0.0, release=0.1, hold=0.0),
+            consonance_filter=None,
+            filter_cutoff=800.0,
+            reverb_wet=0.0,
+        ),
+        "piano_ballad": dict(
+            oscillator=dict(lattice_shape="triangle", lattice_stretch=1.002),
+            envelope=dict(attack=0.008, decay=0.5, sustain=0.4, release=0.8, hold=0.0),
+            consonance_filter=dict(cutoff=0.6, resonance=0.8),
+            filter_cutoff=4000.0,
+            reverb_wet=0.5,
+        ),
+        "808_kick": dict(
+            oscillator=dict(lattice_shape="sine", lattice_stretch=1.0),
+            envelope=dict(attack=0.001, decay=0.0, sustain=1.0, release=0.35, hold=0.0),
+            consonance_filter=None,
+            filter_cutoff=400.0,
+            reverb_wet=0.0,
+        ),
+    }
+
+    @classmethod
+    def from_preset(cls, name: str) -> "ConstraintSynth":
+        """Create a ConstraintSynth from a named preset."""
+        if name not in cls.PRESETS:
+            raise ValueError(f"Unknown preset '{name}'. Available: {list(cls.PRESETS)}")
+        cfg = cls.PRESETS[name]
+        osc = LatticeOscillator(**cfg["oscillator"])
+        env = FunnelEnvelope(**cfg["envelope"])
+        filt = ConsonanceFilter(**cfg["consonance_filter"]) if cfg.get("consonance_filter") else None
+        return cls(oscillator=osc, envelope=env, filter=filt,
+                   filter_cutoff=cfg["filter_cutoff"], reverb_wet=cfg["reverb_wet"])
+
+    @staticmethod
+    def _crossfade(tail: np.ndarray, head: np.ndarray, samples: int = 64) -> tuple[np.ndarray, np.ndarray]:
+        """Apply a short crossfade between the tail of one note and the head of the next."""
+        samples = min(samples, len(tail), len(head))
+        if samples <= 0:
+            return tail, head
+        fade_out = np.linspace(1, 0, samples)
+        fade_in = np.linspace(0, 1, samples)
+        tail[-samples:] *= fade_out
+        head[:samples] = (head[:samples] * fade_in) + (tail[-samples:] * (1 - fade_in))
+        return tail, head
+
+    def render_melody(
+        self,
+        notes: list[tuple[int, int, float]],  # (pitch, velocity, duration)
+        spacing: float = 0.05,
+        crossfade_samples: int = 64,
+    ) -> np.ndarray:
+        """Render a sequence of notes into a single audio buffer."""
+        buffers: list[np.ndarray] = []
+        for pitch, velocity, duration in notes:
+            note = self.play_note(pitch, velocity, duration)
+            # Crossfade with previous note to avoid click artifacts at boundaries
+            if buffers and crossfade_samples > 0:
+                prev = buffers[-1]
+                prev, note = self._crossfade(prev, note, crossfade_samples)
+                buffers[-1] = prev
+            buffers.append(note)
+            if spacing > 0:
+                silence = np.zeros(int(self.oscillator.sample_rate * spacing))
+                buffers.append(silence)
+        return np.concatenate(buffers) if buffers else np.array([])
+
+    @staticmethod
+    def to_wav(signal: np.ndarray, path: str, sample_rate: int = 44100) -> None:
+        """Save a numpy array as a 16-bit WAV file (mono or stereo)."""
+        signal = np.clip(signal, -1.0, 1.0)
+        if signal.ndim == 1:
+            nchannels = 1
+            data = (signal * 32767).astype(np.int16)
+        else:
+            # shape (N, 2) for stereo
+            nchannels = signal.shape[1]
+            data = (signal * 32767).astype(np.int16)
+        with wave.open(path, "w") as f:
+            f.setnchannels(nchannels)
+            f.setsampwidth(2)
+            f.setframerate(sample_rate)
+            f.writeframes(data.tobytes())

constraint_synth-0.1.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: constraint-synth
+Version: 0.1.0
+Summary: Constraint-theory synthesizer prototype — waveshape as lattice geometry
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"

constraint_synth-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+constraint_synth/__init__.py,sha256=DRzeWNueewH_BOt7kjIxabwrI9lPjaesaHlLEghaPvA,531
+constraint_synth/constraint_filter.py,sha256=ZjDUM_K8Y_gQr5c8iWsMek6cYcCuqvn9QYGWYc3xiO0,1645
+constraint_synth/envelope.py,sha256=qHCL8uXdEiKDw-wtnOzcNH3gyJM5juUHNWpiPvA1pH4,2519
+constraint_synth/flux_bridge.py,sha256=FErJpl_pdzVF3v0Jof8IOo_aFtTpIu0u1faGjYAgLAU,18915
+constraint_synth/midi_renderer.py,sha256=XFRifFc1GllSuIiQw7FKhdt_gU-CZ2OHyPcYQlN4wI0,6697
+constraint_synth/oscillator.py,sha256=Rt1oBrwrXR1liTORTEjUQXwj-dCiM0AnSdajyd050Zs,5253
+constraint_synth/playback.py,sha256=mKadFhkiHVdkexBs24E-FiNZw4Xps_OQmKU9vJIl8fI,1951
+constraint_synth/synth.py,sha256=jwjyQKpUWo9mr2SgjFh_3H59-hgLVV2AR4lCnyMbvjM,9588
+constraint_synth-0.1.0.dist-info/METADATA,sha256=-TG-3ifRRKOOcjpnglIISgCnKgB7a_nu_YU1AgkQmKI,257
+constraint_synth-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+constraint_synth-0.1.0.dist-info/top_level.txt,sha256=81a-bO4roFt5nqNIloBStP-nRorH3JLEZYYE0G12lHU,17
+constraint_synth-0.1.0.dist-info/RECORD,,

constraint_synth-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

constraint_synth-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+constraint_synth