tonable 0.5.2__py3-none-any.whl

tonable/remote_script/Tonable/song.py

@@ -0,0 +1,304 @@
+"""The Set as a whole: undo, transport, update_set and scene. Main thread only."""
+
+from . import objects
+from .server import CommandError
+
+UNDO_ACTIONS = ("undo", "redo")
+TRANSPORT_ACTIONS = (
+    "play",
+    "stop",
+    "continue",
+    "fire_clip",
+    "stop_track",
+    "fire_scene",
+    "stop_all_clips",
+    "jump",
+    "re_enable_automation",
+)
+SCENE_ACTIONS = ("create", "update", "duplicate", "capture")
+
+
+class undo_step:
+    """Everything inside is one step for Cmd+Z in Live.
+
+    Live's undo steps do not nest (a batch's inner step would close the outer one),
+    so only the outermost step talks to Live. Commands run one at a time on Live's
+    main thread, so a plain counter is enough.
+    """
+
+    depth = 0
+
+    def __init__(self, song):
+        self._song = song
+
+    def __enter__(self):
+        if undo_step.depth == 0:
+            begin = getattr(self._song, "begin_undo_step", None)
+            if begin is not None:
+                begin()
+        undo_step.depth += 1
+
+    def __exit__(self, *exc):
+        undo_step.depth -= 1
+        if undo_step.depth == 0:
+            end = getattr(self._song, "end_undo_step", None)
+            if end is not None:
+                end()
+        return False
+
+
+def undo(song, params):
+    action = params.get("action") or "undo"
+    if action not in UNDO_ACTIONS:
+        raise CommandError("bad_params", "action must be undo or redo")
+    can = song.can_undo if action == "undo" else song.can_redo
+    if not can:
+        raise CommandError("nothing_to_" + action, f"there is nothing to {action}")
+    (song.undo if action == "undo" else song.redo)()
+    return {
+        "done": action,
+        "can_undo": bool(song.can_undo),
+        "can_redo": bool(song.can_redo),
+    }
+
+
+def transport(song, params):
+    action = params.get("action")
+    if action not in TRANSPORT_ACTIONS:
+        raise CommandError(
+            "bad_params", "action must be one of: " + ", ".join(TRANSPORT_ACTIONS)
+        )
+    out = {"done": action}
+    if action == "play":
+        song.start_playing()
+    elif action == "stop":
+        song.stop_playing()
+    elif action == "continue":
+        song.continue_playing()
+    elif action == "stop_all_clips":
+        song.stop_all_clips()
+    elif action == "re_enable_automation":
+        song.re_enable_automation()
+    elif action in ("fire_clip", "stop_track"):
+        track = objects.track(song, _need(params, "track"))
+        path = objects.track_path(song, track)
+        if not path.startswith("t"):
+            raise CommandError("bad_target", f"{path} has no clips to launch")
+        if action == "stop_track":
+            track.stop_all_clips()
+        else:
+            slot = _slot(track, params.get("slot"), path)
+            slot.fire()
+            out["clip"] = slot.clip.name if slot.has_clip else None
+        out["track"] = path
+    elif action == "fire_scene":
+        index, scene = find_scene(song, params.get("scene"))
+        scene.fire()
+        out["scene"] = {"index": index, "name": scene.name}
+    elif action == "jump":
+        out.update(_jump(song, params))
+    out["is_playing"] = bool(song.is_playing)
+    return out
+
+
+def update_set(song, params):
+    """Tempo, time signature, loop, metronome, key. Only given fields change."""
+    changed = []
+    with undo_step(song):
+        if _given(params, "tempo"):
+            song.tempo = _number(params["tempo"], "tempo")
+            changed.append("tempo")
+        if _given(params, "time_signature"):
+            num, den = _signature(params["time_signature"])
+            song.signature_numerator = num
+            song.signature_denominator = den
+            changed.append("time_signature")
+        if _given(params, "loop"):
+            song.loop = _bool(params["loop"])
+            changed.append("loop")
+        if _given(params, "loop_start_beats"):
+            song.loop_start = _number(params["loop_start_beats"], "loop_start_beats")
+            changed.append("loop_start_beats")
+        if _given(params, "loop_length_beats"):
+            song.loop_length = _number(params["loop_length_beats"], "loop_length_beats")
+            changed.append("loop_length_beats")
+        if _given(params, "metronome"):
+            song.metronome = _bool(params["metronome"])
+            changed.append("metronome")
+        if _given(params, "root_note"):
+            song.root_note = _root_note(params["root_note"])
+            changed.append("root_note")
+        if _given(params, "scale"):
+            song.scale_name = str(params["scale"]).strip()
+            changed.append("scale")
+    if not changed:
+        raise CommandError("bad_params", "nothing to change: give at least one field")
+    return {"changed": changed, **set_state(song)}
+
+
+def set_state(song):
+    out = {
+        "tempo": song.tempo,
+        "time_signature": f"{song.signature_numerator}/{song.signature_denominator}",
+        "loop": {
+            "on": bool(song.loop),
+            "start_beats": song.loop_start,
+            "length_beats": song.loop_length,
+        },
+        "metronome": bool(getattr(song, "metronome", False)),
+    }
+    root = getattr(song, "root_note", None)
+    if root is not None:
+        out["key"] = {
+            "root": objects.note_name(int(root) % 12 + 60)[:-1],
+            "scale": getattr(song, "scale_name", ""),
+        }
+    return out
+
+
+def scene(song, params):
+    action = params.get("action")
+    if action not in SCENE_ACTIONS:
+        raise CommandError(
+            "bad_params", "action must be one of: " + ", ".join(SCENE_ACTIONS)
+        )
+    with undo_step(song):
+        if action == "create":
+            scenes = list(song.scenes)
+            index = params.get("index")
+            index = len(scenes) if index in (None, "", -1) else int(index)
+            if not 0 <= index <= len(scenes):
+                raise CommandError("not_found", f"index must be 0-{len(scenes)}")
+            song.create_scene(index)
+        elif action == "capture":
+            song.capture_and_insert_scene()
+            index = list(song.scenes).index(song.view.selected_scene)
+        else:
+            index, _ = find_scene(song, params.get("scene"))
+            if action == "duplicate":
+                song.duplicate_scene(index)
+                index += 1
+        target = list(song.scenes)[index]
+        _update_scene(target, params)
+    return {"done": action, **_scene_info(index, target)}
+
+
+def find_scene(song, ref):
+    """A scene by index (0) or exact name ("Verse")."""
+    scenes = list(song.scenes)
+    if ref is None or str(ref).strip() == "":
+        raise CommandError("bad_params", "scene is required: an index from 0 or a name")
+    text = str(ref).strip()
+    if text.lstrip("-").isdigit():
+        index = int(text)
+        if not 0 <= index < len(scenes):
+            raise CommandError(
+                "not_found", f"no scene {index}: scenes are 0-{len(scenes) - 1}"
+            )
+        return index, scenes[index]
+    hits = [
+        i for i, s in enumerate(scenes) if s.name.strip().casefold() == text.casefold()
+    ]
+    if len(hits) != 1:
+        names = [s.name for s in scenes if s.name]
+        what = "no scene named" if not hits else "several scenes named"
+        raise CommandError("not_found", f"{what} {text!r}; scenes: {names}")
+    return hits[0], scenes[hits[0]]
+
+
+# --- helpers -----------------------------------------------------------------
+
+
+def _update_scene(target, params):
+    if _given(params, "name"):
+        target.name = str(params["name"])
+    if _given(params, "color_index"):
+        target.color_index = int(params["color_index"])
+    if _given(params, "tempo"):
+        tempo = params["tempo"]
+        if str(tempo).strip().lower() in ("off", "none", "0"):
+            target.tempo_enabled = False
+        else:
+            target.tempo = _number(tempo, "tempo")
+            target.tempo_enabled = True
+
+
+def _scene_info(index, target):
+    out = {"index": index, "name": target.name}
+    if getattr(target, "tempo_enabled", False):
+        out["tempo"] = target.tempo
+    return out
+
+
+def _jump(song, params):
+    if _given(params, "locator"):
+        name = str(params["locator"]).strip().casefold()
+        cues = [c for c in song.cue_points if c.name.strip().casefold() == name]
+        if not cues:
+            names = [c.name for c in song.cue_points]
+            raise CommandError(
+                "not_found", f"no locator {params['locator']!r}; locators: {names}"
+            )
+        cues[0].jump()
+        return {"locator": cues[0].name, "time_beats": cues[0].time}
+    time = _number(_need(params, "time_beats"), "time_beats")
+    if time < 0:
+        raise CommandError("bad_params", "time_beats must be 0 or more")
+    song.current_song_time = time
+    return {"time_beats": time}
+
+
+def _slot(track, slot_index, path):
+    try:
+        index = int(slot_index)
+    except (TypeError, ValueError):
+        raise CommandError(
+            "bad_params", "slot is required: a scene row from 0"
+        ) from None
+    slots = list(track.clip_slots)
+    if not 0 <= index < len(slots):
+        raise CommandError(
+            "not_found", f"no slot {index} on {path}: slots 0-{len(slots) - 1}"
+        )
+    return slots[index]
+
+
+def _given(params, name):
+    return params.get(name) not in (None, "")
+
+
+def _need(params, name):
+    if not _given(params, name):
+        raise CommandError("bad_params", f"{name} is required")
+    return params[name]
+
+
+def _number(value, name):
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        raise CommandError("bad_params", f"{name} must be a number") from None
+
+
+def _bool(value):
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "on", "yes", "1")
+    return bool(value)
+
+
+def _signature(value):
+    text = str(value).replace(" ", "")
+    try:
+        num, den = (int(part) for part in text.split("/"))
+    except ValueError:
+        raise CommandError(
+            "bad_params", "time_signature must look like 4/4 or 6/8"
+        ) from None
+    return num, den
+
+
+def _root_note(value):
+    text = str(value).strip()
+    if text.isdigit():
+        return int(text) % 12
+    return objects.note_number(text + "3") % 12

