prototype.py

"""
prototype.py — Python mirror of engine.js

Exact same logic as the JS engine, in Python. Use this to:
  - Understand and reason about the sequencer before touching Max
  - Prototype new generative algorithms (Markov chains, etc.) cleanly
  - Verify behaviour with the test suite below

Run directly:  python prototype.py
"""

import random
from dataclasses import dataclass, field
from typing import Optional
from copy import deepcopy


NUM_TRACKS = 8
NUM_STEPS  = 16

DEFAULT_NOTES = [36, 37, 38, 39, 40, 41, 42, 43]
TRACK_NAMES   = ["Kick", "Snare", "Clap", "HH Closed", "HH Open", "Tom Lo", "Tom Hi", "Perc"]

NOTE_NAMES = {
    36: "Kick", 37: "Snare", 38: "Clap",  39: "HHcl",
    40: "HHop", 41: "TomLo", 42: "TomHi", 43: "Perc"
}


# ─── Data Structures ──────────────────────────────────────────────────────────

@dataclass
class Step:
    active:      bool = False
    velocity:    int  = 100   # 0–127
    probability: int  = 100   # 0–100


@dataclass
class Track:
    midi_note:    int
    name:         str
    steps:        list = field(default_factory=lambda: [Step() for _ in range(NUM_STEPS)])
    length:       int  = NUM_STEPS  # natural loop length (1–16)
    current_step: int  = 0
    muted:        bool = False


# ─── Sequencer ────────────────────────────────────────────────────────────────

class Sequencer:
    def __init__(self):
        self.tracks: list[Track] = [
            Track(midi_note=DEFAULT_NOTES[i], name=TRACK_NAMES[i])
            for i in range(NUM_TRACKS)
        ]
        self.loop_start: Optional[int] = None  # None = no loop override
        self.loop_end:   Optional[int] = None

    # ── Clock ──────────────────────────────────────────────────────────────

    def tick(self) -> list[tuple[int, int, str]]:
        """
        Advance one clock step.
        Returns list of (midi_note, velocity, track_name) for notes fired this tick.
        """
        fired = []

        for track in self.tracks:
            if track.muted:
                continue
            step = track.steps[track.current_step]
            if step.active and random.randint(0, 99) < step.probability:
                fired.append((track.midi_note, step.velocity, track.name))

        self._advance_steps()
        return fired

    def _advance_steps(self):
        for track in self.tracks:
            if self.loop_start is not None and self.loop_end is not None:
                region_len = self.loop_end - self.loop_start + 1
                track.current_step = (
                    self.loop_start
                    + ((track.current_step - self.loop_start + 1) % region_len)
                )
            else:
                track.current_step = (track.current_step + 1) % track.length

    # ── Performance Controls ───────────────────────────────────────────────

    def jump_to_step(self, step: int):
        """Snap all track playheads to a specific step."""
        step = max(0, min(NUM_STEPS - 1, step))
        for track in self.tracks:
            track.current_step = step

    def set_loop(self, start: int, end: int):
        """
        Define a loop override region. All tracks cycle within [start, end]
        regardless of their natural length, until clear_loop() is called.
        """
        if start > end:
            start, end = end, start
        self.loop_start = max(0, min(NUM_STEPS - 1, start))
        self.loop_end   = max(0, min(NUM_STEPS - 1, end))
        # Clamp out-of-region playheads
        for track in self.tracks:
            if track.current_step < self.loop_start or track.current_step > self.loop_end:
                track.current_step = self.loop_start

    def clear_loop(self):
        """Release loop override. Tracks return to independent natural lengths."""
        self.loop_start = None
        self.loop_end   = None

    def reset(self):
        """Reset all playheads to step 0."""
        for track in self.tracks:
            track.current_step = 0

    # ── Step Editing ───────────────────────────────────────────────────────

    def set_step(self, track_idx: int, step_idx: int, *,
                 active: bool = None,
                 velocity: int = None,
                 probability: int = None):
        step = self.tracks[track_idx].steps[step_idx]
        if active      is not None: step.active      = active
        if velocity    is not None: step.velocity     = max(0, min(127, velocity))
        if probability is not None: step.probability  = max(0, min(100, probability))

    # ── Track Configuration ────────────────────────────────────────────────

    def set_track_length(self, track_idx: int, length: int):
        track = self.tracks[track_idx]
        track.length = max(1, min(NUM_STEPS, length))
        if track.current_step >= track.length:
            track.current_step = track.current_step % track.length

    def set_track_mute(self, track_idx: int, muted: bool):
        self.tracks[track_idx].muted = muted

    def set_track_note(self, track_idx: int, note: int):
        self.tracks[track_idx].midi_note = max(0, min(127, note))

    # ── State ──────────────────────────────────────────────────────────────

    def get_state(self) -> dict:
        return {
            "positions": [t.current_step for t in self.tracks],
            "lengths":   [t.length       for t in self.tracks],
            "loop":      (self.loop_start, self.loop_end),
        }

    # ── Visualization ──────────────────────────────────────────────────────

    def render_grid(self) -> str:
        """
        ASCII grid of the current pattern.
        Active steps shown as '●', inactive as '·'.
        Current playhead position shown as '▶' (active) or '○' (inactive).
        Steps outside the track's natural length shown as '░'.
        """
        lines = []
        header = "     " + "".join(f"{i+1:>3}" for i in range(NUM_STEPS))
        lines.append(header)
        lines.append("     " + "─" * (NUM_STEPS * 3))

        loop_marker = ""
        if self.loop_start is not None:
            loop_row = "     "
            for i in range(NUM_STEPS):
                if i == self.loop_start:
                    loop_row += "  ["
                elif i == self.loop_end:
                    loop_row += "  ]"
                elif self.loop_start < i < self.loop_end:
                    loop_row += "───"
                else:
                    loop_row += "   "
            loop_marker = loop_row

        for t, track in enumerate(self.tracks):
            row = f"{track.name[:5]:>5} "
            for s in range(NUM_STEPS):
                step = track.steps[s]
                is_current = (track.current_step == s)
                in_range   = (s < track.length)

                if not in_range:
                    sym = "░"
                elif is_current and step.active:
                    sym = "▶"
                elif is_current:
                    sym = "○"
                elif step.active:
                    sym = "●"
                else:
                    sym = "·"
                row += f"  {sym}"
            row += f"  (len={track.length})"
            lines.append(row)

        if loop_marker:
            lines.append(loop_marker + "  ← loop region")

        return "\n".join(lines)


