tonable 0.5.2__py3-none-any.whl

tonable/presets.py

@@ -0,0 +1,119 @@
+"""What is inside a .adg / .adv preset, read from the file without Live.
+
+A preset is gzip-compressed XML. A rack (GroupDevicePreset) holds its device, macro
+names and BranchPresets (chains); each chain holds DevicePresets, which may be racks
+again. Drum Rack pads keep their note as ReceivingNote = 128 - MIDI note (a Carbonized
+Kit has Kick at 92 = C1, Snare at 90 = D1).
+
+Only files in folders Live's browser shows are read (see docs/plan.md):
+the User Library, the packs and the Core Library.
+"""
+
+import gzip
+import os
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from tonable import cli
+
+SUFFIXES = (".adg", ".adv")
+NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+CORE_LIBRARY = Path(
+    "/Applications/Ableton Live 12 Suite.app/Contents/App-Resources/Core Library"
+)
+
+
+class PresetError(Exception):
+    pass
+
+
+def allowed_folders():
+    """The User Library, every pack folder Live knows, and the Core Library."""
+    prefs, _ = cli.live_preferences()
+    folders = [cli.user_library(prefs), CORE_LIBRARY]
+    if prefs is not None:
+        try:
+            root = ET.parse(Path(prefs) / "Library.cfg").getroot()
+        except (OSError, ET.ParseError):
+            root = None
+        if root is not None:
+            for slice_info in root.iter("LibrarySliceInfo"):
+                if slice_info.get("Path"):
+                    folders.append(Path(slice_info.get("Path")))
+            preferred = root.find(".//PreferredFactoryPacksInstallationPath")
+            if preferred is not None and preferred.get("Value"):
+                folders.append(Path(preferred.get("Value")))
+    return [Path(os.path.realpath(f)) for f in folders if f is not None]
+
+
+def inspect(path, folders=None):
+    file = Path(os.path.realpath(os.path.expanduser(str(path))))
+    if file.suffix.lower() not in SUFFIXES:
+        raise PresetError("only .adg and .adv presets can be read")
+    folders = allowed_folders() if folders is None else folders
+    if not any(file.is_relative_to(f) for f in folders):
+        raise PresetError(
+            f"{file} is outside the folders Live's browser shows (User Library, "
+            "packs, Core Library)"
+        )
+    if not file.is_file():
+        raise PresetError(f"no file {file}")
+    try:
+        with gzip.open(file) as f:
+            root = ET.parse(f).getroot()
+    except (OSError, EOFError, ET.ParseError) as err:
+        raise PresetError(f"cannot read {file.name}: {err}") from None
+    preset = root[0] if len(root) else None
+    if preset is None:
+        raise PresetError(f"{file.name} holds no device")
+    out = {"file": str(file), "created_by": root.get("Creator")}
+    out.update(_preset(preset))
+    return out
+
+
+def _preset(preset):
+    """A device preset or a rack preset, with its chains."""
+    holder = preset.find("Device")
+    device = holder[0] if holder is not None and len(holder) else None
+    if device is None:
+        return {"device": preset.tag}
+    out = {"device": _name(device), "class": device.tag}
+    if preset.tag == "GroupDevicePreset":
+        out["macros"] = _macros(device)
+        chains = []
+        branches = preset.find("BranchPresets")
+        for i, branch in enumerate(branches if branches is not None else []):
+            presets = branch.find("DevicePresets")
+            devices = [_preset(p) for p in (presets if presets is not None else [])]
+            # An unnamed chain shows its first device's name in Live.
+            first = devices[0]["device"] if devices else None
+            entry = {"name": _value(branch.find("Name")) or first or f"Chain {i + 1}"}
+            note = branch.find("ZoneSettings/ReceivingNote")
+            if branch.tag == "DrumBranchPreset" and note is not None:
+                entry["note"] = _note_name(128 - int(note.get("Value")))
+            entry["devices"] = devices
+            chains.append(entry)
+        out["pads" if device.tag == "DrumGroupDevice" else "chains"] = chains
+    return out
+
+
+def _macros(device):
+    count = device.find("NumVisibleMacroControls")
+    visible = int(count.get("Value")) if count is not None else 0
+    names = []
+    for i in range(visible):
+        name = device.find(f"MacroDisplayNames.{i}")
+        names.append(_value(name) or f"Macro {i + 1}")
+    return names
+
+
+def _name(device):
+    return _value(device.find("UserName")) or device.tag
+
+
+def _value(element):
+    return element.get("Value") if element is not None else None
+
+
+def _note_name(number):
+    return f"{NOTE_NAMES[number % 12]}{number // 12 - 2}"

