livepilot 1.14.1 → 1.16.0

package/remote_script/LivePilot/_clip_helpers.py

@@ -0,0 +1,86 @@
+"""Pure-Python helpers for clip-length and note-range invariants.
+
+Importable outside Ableton (no `_Framework` dependency, no `import Live`).
+The main `clips.py` and `notes.py` modules re-import these helpers so
+both the live handler and the contract tests run identical logic.
+
+Bug context: `clip_slot.create_clip(length)` in Live 12 sets the clip's
+*length* but defaults `loop_end` to length/2 in some configurations
+(depends on time signature defaults). Downstream tools that add notes
+beyond the implicit half-length loop see them silently dropped — silent
+data corruption. These helpers centralize the "loop_end must equal
+intent" rule so it can't drift back.
+"""
+
+from __future__ import annotations
+
+
+def _required_loop_end(notes) -> float:
+    """Return the largest start_time + duration across the notes list.
+
+    Pure function. Used by `add_notes` to decide whether to extend the
+    clip's loop_end before adding the notes — Live silently drops notes
+    that fall outside [loop_start, loop_end).
+
+    Returns 0.0 for an empty list. Defensively treats missing duration
+    as 0 so a malformed note (start_time only) doesn't raise.
+    """
+    if not notes:
+        return 0.0
+    return max(
+        float(n.get("start_time", 0.0)) + float(n.get("duration", 0.0))
+        for n in notes
+    )
+
+
+def _apply_clip_length_invariants(clip, length: float) -> dict:
+    """Force a freshly-created clip's loop_end + end_marker to match length.
+
+    Mutates `clip` in place. Returns a dict suitable for inclusion in a
+    handler response (`{loop_end, end_marker}`). Catches AttributeError
+    and RuntimeError defensively — some Live builds enforce
+    `loop_end <= sample_length` on audio clips, but for MIDI this should
+    always succeed. On failure, returns the actual current values so the
+    caller can surface the discrepancy.
+    """
+    try:
+        clip.loop_end = length
+    except (AttributeError, RuntimeError):
+        pass
+    try:
+        clip.end_marker = length
+    except (AttributeError, RuntimeError):
+        pass
+
+    return {
+        "loop_end": getattr(clip, "loop_end", None),
+        "end_marker": getattr(clip, "end_marker", None),
+    }
+
+
+def _extend_loop_end_for_notes(clip, notes) -> float | None:
+    """If any incoming note exceeds clip.loop_end, extend it to fit.
+
+    Returns the new loop_end value if extended, or None if no extension
+    was needed. Also updates `end_marker` to keep them aligned (Live
+    treats end_marker as the "stop reading" marker when looping is off).
+    """
+    required = _required_loop_end(notes)
+    current = getattr(clip, "loop_end", 0.0)
+    if required <= current:
+        return None
+
+    try:
+        clip.loop_end = required
+    except (AttributeError, RuntimeError):
+        return None
+
+    try:
+        # Keep end_marker at least as far out as loop_end. Don't shrink
+        # it if the user has set it further out manually.
+        existing_end = getattr(clip, "end_marker", required)
+        clip.end_marker = max(existing_end, required)
+    except (AttributeError, RuntimeError):
+        pass
+
+    return required

package/remote_script/LivePilot/_drum_helpers.py

@@ -0,0 +1,40 @@
+"""Pure-Python helpers for Drum Rack chain operations.
+
+Importable outside Ableton (no `_Framework` dependency, no `import Live`).
+The main `devices.py` module re-imports these helpers so the live
+handler and contract tests run identical logic.
+
+BUG-2026-04-22 #13 context: Live's `RackDevice.insert_chain()` always
+defaults the new chain's `in_note` to 36 — same as every previous chain.
+Repeated inserts pile up multiple chains on note 36 ("Multi") and they
+can't be triggered independently from a MIDI pattern. The helper here
+picks the next free MIDI slot above any existing chain so each
+insert_rack_chain call lands on a distinct pad.
+"""
+
+from __future__ import annotations
+
+
+def _next_drum_chain_note(device):
+    """Pick the next MIDI note for a new Drum Rack chain.
+
+    Walks existing drum-rack chains, returns max(in_note) + 1 clamped to
+    127. Returns 36 (standard kick slot) if the rack has no chains yet.
+    Returns None if the device is not a drum rack — chains without an
+    `in_note` attribute mean it's an Instrument or Audio Effect Rack,
+    where pad-note assignment doesn't apply.
+
+    Pure function — `device` only needs `.chains` (iterable) and each
+    chain only needs `.in_note` (int). Tests pass plain Python objects.
+    """
+    chains = list(getattr(device, "chains", []) or [])
+    in_notes = []
+    for chain in chains:
+        try:
+            in_notes.append(int(chain.in_note))
+        except (AttributeError, TypeError, ValueError):
+            # Non-drum rack chains don't have in_note — bail.
+            return None
+    if not in_notes:
+        return 36  # standard kick slot for the first chain
+    return min(127, max(in_notes) + 1)