# ─── Tests ────────────────────────────────────────────────────────────────────

def test_basic_advance():
    """Steps advance correctly in free mode."""
    seq = Sequencer()
    seq.set_track_length(0, 4)

    positions = []
    for _ in range(8):
        seq.tick()
        positions.append(seq.tracks[0].current_step)

    # Should cycle: 1, 2, 3, 0, 1, 2, 3, 0
    assert positions == [1, 2, 3, 0, 1, 2, 3, 0], f"Got {positions}"
    print("✓ test_basic_advance")


def test_independent_lengths():
    """Tracks with different lengths advance independently (polyrhythm)."""
    seq = Sequencer()
    seq.set_track_length(0, 3)   # cycles every 3
    seq.set_track_length(1, 4)   # cycles every 4

    t0_positions = []
    t1_positions = []
    for _ in range(12):
        seq.tick()
        t0_positions.append(seq.tracks[0].current_step)
        t1_positions.append(seq.tracks[1].current_step)

    # Track 0 (len=3): 1,2,0,1,2,0,1,2,0,1,2,0
    assert t0_positions == [1,2,0,1,2,0,1,2,0,1,2,0], f"T0: {t0_positions}"
    # Track 1 (len=4): 1,2,3,0,1,2,3,0,1,2,3,0
    assert t1_positions == [1,2,3,0,1,2,3,0,1,2,3,0], f"T1: {t1_positions}"
    print("✓ test_independent_lengths")


def test_loop_override():
    """Loop override constrains all tracks to [start, end] region."""
    seq = Sequencer()
    seq.set_track_length(0, 3)   # would normally cycle at 3
    seq.set_track_length(1, 7)   # would normally cycle at 7

    seq.jump_to_step(4)          # start everyone at step 4
    seq.set_loop(4, 7)           # lock to steps 4–7 (4-step region)

    t0_positions = []
    t1_positions = []
    for _ in range(8):
        seq.tick()
        t0_positions.append(seq.tracks[0].current_step)
        t1_positions.append(seq.tracks[1].current_step)

    # Both tracks should cycle within [4,7]: 5,6,7,4,5,6,7,4
    expected = [5, 6, 7, 4, 5, 6, 7, 4]
    assert t0_positions == expected, f"T0: {t0_positions}"
    assert t1_positions == expected, f"T1: {t1_positions}"
    print("✓ test_loop_override")


def test_loop_release():
    """After clear_loop, tracks return to independent natural lengths."""
    seq = Sequencer()
    seq.set_track_length(0, 3)
    seq.set_track_length(1, 5)

    seq.jump_to_step(0)
    seq.set_loop(0, 3)

    for _ in range(4):  # advance inside loop
        seq.tick()

    seq.clear_loop()

    # After release, track 0 (len=3) and track 1 (len=5) should diverge again
    t0_before = seq.tracks[0].current_step
    t1_before = seq.tracks[1].current_step
    for _ in range(6):
        seq.tick()
    t0_after = seq.tracks[0].current_step
    t1_after = seq.tracks[1].current_step

    assert t0_after != t1_after or t0_before == t1_before, \
        "Tracks should diverge after loop release"
    print("✓ test_loop_release")


