tonable 0.5.2__py3-none-any.whl

tonable/tools/clips.py

@@ -0,0 +1,179 @@
+"""read_clip and write_clip: Session clips and their notes."""
+
+from typing import Annotated, Literal
+
+from mcp.types import ToolAnnotations
+from pydantic import BeforeValidator, Field, WithJsonSchema
+
+from tonable.server import call, mcp, read_only
+from tonable.tools import TrackAddress, changes, empty_to, objects_or_names, text
+
+NOTE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "pitch": {
+            "type": "string",
+            "description": 'MIDI number or note name, C3 = 60. Example: "60" or "C3"',
+        },
+        "start": {
+            "type": "number",
+            "description": "Start in beats from the clip start",
+        },
+        "length": {"type": "number", "description": "Length in beats, more than 0"},
+        "velocity": {"type": "number", "description": "1-127"},
+        "mute": {"type": "boolean", "description": "Optional: a muted note"},
+    },
+    "required": ["pitch", "start", "length", "velocity"],
+}
+
+
+def _note_list(value):
+    if value is None or value == "":
+        return []
+    if isinstance(value, dict):
+        return [value]
+    return value
+
+
+Slot = Annotated[
+    int,
+    Field(
+        description="Clip slot: the scene row, from 0. Example: 0 for the first scene"
+    ),
+]
+
+# Notes are checked one by one in Live, so one bad note never rejects the call.
+Notes = Annotated[
+    list[dict],
+    BeforeValidator(_note_list),
+    WithJsonSchema(
+        {
+            "type": "array",
+            "items": NOTE_SCHEMA,
+            "description": (
+                'Notes to write. Example: [{"pitch": "C3", "start": 0, "length": 1, '
+                '"velocity": 100}, {"pitch": "E3", "start": 1, "length": 1, '
+                '"velocity": 90}]'
+            ),
+        }
+    ),
+]
+
+Mode = Annotated[
+    Literal["replace", "add"],
+    BeforeValidator(empty_to("replace")),
+    Field(
+        description=(
+            "replace: the clip ends up with exactly these notes (old ones removed). "
+            "add: keep the old notes and add these."
+        )
+    ),
+]
+
+LengthBeats = Annotated[
+    float,
+    BeforeValidator(empty_to(0)),
+    Field(
+        description=(
+            "Clip length in beats (16 = four 4/4 bars). 0 or empty: a new clip gets "
+            "whole bars that fit the notes, an existing clip keeps its length."
+        )
+    ),
+]
+
+ClipName = Annotated[
+    str,
+    BeforeValidator(empty_to("")),
+    Field(description="Optional new clip name; empty keeps the current name."),
+]
+
+
+@mcp.tool(annotations=read_only("Read a clip"))
+def read_clip(track: TrackAddress, slot: Slot) -> dict:
+    """A Session clip: name, length, loop, and for a MIDI clip every note with pitch
+    name and number, start and length in beats, and velocity.
+
+    Use it before changing notes and to check what write_clip did.
+    """
+    return call("read_clip", {"track": track, "slot": slot})
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Write a clip",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=False,
+    )
+)
+def write_clip(
+    track: TrackAddress,
+    slot: Slot,
+    notes: Notes = [],  # noqa: B006 - pydantic copies defaults
+    mode: Mode = "replace",
+    length_beats: LengthBeats = 0,
+    name: ClipName = "",
+) -> dict:
+    """Create a MIDI clip in a Session slot, or change one, and write its notes.
+
+    An empty slot gets a new clip. mode=replace (default) leaves exactly the given
+    notes in the clip; mode=add keeps the existing ones. All of it is one undo step.
+    Notes that fail a check come back in "rejected" with the reason; the rest are
+    written. Works on MIDI tracks only; read_set shows the tracks and scenes.
+    """
+    return call(
+        "write_clip",
+        {
+            "track": track,
+            "slot": slot,
+            "notes": notes,
+            "mode": mode,
+            "length_beats": length_beats,
+            "name": name,
+        },
+    )
+
+
+@mcp.tool(annotations=changes("Edit notes", destructive=True))
+def edit_notes(
+    track: TrackAddress,
+    slot: Slot,
+    action: Annotated[
+        Literal["delete", "transpose", "shift", "quantize", "velocity", "length"],
+        Field(description="What to do with the chosen notes."),
+    ],
+    from_beats: text("Only notes starting at or after this beat.") = "",
+    to_beats: text("Only notes starting before this beat.") = "",
+    pitches: objects_or_names(
+        'Only these pitches, e.g. ["C3", "E3"] or ["60"]. Empty: all pitches.'
+    ) = [],  # noqa: B006 - pydantic copies defaults
+    semitones: text("For transpose: e.g. 12 or -5.") = "",
+    beats: text("For shift: move by this many beats, e.g. 0.5 or -1.") = "",
+    grid_beats: text("For quantize: grid in beats, e.g. 0.25 for 1/16 notes.") = "",
+    velocity: text("For velocity: new velocity 1-127.") = "",
+    length_beats: text("For length: new note length in beats.") = "",
+) -> dict:
+    """Change some notes of a MIDI clip without rewriting it: delete, transpose,
+    shift in time, quantize starts to a grid, set velocity or set length.
+
+    Choose notes by start time (from_beats/to_beats) and pitches; with neither, all
+    notes. Notes that would leave the MIDI range or the clip start are skipped and
+    listed. One undo step. To replace all notes use write_clip.
+    """
+    return call(
+        "edit_notes",
+        {
+            "track": track,
+            "slot": slot,
+            "action": action,
+            "from_beats": from_beats,
+            "to_beats": to_beats,
+            "pitches": pitches,
+            "semitones": semitones,
+            "beats": beats,
+            "grid_beats": grid_beats,
+            "velocity": velocity,
+            "length_beats": length_beats,
+        },
+    )

