livepilot 1.6.4 → 1.7.0

package/mcp_server/tools/harmony.py

@@ -0,0 +1,253 @@
+"""Neo-Riemannian harmony tools — Tonnetz navigation, voice-leading paths,
+progression classification, chromatic mediant suggestions.
+
+4 tools for advanced harmonic analysis and exploration.
+Pure computation — no Ableton connection needed.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import _harmony_engine as harmony
+from . import _theory_engine as theory
+
+
+def _ensure_list(value: Any) -> list:
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+# -- Tool 1: navigate_tonnetz ------------------------------------------------
+
+@mcp.tool()
+def navigate_tonnetz(
+    ctx: Context,
+    chord: str,
+    depth: int = 1,
+) -> dict:
+    """Show neo-Riemannian neighbors of a chord on the Tonnetz.
+
+    P (Parallel) flips the third: C major → C minor.
+    L (Leading-tone) shifts by semitone: C major → E minor.
+    R (Relative) shifts by whole tone: C major → A minor.
+
+    Use depth 2-3 to see compound transforms (PL, PR, PRL, etc.).
+    """
+    if not 1 <= depth <= 3:
+        return {"error": "depth must be 1-3"}
+    try:
+        root_pc, quality = harmony.parse_chord(chord)
+    except ValueError as e:
+        return {"error": str(e)}
+
+    all_neighbors = harmony.get_neighbors(root_pc, quality, depth)
+
+    descriptions = {
+        "P": "flip third (Parallel)",
+        "L": "shift by semitone (Leading-tone)",
+        "R": "shift by whole tone (Relative)",
+    }
+
+    depth_1 = {}
+    for label in ("P", "L", "R"):
+        if label in all_neighbors:
+            r, q = all_neighbors[label]
+            depth_1[label] = {
+                "chord": harmony.chord_to_str(r, q),
+                "transform": label,
+                "description": descriptions[label],
+            }
+
+    result: dict = {"chord": chord, "neighbors": depth_1}
+
+    if depth >= 2:
+        depth_2 = {}
+        for key, (r, q) in all_neighbors.items():
+            if len(key) == 2:
+                depth_2[key] = {
+                    "chord": harmony.chord_to_str(r, q),
+                    "transforms": key,
+                }
+        result["depth_2"] = depth_2
+
+    if depth >= 3:
+        depth_3 = {}
+        for key, (r, q) in all_neighbors.items():
+            if len(key) == 3:
+                depth_3[key] = {
+                    "chord": harmony.chord_to_str(r, q),
+                    "transforms": key,
+                }
+        result["depth_3"] = depth_3
+
+    return result
+
+
+# -- Tool 2: find_voice_leading_path -----------------------------------------
+
+@mcp.tool()
+def find_voice_leading_path(
+    ctx: Context,
+    from_chord: str,
+    to_chord: str,
+    max_steps: int = 4,
+) -> dict:
+    """Find the shortest neo-Riemannian path between two chords.
+
+    Returns each intermediate chord and the specific voice movements.
+    This is the 'film score progression finder' — chromatic mediants,
+    hexatonic poles, and other cinematic chord moves.
+    """
+    if not 1 <= max_steps <= 6:
+        return {"error": "max_steps must be 1-6"}
+    try:
+        from_parsed = harmony.parse_chord(from_chord)
+        to_parsed = harmony.parse_chord(to_chord)
+    except ValueError as e:
+        return {"error": str(e)}
+
+    result = harmony.find_shortest_path(from_parsed, to_parsed, max_steps)
+
+    if not result["found"]:
+        return {
+            "from": from_chord,
+            "to": to_chord,
+            "found": False,
+            "steps": -1,
+            "path": [],
+            "transforms": [],
+            "voice_leading": [],
+        }
+
+    path_strs = [harmony.chord_to_str(*c) for c in result["path"]]
+    voice_leading = []
+    for i in range(len(result["path"]) - 1):
+        from_midi = harmony.chord_to_midi(*result["path"][i])
+        to_midi = harmony.chord_to_midi(*result["path"][i + 1])
+        movements = []
+        for f, t in zip(from_midi, to_midi):
+            if f != t:
+                movements.append(f"{theory.pitch_name(f)}→{theory.pitch_name(t)}")
+        voice_leading.append({
+            "from": from_midi,
+            "to": to_midi,
+            "movement": ", ".join(movements) if movements else "no movement",
+        })
+
+    return {
+        "from": from_chord,
+        "to": to_chord,
+        "found": True,
+        "steps": result["steps"],
+        "path": path_strs,
+        "transforms": result["transforms"],
+        "voice_leading": voice_leading,
+    }
+
+
+# -- Tool 3: classify_progression --------------------------------------------
+
+@mcp.tool()
+def classify_progression(
+    ctx: Context,
+    chords: Any,
+) -> dict:
+    """Classify a chord progression by its neo-Riemannian transform pattern.
+
+    Identifies hexatonic cycles (PL), octatonic cycles (PR), diatonic
+    cycles (LR), and other known patterns. Pairs with analyze_harmony
+    to understand why a progression sounds 'cinematic' or 'otherworldly'.
+    """
+    chords = _ensure_list(chords)
+    if len(chords) < 2:
+        return {"error": "Need at least 2 chords to classify"}
+
+    try:
+        parsed = [harmony.parse_chord(c) for c in chords]
+    except ValueError as e:
+        return {"error": str(e)}
+
+    transforms = harmony.classify_transform_sequence(parsed)
+    pattern = "".join(transforms)
+
+    classification = "free neo-Riemannian progression"
+    notable_usage = None
+    clean = pattern.replace("?", "")
+
+    if len(clean) >= 2:
+        pair = clean[:2]
+        if pair in ("PL", "LP") and all(c in "PL" for c in clean):
+            classification = "hexatonic cycle fragment"
+            notable_usage = "Radiohead, film scores (Zimmer, Howard)"
+        elif pair in ("PR", "RP") and all(c in "PR" for c in clean):
+            classification = "octatonic cycle fragment"
+            notable_usage = "late Romantic (Wagner, Strauss), horror film scores"
+        elif pair in ("LR", "RL") and all(c in "LR" for c in clean):
+            classification = "diatonic cycle fragment"
+            notable_usage = "functional harmony, common in classical and pop"
+
+    if len(clean) == 1:
+        names = {"P": "parallel transform", "L": "leading-tone transform",
+                 "R": "relative transform"}
+        classification = names.get(clean, classification)
+
+    return {
+        "chords": chords,
+        "transforms": transforms,
+        "pattern": pattern,
+        "classification": classification,
+        "notable_usage": notable_usage,
+    }
+
+
+# -- Tool 4: suggest_chromatic_mediants --------------------------------------
+
+@mcp.tool()
+def suggest_chromatic_mediants(
+    ctx: Context,
+    chord: str,
+) -> dict:
+    """Suggest all chromatic mediant relations for a chord.
+
+    Chromatic mediants are chords a major/minor third away — they share
+    0-1 common tones, creating maximum color shift with minimal voice movement.
+    Includes 'cinematic picks' highlighting the most film-score-friendly options.
+    """
+    try:
+        root_pc, quality = harmony.parse_chord(chord)
+    except ValueError as e:
+        return {"error": str(e)}
+
+    mediants = harmony.get_chromatic_mediants(root_pc, quality)
+
+    chord_pcs = set(harmony.chord_to_midi(root_pc, quality))
+    formatted = {}
+    for key, (r, q) in mediants.items():
+        mediant_pcs = set(harmony.chord_to_midi(r, q))
+        common = len(chord_pcs & mediant_pcs)
+        formatted[key] = {
+            "chord": harmony.chord_to_str(r, q),
+            "common_tones": common,
+            "relation": key.replace("_", " "),
+        }
+
+    cinematic = [
+        harmony.chord_to_str(*mediants["lower_major_third"]),
+        harmony.chord_to_str(*mediants["upper_major_third"]),
+    ]
+
+    return {
+        "chord": chord,
+        "chromatic_mediants": formatted,
+        "cinematic_picks": cinematic,
+        "explanation": (
+            "Chromatic mediants share 0-1 common tones with the original chord. "
+            "Maximum color shift with minimal voice movement — the 'epic' sound."
+        ),
+    }

package/mcp_server/tools/midi_io.py

@@ -0,0 +1,305 @@
+"""MIDI file I/O tools — export, import, analyze, piano roll.
+
+4 tools bridging LivePilot's session clips with .mid files.
+Tools 1-2 require Ableton connection. Tools 3-4 are offline-capable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import statistics
+from pathlib import Path
+from typing import Any, Optional
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import _theory_engine as theory
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+def _require_midiutil():
+    try:
+        from midiutil import MIDIFile
+        return MIDIFile
+    except ImportError:
+        raise ImportError(
+            "midiutil is required for MIDI export. "
+            "Install with: pip install midiutil"
+        )
+
+
+def _require_pretty_midi():
+    try:
+        import pretty_midi
+        return pretty_midi
+    except ImportError:
+        raise ImportError(
+            "pretty-midi is required for this tool. "
+            "Install with: pip install pretty-midi"
+        )
+
+
+def _output_dir() -> Path:
+    d = Path.home() / "Documents" / "LivePilot" / "outputs" / "midi"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _validate_midi_path(file_path: str) -> Path:
+    p = Path(file_path)
+    if not p.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+    if p.suffix.lower() not in (".mid", ".midi"):
+        raise ValueError(f"Not a MIDI file: {file_path}")
+    return p
+
+
+# -- Tool 1: export_clip_midi ------------------------------------------------
+
+@mcp.tool()
+def export_clip_midi(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    filename: Optional[str] = None,
+) -> dict:
+    """Export a session clip's notes to a .mid file.
+
+    Fetches notes from the clip and writes them to a standard MIDI file.
+    Auto-generates filename from track/clip if not provided.
+    """
+    MIDIFile = _require_midiutil()
+    ableton = _get_ableton(ctx)
+
+    notes_result = ableton.send_command("get_notes", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+    notes = notes_result.get("notes", [])
+
+    session = ableton.send_command("get_session_info", {})
+    tempo = float(session.get("tempo", 120.0))
+
+    if not filename:
+        filename = f"track{track_index}_clip{clip_index}.mid"
+    if not filename.endswith((".mid", ".midi")):
+        filename += ".mid"
+
+    out_path = _output_dir() / filename
+
+    midi = MIDIFile(1)
+    midi.addTempo(0, 0, tempo)
+
+    duration_beats = 0.0
+    for n in notes:
+        start = float(n["start_time"])
+        dur = float(n["duration"])
+        pitch = int(n["pitch"])
+        vel = int(n.get("velocity", 100))
+        midi.addNote(0, 0, pitch, start, dur, vel)
+        duration_beats = max(duration_beats, start + dur)
+
+    with open(out_path, "wb") as f:
+        midi.writeFile(f)
+
+    return {
+        "file_path": str(out_path),
+        "note_count": len(notes),
+        "duration_beats": round(duration_beats, 4),
+        "tempo": tempo,
+    }
+
+
+# -- Tool 2: import_midi_to_clip ---------------------------------------------
+
+@mcp.tool()
+def import_midi_to_clip(
+    ctx: Context,
+    file_path: str,
+    track_index: int,
+    clip_index: int,
+    create_clip: bool = True,
+) -> dict:
+    """Load a .mid file into a session clip.
+
+    Reads MIDI, converts timing to beats using session tempo, and writes
+    notes into the target clip slot. Creates the clip if needed.
+    """
+    pretty_midi = _require_pretty_midi()
+    ableton = _get_ableton(ctx)
+
+    path = _validate_midi_path(file_path)
+    pm = pretty_midi.PrettyMIDI(str(path))
+
+    session = ableton.send_command("get_session_info", {})
+    tempo = float(session.get("tempo", 120.0))
+
+    notes_raw = []
+    for inst in pm.instruments:
+        for n in inst.notes:
+            start_beat = round(n.start * (tempo / 60.0), 3)
+            dur_beat = round((n.end - n.start) * (tempo / 60.0), 3)
+            notes_raw.append({
+                "pitch": n.pitch,
+                "start_time": start_beat,
+                "duration": max(dur_beat, 0.001),
+                "velocity": n.velocity,
+            })
+
+    seen = set()
+    notes = []
+    for n in notes_raw:
+        key = (n["pitch"], round(n["start_time"], 3), round(n["duration"], 3))
+        if key not in seen:
+            seen.add(key)
+            notes.append(n)
+
+    notes = notes[:2000]
+
+    duration_beats = max((n["start_time"] + n["duration"] for n in notes),
+                         default=4.0)
+
+    if create_clip:
+        ableton.send_command("create_clip", {
+            "track_index": track_index,
+            "clip_index": clip_index,
+            "length": round(duration_beats, 2),
+        })
+
+    if notes:
+        ableton.send_command("add_notes", {
+            "track_index": track_index,
+            "clip_index": clip_index,
+            "notes": notes,
+        })
+
+    return {
+        "note_count": len(notes),
+        "duration_beats": round(duration_beats, 4),
+        "tempo_source": tempo,
+    }
+
+
+# -- Tool 3: analyze_midi_file -----------------------------------------------
+
+@mcp.tool()
+def analyze_midi_file(
+    ctx: Context,
+    file_path: str,
+) -> dict:
+    """Analyze a .mid file — works offline, no Ableton needed.
+
+    Returns note count, duration, tempo, pitch range, instruments,
+    velocity stats, density curve, and estimated key.
+    """
+    pretty_midi = _require_pretty_midi()
+    path = _validate_midi_path(file_path)
+    pm = pretty_midi.PrettyMIDI(str(path))
+
+    all_notes = []
+    for inst in pm.instruments:
+        for n in inst.notes:
+            all_notes.append(n)
+
+    if not all_notes:
+        return {
+            "note_count": 0,
+            "duration_seconds": round(pm.get_end_time(), 2),
+            "tempo_estimates": list(pm.get_tempo_changes()[1]),
+            "pitch_range": [0, 0],
+            "instruments": [i.name for i in pm.instruments],
+            "velocity_stats": {},
+            "density_curve": [],
+            "key_estimate": "unknown",
+        }
+
+    pitches = [n.pitch for n in all_notes]
+    velocities = [n.velocity for n in all_notes]
+    duration = pm.get_end_time()
+
+    density_curve = []
+    window = 1.0
+    t = 0.0
+    while t < duration:
+        count = sum(1 for n in all_notes if t <= n.start < t + window)
+        density_curve.append({
+            "time": round(t, 1),
+            "density": count / window,
+        })
+        t += window
+
+    notes_for_key = [
+        {"pitch": n.pitch, "duration": n.end - n.start}
+        for n in all_notes
+    ]
+    key_result = theory.detect_key(notes_for_key)
+    key_str = f"{key_result['tonic_name']} {key_result['mode']}"
+
+    vel_stats = {
+        "mean": round(statistics.mean(velocities), 1),
+        "min": min(velocities),
+        "max": max(velocities),
+        "std": round(statistics.stdev(velocities), 1) if len(velocities) > 1 else 0.0,
+    }
+
+    return {
+        "note_count": len(all_notes),
+        "duration_seconds": round(duration, 2),
+        "tempo_estimates": [round(t, 1) for t in pm.get_tempo_changes()[1]],
+        "pitch_range": [min(pitches), max(pitches)],
+        "instruments": [i.name for i in pm.instruments],
+        "velocity_stats": vel_stats,
+        "density_curve": density_curve,
+        "key_estimate": key_str,
+    }
+
+
+# -- Tool 4: extract_piano_roll ----------------------------------------------
+
+@mcp.tool()
+def extract_piano_roll(
+    ctx: Context,
+    file_path: str,
+    resolution: float = 0.125,
+) -> dict:
+    """Extract a 2D piano roll matrix from a .mid file. Offline-capable.
+
+    Returns a velocity matrix [pitch_index][time_step] trimmed to
+    the actual pitch range. Resolution is in beats (0.125 = 32nd note).
+    """
+    pretty_midi = _require_pretty_midi()
+    path = _validate_midi_path(file_path)
+    pm = pretty_midi.PrettyMIDI(str(path))
+
+    tempo_changes = pm.get_tempo_changes()
+    tempo = float(tempo_changes[1][0]) if len(tempo_changes[1]) > 0 else 120.0
+    fs = (tempo / 60.0) / resolution
+
+    roll = pm.get_piano_roll(fs=fs)  # shape (128, T)
+
+    active_pitches = roll.sum(axis=1).nonzero()[0]
+    if len(active_pitches) == 0:
+        return {
+            "piano_roll": [],
+            "pitch_min": 0,
+            "pitch_max": 0,
+            "time_steps": 0,
+            "resolution": resolution,
+        }
+
+    pitch_min = int(active_pitches[0])
+    pitch_max = int(active_pitches[-1])
+    trimmed = roll[pitch_min:pitch_max + 1, :]
+
+    return {
+        "piano_roll": trimmed.astype(int).tolist(),
+        "pitch_min": pitch_min,
+        "pitch_max": pitch_max,
+        "time_steps": int(trimmed.shape[1]),
+        "resolution": resolution,
+    }