tonable 0.5.2__py3-none-any.whl

tonable/remote_script/Tonable/dispatch.py

@@ -0,0 +1,160 @@
+"""The command table: what the MCP server may ask Live to do. Main thread only."""
+
+import importlib
+import sys
+
+# Reload every command module that is already loaded before importing them. A
+# running Live reloads this module last (see __init__._reload), and the list in an
+# older __init__ may not know the newer modules.
+MODULES = (
+    "version",
+    "params",
+    "objects",
+    "reading",
+    "song",
+    "clips",
+    "edit",
+    "devices",
+    "library",
+    "envelopes",
+    "arrangement",
+)
+for _name in MODULES:
+    _module = sys.modules.get(f"{__package__}.{_name}")
+    if _module is not None:
+        importlib.reload(_module)
+
+from . import (  # noqa: E402
+    arrangement,
+    clips,
+    devices,
+    edit,
+    envelopes,
+    library,
+    reading,
+    song,
+)
+from .server import CommandError  # noqa: E402
+from .version import VERSION  # noqa: E402
+
+
+def commands(surface):
+    """Command name -> function of `params`, bound to the running control surface."""
+    table = {
+        "status": lambda params: status(surface),
+        "read_set": lambda params: reading.read_set(surface.song),
+        "read_track": lambda params: reading.read_track(
+            surface.song, _required(params, "track")
+        ),
+        "read_device": lambda params: reading.read_device(
+            surface.song,
+            _required(params, "target"),
+            wanted=params.get("params") or None,
+            all_params=bool(params.get("all_params")),
+        ),
+        "read_clip": lambda params: clips.read_clip(
+            surface.song, _required(params, "track"), params.get("slot")
+        ),
+        "write_clip": lambda params: clips.write_clip(surface.song, params),
+        "undo": lambda params: song.undo(surface.song, params),
+        "transport": lambda params: song.transport(surface.song, params),
+        "update_set": lambda params: song.update_set(surface.song, params),
+        "scene": lambda params: song.scene(surface.song, params),
+        "edit_notes": lambda params: clips.edit_notes(surface.song, params),
+        "create_track": lambda params: edit.create_track(surface.song, params),
+        "update_track": lambda params: edit.update_track(surface.song, params),
+        "delete": lambda params: edit.delete(surface.song, params),
+        "duplicate": lambda params: edit.duplicate(surface.song, params),
+        "set_device_params": lambda params: devices.set_device_params(
+            surface.song, params
+        ),
+        "update_device": lambda params: devices.update_device(surface.song, params),
+        "find_in_library": lambda params: library.find_in_library(params),
+        "load_device": lambda params: library.load_device(surface.song, params),
+        "read_envelope": lambda params: envelopes.read_envelope(surface.song, params),
+        "write_envelope": lambda params: envelopes.write_envelope(surface.song, params),
+        "arrangement": lambda params: arrangement.arrangement(surface.song, params),
+    }
+    table["batch"] = lambda params: batch(surface.song, table, params)
+    return table
+
+
+# Never inside a batch: they would nest batches or swap the table mid-run.
+NOT_IN_BATCH = ("batch", "reload")
+
+
+def batch(song_, table, params):
+    """Run several commands in order as one undo step; each gets its own result.
+
+    A failed action does not stop the rest unless stop_on_error is set.
+    """
+    actions = params.get("actions")
+    if isinstance(actions, dict):
+        actions = [actions]
+    if not isinstance(actions, list) or not actions:
+        raise CommandError(
+            "bad_params", 'actions is required: [{"command": ..., "params": {...}}]'
+        )
+    stop = bool(params.get("stop_on_error"))
+    results = []
+    with song.undo_step(song_):
+        for i, action in enumerate(actions):
+            if not isinstance(action, dict):
+                results.append(
+                    {"index": i, "ok": False, "error": "an action is an object"}
+                )
+                continue
+            name = action.get("command") or action.get("tool")
+            handler = None if name in NOT_IN_BATCH else table.get(name)
+            if handler is None:
+                results.append(
+                    {"index": i, "ok": False, "error": f"unknown command {name!r}"}
+                )
+            else:
+                try:
+                    out = handler(action.get("params") or action.get("args") or {})
+                    results.append(
+                        {"index": i, "command": name, "ok": True, "result": out}
+                    )
+                except CommandError as err:
+                    results.append(
+                        {
+                            "index": i,
+                            "command": name,
+                            "ok": False,
+                            "code": err.code,
+                            "error": str(err),
+                        }
+                    )
+            if stop and not results[-1]["ok"]:
+                break
+    return {
+        "ran": len(results),
+        "failed": sum(not r["ok"] for r in results),
+        "results": results,
+    }
+
+
+def status(surface):
+    """Versions and a one-line picture of the open Set, for live_status and doctor."""
+    song = surface.song
+    signature = f"{song.signature_numerator}/{song.signature_denominator}"
+    return {
+        "live_version": surface.live_version,
+        "script_version": VERSION,
+        "set": {
+            "tempo": song.tempo,
+            "time_signature": signature,
+            "tracks": len(song.tracks),
+            "return_tracks": len(song.return_tracks),
+            "scenes": len(song.scenes),
+            "is_playing": bool(song.is_playing),
+        },
+    }
+
+
+def _required(params, name):
+    value = params.get(name)
+    if value is None or str(value).strip() == "":
+        raise CommandError("bad_params", f"{name} is required")
+    return str(value).strip()