package/remote_script/LivePilot/_scale_helpers.py

@@ -0,0 +1,87 @@
+"""Pure-Python helpers for scale handling — importable outside Ableton.
+
+These helpers are extracted so tests can import them without pulling in
+Live's `_Framework` package (which only exists inside the Ableton
+runtime). The main scales.py module re-imports them.
+
+Nothing here talks to Live's LOM. The `_resolve_scale_names` helper
+takes a `song` argument but only calls `getattr` on it, so duck-typing
+is enough — tests pass a plain object with the right attrs.
+"""
+
+from __future__ import annotations
+
+
+# Live's built-in scale names — stable since 12.0. Used as a final fallback
+# when both `Song.scale_names` and the alternative attribute names are absent
+# (e.g. Live 12.4.0 where `scale_names` attribute was dropped from Python LOM).
+# Source: Live 12 Manual — "Scale Mode" chapter; order matches Live's picker.
+_BUILTIN_SCALES_FALLBACK = [
+    "Major", "Minor", "Dorian", "Mixolydian", "Lydian", "Phrygian",
+    "Locrian", "Whole Tone", "Half-whole Dim.", "Whole-half Dim.",
+    "Minor Blues", "Minor Pentatonic", "Major Pentatonic",
+    "Harmonic Minor", "Harmonic Major", "Dorian #4", "Phrygian Dominant",
+    "Melodic Minor", "Lydian Augmented", "Lydian Dominant",
+    "Super Locrian", "8-Tone Spanish",
+]
+
+
+def _resolve_scale_names(song):
+    """Get Live's available scale names, resilient to 12.4 API changes.
+
+    Probes: song.scale_names, song.available_scale_names, song.get_scale_names()
+    in that order. Falls back to _BUILTIN_SCALES_FALLBACK so callers always
+    get a usable list rather than an AttributeError.
+    """
+    for attr in ("scale_names", "available_scale_names"):
+        try:
+            value = getattr(song, attr, None)
+            if value is not None:
+                return list(value)
+        except Exception:
+            continue
+    for attr in ("get_scale_names", "get_available_scale_names"):
+        try:
+            fn = getattr(song, attr, None)
+            if callable(fn):
+                value = fn()
+                if value is not None:
+                    return list(value)
+        except Exception:
+            continue
+    return list(_BUILTIN_SCALES_FALLBACK)
+
+
+def _coerce_root_note(value):
+    """Accept int 0-11 OR note-name string ('C', 'C#', 'Db', 'F#', etc.)."""
+    if isinstance(value, bool):
+        # bool is a subclass of int in Python — reject explicitly.
+        raise ValueError("root_note cannot be a boolean")
+    if isinstance(value, int):
+        root = value
+    elif isinstance(value, str):
+        s = value.strip()
+        try:
+            root = int(s)
+        except ValueError:
+            name_map = {
+                "C": 0, "C#": 1, "Db": 1, "D": 2, "D#": 3, "Eb": 3,
+                "E": 4, "Fb": 4, "E#": 5, "F": 5, "F#": 6, "Gb": 6,
+                "G": 7, "G#": 8, "Ab": 8, "A": 9, "A#": 10, "Bb": 10,
+                "B": 11, "Cb": 11,
+            }
+            if not s:
+                raise ValueError("root_note string cannot be empty")
+            norm = s[0].upper() + s[1:]
+            if norm not in name_map:
+                raise ValueError(
+                    "Unknown note name '%s'. Use C, C#, Db, D, ..., B." % value
+                )
+            root = name_map[norm]
+    else:
+        raise ValueError(
+            "root_note must be int (0-11) or note name string ('C#', 'F', ...)"
+        )
+    if not 0 <= root <= 11:
+        raise ValueError("root_note must be 0-11 (C=0, C#=1, ... B=11)")
+    return root

