livepilot 1.10.8 → 1.12.2

package/remote_script/LivePilot/follow_actions.py

@@ -0,0 +1,235 @@
+"""
+LivePilot — Follow Actions handlers (Live 12.0+ clip, 12.2+ scene).
+
+Exposes the revamped clip follow-action API (Live 12.0) and the
+scene-level follow-action properties added in Live 12.2.
+
+Clip follow-actions use an integer enum internally (0..8) mapped
+bidirectionally to string names via ``_FOLLOW_ACTION_NAMES``. We
+accept strings from tool wrappers and convert to int for the Live
+API; on read we convert back to the string form. Unknown / future
+enum values (e.g. anything Live 12.4+ might add) fall through as a
+plain stringified int rather than raising, so the tool remains
+forward-compatible for additive enum growth.
+
+Chance values are documented by Live as 0.0-1.0 normalized. We
+accept the same range from callers and pass through unchanged.
+"""
+
+from .router import register
+from .utils import get_clip, get_scene
+
+
+_FOLLOW_ACTION_NAMES = [
+    "stop",         # 0
+    "play_again",   # 1
+    "previous",     # 2
+    "next",         # 3
+    "first",        # 4
+    "last",         # 5
+    "any",          # 6
+    "other",        # 7
+    "jump",         # 8
+]
+_FOLLOW_ACTION_IDX = {name: i for i, name in enumerate(_FOLLOW_ACTION_NAMES)}
+
+_FOLLOW_ACTION_PRESETS = {
+    "loop_forever":    {"action_a": "play_again", "action_b": "stop",
+                        "chance_a": 1.0, "chance_b": 0.0, "time": 1.0},
+    "random_walk":     {"action_a": "next", "action_b": "previous",
+                        "chance_a": 0.5, "chance_b": 0.5, "time": 1.0},
+    "next_after_one":  {"action_a": "next", "action_b": "stop",
+                        "chance_a": 1.0, "chance_b": 0.0, "time": 1.0},
+    "stop_after_one":  {"action_a": "stop", "action_b": "stop",
+                        "chance_a": 1.0, "chance_b": 0.0, "time": 1.0},
+}
+
+
+def _action_name(idx):
+    """Map int enum → string, tolerating out-of-range (future) values."""
+    try:
+        return _FOLLOW_ACTION_NAMES[int(idx)]
+    except (IndexError, ValueError):
+        return str(idx)
+
+
+def _action_idx(name_or_int):
+    """Map string → int enum, passing through ints untouched."""
+    if isinstance(name_or_int, int):
+        return name_or_int
+    key = str(name_or_int).lower()
+    if key not in _FOLLOW_ACTION_IDX:
+        raise ValueError(
+            "Unknown follow action '%s'. Valid: %s"
+            % (name_or_int, ", ".join(_FOLLOW_ACTION_NAMES))
+        )
+    return _FOLLOW_ACTION_IDX[key]
+
+
+def _read_clip_follow_action(clip):
+    """Snapshot all clip follow-action fields as a plain dict."""
+    return {
+        "enabled": bool(getattr(clip, "follow_action_enabled", False)),
+        "action_a": _action_name(clip.follow_action_a),
+        "action_b": _action_name(clip.follow_action_b),
+        "chance_a": float(clip.follow_action_chance_a),
+        "chance_b": float(clip.follow_action_chance_b),
+        "time": float(clip.follow_action_time),
+    }
+
+
+@register("list_follow_action_types")
+def list_follow_action_types(song, params):
+    """Return the list of valid follow-action names."""
+    return {"actions": list(_FOLLOW_ACTION_NAMES)}
+
+
+@register("get_clip_follow_action")
+def get_clip_follow_action(song, params):
+    """Read a clip's follow-action state (Live 12.0+)."""
+    from .version_detect import has_feature
+    if not has_feature("clip_follow_action_v2"):
+        raise RuntimeError("Clip follow actions require Live 12.0+.")
+    clip = get_clip(song, int(params["track_index"]), int(params["clip_index"]))
+    return _read_clip_follow_action(clip)
+
+
+@register("set_clip_follow_action")
+def set_clip_follow_action(song, params):
+    """Set a clip's follow-action state (Live 12.0+).
+
+    Any of action_a, action_b, chance_a, chance_b, time, enabled may
+    be omitted — omitted fields leave the current value untouched.
+    Chance values are 0.0-1.0 normalized per Live's public API.
+    """
+    from .version_detect import has_feature
+    if not has_feature("clip_follow_action_v2"):
+        raise RuntimeError("Clip follow actions require Live 12.0+.")
+    clip = get_clip(song, int(params["track_index"]), int(params["clip_index"]))
+
+    if "action_a" in params:
+        clip.follow_action_a = _action_idx(params["action_a"])
+    if "action_b" in params:
+        clip.follow_action_b = _action_idx(params["action_b"])
+    if "chance_a" in params:
+        c = float(params["chance_a"])
+        if not 0.0 <= c <= 1.0:
+            raise ValueError("chance_a must be 0.0-1.0")
+        clip.follow_action_chance_a = c
+    if "chance_b" in params:
+        c = float(params["chance_b"])
+        if not 0.0 <= c <= 1.0:
+            raise ValueError("chance_b must be 0.0-1.0")
+        clip.follow_action_chance_b = c
+    if "time" in params:
+        t = float(params["time"])
+        if t < 0.0:
+            raise ValueError("time must be >= 0.0 beats")
+        clip.follow_action_time = t
+    if "enabled" in params:
+        # Some Live versions expose this as ``follow_action_enabled``; fall
+        # back silently if the attribute isn't present so the rest of the
+        # set still applies on e.g. an older 12.0 point release.
+        if hasattr(clip, "follow_action_enabled"):
+            clip.follow_action_enabled = bool(params["enabled"])
+
+    return _read_clip_follow_action(clip)
+
+
+@register("clear_clip_follow_action")
+def clear_clip_follow_action(song, params):
+    """Disable a clip's follow actions (Live 12.0+)."""
+    from .version_detect import has_feature
+    if not has_feature("clip_follow_action_v2"):
+        raise RuntimeError("Clip follow actions require Live 12.0+.")
+    clip = get_clip(song, int(params["track_index"]), int(params["clip_index"]))
+    if hasattr(clip, "follow_action_enabled"):
+        clip.follow_action_enabled = False
+    return {"enabled": False}
+
+
+@register("apply_follow_action_preset")
+def apply_follow_action_preset(song, params):
+    """Apply a named follow-action preset to a clip (Live 12.0+)."""
+    from .version_detect import has_feature
+    if not has_feature("clip_follow_action_v2"):
+        raise RuntimeError("Clip follow actions require Live 12.0+.")
+    preset_name = str(params["preset"]).lower()
+    if preset_name not in _FOLLOW_ACTION_PRESETS:
+        raise ValueError(
+            "Unknown preset '%s'. Valid: %s"
+            % (params["preset"], ", ".join(_FOLLOW_ACTION_PRESETS))
+        )
+    preset = _FOLLOW_ACTION_PRESETS[preset_name]
+    # Delegate to set_clip_follow_action with the preset values merged in.
+    # User-supplied params take no precedence — presets are all-or-nothing.
+    apply_params = dict(params)
+    apply_params.update(preset)
+    apply_params["enabled"] = True
+    return set_clip_follow_action(song, apply_params)
+
+
+# ── Scene follow actions (Live 12.2+) ────────────────────────────────────
+
+
+def _read_scene_follow_action(scene):
+    """Snapshot all scene follow-action fields as a plain dict."""
+    return {
+        "enabled": bool(scene.follow_action_enabled),
+        "time": float(scene.follow_action_time),
+        "linked": bool(getattr(scene, "follow_action_linked", False)),
+        "multiplier": int(getattr(scene, "follow_action_multiplier", 1)),
+    }
+
+
+@register("get_scene_follow_action")
+def get_scene_follow_action(song, params):
+    """Read a scene's follow-action state (Live 12.2+)."""
+    from .version_detect import has_feature
+    if not has_feature("scene_follow_actions"):
+        raise RuntimeError("Scene follow actions require Live 12.2+.")
+    scene = get_scene(song, int(params["scene_index"]))
+    return _read_scene_follow_action(scene)
+
+
+@register("set_scene_follow_action")
+def set_scene_follow_action(song, params):
+    """Set a scene's follow-action state (Live 12.2+).
+
+    All args except scene_index are optional; omitted ones preserve
+    the current value. ``linked`` controls "Longest" mode — when True
+    the scene waits for the longest clip's loop length; when False it
+    uses ``time * multiplier`` as the trigger point.
+    """
+    from .version_detect import has_feature
+    if not has_feature("scene_follow_actions"):
+        raise RuntimeError("Scene follow actions require Live 12.2+.")
+    scene = get_scene(song, int(params["scene_index"]))
+
+    if "enabled" in params:
+        scene.follow_action_enabled = bool(params["enabled"])
+    if "time" in params:
+        t = float(params["time"])
+        if t < 0.0:
+            raise ValueError("time must be >= 0.0 beats")
+        scene.follow_action_time = t
+    if "linked" in params and hasattr(scene, "follow_action_linked"):
+        scene.follow_action_linked = bool(params["linked"])
+    if "multiplier" in params and hasattr(scene, "follow_action_multiplier"):
+        m = int(params["multiplier"])
+        if not 1 <= m <= 8:
+            raise ValueError("multiplier must be 1-8")
+        scene.follow_action_multiplier = m
+
+    return _read_scene_follow_action(scene)
+
+
+@register("clear_scene_follow_action")
+def clear_scene_follow_action(song, params):
+    """Disable a scene's follow action (Live 12.2+)."""
+    from .version_detect import has_feature
+    if not has_feature("scene_follow_actions"):
+        raise RuntimeError("Scene follow actions require Live 12.2+.")
+    scene = get_scene(song, int(params["scene_index"]))
+    scene.follow_action_enabled = False
+    return {"enabled": False}