tonable/remote_script/Tonable/edit.py

@@ -0,0 +1,281 @@
+"""Tracks and the objects in them: create_track, update_track, delete, duplicate.
+
+delete and duplicate take one address for anything they can act on:
+    t0, rA          a track or return track
+    t0/d1, ...      a device (inside racks too)
+    t0/s2           the clip in slot 2 of t0
+    s2              scene 2
+"""
+
+import re
+
+from . import objects, params
+from .server import CommandError
+from .song import find_scene, undo_step
+
+TRACK_KINDS = ("midi", "audio", "return")
+
+
+def create_track(song, p):
+    kind = p.get("kind") or "midi"
+    if kind not in TRACK_KINDS:
+        raise CommandError("bad_params", "kind must be midi, audio or return")
+    with undo_step(song):
+        if kind == "return":
+            song.create_return_track()
+            track = list(song.return_tracks)[-1]
+        else:
+            tracks = list(song.tracks)
+            index = p.get("index")
+            index = len(tracks) if index in (None, "", -1) else int(index)
+            if not 0 <= index <= len(tracks):
+                raise CommandError("not_found", f"index must be 0-{len(tracks)}")
+            create = (
+                song.create_midi_track if kind == "midi" else song.create_audio_track
+            )
+            create(index)
+            track = list(song.tracks)[index]
+        if p.get("name"):
+            track.name = str(p["name"])
+    return {
+        "created": objects.track_path(song, track),
+        "name": track.name,
+        "kind": kind,
+    }
+
+
+def update_track(song, p):
+    """Change only the given fields; one line per field in the answer."""
+    track = objects.track(song, p.get("track") or "")
+    path = objects.track_path(song, track) if p.get("track") != "m" else "m"
+    results = []
+    with undo_step(song):
+        for field in ("name", "color_index", "mute", "solo", "arm"):
+            if p.get(field) in (None, ""):
+                continue
+            results.append(_set_field(track, field, p[field]))
+        mixer = track.mixer_device
+        if p.get("volume_db") not in (None, ""):
+            results.append(_set_param("volume", mixer.volume, _db(p["volume_db"])))
+        if p.get("pan") not in (None, ""):
+            results.append(_set_param("pan", mixer.panning, _pan(p["pan"])))
+        for send in _sends(p.get("sends")):
+            results.append(_set_send(song, mixer, send))
+        for key, attr in (
+            ("input", "input_routing_type"),
+            ("output", "output_routing_type"),
+        ):
+            if p.get(key) not in (None, ""):
+                results.append(_set_routing(track, key, attr, str(p[key])))
+    if not results:
+        raise CommandError("bad_params", "nothing to change: give at least one field")
+    return {"track": path, "name": track.name, "results": results}
+
+
+def delete(song, p):
+    """Delete after checking `name` against the object's name, as one undo step."""
+    target = str(p.get("target") or "").strip()
+    confirm = str(p.get("name") or "").strip()
+    kind, obj, holder, index, path = _locate(song, target)
+    actual = obj.name if kind != "clip" else obj.clip.name
+    if not confirm or confirm.casefold() != actual.strip().casefold():
+        raise CommandError(
+            "confirm_name",
+            f"to delete {path} give its name exactly: {actual!r}",
+        )
+    with undo_step(song):
+        if kind == "track":
+            song.delete_track(index)
+        elif kind == "return":
+            song.delete_return_track(index)
+        elif kind == "device":
+            holder.delete_device(index)
+        elif kind == "clip":
+            obj.delete_clip()
+        elif kind == "scene":
+            song.delete_scene(index)
+    return {"deleted": path, "kind": kind, "name": actual}
+
+
+def duplicate(song, p):
+    target = str(p.get("target") or "").strip()
+    kind, obj, holder, index, path = _locate(song, target)
+    with undo_step(song):
+        if kind == "track":
+            song.duplicate_track(index)
+            return {"duplicated": path, "copy": f"t{index + 1}", "name": obj.name}
+        if kind == "scene":
+            song.duplicate_scene(index)
+            return {"duplicated": path, "copy": f"s{index + 1}", "name": obj.name}
+        if kind == "clip":
+            to = p.get("to_slot")
+            track = holder
+            if to in (None, ""):
+                track.duplicate_clip_slot(index)
+                to = index + 1
+            else:
+                slots = list(track.clip_slots)
+                to = int(to)
+                if not 0 <= to < len(slots):
+                    raise CommandError(
+                        "not_found", f"no slot {to}: slots 0-{len(slots) - 1}"
+                    )
+                if slots[to].has_clip:
+                    raise CommandError(
+                        "slot_taken",
+                        f"slot {to} holds {slots[to].clip.name!r}; delete it first",
+                    )
+                obj.duplicate_clip_to(slots[to])
+            copy = path.rsplit("/", 1)[0] + f"/s{to}"
+            return {"duplicated": path, "copy": copy, "name": obj.clip.name}
+        if kind == "device":
+            dup = getattr(holder, "duplicate_device", None)
+            if dup is None:
+                raise CommandError(
+                    "not_supported",
+                    "Live's API cannot duplicate a device; load it again",
+                )
+            dup(index)
+            copy = path.rsplit("/", 1)[0] + f"/d{index + 1}"
+            return {"duplicated": path, "copy": copy, "name": obj.name}
+    raise CommandError("not_supported", f"cannot duplicate a {kind}")
+
+
+# --- addresses -----------------------------------------------------------------
+
+
+def _locate(song, target):
+    """(kind, object, holder, index, path) for a delete/duplicate address."""
+    if not target:
+        raise CommandError(
+            "bad_params", "target is required, e.g. t0, t0/d1, t0/s2, s2"
+        )
+    scene = re.fullmatch(r"[sS](\d+)", target)
+    if scene:
+        index, obj = find_scene(song, scene.group(1))
+        return "scene", obj, song, index, f"s{index}"
+    clip = re.fullmatch(r"(.+)/[sS](\d+)", target)
+    if clip:
+        track = objects.track(song, clip.group(1))
+        path = objects.track_path(song, track)
+        slots = list(track.clip_slots)
+        index = int(clip.group(2))
+        if not path.startswith("t") or not 0 <= index < len(slots):
+            raise CommandError("not_found", f"no slot {index} on {path}")
+        if not slots[index].has_clip:
+            raise CommandError("not_found", f"{path}/s{index} is empty")
+        return "clip", slots[index], track, index, f"{path}/s{index}"
+    kind, obj, path = objects.resolve(song, target)
+    if kind == "track":
+        if path == "m":
+            raise CommandError(
+                "bad_target", "the master track cannot be deleted or copied"
+            )
+        if path.startswith("r"):
+            return "return", obj, song, ord(path[1]) - ord("A"), path
+        return "track", obj, song, int(path[1:]), path
+    if kind == "device":
+        parent_path, last = path.rsplit("/", 1)
+        _, holder, _ = objects.resolve(song, parent_path)
+        return "device", obj, holder, int(last[1:]), path
+    raise CommandError(
+        "bad_target", f"{path} is a {kind}; give a track, device, clip or scene"
+    )
+
+
+# --- fields --------------------------------------------------------------------
+
+
+def _set_field(track, field, value):
+    try:
+        if field in ("mute", "solo", "arm"):
+            setattr(track, field, _bool(value))
+        elif field == "color_index":
+            track.color_index = int(value)
+        else:
+            track.name = str(value)
+    except Exception as err:
+        return {"field": field, "error": _why(err)}
+    return {"field": field, "now": getattr(track, field)}
+
+
+def _set_param(field, param, text):
+    try:
+        raw, note = params.value_for(param, text)
+        param.value = raw
+    except CommandError as err:
+        return {"field": field, "error": str(err)}
+    except Exception as err:
+        return {"field": field, "error": _why(err)}
+    out = {"field": field, "now": params.display(param)}
+    if note:
+        out["note"] = note
+    return out
+
+
+def _set_send(song, mixer, send):
+    letter = str(send.get("return") or "").strip().upper()
+    sends = list(mixer.sends)
+    i = ord(letter) - ord("A") if len(letter) == 1 else -1
+    field = f"send {letter or '?'}"
+    if not 0 <= i < len(sends):
+        have = ", ".join(objects.return_letter(n) for n in range(len(sends))) or "none"
+        return {"field": field, "error": f"no return {letter or '?'}; returns: {have}"}
+    value = send.get("db", send.get("level"))
+    if value in (None, ""):
+        return {"field": field, "error": "give db, e.g. -12 or -inf"}
+    return _set_param(field, sends[i], _db(value))
+
+
+def _set_routing(track, key, attr, wanted):
+    options = list(getattr(track, "available_" + attr + "s", []) or [])
+    names = [o.display_name for o in options]
+    for option in options:
+        if option.display_name.strip().casefold() == wanted.strip().casefold():
+            try:
+                setattr(track, attr, option)
+            except Exception as err:
+                return {"field": key, "error": _why(err)}
+            return {"field": key, "now": getattr(track, attr).display_name}
+    return {"field": key, "error": f"no {key} {wanted!r}; options: {names}"}
+
+
+def _sends(raw):
+    if raw in (None, ""):
+        return []
+    if isinstance(raw, dict):
+        # {"A": -12} or one send object
+        if "return" in raw:
+            return [raw]
+        return [{"return": k, "db": v} for k, v in raw.items()]
+    return [s for s in raw if isinstance(s, dict)]
+
+
+def _db(value):
+    text = str(value).strip()
+    if text.lower() in ("-inf", "inf", "off"):
+        return "-inf dB"
+    return text if text.lower().endswith("db") else text + " dB"
+
+
+def _pan(value):
+    """Pan as Live shows it: C, 25L, 30R; numbers -50 (left) .. 50 (right) too."""
+    text = str(value).strip()
+    if re.fullmatch(r"[+-]?\d+(\.\d*)?", text):
+        number = float(text)
+        if number == 0:
+            return "C"
+        return f"{abs(number):g}{'L' if number < 0 else 'R'}"
+    return text
+
+
+def _bool(value):
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "on", "yes", "1")
+    return bool(value)
+
+
+def _why(err):
+    return (
+        f"Live refused: {err}" if str(err) else f"Live refused ({type(err).__name__})"
+    )