package/remote_script/LivePilot/arrangement.py

@@ -608,24 +608,53 @@ def set_arrangement_automation(song, params):
             "method": "direct",
         }
 
-    # No fallback — direct envelope creation is the only safe approach.
-    # Session-clip duplication can silently create overlapping clips.
+    # BUG-2026-04-22#1b: This is a LIVE API LIMITATION, not a LivePilot bug.
     #
-    # Known limitation: clips created via create_arrangement_clip
-    # (duplicate_clip_to_arrangement) often cannot have envelopes
-    # created programmatically. Workaround: record automation by
-    # arming the track and playing back with parameter changes,
-    # or use session-clip automation (set_clip_automation) and then
-    # record the session performance to arrangement.
+    # Per Ableton's Python LOM documentation:
+    #   "Clip.automation_envelope returns None for Arrangement clips
+    #    and parameters from a different track."
+    #
+    # The Python LOM exposes value_at_time() for READING existing
+    # arrangement automation, but does NOT expose a method to CREATE
+    # new automation breakpoints programmatically in the arrangement
+    # view. Automation in arrangement view lives on the track's
+    # automation lane, which is only writable via the GUI or by
+    # recording.
+    #
+    # The two viable workarounds:
+    #
+    # 1. session-clip path (programmatic, but requires manual record):
+    #    a. Use set_clip_automation on a session clip to write the points
+    #    b. Arm the track for recording
+    #    c. Switch to arrangement view and start recording at the target
+    #       position
+    #    d. Fire the session clip — Live records the parameter changes
+    #       into the arrangement automation lane
+    #    e. Stop recording when the session clip completes
+    #
+    # 2. manual draw path (most reliable): the user draws the envelope
+    #    in arrangement view by hand. No code can replace this for now.
+    #
+    # We surface this clearly rather than silently failing or attempting
+    # an unreliable workaround that could leave the session in a half-
+    # configured state.
     raise RuntimeError(
         "Cannot create automation envelope for parameter '%s' on this "
-        "arrangement clip. Direct envelope access is not supported for "
-        "programmatically-created arrangement clips (known Live API limitation). "
-        "Workarounds: "
-        "(1) use set_clip_automation on a session clip instead, then fire "
-        "the scene and record to arrangement; "
-        "(2) use arrangement-level volume/pan fades by creating separate "
-        "clips at different volumes for each section."
+        "arrangement clip. This is a Live LOM limitation, not a "
+        "LivePilot bug: per Ableton's Python API docs, "
+        "Clip.automation_envelope returns None for arrangement clips, "
+        "and the LOM does not expose a method to CREATE new automation "
+        "breakpoints in arrangement view (only value_at_time for "
+        "READING existing automation). "
+        "Two workarounds: "
+        "(1) Session-clip path — call set_clip_automation on a session "
+        "clip with the same points, then arm the track, switch to "
+        "arrangement view, start arrangement record, fire the session "
+        "clip, stop record when it finishes. Live records the parameter "
+        "changes into the arrangement track lane. "
+        "(2) Section-clip path — slice the arrangement into multiple "
+        "clips and set per-clip volume/parameter values per section "
+        "(no envelope, just stepped values per region)."
         % parameter.name
     )
 

package/remote_script/LivePilot/clips.py

@@ -1,11 +1,176 @@
 """
-LivePilot - Clip domain handlers (11 commands).
+LivePilot - Clip domain handlers (12 commands).
 """
 
 from .router import register
 from .utils import get_clip, get_clip_slot
 
 
