livepilot 1.10.9 → 1.12.2

package/mcp_server/runtime/remote_commands.py

@@ -48,6 +48,21 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "insert_device",           # 12.3+ native device insertion
     "insert_rack_chain",       # 12.3+ rack chain insertion
     "set_drum_chain_note",     # 12.3+ drum chain note assignment
+    # rack variations + macro CRUD (Live 11+)
+    "get_rack_variations", "store_rack_variation",
+    "recall_rack_variation", "delete_rack_variation",
+    "randomize_rack_macros", "add_rack_macro",
+    "remove_rack_macro", "set_rack_visible_macros",
+    # simpler slice CRUD (Live 11+)
+    "insert_simpler_slice", "move_simpler_slice",
+    "remove_simpler_slice", "clear_simpler_slices",
+    "reset_simpler_slices", "import_slices_from_onsets",
+    # wavetable modulation matrix (Live 11+)
+    "get_wavetable_mod_targets", "add_wavetable_mod_route",
+    "set_wavetable_mod_amount", "get_wavetable_mod_amount",
+    "get_wavetable_mod_matrix",
+    # device A/B compare (Live 12.3+)
+    "get_device_ab_state", "toggle_device_ab", "copy_device_state",
     # clip_automation (3)
     "get_clip_automation", "set_clip_automation", "clear_clip_automation",
     # browser (6)
@@ -65,8 +80,39 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "capture_midi", "start_recording", "stop_recording",
     "get_cue_points", "jump_to_cue", "toggle_cue_point",
     "back_to_arranger", "force_arrangement",
+    # scales — Song + per-clip scale awareness (Live 12.0+)
+    "get_song_scale", "set_song_scale", "set_song_scale_mode",
+    "list_available_scales",
+    "get_clip_scale", "set_clip_scale", "set_clip_scale_mode",
+    # tuning system (Live 12.1+)
+    "get_tuning_system", "set_tuning_reference_pitch",
+    "set_tuning_note", "reset_tuning_system",
+    # follow actions — clip (Live 12.0 revamp) + scene (Live 12.2+)
+    "get_clip_follow_action", "set_clip_follow_action",
+    "clear_clip_follow_action", "list_follow_action_types",
+    "apply_follow_action_preset",
+    "get_scene_follow_action", "set_scene_follow_action",
+    "clear_scene_follow_action",
+    # groove pool (Live 11+)
+    "list_grooves", "get_groove_info", "set_groove_params",
+    "assign_clip_groove", "get_clip_groove",
+    "get_song_groove_amount", "set_song_groove_amount",
+    # take lanes (Live 12.0 UI / 12.2 API)
+    "get_take_lanes", "create_take_lane", "set_take_lane_name",
+    "create_audio_clip_on_take_lane", "create_midi_clip_on_take_lane",
+    "get_take_lane_clips",
     # diagnostics (1)
     "get_session_diagnostics",
+    # control surfaces (diagnostic)
+    "list_control_surfaces", "get_control_surface_info",
+    # song primitives — transport/link
+    "tap_tempo", "nudge_tempo",
+    "set_exclusive_arm", "set_exclusive_solo",
+    "capture_and_insert_scene", "set_count_in_duration",
+    "get_link_state", "set_link_enabled", "force_link_beat_time",
+    # track primitives
+    "jump_in_session_clip", "get_track_performance_impact",
+    "get_appointed_device",
     # ping (built-in)
     "ping",
 })
@@ -92,6 +138,14 @@ BRIDGE_COMMANDS: frozenset[str] = frozenset({
     # async Python MCP tool in mcp_server/tools/analyzer.py, not a bridge
     # command. It has no case in livepilot_bridge.js and no @register handler
     # in remote_script. See mcp_server/runtime/execution_router.MCP_TOOLS.
+    # NOTE: MIDI Tool bridge commands (Live 12.0+ MIDI Generators /
+    # Transformations, requires LivePilot_MIDITool.amxd) do NOT belong in
+    # this set. They ride OSC prefixes /miditool/request, /miditool/ready
+    # (bridge→server) and miditool/config, miditool/response (server→bridge),
+    # dispatched through m4l_device/miditool_bridge.js (a separate JS, not
+    # livepilot_bridge.js) and pushed directly via M4LBridge.send_miditool_*
+    # helpers rather than through send_command. BRIDGE_COMMANDS is reserved
+    # for send_command targets that dispatch inside livepilot_bridge.js.
 })
 
 # Combined: all valid send_command targets