tonable/remote_script/Tonable/envelopes.py

@@ -0,0 +1,195 @@
+"""read_envelope and write_envelope: automation in Session clips. Main thread only.
+
+Live's API reaches envelopes of Session clips only, for mixer and device
+parameters; MIDI CC envelopes are invisible (stage 0: use CC Control's Custom A,
+CC 64 Sustain, for the pedal). To get automation into the Arrangement, copy the clip
+there: Live writes the track automation for its span.
+
+The parameter is one of:
+    volume, pan, send A        the track's mixer
+    t0/d0:Release              a device parameter by name (or index) on this track
+Curves follow Producer Pal's findings: each event's control_coefficients
+(x1, y1, x2, y2) shape the segment it starts, and (0.5, 0.5, 0.5, 0.5) is straight.
+"""
+
+import struct
+
+from . import objects, params
+from .clips import _slot
+from .server import CommandError
+from .song import undo_step
+
+STRAIGHT = (0.5, 0.5, 0.5, 0.5)
+# Reads cover events past the clip end too (Live keeps them). Live refuses larger
+# ranges; this is its own limit for song time, from Track.create_midi_clip's doc.
+LIVE_MAX_BEATS = 1576800.0
+
+
+def read_envelope(song, p):
+    track, clip, param, label = _target(song, p)
+    env = clip.automation_envelope(param)
+    out = {
+        "track": objects.track_path(song, track),
+        "slot": int(p.get("slot")),
+        "parameter": label,
+        "now": params.display(param),
+    }
+    if env is None:
+        out["exists"] = False
+        return out
+    events = list(env.events_in_range(0.0, LIVE_MAX_BEATS))
+    out["exists"] = True
+    out["points"] = [_event_out(env, events, i, param) for i in range(len(events))]
+    return out
+
+
+def write_envelope(song, p):
+    """Replace the envelope with `points` (or clear it), as one undo step."""
+    track, clip, param, label = _target(song, p)
+    raw_points = p.get("points") or []
+    if isinstance(raw_points, dict):
+        raw_points = [raw_points]
+    points = [_point(param, item, i) for i, item in enumerate(raw_points)]
+    if any(b["time"] < a["time"] for a, b in zip(points, points[1:], strict=False)):
+        raise CommandError("bad_params", "point times must not go back")
+    with undo_step(song):
+        if clip.automation_envelope(param) is not None:
+            clip.clear_envelope(param)
+        if points:
+            env = clip.create_automation_envelope(param)
+            if env is None:
+                raise CommandError(
+                    "not_supported", f"Live gives no envelope for {label} in this clip"
+                )
+            _write_events(env, points)
+            param.re_enable_automation()
+    out = read_envelope(song, p)
+    out["written"] = len(points)
+    return out
+
+
+# --- pieces ------------------------------------------------------------------
+
+
+def _target(song, p):
+    track, slot, where = _slot(song, p.get("track"), p.get("slot"))
+    if not slot.has_clip:
+        raise CommandError("not_found", f"{where} is empty")
+    ref = str(p.get("parameter") or "").strip()
+    if not ref:
+        raise CommandError(
+            "bad_params", "parameter is required: volume, pan, send A or t0/d0:Name"
+        )
+    mixer = track.mixer_device
+    low = ref.casefold()
+    if low == "volume":
+        return track, slot.clip, mixer.volume, "volume"
+    if low in ("pan", "panning"):
+        return track, slot.clip, mixer.panning, "pan"
+    if low.startswith("send"):
+        letter = ref[4:].strip().upper()
+        sends = list(mixer.sends)
+        i = ord(letter) - ord("A") if len(letter) == 1 else -1
+        if not 0 <= i < len(sends):
+            raise CommandError(
+                "not_found", f"no {ref}: the Set has {len(sends)} return tracks"
+            )
+        return track, slot.clip, sends[i], f"send {letter}"
+    if ":" not in ref:
+        raise CommandError(
+            "bad_params", f"{ref!r}: use volume, pan, send A or t0/d0:Name"
+        )
+    device_path, name = ref.rsplit(":", 1)
+    kind, device, path = objects.resolve(song, device_path)
+    if kind != "device":
+        raise CommandError("bad_target", f"{path} is not a device")
+    if not path.startswith(objects.track_path(song, track) + "/"):
+        raise CommandError(
+            "bad_target", f"{path} is not on {objects.track_path(song, track)}"
+        )
+    plist = list(device.parameters)
+    name = name.strip()
+    hits = [x for x in plist if x.name.casefold() == name.casefold()]
+    if not hits and name.isdigit() and int(name) < len(plist):
+        hits = [plist[int(name)]]
+    if not hits:
+        raise CommandError("not_found", f"{device.name} has no parameter {name!r}")
+    return track, slot.clip, hits[0], f"{path}:{hits[0].name}"
+
+
+def _point(param, item, i):
+    if not isinstance(item, dict):
+        raise CommandError(
+            "bad_params", f"point {i} must be an object with time and value"
+        )
+    try:
+        time = float(item.get("time", item.get("time_beats")))
+    except (TypeError, ValueError):
+        raise CommandError(
+            "bad_params", f"point {i}: time is required (beats)"
+        ) from None
+    if time < 0:
+        raise CommandError("bad_params", f"point {i}: time must be 0 or more")
+    if item.get("value") in (None, ""):
+        raise CommandError("bad_params", f"point {i}: value is required")
+    raw, _ = params.value_for(param, item["value"])
+    curve = item.get("curve")
+    if curve not in (None, "", []):
+        if not (isinstance(curve, list) and len(curve) == 4):
+            raise CommandError(
+                "bad_params", f"point {i}: curve is 4 numbers x1, y1, x2, y2"
+            )
+        curve = tuple(float(c) for c in curve)
+        if not all(0 <= c <= 1 for c in curve):
+            raise CommandError("bad_params", f"point {i}: curve numbers are 0-1")
+    else:
+        curve = None
+    return {"time": time, "value": raw, "jump": bool(item.get("jump")), "curve": curve}
+
+
+def _write_events(env, points):
+    """Create the events last time first: Live straightens a curve whose segment
+    end doesn't exist yet. A jump is two events at one time: the previous value,
+    then the new one."""
+    from Live.Envelope import EnvelopeEvent, EnvelopeEventControlCoefficients
+
+    events = []
+    previous = None
+    for point in points:
+        if point["jump"] and previous is not None:
+            events.append((point["time"], previous, None))
+        events.append((point["time"], point["value"], point["curve"]))
+        previous = point["value"]
+    groups = []
+    for event in events:
+        if groups and groups[-1][0][0] == event[0]:
+            groups[-1].append(event)
+        else:
+            groups.append([event])
+    for group in reversed(groups):
+        for time, value, curve in group:
+            if curve is None:
+                env.create_event(EnvelopeEvent(time, value))
+            else:
+                coefficients = EnvelopeEventControlCoefficients(*curve)
+                env.create_event(EnvelopeEvent(time, value, coefficients))
+
+
+def _event_out(env, events, i, param):
+    event = events[i]
+    # Two events at one time are a jump: sample just after it for the second.
+    same_time = i > 0 and events[i - 1].time == event.time
+    raw = env.value_at_time(event.time if not same_time else _after(event.time))
+    out = {"time": event.time, "value": raw, "display": param.str_for_value(raw)}
+    c = getattr(event, "control_coefficients", None)
+    if c is not None and (c.x1, c.y1, c.x2, c.y2) != STRAIGHT:
+        out["curve"] = [c.x1, c.y1, c.x2, c.y2]
+    return out
+
+
+def _after(time):
+    """The next time Live can tell apart from `time`: it keeps envelope times as
+    32-bit floats, so step to the next float32, not the next double."""
+    (bits,) = struct.unpack("<I", struct.pack("<f", time))
+    (later,) = struct.unpack("<f", struct.pack("<I", bits + 1))
+    return later