tonable 0.5.2__py3-none-any.whl

tonable/remote_script/Tonable/library.py

@@ -0,0 +1,300 @@
+"""find_in_library and load_device. Main thread only.
+
+The browser tree is walked once and kept (stage 0: 60 115 items in 5.2 s); `refresh`
+walks it again. Places are left out: Live 12.4 does not show them to scripts
+(see docs/plan.md), so presets live in the User Library, Packs and the Core Library.
+"""
+
+import os
+import time
+
+from . import objects, reading
+from .server import CommandError
+from .song import undo_step
+
+try:
+    import Live
+except ImportError:  # imported by the tests, outside Live
+    Live = None
+
+# Browser attribute -> the name used in paths and answers.
+ROOTS = (
+    ("instruments", "Instruments"),
+    ("audio_effects", "Audio Effects"),
+    ("midi_effects", "MIDI Effects"),
+    ("sounds", "Sounds"),
+    ("drums", "Drums"),
+    ("max_for_live", "Max for Live"),
+    ("plugins", "Plug-ins"),
+    ("packs", "Packs"),
+    ("user_library", "User Library"),
+    ("current_project", "Current Project"),
+)
+KINDS = {
+    "instrument": "Instruments",
+    "audio_effect": "Audio Effects",
+    "midi_effect": "MIDI Effects",
+    "sound": "Sounds",
+    "drum": "Drums",
+    "max_for_live": "Max for Live",
+    "plugin": "Plug-ins",
+    "pack": "Packs",
+    "user_library": "User Library",
+}
+SUFFIXES = (".adg", ".adv", ".amxd", ".aupreset", ".fxp")
+# Live Sets in packs (demo songs) are loadable but not onto a track.
+SETS = (".als",)
+# This file is <User Library>/Remote Scripts/Tonable/library.py once installed.
+_HERE = os.path.dirname(os.path.abspath(__file__))
+USER_LIBRARY = os.path.dirname(os.path.dirname(_HERE))
+
+_cache = {"items": None, "built": None, "seconds": None}
+
+
+def browser():
+    return Live.Application.get_application().browser
+
+
+def index(refresh=False):
+    """[(root name, path, item)] for every loadable item, walked once."""
+    if _cache["items"] is None or refresh:
+        started = time.perf_counter()
+        items = []
+        b = browser()
+        for attr, label in ROOTS:
+            root = getattr(b, attr, None)
+            if root is not None:
+                _walk(root, label, items)
+        _cache.update(
+            items=items,
+            built=time.strftime("%H:%M:%S"),
+            seconds=round(time.perf_counter() - started, 1),
+        )
+    return _cache["items"]
+
+
+def _walk(item, path, out):
+    for child in item.children:
+        child_path = f"{path}/{child.name}"
+        if child.is_loadable and not plain(child.name).endswith(SETS):
+            out.append((path.split("/", 1)[0], child_path, child))
+        # Folders hold items, and a device's children are its presets.
+        _walk(child, child_path, out)
+
+
+def plain(name):
+    text = str(name).strip().casefold()
+    for suffix in SUFFIXES:
+        if text.endswith(suffix):
+            return text[: -len(suffix)]
+    return text
+
+
+def find_in_library(p):
+    query = str(p.get("query") or "").strip()
+    if not query:
+        raise CommandError("bad_params", "query is required, e.g. Electric Bass")
+    limit = p.get("limit")
+    try:
+        limit = int(limit) if limit not in (None, "") else 0
+    except (TypeError, ValueError):
+        raise CommandError("bad_params", "limit must be a whole number") from None
+    if limit < 0:
+        raise CommandError("bad_params", "limit must be 0 (all) or more")
+    # No limit (empty or 0) returns everything found.
+    limit = limit or None
+    kind = p.get("kind") or "any"
+    if kind != "any" and kind not in KINDS:
+        raise CommandError(
+            "bad_params", "kind must be any or one of: " + ", ".join(KINDS)
+        )
+    words = plain(query).split()
+    hits = []
+    seen = set()
+    for root, path, item in index(bool(p.get("refresh"))):
+        if kind != "any" and root != KINDS[kind]:
+            continue
+        name = plain(item.name)
+        if not all(w in name for w in words):
+            continue
+        key = _identity(item, path)
+        if key in seen:
+            continue
+        seen.add(key)
+        rank = 0 if name == plain(query) else 1 if name.startswith(words[0]) else 2
+        hits.append((rank, len(path), path, item))
+    hits.sort(key=lambda h: (h[0], h[1], h[2]))
+    shown = [
+        {"name": item.name, "path": path, "kind": _item_kind(item)}
+        for _, _, path, item in hits[:limit]
+    ]
+    if p.get("show_uri"):
+        for entry, (_, _, _, item) in zip(shown, hits, strict=False):
+            entry["uri"] = getattr(item, "uri", None)
+    out = {"query": query, "found": len(hits), "results": shown}
+    if limit is not None and len(hits) > limit:
+        out["more"] = len(hits) - limit
+    out["index"] = {"items": len(_cache["items"]), "built": _cache["built"]}
+    return out
+
+
+def load_device(song, p):
+    """Load a native device by name, a browser item by path, or a preset file."""
+    item_ref = str(p.get("item") or "").strip()
+    if not item_ref:
+        raise CommandError(
+            "bad_params", "item is required: Operator, a browser path or a file"
+        )
+    kind, holder, path = objects.resolve(song, p.get("target") or "")
+    if kind not in ("track", "chain"):
+        raise CommandError(
+            "bad_target", f"{path} is a {kind}: load onto a track or chain"
+        )
+    position = p.get("index")
+    before = list(holder.devices)
+    before_names = [(d.name, d.class_name) for d in before]
+    position = len(before) if position in (None, "", -1) else int(position)
+    if not 0 <= position <= len(before):
+        raise CommandError("bad_params", f"index must be 0-{len(before)}")
+
+    with undo_step(song):
+        how = _insert_native(holder, item_ref, position)
+        if how is None:
+            if kind != "track":
+                raise CommandError(
+                    "bad_target",
+                    "Live loads presets onto tracks only; load it on the track, then "
+                    "move it into the chain with update_device move_to",
+                )
+            item, how = _browser_item(item_ref, bool(p.get("refresh")))
+            song.view.selected_track = holder
+            browser().load_item(item)
+
+    after = list(holder.devices)
+    after_names = [(d.name, d.class_name) for d in after]
+    new = [i for i, d in enumerate(after) if all(d != old for old in before)]
+    replaced = None
+    if not new and len(after) == len(before):
+        # A track has one instrument: loading another one replaces it in place.
+        changed = [i for i, n in enumerate(after_names) if n != before_names[i]]
+        if changed:
+            new = changed
+            replaced = before_names[changed[0]][0]
+    if not new:
+        return {
+            "loaded": item_ref,
+            "how": how,
+            "warning": "Live has not shown the device yet; check with read_track",
+        }
+    device_path = f"{path}/d{new[0]}"
+    out = {"loaded": after[new[0]].name, "how": how, "path": device_path}
+    if replaced:
+        out["replaced"] = replaced
+    info = reading.read_device(song, device_path)
+    if "macros" in info:
+        out["macros"] = [m["name"] for m in info["macros"]]
+    out["note"] = "Live selects the track it loads onto"
+    return out
+
+
+def _insert_native(holder, name, position):
+    """Insert a built-in device by name; None if Live doesn't know the name."""
+    if "/" in name or plain(name) != name.strip().casefold():
+        return None
+    insert = getattr(holder, "insert_device", None)
+    if insert is None:
+        return None
+    try:
+        insert(name, position)
+    except Exception:
+        return None
+    return "native device"
+
+
+def _browser_item(ref, refresh):
+    """The browser item for a file path, a browser path, or a unique name."""
+    if ref.startswith(("/", "~")):
+        return _by_file(os.path.expanduser(ref), refresh), "file"
+    items = index(refresh)
+    if "/" in ref:
+        wanted = [plain(s) for s in ref.split("/") if s]
+        for _, path, item in items:
+            if [plain(s) for s in path.split("/")] == wanted:
+                return item, "browser path"
+        raise CommandError(
+            "not_found",
+            f"no browser item at {ref!r}; use find_in_library to get its path",
+        )
+    return _unique(items, plain(ref), ref), "name"
+
+
+def _by_file(file_path, refresh):
+    if not os.path.isfile(file_path):
+        raise CommandError("not_found", f"no file {file_path}")
+    items = index(refresh)
+    segments = [s for s in os.path.realpath(file_path).split(os.sep) if s]
+    library = [s for s in os.path.realpath(USER_LIBRARY).split(os.sep) if s]
+    if segments[: len(library)] == library:
+        wanted = ["user library"] + [plain(s) for s in segments[len(library) :]]
+        for _, path, item in items:
+            if [plain(s) for s in path.split("/")] == wanted:
+                return item
+    for _, path, item in items:
+        parts = [plain(s) for s in path.split("/")]
+        if parts[0] == "packs":
+            pack = parts[1]
+            if pack in [plain(s) for s in segments]:
+                tail = [
+                    plain(s)
+                    for s in segments[[plain(s) for s in segments].index(pack) + 1 :]
+                ]
+                if parts[2:] == tail:
+                    return item
+    # The Core Library and anything else: by file name, if only one file has it.
+    try:
+        return _unique(items, plain(segments[-1]), file_path)
+    except CommandError as err:
+        if err.code != "not_found":
+            raise
+    raise CommandError(
+        "outside_library",
+        f"{file_path} is not in a folder Live's browser shows. Move it into the User "
+        f"Library ({USER_LIBRARY}/Presets/...) and try again.",
+    )
+
+
+def _unique(items, name, shown):
+    matches = {}
+    for _, path, item in items:
+        if plain(item.name) == name:
+            matches.setdefault(_identity(item, path), (path, item))
+    if not matches:
+        raise CommandError("not_found", f"nothing named {shown!r} in the library")
+    # The category views (Instruments, Sounds...) list the Core Library and the
+    # packs again, with a FileId in the uri. One FileId item plus same-named items
+    # under Packs is one file seen twice.
+    filed = [m for key, m in matches.items() if key.startswith("FileId_")]
+    rest = [m for key, m in matches.items() if not key.startswith("FileId_")]
+    if len(filed) == 1 and all(path.startswith("Packs/") for path, _ in rest):
+        return filed[0][1]
+    if len(matches) > 1:
+        paths = sorted(path for path, _ in matches.values())
+        raise CommandError(
+            "ambiguous", f"{len(paths)} items are named {shown!r}; give a path: {paths}"
+        )
+    return next(iter(matches.values()))[1]
+
+
+def _identity(item, path):
+    """The same file shows up in several folders (Instrument Rack/Bass and
+    Simpler/Bass); its uri ends with the same FileId."""
+    uri = getattr(item, "uri", "") or ""
+    if "FileId_" in uri:
+        return uri[uri.rindex("FileId_") :]
+    return uri or path
+
+
+def _item_kind(item):
+    if item.is_device:
+        return "device"
+    return "preset" if plain(item.name) != item.name.strip().casefold() else "item"

