tonable 0.5.2__py3-none-any.whl

tonable/remote_script/Tonable/reading.py

@@ -0,0 +1,289 @@
+"""read_set, read_track and read_device. Main thread only; nothing here changes Live."""
+
+import difflib
+
+from . import objects, params
+from .server import CommandError
+
+# Device.type
+DEVICE_KINDS = {1: "instrument", 2: "audio_effect", 4: "midi_effect"}
+
+
+def read_set(song):
+    """The Set at a glance: transport, tracks, returns, scenes and their clips."""
+    tracks = list(song.tracks)
+    scenes = []
+    for s, scene in enumerate(song.scenes):
+        entry = {"index": s, "name": scene.name}
+        if _get(scene, "tempo_enabled", False):
+            entry["tempo"] = scene.tempo
+        clips = {}
+        for t, track in enumerate(tracks):
+            slots = list(track.clip_slots)
+            if s < len(slots) and slots[s].has_clip:
+                clips[f"t{t}"] = slots[s].clip.name
+        entry["clips"] = clips
+        scenes.append(entry)
+    return {
+        "tempo": song.tempo,
+        "time_signature": f"{song.signature_numerator}/{song.signature_denominator}",
+        "is_playing": bool(song.is_playing),
+        "loop": {
+            "on": bool(song.loop),
+            "start_beats": song.loop_start,
+            "length_beats": song.loop_length,
+        },
+        "tracks": [_track_summary(song, track) for track in tracks],
+        "returns": [
+            {"path": "r" + objects.return_letter(i), "name": track.name}
+            for i, track in enumerate(song.return_tracks)
+        ],
+        "master": {"path": "m", "name": song.master_track.name},
+        "scenes": scenes,
+        "locators": [
+            {"name": cue.name, "time_beats": cue.time} for cue in song.cue_points
+        ],
+    }
+
+
+def read_track(song, ref):
+    """One track: mixer, routing, the device tree and its clips."""
+    track = objects.track(song, ref)
+    path = objects.track_path(song, track) if ref != "m" else "m"
+    out = _track_summary(song, track)
+    out["path"] = path
+    out["mixer"] = _mixer(song, track)
+    routing = _routing(track)
+    if routing:
+        out["routing"] = routing
+    out["devices"] = _devices(track, path)
+    clips = [
+        _clip(i, slot.clip)
+        for i, slot in enumerate(_get(track, "clip_slots", []) or [])
+        if slot.has_clip
+    ]
+    if path.startswith("t"):
+        out["session_clips"] = clips
+        out["arrangement_clips"] = [
+            {"name": c.name, "start_beats": c.start_time, "end_beats": c.end_time}
+            for c in _get(track, "arrangement_clips", []) or []
+        ]
+    return out
+
+
+def read_device(song, path, wanted=None, all_params=False):
+    """A device, chain or pad. Racks show their macros; other devices all parameters.
+
+    `wanted` lists parameter names to show (any device); `all_params` shows every
+    parameter of a rack too.
+    """
+    kind, obj, path = objects.resolve(song, path)
+    if kind == "track":
+        raise CommandError(
+            "bad_address",
+            f"{path} is a track: use read_track, or {path}/d0 for a device",
+        )
+    if kind in ("chain", "pad"):
+        out = {"path": path, "kind": kind, "name": obj.name}
+        if kind == "pad":
+            out["note"] = objects.note_name(obj.note)
+        for flag in ("mute", "solo"):
+            if _get(obj, flag, False):
+                out[flag] = True
+        if kind == "chain":
+            out["devices"] = _devices(obj, path)
+        else:
+            out["chains"] = _chains(obj, path)
+        return out
+
+    device = obj
+    plist = list(device.parameters)
+    out = {"path": path, **_device_head(device)}
+    if plist:
+        out["on"] = _is_on(plist[0])
+    is_rack = bool(_get(device, "can_have_chains", False))
+    if is_rack:
+        out["macros"] = _macros(device, plist)
+        out["chains"] = _chains(device, path)
+    if wanted:
+        out["parameters"] = _pick(plist, wanted)
+    elif all_params or not is_rack:
+        # Parameter 0 is Device On, already shown as "on".
+        out["parameters"] = [params.describe(p, i) for i, p in enumerate(plist) if i]
+    return out
+
+
+# --- pieces ------------------------------------------------------------------
+
+
+def _track_summary(song, track):
+    out = {"path": objects.track_path(song, track), "name": track.name}
+    out["kind"] = _track_kind(track)
+    for flag in ("mute", "solo", "arm"):
+        if _get(track, flag, False):
+            out[flag] = True
+    if _get(track, "is_grouped", False) and track.group_track is not None:
+        out["group"] = objects.track_path(song, track.group_track)
+    devices = list(track.devices)
+    if devices:
+        out["device_names"] = [d.name for d in devices]
+    return out
+
+
+def _track_kind(track):
+    if _get(track, "is_foldable", False):
+        return "group"
+    if _get(track, "has_midi_input", False):
+        return "midi"
+    if _get(track, "has_audio_input", False):
+        return "audio"
+    return "return_or_master"
+
+
+def _mixer(song, track):
+    mixer = track.mixer_device
+    out = {
+        "volume": params.display(mixer.volume),
+        "pan": params.display(mixer.panning),
+    }
+    sends = list(_get(mixer, "sends", []) or [])
+    if sends:
+        out["sends"] = [
+            {"return": objects.return_letter(i), "level": params.display(send)}
+            for i, send in enumerate(sends)
+        ]
+    return out
+
+
+def _routing(track):
+    out = {}
+    for key, attr in (
+        ("input", "input_routing_type"),
+        ("output", "output_routing_type"),
+    ):
+        value = _get(track, attr, None)
+        name = _get(value, "display_name", None)
+        if name:
+            out[key] = name
+    return out
+
+
+def _clip(slot, clip):
+    out = {"slot": slot, "name": clip.name, "length_beats": clip.length}
+    out["type"] = "midi" if clip.is_midi_clip else "audio"
+    if clip.looping:
+        out["looping"] = True
+    if clip.is_playing:
+        out["playing"] = True
+    return out
+
+
+def _device_head(device):
+    out = {"name": device.name, "class": device.class_name}
+    kind = DEVICE_KINDS.get(int(_get(device, "type", 0)))
+    if kind:
+        out["kind"] = kind
+    if _get(device, "can_have_drum_pads", False):
+        out["rack"] = "drum_rack"
+    elif _get(device, "can_have_chains", False):
+        out["rack"] = "rack"
+    return out
+
+
+def _devices(holder, prefix):
+    """The device tree below a track or chain, with racks opened up."""
+    out = []
+    for i, device in enumerate(holder.devices):
+        path = f"{prefix}/d{i}"
+        entry = {"path": path, **_device_head(device)}
+        plist = list(device.parameters)
+        if plist and not _is_on(plist[0]):
+            entry["on"] = False
+        if _get(device, "can_have_chains", False):
+            entry["chains"] = _chains(device, path)
+        out.append(entry)
+    return out
+
+
+def _chains(device, path):
+    """Chains of a rack, or the filled pads of a Drum Rack, each with its devices."""
+    if _get(device, "can_have_drum_pads", False):
+        pads = []
+        for pad in device.drum_pads:
+            chains = list(pad.chains)
+            if not chains:
+                continue
+            pad_path = f"{path}/p{objects.note_name(pad.note)}"
+            entry = {
+                "path": pad_path,
+                "name": pad.name,
+                "note": objects.note_name(pad.note),
+                "devices": _devices(chains[0], pad_path + "/c0"),
+            }
+            if len(chains) > 1:
+                entry["chain_count"] = len(chains)
+            pads.append(entry)
+        return pads
+    out = []
+    for c, chain in enumerate(_get(device, "chains", []) or []):
+        chain_path = f"{path}/c{c}"
+        out.append(
+            {
+                "path": chain_path,
+                "name": chain.name,
+                "devices": _devices(chain, chain_path),
+            }
+        )
+    return out
+
+
+def _macros(rack, plist):
+    """The rack's visible, mapped macro knobs (Live 12 racks have up to 16)."""
+    macros = plist[1:]
+    visible = _get(rack, "visible_macro_count", len(macros))
+    mapped = list(_get(rack, "macros_mapped", []) or [True] * len(macros))
+    out = []
+    for i, param in enumerate(macros[:visible]):
+        if i < len(mapped) and mapped[i]:
+            out.append(params.describe(param, i + 1))
+    return out
+
+
+def _pick(plist, wanted):
+    """Parameters by name (case-insensitive), with close matches for typos."""
+    by_name = {}
+    for i, p in enumerate(plist):
+        by_name.setdefault(p.name.casefold(), (i, p))
+    out = []
+    for name in wanted:
+        hit = by_name.get(str(name).strip().casefold())
+        if hit:
+            out.append(params.describe(hit[1], hit[0]))
+        else:
+            out.append(
+                {
+                    "name": name,
+                    "error": "no such parameter",
+                    "similar": _similar(name, plist),
+                }
+            )
+    return out
+
+
+def _similar(name, plist):
+    # difflib's defaults: up to 3 names, similarity 0.6 or more.
+    return difflib.get_close_matches(str(name), [p.name for p in plist])
+
+
+def _is_on(device_on):
+    """Parameter 0 of every device is Device On, quantized Off/On."""
+    return device_on.value > device_on.min
+
+
+def _get(obj, name, default=None):
+    """An optional Live property. Live raises RuntimeError, not AttributeError, for
+    some that a track type lacks (the master's mute, a return's arm)."""
+    try:
+        return getattr(obj, name)
+    except Exception:
+        return default