tonable/tools/devices.py

@@ -0,0 +1,207 @@
+"""read_device, set_device_params, update_device, find_in_library, load_device."""
+
+from typing import Annotated, Literal
+
+from pydantic import BeforeValidator, Field
+
+from tonable.server import call, mcp, read_only
+from tonable.tools import (
+    AllParameters,
+    ObjectAddress,
+    ParameterNames,
+    changes,
+    empty_to,
+    objects_list,
+    text,
+)
+
+PARAM_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "param": {
+            "type": "string",
+            "description": "Parameter name as Live shows it (Release), or its index",
+        },
+        "value": {
+            "type": "string",
+            "description": (
+                'Display text: "400 ms", "-6 dB", "50 %", "On", "Sine"; or a raw number'
+            ),
+        },
+    },
+    "required": ["param", "value"],
+}
+
+
+@mcp.tool(annotations=read_only("Read a device"))
+def read_device(
+    target: ObjectAddress,
+    params: ParameterNames = [],  # noqa: B006 - pydantic copies defaults
+    all_params: AllParameters = False,
+) -> dict:
+    """A device's parameters as Live shows them ("262 ms", "-6.0 dB", "On"), with
+    raw value and range, plus whether the device is on.
+
+    For a rack: its visible mapped macro knobs and its chains, not every parameter
+    (set all_params to see them all). For other devices: all parameters. Give
+    params to see only some, by name; a wrong name comes back with similar names.
+    A chain or pad address shows its devices instead.
+    """
+    return call(
+        "read_device", {"target": target, "params": params, "all_params": all_params}
+    )
+
+
+@mcp.tool(annotations=changes("Set device parameters", idempotent=True))
+def set_device_params(
+    target: Annotated[str, Field(description="Device address: t0/d0, t1/d0/c0/d1")],
+    params: objects_list(
+        'Parameters to set. Example: [{"param": "Release", "value": "400 ms"}, '
+        '{"param": "Decay", "value": "1.2 s"}]',
+        PARAM_SCHEMA,
+    ),
+) -> dict:
+    """Set one or more parameters of a device or rack macro, by name, in the units
+    Live shows ("400 ms", "-6 dB", "50 %", "On") or as raw numbers.
+
+    Each parameter gets its own line: "now" is what Live shows afterwards, a wrong
+    name comes back with similar names, and one failure never stops the others. If
+    a parameter has automation, Live stops playing it (the answer warns; use
+    transport re_enable_automation). One undo step.
+    """
+    return call("set_device_params", {"target": target, "params": params})
+
+
+@mcp.tool(annotations=changes("Change a device"))
+def update_device(
+    target: ObjectAddress,
+    on: text("Device on: true / false. Empty: unchanged.") = "",
+    name: text("New device name.") = "",
+    move_to: text("Move into this track or chain: t2, t0/d0/c1.") = "",
+    index: text("With move_to: position from 0. Empty: at the end.") = "",
+    visible_macros: text("For a rack: how many macro knobs to show.") = "",
+    variation: text("For a rack: store, or a variation number to recall.") = "",
+    mute: text("For a chain or pad: true / false.") = "",
+    solo: text("For a chain or pad: true / false.") = "",
+) -> dict:
+    """Turn a device on or off, rename it, move it to another track or chain, set a
+    rack's visible macros, store or recall a macro variation, or mute and solo a
+    rack chain or Drum Rack pad. Only given fields change. One undo step.
+    """
+    return call(
+        "update_device",
+        {
+            "target": target,
+            "on": on,
+            "name": name,
+            "move_to": move_to,
+            "index": index,
+            "visible_macros": visible_macros,
+            "variation": variation,
+            "mute": mute,
+            "solo": solo,
+        },
+    )
+
+
+@mcp.tool(annotations=read_only("Find in the library"))
+def find_in_library(
+    query: Annotated[
+        str, Field(description="Words in the name, e.g. electric bass, reverb")
+    ],
+    limit: Annotated[
+        int,
+        BeforeValidator(empty_to(0)),
+        Field(description="At most this many results. Empty or 0: all results."),
+    ] = 0,
+    kind: Annotated[
+        Literal[
+            "any",
+            "instrument",
+            "audio_effect",
+            "midi_effect",
+            "sound",
+            "drum",
+            "max_for_live",
+            "plugin",
+            "pack",
+            "user_library",
+        ],
+        BeforeValidator(empty_to("any")),
+        Field(description="Only one part of the browser; any searches all."),
+    ] = "any",
+    refresh: Annotated[
+        bool,
+        BeforeValidator(empty_to(False)),
+        Field(description="Walk the browser again after adding presets or packs."),
+    ] = False,
+) -> dict:
+    """Search Live's browser: devices, presets (.adg, .adv) and samples in the
+    Core Library, Packs and User Library. Returns paths for load_device.
+
+    The first search walks the whole browser (about 5 s, Live pauses briefly); later
+    ones are instant. Exact names come first. Places are not searchable: Live does
+    not show them to scripts.
+    """
+    return call(
+        "find_in_library",
+        {"query": query, "limit": limit, "kind": kind, "refresh": refresh},
+        long=True,
+    )
+
+
+@mcp.tool(annotations=changes("Load a device or preset", destructive=True))
+def load_device(
+    target: Annotated[
+        str,
+        Field(description="Track (t0, rA, m) or, for built-in devices, a chain"),
+    ],
+    item: Annotated[
+        str,
+        Field(
+            description=(
+                "A built-in device name (Operator, Reverb, CC Control), a path from "
+                "find_in_library (Instruments/Instrument Rack/Bass/Electric Bass "
+                "Soft.adg), a preset name, or a file path in the User Library or Packs"
+            )
+        ),
+    ],
+    index: text("For built-in devices: position from 0. Empty: at the end.") = "",
+) -> dict:
+    """Load a device or preset onto a track and return its address and, for a rack,
+    its macro names.
+
+    Built-in devices go exactly at index. Presets load like a drag from the
+    browser: an instrument replaces the track's instrument (the answer names what
+    it replaced). A file outside the User Library and Packs is refused with a hint
+    to move it into the User Library. Live selects the track it loads onto.
+    """
+    return call(
+        "load_device", {"target": target, "item": item, "index": index}, long=True
+    )
+
+
+@mcp.tool(annotations=read_only("Inspect a preset file"))
+def inspect_preset_file(
+    path: Annotated[
+        str,
+        Field(
+            description=(
+                "A .adg or .adv file in the User Library, a pack or the Core "
+                "Library, e.g. ~/Music/Ableton/User Library/Presets/Example.adg"
+            )
+        ),
+    ],
+) -> dict:
+    """What a preset file holds, without loading it and without Live: the device,
+    a rack's visible macro names, its chains (or Drum Rack pads with their notes)
+    and the devices in each, nested racks included.
+    """
+    from mcp.server.fastmcp.exceptions import ToolError
+
+    from tonable import presets
+
+    try:
+        return presets.inspect(path)
+    except presets.PresetError as err:
+        raise ToolError(str(err)) from None