tonable/remote_script/Tonable/objects.py

@@ -0,0 +1,134 @@
+"""Addresses for Live objects (see docs/tools.md). Main thread only.
+
+t0            first track (numbers from 0)
+rA            return track A
+m             master track
+t0/d1         second device on t0
+t0/d0/c1/d0   first device in the rack's second chain
+t0/d0/pC1     the Drum Rack pad on note C1 (C3 = MIDI 60, as Live shows it)
+"""
+
+import re
+
+from .server import CommandError
+
+NOTE_NAMES = {"C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11}
+_NOTE = re.compile(r"([A-Ga-g])([#b]?)(-?\d+)")
+
+
+def note_number(name):
+    """MIDI note for a name like C1, F#-1 or Bb3, in Live's octave numbering."""
+    match = _NOTE.fullmatch(name)
+    if not match:
+        raise CommandError("bad_address", f"{name!r} is not a note name like C1 or F#2")
+    letter, accidental, octave = match.groups()
+    number = (int(octave) + 2) * 12 + NOTE_NAMES[letter.upper()]
+    number += {"#": 1, "b": -1, "": 0}[accidental]
+    if not 0 <= number <= 127:
+        raise CommandError("bad_address", f"note {name} is outside MIDI notes 0-127")
+    return number
+
+
+def note_name(number):
+    """Live's name for a MIDI note: 36 -> C1, 61 -> C#3."""
+    names = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+    return f"{names[number % 12]}{number // 12 - 2}"
+
+
+def return_letter(index):
+    return chr(ord("A") + index)
+
+
+def track_path(song, track):
+    """The address of a track object: t3, rB or m."""
+    for i, t in enumerate(song.tracks):
+        if t == track:
+            return f"t{i}"
+    for i, t in enumerate(song.return_tracks):
+        if t == track:
+            return "r" + return_letter(i)
+    return "m"
+
+
+def track(song, ref):
+    """The track for `t0`, `rA` or `m`."""
+    ref = str(ref).strip()
+    if ref == "m":
+        return song.master_track
+    match = re.fullmatch(r"t(\d+)", ref)
+    if match:
+        tracks = list(song.tracks)
+        i = int(match.group(1))
+        if i >= len(tracks):
+            raise CommandError("not_found", f"no {ref}: {_range('t', len(tracks))}")
+        return tracks[i]
+    match = re.fullmatch(r"r([A-Za-z])", ref)
+    if match:
+        returns = list(song.return_tracks)
+        i = ord(match.group(1).upper()) - ord("A")
+        if i >= len(returns):
+            letters = [return_letter(n) for n in range(len(returns))]
+            have = "returns " + ", ".join(letters) if letters else "no return tracks"
+            raise CommandError("not_found", f"no {ref}: the Set has {have}")
+        return returns[i]
+    raise CommandError(
+        "bad_address", f"{ref!r} is not a track address: use t0, rA or m"
+    )
+
+
+def resolve(song, path):
+    """The object at `path` and the path in canonical form.
+
+    Returns (kind, obj, path) where kind is track, device, chain or pad.
+    """
+    parts = [p for p in str(path).strip().split("/") if p]
+    if not parts:
+        raise CommandError("bad_address", "empty address")
+    obj = track(song, parts[0])
+    kind = "track"
+    walked = [parts[0] if parts[0] == "m" else track_path(song, obj)]
+    for part in parts[1:]:
+        kind, obj = _step(kind, obj, part, "/".join(walked))
+        walked.append(part if kind != "pad" else "p" + note_name(obj.note))
+    return kind, obj, "/".join(walked)
+
+
+def _step(kind, obj, part, where):
+    if kind in ("track", "chain") and re.fullmatch(r"d\d+", part):
+        return "device", _index(list(obj.devices), int(part[1:]), part, where, "d")
+    if kind in ("device", "pad") and re.fullmatch(r"c\d+", part):
+        chains = list(getattr(obj, "chains", []) or [])
+        if kind == "device" and not getattr(obj, "can_have_chains", False):
+            raise CommandError("not_found", f"{where} is not a rack: it has no chains")
+        return "chain", _index(chains, int(part[1:]), part, where, "c")
+    if kind == "device" and part.startswith("p"):
+        if not getattr(obj, "can_have_drum_pads", False):
+            raise CommandError(
+                "not_found", f"{where} is not a Drum Rack: it has no pads"
+            )
+        number = note_number(part[1:])
+        for pad in obj.drum_pads:
+            if pad.note == number:
+                return "pad", pad
+        raise CommandError("not_found", f"{where} has no pad {part}")
+    raise CommandError(
+        "bad_address",
+        f"{part!r} after {where} is not valid: tracks and chains hold devices (d0), "
+        "racks hold chains (c0), Drum Racks hold pads (pC1)",
+    )
+
+
+def _index(items, i, part, where, letter):
+    if i >= len(items):
+        raise CommandError(
+            "not_found", f"no {part} in {where}: {_range(letter, len(items))}"
+        )
+    return items[i]
+
+
+def _range(letter, count):
+    if count == 0:
+        return "there are none"
+    if count == 1:
+        return f"only {letter}0"
+    return f"{letter}0-{letter}{count - 1}"

tonable/remote_script/Tonable/params.py

@@ -0,0 +1,170 @@
+"""Device parameters as the model should see them: name, display text, raw value."""
+
+import math
+import re
+
+from .server import CommandError
+
+# DeviceParameter.automation_state
+AUTOMATION_STATES = {0: None, 1: "automated", 2: "overridden"}
+
+
+def describe(param, index=None):
+    """One parameter: display text first, then the raw value and its range."""
+    out = {}
+    if index is not None:
+        out["index"] = index
+    out["name"] = param.name
+    out["display"] = display(param)
+    out["value"] = param.value
+    if param.is_quantized:
+        out["options"] = [str(item) for item in param.value_items]
+    else:
+        out["min"] = param.min
+        out["max"] = param.max
+    if not param.is_enabled:
+        out["enabled"] = False
+    state = AUTOMATION_STATES.get(int(getattr(param, "automation_state", 0)))
+    if state:
+        out["automation"] = state
+    return out
+
+
+def display(param):
+    """The text Live shows for the current value ("262 ms", "-6.0 dB", "On")."""
+    try:
+        return param.str_for_value(param.value)
+    except Exception:
+        return str(param)
+
+
+# --- display text -> raw value ------------------------------------------------
+
+# Base unit for each unit Live shows, and the factor to get there.
+UNITS = {
+    "hz": ("hz", 1.0),
+    "khz": ("hz", 1000.0),
+    "ms": ("ms", 1.0),
+    "s": ("ms", 1000.0),
+    "db": ("db", 1.0),
+    "%": ("%", 1.0),
+    "": ("", 1.0),
+}
+_NUMBER = re.compile(r"\s*([+-]?(?:\d+(?:\.\d*)?|\.\d+)|-?inf)\s*([a-zA-Z%]*)\s*")
+_PAN = re.compile(r"\s*(\d+(?:\.\d*)?)\s*([LR])\s*|\s*(C)\s*", re.I)
+
+
+def parse_display(text):
+    """("number", base unit) for display text like "22.0 kHz", "-inf dB", "25L", "C".
+
+    Pan is a number from left (negative) to right. Returns None if not numeric.
+    """
+    text = str(text)
+    pan = _PAN.fullmatch(text)
+    if pan:
+        if pan.group(3):
+            return 0.0, "pan"
+        sign = -1.0 if pan.group(2).upper() == "L" else 1.0
+        return sign * float(pan.group(1)), "pan"
+    match = _NUMBER.fullmatch(text)
+    if not match:
+        return None
+    number = match.group(1).lower()
+    unit = match.group(2).lower()
+    if unit not in UNITS:
+        return None
+    base, factor = UNITS[unit]
+    value = float("-inf") if number == "-inf" else float(number) * factor
+    return value, base
+
+
+def value_for(param, requested):
+    """(raw value, note or None) for a JSON number (raw) or display text.
+
+    Text is matched against what Live shows: an option name for switches
+    ("On", "Sine"), or a number with or without its unit ("400 ms", "-6", "25L").
+    Nothing is written here; the caller writes and reads the result back.
+    """
+    if isinstance(requested, bool):
+        if param.is_quantized and len(list(param.value_items)) == 2:
+            return (param.max if requested else param.min), None
+        requested = "On" if requested else "Off"
+    if isinstance(requested, (int, float)):
+        raw = float(requested)
+        if not math.isfinite(raw):
+            raise CommandError("bad_value", "the value must be finite")
+        if param.min <= raw <= param.max:
+            return raw, None
+        # Out of the raw range: most likely meant as shown (-6 for -6 dB, 400 for
+        # 400 ms, 30 for 30R), so try it as display text before clamping.
+        if not param.is_quantized:
+            try:
+                return _search(param, f"{raw:g}")
+            except CommandError:
+                pass
+        clamped = min(max(raw, param.min), param.max)
+        return clamped, "clamped to the range"
+    text = str(requested).strip()
+    if param.is_quantized:
+        return _option(param, text), None
+    return _search(param, text)
+
+
+def _option(param, text):
+    items = [str(item) for item in param.value_items]
+    for i, item in enumerate(items):
+        if item.strip().casefold() == text.casefold():
+            return param.min + i
+    if text.lstrip("-").isdigit() and param.min <= int(text) <= param.max:
+        return float(int(text))
+    raise CommandError("bad_value", f"{text!r} is not an option; options: {items}")
+
+
+def _search(param, text):
+    target = parse_display(text)
+    if target is None:
+        raise CommandError(
+            "bad_value",
+            f"{text!r} is not a value like 400 ms, -6 dB, 50 %, 25L or a number",
+        )
+    want, unit = target
+    lo_shown = parse_display(param.str_for_value(param.min))
+    hi_shown = parse_display(param.str_for_value(param.max))
+    if lo_shown is None or hi_shown is None:
+        raise CommandError(
+            "bad_value",
+            f"{param.name} shows {display(param)!r}; give a raw number from "
+            f"{param.min:g} to {param.max:g}",
+        )
+    shown_unit = lo_shown[1]
+    if unit and shown_unit and unit != shown_unit:
+        raise CommandError(
+            "bad_value",
+            f"{param.name} is in {shown_unit or 'plain numbers'}, not {unit}",
+        )
+    rising = hi_shown[0] >= lo_shown[0]
+    lo, hi = param.min, param.max
+    low_end, high_end = sorted((lo_shown[0], hi_shown[0]))
+    if want <= low_end:
+        return (lo if rising else hi), _edge_note(want, low_end)
+    if want >= high_end:
+        return (hi if rising else lo), _edge_note(want, high_end)
+    # Bisect until the floats run out; keep the closest display seen.
+    best = (math.inf, param.value)
+    while True:
+        mid = (lo + hi) / 2
+        if mid in (lo, hi):
+            break
+        shown = parse_display(param.str_for_value(mid))
+        if shown is None:
+            break
+        best = min(best, (abs(shown[0] - want), mid))
+        if (shown[0] < want) == rising:
+            lo = mid
+        else:
+            hi = mid
+    return best[1], None
+
+
+def _edge_note(want, edge):
+    return None if want == edge else "outside the range: set to the nearest end"