def test_jump_to_step():
    """jumpToStep snaps all playheads to the target."""
    seq = Sequencer()
    seq.set_track_length(0, 3)
    seq.set_track_length(1, 7)
    seq.set_track_length(2, 11)

    for _ in range(5):  # advance to diverge them
        seq.tick()

    seq.jump_to_step(8)
    for t in seq.tracks:
        assert t.current_step == 8, f"Expected 8, got {t.current_step}"
    print("✓ test_jump_to_step")


def test_probability():
    """Probability=0 never fires; probability=100 always fires."""
    seq = Sequencer()
    seq.set_step(0, 0, active=True, probability=0)
    seq.set_step(1, 0, active=True, probability=100)

    fires_0 = 0
    fires_1 = 0
    for _ in range(200):
        seq.jump_to_step(0)
        notes = seq.tick()
        for note, vel, name in notes:
            if note == seq.tracks[0].midi_note:
                fires_0 += 1
            if note == seq.tracks[1].midi_note:
                fires_1 += 1

    assert fires_0 == 0,   f"prob=0 fired {fires_0} times"
    assert fires_1 == 200, f"prob=100 fired {fires_1}/200 times"
    print("✓ test_probability")


# ─── Demo: Polyrhythmic Drum Pattern ──────────────────────────────────────────

def demo_polyrhythm():
    """
    A classic polyrhythmic pattern demonstrating independent track lengths.
    Shows the grid and simulates 32 ticks, then demonstrates loop override.
    """
    random.seed(42)
    seq = Sequencer()

    # Kick: 4-on-the-floor across 16 steps
    seq.set_track_length(0, 16)
    for i in [0, 4, 8, 12]:
        seq.set_step(0, i, active=True, velocity=127)

    # Snare: beats 2 and 4
    seq.set_track_length(1, 16)
    for i in [4, 12]:
        seq.set_step(1, i, active=True, velocity=110)

    # Clap: syncopated, short loop (5 steps → creates metric drift)
    seq.set_track_length(2, 5)
    for i in [0, 3]:
        seq.set_step(2, i, active=True, velocity=95)

    # HH Closed: every 2 steps, 8-step loop (standard 8th notes)
    seq.set_track_length(3, 8)
    for i in range(0, 8, 2):
        seq.set_step(3, i, active=True, velocity=75)

    # HH Open: sparse, 6-step loop
    seq.set_track_length(4, 6)
    seq.set_step(4, 5, active=True, velocity=90)

    # Tom Lo: 3-step euclidean-style
    seq.set_track_length(5, 3)
    seq.set_step(5, 0, active=True, velocity=100)

    # Perc: 7-step loop with 70% probability (introduces variation)
    seq.set_track_length(7, 7)
    for i in [0, 2, 4]:
        seq.set_step(7, i, active=True, probability=70, velocity=85)

    print("\n" + "=" * 60)
    print("INITIAL PATTERN GRID")
    print("=" * 60)
    print(seq.render_grid())

    print("\n" + "=" * 60)
    print("SIMULATING 32 TICKS (free polyrhythm)")
    print("=" * 60)
    for tick in range(32):
        notes = seq.tick()
        bar   = "│" + "░" * tick + " " * (31 - tick) + "│"
        fired = " ".join(n[2][:4] for n in notes) if notes else "·"
        print(f"  tick {tick:02d}  {bar}  {fired}")

    print("\n" + "=" * 60)
    print("ENGAGING LOOP OVERRIDE: steps 0–3 (one-bar drop)")
    print("=" * 60)
    seq.jump_to_step(0)
    seq.set_loop(0, 3)
    print(seq.render_grid())

    for tick in range(8):
        notes = seq.tick()
        fired = " ".join(n[2][:4] for n in notes) if notes else "·"
        print(f"  tick {tick:02d} [LOOP]  {fired}")

    print("\n" + "=" * 60)
    print("RELEASING LOOP — tracks return to natural lengths")
    print("=" * 60)
    seq.clear_loop()
    for tick in range(8):
        notes = seq.tick()
        fired = " ".join(n[2][:4] for n in notes) if notes else "·"
        print(f"  tick {tick:02d}           {fired}")

    print()


# ─── Entry Point ──────────────────────────────────────────────────────────────

if __name__ == "__main__":
    print("Running tests...")
    test_basic_advance()
    test_independent_lengths()
    test_loop_override()
    test_loop_release()
    test_jump_to_step()
    test_probability()
    print("\nAll tests passed.\n")
    demo_polyrhythm()