tonable/remote_script/Tonable/__init__.py

@@ -0,0 +1,146 @@
+"""Tonable: the Remote Script half of the Tonable MCP server for Ableton Live 12.4+.
+
+`tonable install` copies this folder to <User Library>/Remote Scripts/Tonable. Choose
+Tonable in Live's Settings -> Link, Tempo & MIDI -> Control Surface. The script opens a
+loopback port (see server.py) and writes its number and a key to
+~/.tonable/session.json for the MCP server.
+"""
+
+import importlib
+import sys
+
+from . import dispatch, version
+from .server import BridgeServer
+from .version import VERSION
+
+# `tonable install` reloads these in a running Live; dispatch then reloads the
+# command modules it lists. server.py is never reloaded: it owns the open socket.
+RELOADABLE = ("version", "dispatch")
+
+try:
+    import Live
+except ImportError:  # imported by the tests, outside Live
+    Live = None
+
+
+def create_instance(c_instance):
+    """Live calls this once when Tonable is chosen in the Control Surface list."""
+    return Tonable(c_instance)
+
+
+class Tonable:
+    def __init__(self, c_instance):
+        self._c_instance = c_instance
+        self.live_version = self._read_live_version()
+        self._commands = dispatch.commands(self)
+        self._commands["reload"] = self._reload
+        self._server = BridgeServer(
+            self._commands,
+            {"script_version": VERSION, "live_version": self.live_version},
+            self.log,
+        )
+        try:
+            self._server.start()
+        except Exception as err:
+            self.log(f"could not start: {type(err).__name__}: {err}")
+            self.show_message(f"Tonable could not start: {err}")
+            self._server = None
+            return
+        self.log(f"{VERSION} listening on 127.0.0.1:{self._server.port}")
+        self.show_message("Tonable is ready")
+
+    def _reload(self, params):
+        """Load the newly installed command modules without restarting Live."""
+        for name in RELOADABLE:
+            module = sys.modules.get(f"{__name__}.{name}")
+            if module is None:
+                importlib.import_module(f".{name}", __name__)
+            else:
+                importlib.reload(module)
+        fresh = dispatch.commands(self)
+        fresh["reload"] = self._reload
+        self._commands.clear()
+        self._commands.update(fresh)
+        self.log(f"reloaded {version.VERSION}")
+        return {"script_version": version.VERSION, "commands": sorted(fresh)}
+
+    @property
+    def song(self):
+        return self._c_instance.song()
+
+    def log(self, message):
+        self._c_instance.log_message("[Tonable] " + str(message))
+
+    def _read_live_version(self):
+        if Live is None:
+            return None
+        app = Live.Application.get_application()
+        parts = (
+            app.get_major_version(),
+            app.get_minor_version(),
+            app.get_bugfix_version(),
+        )
+        return ".".join(str(p) for p in parts)
+
+    # --- Live calls these ---------------------------------------------
+
+    def update_display(self):
+        """Live calls this about ten times a second on its main thread."""
+        if self._server is not None:
+            self._server.run_pending()
+
+    def disconnect(self):
+        if self._server is not None:
+            self._server.stop()
+            self._server = None
+
+    def connect_script_instances(self, instances):
+        pass
+
+    def can_lock_to_devices(self):
+        return False
+
+    def lock_to_device(self, device):
+        pass
+
+    def unlock_from_device(self, device):
+        pass
+
+    def toggle_lock(self):
+        pass
+
+    def set_appointed_device(self, device):
+        pass
+
+    def suggest_input_port(self):
+        return ""
+
+    def suggest_output_port(self):
+        return ""
+
+    def suggest_map_mode(self, cc_no, channel):
+        return Live.MidiMap.MapMode.absolute
+
+    def supports_pad_translation(self):
+        return False
+
+    def show_message(self, message):
+        self._c_instance.show_message(message)
+
+    def request_rebuild_midi_map(self):
+        self._c_instance.request_rebuild_midi_map()
+
+    def build_midi_map(self, midi_map_handle):
+        pass
+
+    def receive_midi(self, midi_bytes):
+        pass
+
+    def handle_sysex(self, midi_bytes):
+        pass
+
+    def refresh_state(self):
+        pass
+
+    def is_extension(self):
+        return False