package/remote_script/LivePilot/grooves.py

@@ -0,0 +1,185 @@
+"""
+LivePilot — Groove Pool handlers (Live 11+).
+
+Exposes ``song.groove_pool`` enumeration, per-groove parameter
+tuning, per-clip groove assignment, and the master
+``song.groove_amount`` dial.
+
+Groove ids are zero-based indices into ``song.groove_pool.grooves``;
+the index is stable for the lifetime of the pool but may shift if
+the user adds/removes grooves in the UI. Callers should re-list
+before issuing long-running sequences that depend on a specific id.
+"""
+
+from .router import register
+from .utils import get_clip
+
+
+def _groove_info(groove, groove_id):
+    """Serialize a Groove object to a plain dict."""
+    return {
+        "id": int(groove_id),
+        "name": str(groove.name),
+        "base": int(getattr(groove, "base", 0)),
+        "quantization_amount": float(groove.quantization_amount),
+        "random_amount": float(groove.random_amount),
+        "timing_amount": float(groove.timing_amount),
+        "velocity_amount": float(groove.velocity_amount),
+    }
+
+
+def _get_groove(song, groove_id):
+    """Resolve a groove_id to a Groove object, raising IndexError on miss."""
+    grooves = list(song.groove_pool.grooves)
+    idx = int(groove_id)
+    if not 0 <= idx < len(grooves):
+        raise IndexError(
+            "groove_id %d out of range (0..%d). Groove pool has %d grooves."
+            % (idx, len(grooves) - 1 if grooves else -1, len(grooves))
+        )
+    return grooves[idx]
+
+
+@register("list_grooves")
+def list_grooves(song, params):
+    """List all grooves in the Groove Pool (Live 11+)."""
+    from .version_detect import has_feature
+    if not has_feature("groove_pool_api"):
+        raise RuntimeError("Groove pool API requires Live 11+.")
+    grooves = []
+    for i, g in enumerate(song.groove_pool.grooves):
+        grooves.append(_groove_info(g, i))
+    return {"grooves": grooves}
+
+
+@register("get_groove_info")
+def get_groove_info(song, params):
+    """Read a single groove's parameters (Live 11+)."""
+    from .version_detect import has_feature
+    if not has_feature("groove_pool_api"):
+        raise RuntimeError("Groove pool API requires Live 11+.")
+    groove = _get_groove(song, params["groove_id"])
+    return _groove_info(groove, params["groove_id"])
+
+
+@register("set_groove_params")
+def set_groove_params(song, params):
+    """Set one or more groove parameters (Live 11+).
+
+    Any of quantization_amount, random_amount, timing_amount,
+    velocity_amount may be omitted — omitted fields leave the current
+    value untouched. quantization/random/timing are 0.0-1.0; velocity
+    is signed -1.0 to 1.0 (negative = subtract velocity, positive = add).
+    """
+    from .version_detect import has_feature
+    if not has_feature("groove_pool_api"):
+        raise RuntimeError("Groove pool API requires Live 11+.")
+    groove = _get_groove(song, params["groove_id"])
+
+    if "quantization_amount" in params:
+        v = float(params["quantization_amount"])
+        if not 0.0 <= v <= 1.0:
+            raise ValueError("quantization_amount must be 0.0-1.0")
+        groove.quantization_amount = v
+    if "random_amount" in params:
+        v = float(params["random_amount"])
+        if not 0.0 <= v <= 1.0:
+            raise ValueError("random_amount must be 0.0-1.0")
+        groove.random_amount = v
+    if "timing_amount" in params:
+        v = float(params["timing_amount"])
+        if not 0.0 <= v <= 1.0:
+            raise ValueError("timing_amount must be 0.0-1.0")
+        groove.timing_amount = v
+    if "velocity_amount" in params:
+        v = float(params["velocity_amount"])
+        if not -1.0 <= v <= 1.0:
+            raise ValueError("velocity_amount must be -1.0 to 1.0")
+        groove.velocity_amount = v
+
+    return _groove_info(groove, params["groove_id"])
+
+
+@register("assign_clip_groove")
+def assign_clip_groove(song, params):
+    """Assign (or clear) a groove on a clip (Live 11+).
+
+    Pass ``groove_id = -1`` (or null/None) to clear the clip's groove.
+    """
+    from .version_detect import has_feature
+    if not has_feature("groove_pool_api"):
+        raise RuntimeError("Groove pool API requires Live 11+.")
+    clip = get_clip(song, int(params["track_index"]), int(params["clip_index"]))
+
+    groove_id = params.get("groove_id")
+    if groove_id is None or int(groove_id) < 0:
+        clip.groove = None
+        return {
+            "track_index": int(params["track_index"]),
+            "clip_index": int(params["clip_index"]),
+            "groove_id": None,
+            "groove_name": None,
+        }
+
+    groove = _get_groove(song, groove_id)
+    clip.groove = groove
+    return {
+        "track_index": int(params["track_index"]),
+        "clip_index": int(params["clip_index"]),
+        "groove_id": int(groove_id),
+        "groove_name": str(groove.name),
+    }
+
+
+@register("get_clip_groove")
+def get_clip_groove(song, params):
+    """Read a clip's current groove assignment (Live 11+).
+
+    Returns ``{groove_id: int, groove_name: str}`` when set, or
+    ``{groove_id: None, groove_name: None}`` when unset.
+    """
+    from .version_detect import has_feature
+    if not has_feature("groove_pool_api"):
+        raise RuntimeError("Groove pool API requires Live 11+.")
+    clip = get_clip(song, int(params["track_index"]), int(params["clip_index"]))
+
+    clip_groove = getattr(clip, "groove", None)
+    if clip_groove is None:
+        return {"groove_id": None, "groove_name": None}
+
+    # Resolve the groove object's id by matching against the pool. Live's
+    # Python API compares Groove objects by identity, so == is fine here;
+    # we fall back to a None id (but keep the name) if the clip's groove
+    # somehow isn't in the current pool — shouldn't happen in practice but
+    # avoids crashing on an orphan reference.
+    for i, g in enumerate(song.groove_pool.grooves):
+        if g == clip_groove:
+            return {"groove_id": i, "groove_name": str(g.name)}
+    return {"groove_id": None, "groove_name": str(clip_groove.name)}
+
+
+@register("get_song_groove_amount")
+def get_song_groove_amount(song, params):
+    """Read the master groove amount dial (Live 11+)."""
+    from .version_detect import has_feature
+    if not has_feature("groove_pool_api"):
+        raise RuntimeError("Groove pool API requires Live 11+.")
+    return {"groove_amount": float(song.groove_amount)}
+
+
+@register("set_song_groove_amount")
+def set_song_groove_amount(song, params):
+    """Set the master groove amount dial (Live 11+).
+
+    Range: 0.0-1.31. Live's spec nominally goes to 1.0 but the
+    exposed property clamps at roughly 1.31 internally; we accept
+    the full exposed range so scripts can match UI nudges exactly.
+    """
+    from .version_detect import has_feature
+    if not has_feature("groove_pool_api"):
+        raise RuntimeError("Groove pool API requires Live 11+.")
+    amount = float(params["amount"])
+    if not 0.0 <= amount <= 1.31:
+        raise ValueError("amount must be 0.0-1.31")
+    song.groove_amount = amount
+    return {"groove_amount": float(song.groove_amount)}