tonable/tools/envelopes.py

@@ -0,0 +1,76 @@
+"""read_envelope and write_envelope: automation in Session clips."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from tonable.server import call, mcp, read_only
+from tonable.tools import TrackAddress, changes, objects_list
+from tonable.tools.clips import Slot
+
+POINT_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "time": {"type": "number", "description": "Beats from the clip start"},
+        "value": {
+            "type": "string",
+            "description": 'Display text ("-6 dB", "400 ms", "25L") or a raw number',
+        },
+        "jump": {
+            "type": "boolean",
+            "description": "Hold the previous value until this time, then jump",
+        },
+        "curve": {
+            "type": "array",
+            "items": {"type": "number"},
+            "description": (
+                "Optional bend of the segment from this point: x1, y1, x2, y2, each "
+                "0-1 (0.5 four times is straight)"
+            ),
+        },
+    },
+    "required": ["time", "value"],
+}
+
+Parameter = Annotated[
+    str,
+    Field(
+        description=(
+            "volume, pan, send A, or a device parameter on the same track as "
+            "t0/d0:Release (device address, colon, parameter name)"
+        )
+    ),
+]
+
+
+@mcp.tool(annotations=read_only("Read an envelope"))
+def read_envelope(track: TrackAddress, slot: Slot, parameter: Parameter) -> dict:
+    """The automation points of one parameter in a Session clip: time in beats,
+    value as Live shows it, raw value, and curve bends. exists=false when the clip
+    has no envelope for it.
+    """
+    return call("read_envelope", {"track": track, "slot": slot, "parameter": parameter})
+
+
+@mcp.tool(annotations=changes("Write an envelope", destructive=True, idempotent=True))
+def write_envelope(
+    track: TrackAddress,
+    slot: Slot,
+    parameter: Parameter,
+    points: objects_list(
+        'Points in time order. Example: [{"time": 0, "value": "200 ms"}, '
+        '{"time": 8, "value": "800 ms"}]. Empty: clear the envelope.',
+        POINT_SCHEMA,
+    ) = [],  # noqa: B006 - pydantic copies defaults
+) -> dict:
+    """Replace one parameter's automation in a Session clip with these points, or
+    clear it with no points. Values ramp from point to point unless a point has
+    jump=true. Works for the mixer (volume, pan, sends) and device parameters,
+    including rack macros; MIDI CC is not reachable (use CC Control's Custom A, CC
+    64 Sustain, for the pedal). Copy the clip to the Arrangement to keep the
+    automation there. One undo step.
+    """
+    return call(
+        "write_envelope",
+        {"track": track, "slot": slot, "parameter": parameter, "points": points},
+    )

tonable/tools/session.py

@@ -0,0 +1,163 @@
+"""live_status, read_set, update_set, transport, undo and scene."""
+
+from typing import Annotated, Literal
+
+from pydantic import BeforeValidator, Field
+
+from tonable import __version__
+from tonable.bridge import BridgeError
+from tonable.server import call, mcp, read_only
+from tonable.tools import changes, empty_to, text
+
+
+@mcp.tool(annotations=read_only("Live status"))
+def live_status() -> dict:
+    """Check the connection to Ableton Live and show the open Set.
+
+    Returns whether Live is connected, the Live and Tonable versions, and the Set's
+    tempo, time signature and numbers of tracks, return tracks and scenes. When Live
+    is not reachable it returns connected=false with the reason and what to do.
+    Use it first in a conversation and after any connection error.
+    """
+    from tonable import server
+
+    try:
+        status = server.bridge.request("status")
+    except BridgeError as err:
+        return {"connected": False, "server_version": __version__, **err.as_dict()}
+    out = {"connected": True, "server_version": __version__, **status}
+    if status.get("script_version") != __version__:
+        out["warning"] = (
+            f"The Remote Script in Live is version {status.get('script_version')}, "
+            f"the server is {__version__}. Run `tonable install` and restart Live."
+        )
+    return out
+
+
+@mcp.tool(annotations=read_only("Read the Set"))
+def read_set() -> dict:
+    """Overview of the open Live Set: tempo, time signature, loop, tracks, return
+    tracks, scenes and locators.
+
+    Each scene lists the clips in its row as {track address: clip name}; empty slots
+    are left out. Each track shows its address, name, kind (midi, audio, group) and
+    device names. Use read_track for one track's mixer, devices and clips.
+    """
+    return call("read_set")
+
+
+@mcp.tool(annotations=changes("Change the Set"))
+def update_set(
+    tempo: text("BPM, e.g. 92. Empty: unchanged.") = "",
+    time_signature: text("e.g. 4/4, 3/4, 6/8. Empty: unchanged.") = "",
+    loop: text("Arrangement loop on or off: true / false. Empty: unchanged.") = "",
+    loop_start_beats: text("Loop start in beats. Empty: unchanged.") = "",
+    loop_length_beats: text("Loop length in beats (16 = four 4/4 bars).") = "",
+    metronome: text("true / false. Empty: unchanged.") = "",
+    root_note: text(
+        "Key root for Live's scale mode: C, F#, Bb. Empty: unchanged."
+    ) = "",
+    scale: text("Scale name as Live shows it: Major, Minor, Dorian...") = "",
+) -> dict:
+    """Change the Set's tempo, time signature, Arrangement loop, metronome or key.
+
+    Only the fields you give change; the answer shows the Set's state afterwards.
+    One undo step.
+    """
+    return call(
+        "update_set",
+        {
+            "tempo": tempo,
+            "time_signature": time_signature,
+            "loop": loop,
+            "loop_start_beats": loop_start_beats,
+            "loop_length_beats": loop_length_beats,
+            "metronome": metronome,
+            "root_note": root_note,
+            "scale": scale,
+        },
+    )
+
+
+@mcp.tool(annotations=changes("Transport"))
+def transport(
+    action: Annotated[
+        Literal[
+            "play",
+            "stop",
+            "continue",
+            "fire_clip",
+            "stop_track",
+            "fire_scene",
+            "stop_all_clips",
+            "jump",
+            "re_enable_automation",
+        ],
+        Field(description="What to do; see the tool description."),
+    ],
+    track: text("For fire_clip and stop_track: t0, t1...") = "",
+    slot: text("For fire_clip: the slot (scene row) from 0.") = "",
+    scene: text("For fire_scene: scene number from 0 or its exact name.") = "",
+    time_beats: text("For jump: song position in beats.") = "",
+    locator: text("For jump: a locator name instead of time_beats.") = "",
+) -> dict:
+    """Play, stop or continue; launch a clip (fire_clip track+slot) or a scene
+    (fire_scene); stop one track's clips (stop_track) or all clips; jump to a time
+    in beats or to a locator; re_enable_automation after a parameter was moved by
+    hand or by set_device_params.
+    """
+    return call(
+        "transport",
+        {
+            "action": action,
+            "track": track,
+            "slot": slot,
+            "scene": scene,
+            "time_beats": time_beats,
+            "locator": locator,
+        },
+    )
+
+
+@mcp.tool(annotations=changes("Undo"))
+def undo(
+    action: Annotated[
+        Literal["undo", "redo"],
+        BeforeValidator(empty_to("undo")),
+        Field(description="undo (Cmd+Z) or redo (Shift+Cmd+Z)."),
+    ] = "undo",
+) -> dict:
+    """Undo or redo one step in Live, like Cmd+Z. Every Tonable change is one step
+    (a batch too). Live's undo history is shared with everyone working in the Set,
+    so read the state afterwards to see what changed.
+    """
+    return call("undo", {"action": action})
+
+
+@mcp.tool(annotations=changes("Scene"))
+def scene(
+    action: Annotated[
+        Literal["create", "update", "duplicate", "capture"],
+        Field(description="create, update (rename, tempo, color), duplicate, capture."),
+    ],
+    scene: text("For update and duplicate: number from 0 or exact name.") = "",
+    index: text("For create: where to insert, from 0. Empty: at the end.") = "",
+    name: text("New name.") = "",
+    tempo: text("Scene tempo in BPM, or off. Empty: unchanged.") = "",
+    color_index: text("Live's color number. Empty: unchanged.") = "",
+) -> dict:
+    """Create a scene, rename it or set its tempo and color, duplicate it, or capture
+    the playing clips into a new scene. Delete scenes with delete (target s2).
+    Launch one with transport fire_scene. One undo step.
+    """
+    return call(
+        "scene",
+        {
+            "action": action,
+            "scene": scene,
+            "index": index,
+            "name": name,
+            "tempo": tempo,
+            "color_index": color_index,
+        },
+    )