package/mcp_server/sample_engine/slice_classifier.py

@@ -0,0 +1,169 @@
+"""Spectral classification of Simpler-slice drum break segments.
+
+Lessons from the 2026-04-18 creative session that drove this module:
+
+- Never assume slice 0 is a kick. Slice content depends on transient
+  detection order in the source audio, not drum-rack convention.
+- Snares ALWAYS have 20-35% mid-frequency energy (drum body resonance).
+  Hi-hats / cymbals have <25% mid (they're thin metal discs with no
+  resonant body). This mid-content threshold is the critical separator
+  that tripped up the first classification pass.
+- Ghosts are defined by low peak amplitude (<0.35) regardless of spectrum.
+
+Thresholds validated against "Break Ghosts 90 bpm" (Ableton Core Library)
+in the session. See ``feedback_analyze_slices_before_programming`` memory
+entry for the full story and the specific slice map for that sample.
+
+This module is pure Python (numpy only). No LivePilot / Ableton /
+FastMCP dependencies — testable and runnable in isolation.
+"""
+from __future__ import annotations
+
+from typing import List, Literal, Sequence, TypedDict
+
+import numpy as np
+
+
+Label = Literal["KICK", "SNARE", "HAT", "ghost"]
+
+
+class SliceFeatures(TypedDict):
+    """Per-slice classification result plus the features that drove the decision."""
+
+    index: int
+    label: Label
+    peak: float
+    rms: float
+    sub_pct: float
+    low_pct: float
+    mid_pct: float
+    high_pct: float
+
+
+# ---------------------------------------------------------------------------
+# Band boundaries (Hz). Tuned against the 2026-04-18 session's working set.
+# ---------------------------------------------------------------------------
+
+_SUB_MAX = 100.0    # sub-bass (kick fundamentals live here)
+_LOW_MAX = 300.0    # body / low-mid (kick "thud" + bass fundamentals)
+_MID_MAX = 3000.0   # presence / drum body / vocals
+# Everything above _MID_MAX is "high" (sizzle / air / cymbal).
+
+
+# ---------------------------------------------------------------------------
+# Classification thresholds. DO NOT loosen these without re-validating on a
+# real break — the 2026-04-18 session proved that relaxing the HAT mid-cap
+# to 32% misclassifies loud snares as hats.
+# ---------------------------------------------------------------------------
+
+_GHOST_PEAK = 0.35        # Below this peak → ghost regardless of spectrum
+_KICK_SUB_LOW_MIN = 0.45  # sub + low must be this dominant
+_KICK_HIGH_MAX = 0.40     # kicks never have >40% high
+_SNARE_MID_MIN = 0.25     # snares HAVE a drum body (mid content)
+_SNARE_HIGH_MIN = 0.40    # + sizzle
+_SNARE_PEAK_MIN = 0.60    # + loud enough to not be a ghost
+_HAT_HIGH_MIN = 0.70      # hats are thin metal — overwhelmingly high
+_HAT_MID_MAX = 0.25       # hats have almost no drum body
+
+
+def _band_energy(segment: np.ndarray, sr: int) -> tuple[float, float, float, float]:
+    """Return (sub, low, mid, high) energy fractions that sum to ~1.0.
+
+    Uses an rFFT. If the segment is empty or silent, returns equal quarters
+    so downstream logic doesn't have to handle zero-sum edge cases (the
+    caller still sees silence via the peak/rms fields).
+    """
+    if len(segment) < 2:
+        return 0.25, 0.25, 0.25, 0.25
+    spec = np.abs(np.fft.rfft(segment))
+    total = float(spec.sum())
+    if total <= 0:
+        return 0.25, 0.25, 0.25, 0.25
+    freqs = np.fft.rfftfreq(len(segment), 1.0 / sr)
+    sub = float(spec[freqs < _SUB_MAX].sum() / total)
+    low = float(spec[(freqs >= _SUB_MAX) & (freqs < _LOW_MAX)].sum() / total)
+    mid = float(spec[(freqs >= _LOW_MAX) & (freqs < _MID_MAX)].sum() / total)
+    high = float(spec[freqs >= _MID_MAX].sum() / total)
+    return sub, low, mid, high
+
+
+def classify_segment(segment: np.ndarray, sr: int) -> Label:
+    """Classify a single audio segment as KICK / SNARE / HAT / ghost.
+
+    Returns the label string. See module docstring for the reasoning behind
+    each threshold.
+    """
+    if len(segment) < 2:
+        return "ghost"
+    peak = float(np.max(np.abs(segment)))
+    if peak < _GHOST_PEAK:
+        return "ghost"
+
+    sub, low, mid, high = _band_energy(segment, sr)
+
+    # KICK: sub+low dominance with limited high content.
+    if (sub + low) >= _KICK_SUB_LOW_MIN and high < _KICK_HIGH_MAX:
+        return "KICK"
+
+    # HAT: overwhelmingly high-freq, almost no drum-body mid content.
+    if high >= _HAT_HIGH_MIN and mid <= _HAT_MID_MAX:
+        return "HAT"
+
+    # SNARE: broadband (mid body + high sizzle) AND loud.
+    if (
+        mid >= _SNARE_MID_MIN
+        and high >= _SNARE_HIGH_MIN
+        and peak >= _SNARE_PEAK_MIN
+    ):
+        return "SNARE"
+
+    # Fallback for ambiguous mid/high dominant loud hits — usually
+    # snares with unusual spectrum (e.g., rim-shots, piccolo snare).
+    if peak >= _SNARE_PEAK_MIN and (mid + high) >= 0.70:
+        return "SNARE"
+
+    # If nothing else matched but there's real energy, call it a hat
+    # rather than a ghost (ghost is reserved for quiet hits).
+    return "HAT"
+
+
+def classify_slices(
+    audio: np.ndarray,
+    sr: int,
+    frame_boundaries: Sequence[int],
+) -> List[SliceFeatures]:
+    """Classify every slice defined by ``frame_boundaries``.
+
+    ``frame_boundaries`` is a list of N+1 frame positions defining N slices.
+    For a sample with slices starting at frames [0, 1000, 3000, 5000] and
+    total length 10000 frames, pass [0, 1000, 3000, 5000, 10000].
+
+    Stereo input is auto-downmixed (mean of the two channels).
+
+    Returns a list of ``SliceFeatures`` in slice-index order.
+    """
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+
+    results: List[SliceFeatures] = []
+    for i in range(len(frame_boundaries) - 1):
+        start = int(frame_boundaries[i])
+        end = int(frame_boundaries[i + 1])
+        segment = audio[start:end]
+        label = classify_segment(segment, sr)
+        peak = float(np.max(np.abs(segment))) if len(segment) else 0.0
+        rms = float(np.sqrt(np.mean(segment ** 2))) if len(segment) else 0.0
+        sub, low, mid, high = _band_energy(segment, sr)
+        results.append(
+            SliceFeatures(
+                index=i,
+                label=label,
+                peak=peak,
+                rms=rms,
+                sub_pct=sub,
+                low_pct=low,
+                mid_pct=mid,
+                high_pct=high,
+            )
+        )
+    return results