+# Scratch clip slot used by fire_test_note (BUG-2026-04-22#19). We pick a
+# slot far above the user's usual scene count; a helper reuses/cleans up
+# the slot between calls so no clutter accumulates.
+_TEST_NOTE_SLOT_INDEX = 127  # max scene count is 1024; 127 is safe
+
+
+@register("fire_test_note")
+def fire_test_note(song, params):
+    """Fire a single MIDI note at a track's instrument to verify output.
+
+    Creates a one-note MIDI clip in a scratch slot, fires it, waits for
+    the note duration, then stops + deletes it. No session clutter.
+
+    Required: track_index, midi_note, velocity, duration_ms
+    Returns: {fired: bool, track_index, note, velocity, duration_ms}
+
+    Refuses on audio tracks (no MIDI input) — returns error instead of
+    crashing. Works on any MIDI track with an instrument loaded, including
+    Drum Racks and Instrument Racks.
+    """
+    track_index = int(params["track_index"])
+    midi_note = int(params["midi_note"])
+    velocity = int(params["velocity"])
+    duration_ms = int(params["duration_ms"])
+
+    if not 0 <= midi_note <= 127:
+        raise ValueError("midi_note must be 0-127")
+    if not 1 <= velocity <= 127:
+        raise ValueError("velocity must be 1-127")
+    if duration_ms < 50 or duration_ms > 5000:
+        raise ValueError("duration_ms must be 50-5000")
+
+    tracks = list(song.tracks)
+    if not 0 <= track_index < len(tracks):
+        return {"error": "track_index out of range", "code": "INDEX_ERROR"}
+    track = tracks[track_index]
+
+    if not getattr(track, "has_midi_input", True):
+        return {
+            "error": "Track has no MIDI input — fire_test_note only works "
+                     "on MIDI tracks with an instrument loaded",
+            "code": "INVALID_PARAM",
+        }
+
+    # Use a scratch slot far above the user's usual scene count.
+    clip_slots = list(track.clip_slots)
+    scene_count = len(clip_slots)
+    slot_idx = min(_TEST_NOTE_SLOT_INDEX, scene_count - 1)
+    if slot_idx < 0:
+        return {"error": "No clip slots available", "code": "STATE_ERROR"}
+
+    slot = clip_slots[slot_idx]
+
+    # If the slot already has a clip (unlikely at index 127), delete it
+    # first to avoid stomping on user content.
+    if slot.has_clip:
+        try:
+            slot.delete_clip()
+        except Exception:
+            pass
+
+    # Create a short MIDI clip. Length is in beats — 0.25 beat at any
+    # reasonable tempo is <500ms; we don't rely on clip length for the
+    # note duration, the MCP tool measures real time.
+    song.begin_undo_step()
+    try:
+        slot.create_clip(0.5)
+        clip = slot.clip
+        if clip is None:
+            return {"error": "Failed to create scratch clip", "code": "INTERNAL"}
+
+        # Add the test note. Live 12 modern API: add_new_notes with a
+        # notes_specification struct. Fall back to legacy set_notes.
+        note_length = min(duration_ms / 1000.0, 0.45)  # stay inside the clip
+        if hasattr(clip, "add_new_notes"):
+            spec = _build_notes_spec(midi_note, velocity, note_length)
+            if spec is not None:
+                try:
+                    clip.add_new_notes(spec)
+                except Exception:
+                    _legacy_set_notes(clip, midi_note, velocity, note_length)
+            else:
+                _legacy_set_notes(clip, midi_note, velocity, note_length)
+        else:
+            _legacy_set_notes(clip, midi_note, velocity, note_length)
+
+        # Fire the clip. The MCP caller samples the meter over duration_ms.
+        slot.fire()
+    finally:
+        song.end_undo_step()
+
+    return {
+        "fired": True,
+        "track_index": track_index,
+        "slot_index": slot_idx,
+        "midi_note": midi_note,
+        "velocity": velocity,
+        "duration_ms": duration_ms,
+        "note": "clip created + fired; caller is responsible for post-sample cleanup via cleanup_test_note",
+    }
+
+
+@register("cleanup_test_note")
+def cleanup_test_note(song, params):
+    """Stop + delete the scratch clip created by fire_test_note.
+
+    Idempotent — does nothing if no scratch clip exists.
+    Required: track_index
+    """
+    track_index = int(params["track_index"])
+    tracks = list(song.tracks)
+    if not 0 <= track_index < len(tracks):
+        return {"cleaned": False}
+    track = tracks[track_index]
+    clip_slots = list(track.clip_slots)
+    slot_idx = min(_TEST_NOTE_SLOT_INDEX, len(clip_slots) - 1)
+    if slot_idx < 0:
+        return {"cleaned": False}
+    slot = clip_slots[slot_idx]
+    try:
+        if slot.has_clip:
+            if slot.is_playing:
+                slot.stop()
+            slot.delete_clip()
+        return {"cleaned": True}
+    except Exception:
+        return {"cleaned": False}
+
+
+def _build_notes_spec(midi_note, velocity, duration_beats):
+    """Build the Live 12 add_new_notes argument — a list of NoteSpecification.
+
+    Returns None when the Live build doesn't expose the modern API (caller
+    falls back to legacy set_notes).
+    """
+    try:
+        from Live.Clip import MidiNoteSpecification
+    except ImportError:
+        return None
+    try:
+        return [MidiNoteSpecification(
+            pitch=midi_note,
+            start_time=0.0,
+            duration=duration_beats,
+            velocity=velocity,
+            mute=False,
+        )]
+    except Exception:
+        return None
+
+
+def _legacy_set_notes(clip, midi_note, velocity, duration_beats):
+    """Fallback for pre-12 Live builds — uses set_notes tuple API."""
+    try:
+        clip.select_all_notes()
+        clip.replace_selected_notes((
+            (midi_note, 0.0, duration_beats, velocity, False),
+        ))
+    except Exception:
+        # Last-resort: ignore silently. Caller will see no meter bump
+        # and report the device as dead — which is less informative
+        # than "handler couldn't fire" but still fails-safe.
+        pass
+
+
 @register("get_clip_info")
 def get_clip_info(song, params):
     """Return detailed info for a single clip."""