tonable/remote_script/Tonable/server.py

@@ -0,0 +1,347 @@
+"""The Remote Script's socket side: loopback only, a key, one JSON message per line.
+
+Socket threads only read and write. Every command runs on Live's main thread, which
+calls `run_pending` from `update_display`. A command that Live hasn't started when its
+time is up is cancelled, so it can never run late and reorder edits (an idea from
+ableton-live-mcp).
+
+The protocol limits are documented in docs/plan.md. The MCP server keeps the same
+values in src/tonable/bridge.py; tests/test_bridge.py checks that they match.
+"""
+
+import hmac
+import json
+import os
+import queue
+import secrets
+import socket
+import threading
+import time
+import traceback
+
+# Fixed: never read from settings or the environment.
+HOST = "127.0.0.1"
+AUTH_TIMEOUT = 3.0
+DEFAULT_TIMEOUT = 10.0
+LONG_TIMEOUT = 30.0
+MAX_MESSAGE_BYTES = 10 * 1024 * 1024
+KEY_BYTES = 32
+SESSION_PATH = os.path.expanduser("~/.tonable/session.json")
+
+# A web page can make a browser send these to a loopback port; we never answer them.
+HTTP_METHODS = (
+    b"GET ",
+    b"POST ",
+    b"PUT ",
+    b"HEAD ",
+    b"DELETE ",
+    b"OPTIONS ",
+    b"PATCH ",
+    b"CONNECT ",
+    b"TRACE ",
+)
+
+
+class CommandError(Exception):
+    """An error the client should see as is: `code` for programs, message for people."""
+
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+
+
+class MessageTooLarge(Exception):
+    pass
+
+
+class LineReader:
+    """Reads newline-terminated messages, each at most MAX_MESSAGE_BYTES."""
+
+    def __init__(self, sock):
+        self._sock = sock
+        self._buffer = bytearray()
+
+    def peek_start(self, size):
+        """Up to `size` first bytes, without consuming them."""
+        while len(self._buffer) < size and b"\n" not in self._buffer:
+            chunk = self._sock.recv(65536)
+            if not chunk:
+                break
+            self._buffer += chunk
+        return bytes(self._buffer[:size])
+
+    def read_line(self):
+        """The next message without its newline, or None when the peer closed."""
+        while True:
+            end = self._buffer.find(b"\n")
+            if end >= 0:
+                line = bytes(self._buffer[:end])
+                del self._buffer[: end + 1]
+                return line
+            if len(self._buffer) > MAX_MESSAGE_BYTES:
+                raise MessageTooLarge()
+            chunk = self._sock.recv(65536)
+            if not chunk:
+                return None
+            self._buffer += chunk
+
+
+def encode(message):
+    return json.dumps(message, ensure_ascii=False, default=str).encode("utf-8") + b"\n"
+
+
+class Job:
+    """One command waiting for Live's main thread."""
+
+    def __init__(self, handler, params):
+        self.handler = handler
+        self.params = params
+        self.state = "queued"  # queued -> running -> done, or queued -> cancelled
+        self.lock = threading.Lock()
+        self.done = threading.Event()
+        self.reply = None
+
+    def run(self, log):
+        with self.lock:
+            if self.state != "queued":
+                return
+            self.state = "running"
+        try:
+            self.reply = {"ok": True, "result": self.handler(self.params)}
+        except CommandError as err:
+            self.reply = {"ok": False, "code": err.code, "error": str(err)}
+        except Exception as err:
+            log("command failed:\n" + traceback.format_exc())
+            self.reply = {
+                "ok": False,
+                "code": "internal",
+                "error": f"{type(err).__name__}: {err}",
+            }
+        with self.lock:
+            self.state = "done"
+        self.done.set()
+
+    def wait(self, timeout):
+        """The reply, or a timeout error that says whether Live changed anything."""
+        if self.done.wait(timeout):
+            return self.reply
+        with self.lock:
+            if self.state == "queued":
+                self.state = "cancelled"
+                return {
+                    "ok": False,
+                    "code": "timeout_not_started",
+                    "error": (
+                        f"Live did not start the command within {timeout:g} s, "
+                        "so nothing changed. A dialog may be open in Live."
+                    ),
+                }
+        return {
+            "ok": False,
+            "code": "timeout_running",
+            "error": (
+                f"The command is still running in Live after {timeout:g} s. It may "
+                "still finish: read the state before repeating it."
+            ),
+        }
+
+
+class BridgeServer:
+    """Listens on a free loopback port and hands commands to Live's main thread.
+
+    `commands` maps a command name to a function of `params`; `hello` is extra data
+    for the reply to a good key.
+    """
+
+    def __init__(self, commands, hello, log, session_path=None):
+        self._commands = commands
+        self._hello = hello
+        self._log = log
+        self._session_path = session_path or SESSION_PATH
+        self._jobs = queue.Queue()
+        self._clients = set()
+        self._clients_lock = threading.Lock()
+        self._listener = None
+        self._running = False
+        self.port = None
+        self.key = None
+
+    # --- lifecycle (main thread) ---------------------------------------
+
+    def start(self):
+        listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        listener.bind((HOST, 0))
+        listener.listen()
+        self._listener = listener
+        self.port = listener.getsockname()[1]
+        self.key = secrets.token_hex(KEY_BYTES)
+        self._write_session()
+        self._running = True
+        threading.Thread(
+            target=self._accept_loop, name="Tonable accept", daemon=True
+        ).start()
+
+    def stop(self):
+        self._running = False
+        if self._listener is not None:
+            try:
+                self._listener.close()
+            except OSError:
+                pass
+        with self._clients_lock:
+            clients = list(self._clients)
+        for conn in clients:
+            try:
+                conn.shutdown(socket.SHUT_RDWR)
+                conn.close()
+            except OSError:
+                pass
+        self._remove_session()
+        # Wake any socket thread still waiting on a job.
+        self.run_pending(cancel=True)
+
+    def run_pending(self, cancel=False):
+        """Run every queued command. Live's main thread calls this on each tick."""
+        while True:
+            try:
+                job = self._jobs.get_nowait()
+            except queue.Empty:
+                return
+            if cancel:
+                with job.lock:
+                    if job.state == "queued":
+                        job.state = "cancelled"
+                        job.reply = {
+                            "ok": False,
+                            "code": "stopped",
+                            "error": "Tonable was switched off in Live",
+                        }
+                        job.done.set()
+                continue
+            job.run(self._log)
+
+    # --- session file ---------------------------------------------------
+
+    def _write_session(self):
+        folder = os.path.dirname(self._session_path)
+        os.makedirs(folder, mode=0o700, exist_ok=True)
+        os.chmod(folder, 0o700)
+        data = {
+            "port": self.port,
+            "key": self.key,
+            "pid": os.getpid(),
+            "started_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        }
+        data.update(self._hello)
+        tmp = self._session_path + ".tmp"
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f)
+        os.replace(tmp, self._session_path)
+
+    def _remove_session(self):
+        """Remove the session file, unless another Live has written its own since."""
+        try:
+            with open(self._session_path, encoding="utf-8") as f:
+                data = json.load(f)
+            if data.get("port") == self.port and data.get("key") == self.key:
+                os.remove(self._session_path)
+        except (OSError, ValueError):
+            pass
+
+    # --- socket threads -------------------------------------------------
+
+    def _accept_loop(self):
+        while self._running:
+            try:
+                conn, _ = self._listener.accept()
+            except OSError:
+                return
+            threading.Thread(
+                target=self._serve, args=(conn,), name="Tonable client", daemon=True
+            ).start()
+
+    def _serve(self, conn):
+        with self._clients_lock:
+            self._clients.add(conn)
+        try:
+            reader = LineReader(conn)
+            if self._authenticate(conn, reader):
+                self._command_loop(conn, reader)
+        except (OSError, MessageTooLarge, ValueError):
+            pass
+        finally:
+            with self._clients_lock:
+                self._clients.discard(conn)
+            try:
+                conn.close()
+            except OSError:
+                pass
+
+    def _authenticate(self, conn, reader):
+        conn.settimeout(AUTH_TIMEOUT)
+        start = reader.peek_start(max(len(m) for m in HTTP_METHODS))
+        if any(start.startswith(m) for m in HTTP_METHODS):
+            self._log("closed an HTTP request on the bridge port")
+            return False
+        line = reader.read_line()
+        if line is None:
+            return False
+        message = json.loads(line)
+        key = message.get("key") if isinstance(message, dict) else None
+        if not isinstance(key, str) or not hmac.compare_digest(key, self.key):
+            conn.sendall(encode({"ok": False, "code": "bad_key", "error": "wrong key"}))
+            return False
+        conn.sendall(encode(dict(self._hello, ok=True)))
+        conn.settimeout(None)
+        return True
+
+    def _command_loop(self, conn, reader):
+        while self._running:
+            try:
+                line = reader.read_line()
+            except MessageTooLarge:
+                conn.sendall(
+                    encode(
+                        {
+                            "ok": False,
+                            "code": "too_large",
+                            "error": f"message over {MAX_MESSAGE_BYTES} bytes",
+                        }
+                    )
+                )
+                return
+            if line is None:
+                return
+            conn.sendall(encode(self._handle(line)))
+
+    def _handle(self, line):
+        try:
+            message = json.loads(line)
+        except ValueError:
+            return {"ok": False, "code": "bad_json", "error": "message is not JSON"}
+        if not isinstance(message, dict):
+            return {
+                "ok": False,
+                "code": "bad_json",
+                "error": "message is not an object",
+            }
+        reply = {"id": message.get("id")}
+        name = message.get("command")
+        handler = self._commands.get(name)
+        if handler is None:
+            reply.update(
+                ok=False,
+                code="unknown_command",
+                error=f"unknown command {name!r}",
+            )
+            return reply
+        params = message.get("params") or {}
+        if not isinstance(params, dict):
+            reply.update(ok=False, code="bad_params", error="params must be an object")
+            return reply
+        timeout = LONG_TIMEOUT if message.get("long") is True else DEFAULT_TIMEOUT
+        job = Job(handler, params)
+        self._jobs.put(job)
+        reply.update(job.wait(timeout))
+        return reply