tonable/remote_script/Tonable/version.py

@@ -0,0 +1,2 @@
+# Must equal the tonable package version: `tonable doctor` and live_status compare them.
+VERSION = "0.5.2"

tonable/server.py

@@ -0,0 +1,78 @@
+"""The MCP server: tool descriptions for the model, calls forwarded to Live over stdio.
+
+Tool descriptions never change at run time: clients cache the tool list
+(see docs/clients.md). The tools live in tonable/tools/.
+"""
+
+from mcp.server.fastmcp import FastMCP
+from mcp.server.fastmcp.exceptions import ToolError
+from mcp.types import ToolAnnotations
+
+from tonable import __version__
+from tonable.bridge import Bridge, BridgeError
+
+INSTRUCTIONS = """\
+Tonable controls Ableton Live 12 on this computer through a Remote Script inside Live.
+Call live_status first: it says whether Live is connected and what Set is open.
+Addresses: t0 is the first track (numbers from 0), rA return track A, m the master.
+Devices: t0/d0 first device; inside racks t0/d0/c1/d0 (chain 1, device 0);
+Drum Rack pads t0/d0/pC1 (note names with C3 = MIDI 60).
+Times are in beats (quarter notes) unless a field says bars.
+Read before you change anything, and quote the address and name to the user.
+If a call fails with code not_running, tell the user to choose Tonable in Live's
+Settings -> Link, Tempo & MIDI -> Control Surface.
+A timeout_not_started error means nothing changed. timeout_running or
+connection_lost means the command may still have run: read the state before
+repeating it.
+"""
+
+
+def read_only(title):
+    """Annotations for a tool that only reads Live."""
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+
+
+mcp = FastMCP("tonable", instructions=INSTRUCTIONS)
+# FastMCP would report the mcp library's version. Clients may cache the tool list
+# by server name and version, so report ours: a new release then looks new.
+mcp._mcp_server.version = __version__
+bridge = Bridge()
+
+
+def call(command, params=None, long=False):
+    """Run a command in Live; a failure becomes a tool error the model can read."""
+    try:
+        try:
+            return bridge.request(command, params, long=long)
+        except BridgeError as err:
+            # The command needed one more Live tick (the playhead, for locators).
+            if err.code != "retry":
+                raise
+            return bridge.request(command, params, long=long)
+    except BridgeError as err:
+        text = f"{err.code}: {err}"
+        if err.hint:
+            text += f" {err.hint}"
+        raise ToolError(text) from None
+
+
+def run():
+    mcp.run("stdio")
+
+
+# Importing the modules registers their tools on `mcp`.
+from tonable.tools import (  # noqa: E402, F401
+    arrangement,
+    batch,
+    clips,
+    devices,
+    envelopes,
+    session,
+    tracks,
+)