@@ -52,7 +217,18 @@ def get_clip_info(song, params):
 
 @register("create_clip")
 def create_clip(song, params):
-    """Create an empty MIDI clip in the given clip slot."""
+    """Create an empty MIDI clip in the given clip slot.
+
+    BUG-2026-04-22#1c FIX: Live's `clip_slot.create_clip(length)` sets
+    the clip's *length* but defaults `loop_end` to length/2 in some
+    configurations (depends on time signature). Without enforcing
+    `loop_end == length`, downstream `add_notes` calls silently drop
+    notes that fall beyond the implicit half-length loop. This handler
+    now applies the invariant via `_apply_clip_length_invariants` (a
+    pure-Python helper that's also unit-tested).
+    """
+    from ._clip_helpers import _apply_clip_length_invariants
+
     track_index = int(params["track_index"])
     clip_index = int(params["clip_index"])
     length = float(params["length"])
@@ -68,11 +244,15 @@ def create_clip(song, params):
     clip_slot.create_clip(length)
     clip = clip_slot.clip
 
+    invariants = _apply_clip_length_invariants(clip, length)
+
     return {
         "track_index": track_index,
         "clip_index": clip_index,
         "name": clip.name,
         "length": clip.length,
+        "loop_end": invariants["loop_end"],
+        "end_marker": invariants["end_marker"],
     }
 
 

package/remote_script/LivePilot/devices.py

@@ -558,9 +558,16 @@ def insert_rack_chain(song, params):
     """Insert a new chain into an Instrument Rack, Audio Effect Rack, or Drum Rack (12.3+).
 
     Required: track_index, device_index
-    Optional: position (-1 = end)
+    Optional: position (-1 = end), auto_pad_note (default True for drum racks)
+
+    BUG-2026-04-22#13 FIX: For Drum Racks, the new chain's `in_note` is
+    auto-incremented to the next free MIDI slot above any existing chain
+    (or 36 if it's the first). Without this, multiple new chains pile up
+    on note 36 ("Multi") and can't be triggered independently. Pass
+    `auto_pad_note=false` to keep Live's default behavior.
     """
     from .version_detect import has_feature
+    from ._drum_helpers import _next_drum_chain_note
 
     if not has_feature("insert_chain"):
         raise RuntimeError(
@@ -570,6 +577,7 @@ def insert_rack_chain(song, params):
     track_index = int(params["track_index"])
     device_index = int(params["device_index"])
     position = int(params.get("position", -1))
+    auto_pad_note = bool(params.get("auto_pad_note", True))
 
     track = get_track(song, track_index)
     device = get_device(track, device_index)
@@ -580,22 +588,94 @@ def insert_rack_chain(song, params):
             % device.name
         )
 
+    next_note = _next_drum_chain_note(device) if auto_pad_note else None
+
     song.begin_undo_step()