tonable/remote_script/Tonable/arrangement.py

@@ -0,0 +1,236 @@
+"""The Arrangement: list clips, place a scene, copy or create clips, locators.
+
+Times are given as at_bar (bars from 1, as Live numbers them) or at_beats; answers
+show both, with bar|beat like Live's display ("17|1"). Live's API copies one clip at a
+time (duplicate_clip_to_arrangement), so place_scene walks the tracks itself, as one
+undo step. Envelopes in a Session clip become track automation on its span.
+"""
+
+from . import clips, objects
+from .server import CommandError
+from .song import find_scene, undo_step
+
+ACTIONS = (
+    "list",
+    "place_scene",
+    "copy_clip",
+    "create_clip",
+    "delete_clip",
+    "add_locator",
+    "rename_locator",
+    "delete_locator",
+)
+
+
+def arrangement(song, p):
+    action = p.get("action")
+    if action not in ACTIONS:
+        raise CommandError("bad_params", "action must be one of: " + ", ".join(ACTIONS))
+    if action == "list":
+        return _list(song)
+    handler = {
+        "place_scene": _place_scene,
+        "copy_clip": _copy_clip,
+        "create_clip": _create_clip,
+        "delete_clip": _delete_clip,
+        "add_locator": _add_locator,
+        "rename_locator": _rename_locator,
+        "delete_locator": _delete_locator,
+    }[action]
+    with undo_step(song):
+        return handler(song, p)
+
+
+def bar_beat(song, beats):
+    """Live's bar|beat for a time in beats: 0 -> "1|1", 18 in 4/4 -> "5|3"."""
+    bar_length = _bar(song)
+    bar = int(beats // bar_length) + 1
+    beat = beats - (bar - 1) * bar_length + 1
+    return f"{bar}|{beat:g}"
+
+
+def _list(song):
+    tracks = []
+    for t, track in enumerate(song.tracks):
+        found = [
+            _clip_out(song, c) for c in getattr(track, "arrangement_clips", []) or []
+        ]
+        if found:
+            tracks.append({"track": f"t{t}", "name": track.name, "clips": found})
+    return {
+        "time_signature": f"{song.signature_numerator}/{song.signature_denominator}",
+        "tracks": tracks,
+        "locators": [_locator_out(song, c) for c in song.cue_points],
+        "loop": {
+            "on": bool(song.loop),
+            "start": bar_beat(song, song.loop_start),
+            "length_beats": song.loop_length,
+        },
+    }
+
+
+def _place_scene(song, p):
+    index, scene = find_scene(song, p.get("scene"))
+    at = _time(song, p)
+    placed, end = [], at
+    for t, track in enumerate(song.tracks):
+        slots = list(track.clip_slots)
+        if index < len(slots) and slots[index].has_clip:
+            clip = slots[index].clip
+            copy = track.duplicate_clip_to_arrangement(clip, at)
+            placed.append({"track": f"t{t}", "clip": clip.name})
+            end = max(end, copy.end_time if copy is not None else at + clip.length)
+    if not placed:
+        raise CommandError("not_found", f"scene {index} ({scene.name!r}) has no clips")
+    return {
+        "scene": {"index": index, "name": scene.name},
+        "start": _time_out(song, at),
+        "end": _time_out(song, end),
+        "placed": placed,
+    }
+
+
+def _copy_clip(song, p):
+    track, slot, where = clips._slot(song, p.get("track"), p.get("slot"))
+    if not slot.has_clip:
+        raise CommandError("not_found", f"{where} is empty")
+    at = _time(song, p)
+    copy = track.duplicate_clip_to_arrangement(slot.clip, at)
+    return {
+        "copied": where,
+        "clip": _clip_out(song, copy) if copy is not None else None,
+    }
+
+
+def _create_clip(song, p):
+    track = objects.track(song, p.get("track") or "")
+    path = objects.track_path(song, track)
+    if not path.startswith("t") or not getattr(track, "has_midi_input", False):
+        raise CommandError("bad_target", f"{path} is not a MIDI track")
+    at = _time(song, p)
+    notes, rejected = clips.parse_notes(p.get("notes") or [])
+    length = clips._beats(p.get("length_beats"), "length_beats", allow_zero=True)
+    length = length or clips.fit_length(song, notes)
+    clip = track.create_midi_clip(at, length)
+    if notes:
+        clip.add_new_notes(tuple(clips._note_spec(n) for n in notes))
+    if p.get("name"):
+        clip.name = str(p["name"])
+    out = {"track": path, "clip": _clip_out(song, clip), "notes_added": len(notes)}
+    if rejected:
+        out["rejected"] = rejected
+    return out
+
+
+def _delete_clip(song, p):
+    track = objects.track(song, p.get("track") or "")
+    path = objects.track_path(song, track)
+    at = _time(song, p)
+    hits = [c for c in track.arrangement_clips if c.start_time == at]
+    if not hits:
+        starts = [bar_beat(song, c.start_time) for c in track.arrangement_clips]
+        raise CommandError(
+            "not_found",
+            f"no clip starts at {bar_beat(song, at)} on {path}; starts: {starts}",
+        )
+    clip = hits[0]
+    name = clip.name
+    if str(p.get("name") or "").strip().casefold() != name.strip().casefold():
+        raise CommandError(
+            "confirm_name", f"to delete it give its name exactly: {name!r}"
+        )
+    track.delete_clip(clip)  # the clip object is dead afterwards
+    return {"deleted": {"track": path, "name": name, "start": _time_out(song, at)}}
+
+
+def _add_locator(song, p):
+    at = _time(song, p)
+    if any(c.time == at for c in song.cue_points):
+        raise CommandError("exists", f"a locator is already at {bar_beat(song, at)}")
+    _playhead_at(song, at)
+    song.set_or_delete_cue()
+    cue = next((c for c in song.cue_points if c.time == at), None)
+    if cue is None:
+        raise CommandError("not_supported", "Live did not add the locator")
+    if p.get("name"):
+        cue.name = str(p["name"])
+    return {"added": _locator_out(song, cue), "note": "the playhead is now there"}
+
+
+def _rename_locator(song, p):
+    cue = _cue(song, p.get("locator"))
+    if not p.get("name"):
+        raise CommandError("bad_params", "name is required")
+    cue.name = str(p["name"])
+    return {"renamed": _locator_out(song, cue)}
+
+
+def _delete_locator(song, p):
+    cue = _cue(song, p.get("locator"))
+    shown = _locator_out(song, cue)
+    _playhead_at(song, cue.time)
+    song.set_or_delete_cue()
+    return {"deleted": shown}
+
+
+def _playhead_at(song, beats):
+    """Live adds and removes locators at the playhead, and a new playhead position
+    only counts from the next tick. If it is elsewhere, move it and ask the MCP
+    server to send the command again (code retry); the second call finds it there."""
+    if song.current_song_time == beats:
+        return
+    if song.is_playing:
+        raise CommandError(
+            "playing", "stop playback first: locators go at the playhead"
+        )
+    song.current_song_time = beats
+    raise CommandError("retry", "the playhead moves on the next tick; send again")
+
+
+# --- helpers ---------------------------------------------------------------------
+
+
+def _bar(song):
+    return song.signature_numerator * 4.0 / song.signature_denominator
+
+
+def _time(song, p):
+    if p.get("at_bar") not in (None, ""):
+        bar = float(p["at_bar"])
+        if bar < 1:
+            raise CommandError("bad_params", "at_bar counts from 1, like Live")
+        return (bar - 1) * _bar(song)
+    if p.get("at_beats") not in (None, ""):
+        beats = float(p["at_beats"])
+        if beats < 0:
+            raise CommandError("bad_params", "at_beats must be 0 or more")
+        return beats
+    raise CommandError("bad_params", "give at_bar (from 1) or at_beats")
+
+
+def _time_out(song, beats):
+    return {"bar_beat": bar_beat(song, beats), "beats": beats}
+
+
+def _clip_out(song, clip):
+    return {
+        "name": clip.name,
+        "start": bar_beat(song, clip.start_time),
+        "start_beats": clip.start_time,
+        "end_beats": clip.end_time,
+    }
+
+
+def _locator_out(song, cue):
+    return {"name": cue.name, "at": bar_beat(song, cue.time), "beats": cue.time}
+
+
+def _cue(song, ref):
+    text = str(ref or "").strip()
+    if not text:
+        raise CommandError("bad_params", "locator is required: its name")
+    for cue in song.cue_points:
+        if cue.name.strip().casefold() == text.casefold():
+            return cue
+    names = [c.name for c in song.cue_points]
+    raise CommandError("not_found", f"no locator {text!r}; locators: {names}")