tonable/tools/__init__.py

@@ -0,0 +1,144 @@
+"""MCP tools, one module per group (see docs/tools.md).
+
+Argument types are shared so every tool explains them the same way. They use
+plain JSON types without anyOf; null or "" in an optional field means "not given".
+"""
+
+from typing import Annotated
+
+from pydantic import BeforeValidator, Field, WithJsonSchema
+
+
+def _names(value):
+    """null/"" -> [], one string -> [it], {"a": ..} -> its keys; lists unchanged."""
+    if value is None or value == "":
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, dict):
+        return list(value)
+    return value
+
+
+def empty_to(default):
+    """A BeforeValidator body: null or "" become `default`."""
+
+    def convert(value):
+        return default if value is None or value == "" else value
+
+    return convert
+
+
+def _flag(value):
+    if value is None or value == "":
+        return False
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "yes", "1")
+    return value
+
+
+TrackAddress = Annotated[
+    str,
+    Field(
+        description=(
+            "Track address: t0 for the first track (numbers from 0), rA for return "
+            "track A, m for the master. Example: t2"
+        )
+    ),
+]
+
+ObjectAddress = Annotated[
+    str,
+    Field(
+        description=(
+            "Device, rack chain or Drum Rack pad address. Examples: t0/d0 (first "
+            "device on t0), t1/d0/c1/d0 (first device in chain 1 of that rack), "
+            "t2/d0/pC1 (Drum Rack pad C1), rA/d0, m/d0"
+        )
+    ),
+]
+
+ParameterNames = Annotated[
+    list[str],
+    BeforeValidator(_names),
+    Field(
+        description=(
+            "Only these parameters, by name as Live shows them. Example: "
+            '["Release", "Decay"]. Leave empty for the default view.'
+        )
+    ),
+]
+
+AllParameters = Annotated[
+    bool,
+    BeforeValidator(_flag),
+    Field(description="For a rack: list every parameter, not only the macros."),
+]
+
+
+def _to_text(value):
+    """null -> "", true/false -> "true"/"false", numbers -> their text."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return f"{value:g}" if isinstance(value, float) else str(value)
+    return value
+
+
+def text(description):
+    """An optional field sent as text; empty means "leave unchanged".
+
+    JSON numbers and booleans are accepted too, so a client that sends 120 or true
+    for a text field is not refused.
+    """
+    return Annotated[str, BeforeValidator(_to_text), Field(description=description)]
+
+
+def objects_list(description, item_schema):
+    """A list of objects, checked one by one in Live (a bad item never rejects the
+    call). null, "" and a single object are accepted."""
+
+    def convert(value):
+        if value is None or value == "":
+            return []
+        if isinstance(value, dict):
+            return [value]
+        return value
+
+    return Annotated[
+        list[dict],
+        BeforeValidator(convert),
+        WithJsonSchema(
+            {"type": "array", "items": item_schema, "description": description}
+        ),
+    ]
+
+
+def changes(title, destructive=False, idempotent=False):
+    """Annotations for a tool that changes the Set."""
+    from mcp.types import ToolAnnotations
+
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=False,
+        destructiveHint=destructive,
+        idempotentHint=idempotent,
+        openWorldHint=False,
+    )
+
+
+def objects_or_names(description):
+    """A list of names: one string, numbers or null are accepted too."""
+
+    def convert(value):
+        if value is None or value == "":
+            return []
+        if not isinstance(value, list):
+            value = [value]
+        return [str(v) for v in value]
+
+    return Annotated[
+        list[str], BeforeValidator(convert), Field(description=description)
+    ]

tonable/tools/arrangement.py

@@ -0,0 +1,62 @@
+"""arrangement: clips and locators on the timeline."""
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from tonable.server import call, mcp
+from tonable.tools import changes, objects_list, text
+from tonable.tools.clips import NOTE_SCHEMA
+
+
+@mcp.tool(annotations=changes("Arrangement", destructive=True))
+def arrangement(
+    action: Annotated[
+        Literal[
+            "list",
+            "place_scene",
+            "copy_clip",
+            "create_clip",
+            "delete_clip",
+            "add_locator",
+            "rename_locator",
+            "delete_locator",
+        ],
+        Field(description="What to do; see the tool description."),
+    ],
+    at_bar: text("Where: bar number from 1, as Live shows it (17 = bar 17).") = "",
+    at_beats: text("Where, in beats from the start, instead of at_bar.") = "",
+    scene: text("For place_scene: scene number from 0 or its exact name.") = "",
+    track: text("For copy_clip, create_clip, delete_clip: t0, t1...") = "",
+    slot: text("For copy_clip: the Session slot to copy, from 0.") = "",
+    length_beats: text("For create_clip: length in beats. Empty: fit the notes.") = "",
+    notes: objects_list("For create_clip: notes, as in write_clip.", NOTE_SCHEMA) = [],  # noqa: B006 - pydantic copies defaults
+    name: text(
+        "Clip or locator name; for delete_clip the clip's name as a check."
+    ) = "",
+    locator: text("For rename_locator, delete_locator: the locator's name.") = "",
+) -> dict:
+    """Work on the Arrangement timeline.
+
+    list: clips per track, locators, loop. place_scene: copy every clip of a Session
+    scene to the timeline at a bar, in one undo step (envelopes come along as track
+    automation). copy_clip: one Session clip to a bar. create_clip: a MIDI clip on
+    the timeline with notes. delete_clip: by track, start and name. add_locator,
+    rename_locator, delete_locator. Times answer as bar|beat ("17|1") and beats.
+    Live cannot read Arrangement automation back.
+    """
+    return call(
+        "arrangement",
+        {
+            "action": action,
+            "at_bar": at_bar,
+            "at_beats": at_beats,
+            "scene": scene,
+            "track": track,
+            "slot": slot,
+            "length_beats": length_beats,
+            "notes": notes,
+            "name": name,
+            "locator": locator,
+        },
+    )

tonable/tools/batch.py

@@ -0,0 +1,53 @@
+"""batch: several commands in one request and one undo step."""
+
+from typing import Annotated
+
+from pydantic import BeforeValidator, Field
+
+from tonable.server import call, mcp
+from tonable.tools import changes, empty_to, objects_list
+
+# Commands that may walk the browser get Live's long timeout.
+LONG = {"find_in_library", "load_device"}
+
+ACTION_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "command": {
+            "type": "string",
+            "description": "A Tonable tool name, e.g. write_clip, update_track",
+        },
+        "params": {
+            "type": "object",
+            "description": "That tool's arguments, as you would pass them to it",
+        },
+    },
+    "required": ["command", "params"],
+}
+
+
+@mcp.tool(annotations=changes("Batch", destructive=True))
+def batch(
+    actions: objects_list(
+        'Actions in order. Example: [{"command": "create_track", "params": {"name": '
+        '"Bass"}}, {"command": "write_clip", "params": {"track": "t4", "slot": 0, '
+        '"notes": [...]}}]',
+        ACTION_SCHEMA,
+    ),
+    stop_on_error: Annotated[
+        bool,
+        BeforeValidator(empty_to(False)),
+        Field(description="Stop at the first failed action. Default: run them all."),
+    ] = False,
+) -> dict:
+    """Run several Tonable tools in one go, as ONE undo step (one Cmd+Z undoes them
+    all). Each action gets its own result; a failed one does not stop the rest
+    unless stop_on_error is set. Arguments are passed as given, so use the forms
+    the tools document.
+    """
+    names = {str(a.get("command") or a.get("tool")) for a in actions}
+    return call(
+        "batch",
+        {"actions": actions, "stop_on_error": stop_on_error},
+        long=bool(names & LONG),
+    )