package/remote_script/LivePilot/scales.py

@@ -0,0 +1,138 @@
+"""
+LivePilot — Song-level scale handlers (Live 12.0+).
+
+Exposes Song.root_note / scale_mode / scale_name / scale_intervals
+and the Song.scale_names list via the LivePilot TCP protocol.
+
+All four props shipped in Live 12.0 when Scale Mode was introduced.
+Gated behind the `song_scale_api` feature flag for defensive safety
+on older versions, even though we target 12.3.6.
+"""
+
+from .router import register
+
+
+@register("get_song_scale")
+def get_song_scale(song, params):
+    """Read Live's current Scale Mode state."""
+    from .version_detect import has_feature
+    if not has_feature("song_scale_api"):
+        raise RuntimeError("Song scale API requires Live 12.0+.")
+    return {
+        "root_note": int(song.root_note),
+        "scale_mode": bool(song.scale_mode),
+        "scale_name": str(song.scale_name),
+        "scale_intervals": list(song.scale_intervals),
+        "available_scales": list(song.scale_names),
+    }
+
+
+@register("set_song_scale")
+def set_song_scale(song, params):
+    """Set both root_note (0-11) and scale_name atomically."""
+    from .version_detect import has_feature
+    if not has_feature("song_scale_api"):
+        raise RuntimeError("Song scale API requires Live 12.0+.")
+    root = int(params["root_note"])
+    if not 0 <= root <= 11:
+        raise ValueError("root_note must be 0-11 (C=0, C#=1, ... B=11)")
+    name = str(params["scale_name"])
+    available = list(song.scale_names)
+    if name not in available:
+        raise ValueError(
+            "Unknown scale '%s'. Available: %s" % (name, ", ".join(available))
+        )
+    song.root_note = root
+    song.scale_name = name
+    return {
+        "root_note": int(song.root_note),
+        "scale_name": str(song.scale_name),
+        "scale_intervals": list(song.scale_intervals),
+    }
+
+
+@register("set_song_scale_mode")
+def set_song_scale_mode(song, params):
+    """Enable/disable Scale Mode on the set."""
+    from .version_detect import has_feature
+    if not has_feature("song_scale_api"):
+        raise RuntimeError("Song scale API requires Live 12.0+.")
+    song.scale_mode = bool(params["enabled"])
+    return {"scale_mode": bool(song.scale_mode)}
+
+
+@register("list_available_scales")
+def list_available_scales(song, params):
+    """Return Live's built-in list of scale names."""
+    from .version_detect import has_feature
+    if not has_feature("song_scale_api"):
+        raise RuntimeError("Song scale API requires Live 12.0+.")
+    return {"scales": list(song.scale_names)}
+
+
+@register("get_tuning_system")
+def get_tuning_system(song, params):
+    """Read the current Tuning System state (Live 12.1+).
+
+    Returns name, pseudo-octave size, range, reference pitch,
+    and the full per-degree cent offset table.
+    """
+    from .version_detect import has_feature
+    if not has_feature("tuning_system"):
+        raise RuntimeError("Tuning System requires Live 12.1+.")
+    ts = song.tuning_system
+    return {
+        "name": str(ts.name),
+        "pseudo_octave_in_cents": float(ts.pseudo_octave_in_cents),
+        "lowest_note": int(ts.lowest_note),
+        "highest_note": int(ts.highest_note),
+        "reference_pitch": float(ts.reference_pitch),
+        "note_tunings": list(ts.note_tunings),
+    }
+
+
+@register("set_tuning_reference_pitch")
+def set_tuning_reference_pitch(song, params):
+    """Set the tuning reference pitch in Hz (Live 12.1+)."""
+    from .version_detect import has_feature
+    if not has_feature("tuning_system"):
+        raise RuntimeError("Tuning System requires Live 12.1+.")
+    pitch = float(params["reference_pitch"])
+    if pitch <= 0:
+        raise ValueError("reference_pitch must be > 0 Hz")
+    song.tuning_system.reference_pitch = pitch
+    return {"reference_pitch": float(song.tuning_system.reference_pitch)}
+
+
+@register("set_tuning_note")
+def set_tuning_note(song, params):
+    """Set the cent offset for a single scale degree (Live 12.1+).
+
+    degree:       0-based index into note_tunings
+    cent_offset:  offset in cents from 12-TET (float, any sign)
+    """
+    from .version_detect import has_feature
+    if not has_feature("tuning_system"):
+        raise RuntimeError("Tuning System requires Live 12.1+.")
+    ts = song.tuning_system
+    degree = int(params["degree"])
+    cents = float(params["cent_offset"])
+    tunings = list(ts.note_tunings)
+    if not 0 <= degree < len(tunings):
+        raise IndexError(
+            "degree %d out of range (0..%d)" % (degree, len(tunings) - 1)
+        )
+    tunings[degree] = cents
+    ts.note_tunings = tunings
+    return {"degree": degree, "cent_offset": cents}
+
+
+@register("reset_tuning_system")
+def reset_tuning_system(song, params):
+    """Reset all per-degree tuning offsets to 12-TET (Live 12.1+)."""
+    from .version_detect import has_feature
+    if not has_feature("tuning_system"):
+        raise RuntimeError("Tuning System requires Live 12.1+.")
+    ts = song.tuning_system
+    ts.note_tunings = [0.0] * len(ts.note_tunings)
+    return {"note_tunings": list(ts.note_tunings)}