+    assigned_note = None
     try:
         if position >= 0:
             device.insert_chain(position)
         else:
             device.insert_chain()
+
+        # Apply auto pad-note if this is a drum rack.
+        if next_note is not None:
+            chains = list(device.chains)
+            if chains:
+                # The newly inserted chain is the last one (insert_chain()
+                # appends; insert_chain(N) inserts at N, so prefer the
+                # explicit position if given).
+                target_idx = position if position >= 0 else len(chains) - 1
+                if 0 <= target_idx < len(chains):
+                    new_chain = chains[target_idx]
+                    try:
+                        new_chain.in_note = next_note
+                        assigned_note = next_note
+                    except (AttributeError, TypeError):
+                        # Not a drum chain after all — silent skip.
+                        pass
     finally:
         song.end_undo_step()
 
     chain_count = len(list(device.chains))
-    return {
+    result = {
         "inserted": True,
         "track_index": track_index,
         "device_index": device_index,
         "chain_count": chain_count,
     }
+    if assigned_note is not None:
+        result["assigned_pad_note"] = assigned_note
+    return result
+
+
+@register("set_chain_name")
+def set_chain_name(song, params):
+    """Rename a chain inside any Rack device (Instrument / Audio Effect / Drum).
+
+    Required: track_index, device_index, chain_index, name
+    Returns the applied name (which Live may truncate) + chain path.
+
+    Completes the Drum-Rack construction UX opened by BUG-2026-04-22#1:
+    add_drum_rack_pad now rides this handler to actually apply the
+    user-supplied chain_name server-side instead of leaving it as a hint.
+    """
+    track_index = int(params["track_index"])
+    device_index = int(params["device_index"])
+    chain_index = int(params["chain_index"])
+    name = str(params.get("name", "")).strip()
+    if not name:
+        raise ValueError("name cannot be empty")
+
+    track = get_track(song, track_index)
+    device = get_device(track, device_index)
+
+    if not getattr(device, "can_have_chains", False):
+        raise ValueError(
+            "Device '%s' is not a rack — cannot rename chains" % device.name
+        )
+
+    chains = list(device.chains)
+    if chain_index < 0 or chain_index >= len(chains):
+        raise IndexError(
+            "Chain index %d out of range (0..%d)"
+            % (chain_index, len(chains) - 1)
+        )
+
+    chain = chains[chain_index]
+    try:
+        chain.name = name
+    except AttributeError:
+        raise RuntimeError(
+            "Chain object does not expose a writable `name` property"
+        )
+
+    return {
+        "track_index": track_index,
+        "device_index": device_index,
+        "chain_index": chain_index,
+        "name": getattr(chain, "name", name),
+    }
 
 
 @register("set_drum_chain_note")

package/remote_script/LivePilot/notes.py

@@ -11,7 +11,17 @@ from .utils import get_clip, get_track
 
 @register("add_notes")
 def add_notes(song, params):
-    """Add MIDI notes to a clip using Live 12's modern API."""
+    """Add MIDI notes to a clip using Live 12's modern API.
+
+    BUG-2026-04-22#1c FIX: Auto-extends `clip.loop_end` if any incoming
+    note's `start_time + duration` exceeds it. Without this, Live
+    silently drops the out-of-range notes — the response would say
+    "notes_added: N" but get_notes would return fewer. The extension
+    is reported back in the response as `loop_end_extended_to` when it
+    fires, so callers can see what happened.
+    """
+    from ._clip_helpers import _extend_loop_end_for_notes
+
     track_index = int(params["track_index"])
     clip_index = int(params["clip_index"])
     notes = params["notes"]
@@ -19,6 +29,8 @@ def add_notes(song, params):
         raise ValueError("notes list cannot be empty")
 
     clip = get_clip(song, track_index, clip_index)
+    extended_to = _extend_loop_end_for_notes(clip, notes)
+
     import Live
     song.begin_undo_step()
     try:
@@ -43,11 +55,14 @@ def add_notes(song, params):
     finally:
         song.end_undo_step()
 
-    return {
+    result = {
         "track_index": track_index,
         "clip_index": clip_index,
         "notes_added": len(notes),
     }
+    if extended_to is not None:
+        result["loop_end_extended_to"] = extended_to
+    return result
 
 
 @register("get_notes")