package/mcp_server/server.py

@@ -9,7 +9,7 @@ import subprocess
 from fastmcp import FastMCP, Context  # noqa: F401
 
 from .connection import AbletonConnection
-from .m4l_bridge import SpectralCache, SpectralReceiver, M4LBridge
+from .m4l_bridge import SpectralCache, SpectralReceiver, M4LBridge, MidiToolCache
 
 # Logger must be defined before any function uses it — several module-level
 # helpers below (e.g. _master_has_livepilot_analyzer) call logger.debug on
@@ -174,8 +174,9 @@ async def lifespan(server):
 
     ableton = AbletonConnection()
     spectral = SpectralCache()
-    receiver = SpectralReceiver(spectral)
-    m4l = M4LBridge(spectral, receiver)
+    miditool = MidiToolCache()
+    receiver = SpectralReceiver(spectral, miditool_cache=miditool)
+    m4l = M4LBridge(spectral, receiver, miditool_cache=miditool)
     mcp_dispatch = build_mcp_dispatch_registry()
 
     # Splice gRPC client — graceful degradation if Splice desktop isn't
@@ -234,6 +235,7 @@ async def lifespan(server):
         yield {
             "ableton": ableton,
             "spectral": spectral,
+            "miditool": miditool,
             "m4l": m4l,
             "_bridge_state": bridge_state,
             "mcp_dispatch": mcp_dispatch,
@@ -257,6 +259,10 @@ from .tools import clips        # noqa: F401, E402
 from .tools import notes        # noqa: F401, E402
 from .tools import devices      # noqa: F401, E402
 from .tools import scenes       # noqa: F401, E402
+from .tools import scales       # noqa: F401, E402
+from .tools import follow_actions  # noqa: F401, E402
+from .tools import grooves      # noqa: F401, E402
+from .tools import take_lanes   # noqa: F401, E402
 from .tools import mixing       # noqa: F401, E402
 from .tools import browser      # noqa: F401, E402
 from .tools import arrangement  # noqa: F401, E402
@@ -299,6 +305,8 @@ from .device_forge import tools as device_forge_tools          # noqa: F401, E40
 from .sample_engine import tools as sample_engine_tools        # noqa: F401, E402
 from .atlas import tools as atlas_tools                        # noqa: F401, E402
 from .composer import tools as composer_tools                  # noqa: F401, E402
+from .tools import diagnostics   # noqa: F401, E402
+from .tools import miditool       # noqa: F401, E402
 
 # ---------------------------------------------------------------------------
 # Schema coercion patch — accept strings for numeric parameters

package/mcp_server/tools/analyzer.py

@@ -34,6 +34,36 @@ logger = logging.getLogger(__name__)
 CAPTURE_DIR = os.path.expanduser("~/Documents/LivePilot/captures")
 
 
+# Live 12 Simpler Slice mode maps slice N to MIDI pitch 36+N (C1 base).
+# This is NOT exposed by the Remote Script API and is a common source of
+# silent audio bugs (BUG-F2). See feedback_analyze_slices_before_programming
+# memory for context.
+SIMPLER_SLICE_BASE_PITCH = 36
+
+
+def _enrich_slice_response(response: Optional[dict]) -> Optional[dict]:
+    """Add base_midi_pitch field + per-slice midi_pitch to bridge response (BUG-F2).
+
+    The Remote Script returns slice indices only. Users then have to know
+    that slice N plays at MIDI pitch 36+N — a fact that's undocumented in
+    both Ableton's and LivePilot's public API. This enrichment makes the
+    mapping explicit so MIDI pattern generation doesn't silently produce
+    out-of-range notes.
+    """
+    if response is None:
+        return None
+    enriched = dict(response)
+    enriched["base_midi_pitch"] = SIMPLER_SLICE_BASE_PITCH
+    slices = enriched.get("slices") or []
+    # BUG-audit-M2: fall back to positional index when the bridge response
+    # omits the `index` field (protects against bridge version skew).
+    enriched["slices"] = [
+        {**s, "midi_pitch": SIMPLER_SLICE_BASE_PITCH + s.get("index", i)}
+        for i, s in enumerate(slices)
+    ]
+    return enriched
+
+
 @mcp.tool()
 async def reconnect_bridge(ctx: Context) -> dict:
     """Attempt to reconnect the M4L UDP bridge (port 9880).
@@ -97,11 +127,36 @@ def get_master_spectrum(ctx: Context) -> dict:
     return result
 
 
+def _sanitize_pitch(pitch: Optional[dict]) -> Optional[dict]:
+    """Validate a pitch reading from the M4L analyzer (BUG-F1).
+
+    The polyphonic pitch detector can emit out-of-range MIDI notes
+    (e.g., 319, -50, 128+) when it can't latch onto a single
+    fundamental — typical for dense mixes. The amplitude field is the
+    reliable confidence signal: if the detector was sure of its
+    reading, amplitude is non-zero.
+
+    Returns the original dict if the reading is usable, None otherwise.
+    """
+    if not pitch:
+        return None
+    amplitude = pitch.get("amplitude")
+    midi_note = pitch.get("midi_note")
+    if amplitude is None or amplitude <= 0:
+        return None
+    if midi_note is None or midi_note < 0 or midi_note > 127:
+        return None
+    return pitch
+
+
 @mcp.tool()
 def get_master_rms(ctx: Context) -> dict:
     """Get real-time RMS and peak levels from the master bus.
 
     More accurate than LOM meters — includes true RMS (not just peak hold).
+    Pitch readings are validated: the field is only present when the
+    polyphonic pitch detector produced a reading with non-zero
+    amplitude and a MIDI note in [0, 127] (BUG-F1).
     Requires LivePilot Analyzer on master track.
     """
     cache = _get_spectral(ctx)
@@ -117,9 +172,11 @@ def get_master_rms(ctx: Context) -> dict:
     if peak:
         result["peak"] = peak["value"]
 
-    pitch = cache.get("pitch")
-    if pitch:
-        result["pitch"] = pitch["value"]
+    pitch_entry = cache.get("pitch")
+    if pitch_entry:
+        clean = _sanitize_pitch(pitch_entry.get("value"))
+        if clean is not None:
+            result["pitch"] = clean
 
     return result
 
@@ -414,15 +471,138 @@ async def get_simpler_slices(
 ) -> dict:
     """Get slice point positions from a Simpler device.
 
-    Returns each slice's position in frames and seconds, plus sample metadata
-    (sample rate, length, playback mode). Use this to understand the rhythmic
-    structure of a sliced sample and program MIDI patterns targeting slices.
+    Returns each slice's position in frames and seconds, the MIDI pitch
+    that triggers it (slice 0 = C1 / MIDI 36, slice 1 = C#1 / MIDI 37, etc.
+    per BUG-F2), plus sample metadata (sample rate, length, playback mode).
+
+    **Always use the returned `midi_pitch` when programming MIDI notes to
+    trigger slices.** The Live 12 Simpler Slice-mode base note is C1,
+    NOT C3 — writing notes at pitch 60+ on a sample with <24 slices
+    triggers nothing and produces silent output.
+
+    Use this to understand the rhythmic structure of a sliced sample
+    and program MIDI patterns targeting slices. Requires LivePilot
+    Analyzer on master track.
+    """
+    cache = _get_spectral(ctx)
+    _require_analyzer(cache)
+    bridge = _get_m4l(ctx)
+    raw = await bridge.send_command("get_simpler_slices", track_index, device_index)
+    return _enrich_slice_response(raw)
+
+
+@mcp.tool()
+async def classify_simpler_slices(
+    ctx: Context,
+    track_index: int,
+    device_index: int = 0,
+    file_path: Optional[str] = None,
+) -> dict:
+    """Classify each Simpler slice as KICK / SNARE / HAT / ghost via FFT analysis.
+
+    Reads slice positions via ``get_simpler_slices``, loads the backing
+    WAV file, and runs 4-band spectral classification on each segment.
+    Returns the enriched slice list with a ``label`` field per entry
+    plus feature breakdown (peak, rms, sub_pct, low_pct, mid_pct,
+    high_pct).
+
+    **Always run this before programming drum patterns on a sliced
+    break.** Slice content depends on transient detection order in the
+    source audio — slice 0 is NOT guaranteed to be a kick. Assuming
+    drum-rack convention produces wrong grooves that take iterations to
+    diagnose (see 2026-04-18 creative session for the canonical case).
+
+    Classification rules (validated on "Break Ghosts 90 bpm"):
+      - KICK: sub+low >= 45%, high < 40%
+      - HAT: high >= 70% AND mid < 25% (thin metal disc = no drum body)
+      - SNARE: mid >= 25% AND high >= 40% AND peak >= 0.6 (broadband loud)
+      - ghost: peak < 0.35
+
+    Parameters:
+      track_index, device_index: the Simpler to analyze
+      file_path: (optional) explicit WAV path. If omitted, attempts
+        lookup via the bridge. Bridge-native resolution is limited in
+        v1.11 — when the sample lives in the Core Library, pass the
+        absolute path explicitly.
+
+    Returns: dict with ``slices`` list. Each slice entry has:
+      index, frame, seconds, midi_pitch (36+index), label, peak, rms,
+      sub_pct, low_pct, mid_pct, high_pct.
+
     Requires LivePilot Analyzer on master track.
     """
+    import soundfile as sf
+
+    from ..sample_engine.slice_classifier import classify_slices
+
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
-    return await bridge.send_command("get_simpler_slices", track_index, device_index)
+
+    # 1. Get slice positions
+    raw_slices = await bridge.send_command(
+        "get_simpler_slices", track_index, device_index
+    )
+    enriched = _enrich_slice_response(raw_slices)
+    if enriched is None:
+        return {"error": "Bridge returned no slice data"}
+
+    # 2. Resolve file path
+    wav_path = file_path
+    if not wav_path:
+        try:
+            file_info = await bridge.send_command(
+                "get_simpler_file_path", track_index, device_index
+            )
+            if isinstance(file_info, dict):
+                wav_path = file_info.get("file_path")
+        except Exception:  # noqa: BLE001 — bridge command may not exist yet
+            wav_path = None
+
+    if not wav_path:
+        return {
+            **enriched,
+            "error": (
+                "No file_path available — pass file_path= explicitly. "
+                "Bridge-based lookup for Simpler sample paths is a v1.12 "
+                "follow-up."
+            ),
+        }
+
+    # 3. Load WAV and build frame boundaries
+    try:
+        audio, sr = sf.read(wav_path)
+    except (sf.LibsndfileError, sf.SoundFileError, RuntimeError, OSError) as exc:
+        # BUG-audit-C3: corrupt / missing / non-audio files must return a
+        # structured error dict instead of raising through the MCP framework
+        # (inconsistent with every other tool in this module).
+        return {
+            **enriched,
+            "error": f"Could not load WAV at {wav_path!r}: {exc}",
+        }
+    slices = enriched["slices"]
+    frame_boundaries = [s["frame"] for s in slices] + [len(audio)]
+
+    # 4. Classify
+    classifications = classify_slices(audio, sr, frame_boundaries)
+
+    # 5. Merge classification into each slice entry
+    merged_slices = []
+    for slice_entry, features in zip(slices, classifications):
+        merged_slices.append({
+            **slice_entry,
+            "label": features["label"],
+            "peak": features["peak"],
+            "rms": features["rms"],
+            "sub_pct": features["sub_pct"],
+            "low_pct": features["low_pct"],
+            "mid_pct": features["mid_pct"],
+            "high_pct": features["high_pct"],
+        })
+
+    enriched["slices"] = merged_slices
+    enriched["classifier_version"] = "v1.0"
+    return enriched
 
 
 @mcp.tool()

package/mcp_server/tools/clips.py

@@ -503,3 +503,68 @@ async def check_clip_key_consistency(
             f"{mode_note}"
         ),
     }
+
+
+@mcp.tool()
+def get_clip_scale(ctx: Context, track_index: int, clip_index: int) -> dict:
+    """Read a clip's per-clip scale override (Live 12.0+).
+
+    Per-clip scales are independent of Song.scale_*. A clip can have
+    Scale Mode enabled with a different root/name than the Song.
+
+    Returns {root_note (0-11), scale_mode (bool), scale_name (str)}.
+    Raises if the clip slot is empty.
+    """
+    return _get_ableton(ctx).send_command("get_clip_scale", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+    })
+
+
+@mcp.tool()
+def set_clip_scale(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    root_note: int,
+    scale_name: str,
+) -> dict:
+    """Set a clip's per-clip scale override (Live 12.0+).
+
+    Overrides the Song-level scale for this clip only. Useful for
+    key changes within a set, or for clips that live in a different
+    mode than the rest of the arrangement.
+
+    root_note:   0-11 (C=0, C#=1, ... B=11)
+    scale_name:  must match one of Live's built-in scales
+                 (call list_available_scales() if unsure)
+    """
+    if not 0 <= root_note <= 11:
+        raise ValueError("root_note must be 0-11")
+    if not scale_name.strip():
+        raise ValueError("scale_name cannot be empty")
+    return _get_ableton(ctx).send_command("set_clip_scale", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "root_note": root_note,
+        "scale_name": scale_name,
+    })
+
+
+@mcp.tool()
+def set_clip_scale_mode(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    enabled: bool,
+) -> dict:
+    """Enable or disable Scale Mode on a single clip (Live 12.0+).
+
+    When enabled on a clip, its notes are constrained/highlighted
+    by the clip's own root_note + scale_name (set via set_clip_scale).
+    """
+    return _get_ableton(ctx).send_command("set_clip_scale_mode", {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "enabled": enabled,
+    })