tonable 0.5.2__py3-none-any.whl

tonable/remote_script/Tonable/clips.py

@@ -0,0 +1,364 @@
+"""Session clips and their notes: read_clip and write_clip. Main thread only.
+
+A clip is addressed by its track (t0) and slot (the scene row, from 0). Times are in
+beats from the clip start. Pitches are MIDI numbers or names with C3 = 60.
+"""
+
+import math
+
+from . import objects
+from .server import CommandError
+from .song import undo_step
+
+try:
+    import Live
+except ImportError:  # imported by the tests, outside Live
+    Live = None
+
+
+def read_clip(song, track_ref, slot_index):
+    track, slot, where = _slot(song, track_ref, slot_index)
+    if not slot.has_clip:
+        raise CommandError("not_found", f"{where} is empty")
+    clip = slot.clip
+    out = {"track": objects.track_path(song, track), "slot": slot_index}
+    out.update(_clip_info(clip))
+    if clip.is_midi_clip:
+        out["notes"] = [_note_out(n) for n in _sorted(clip.get_all_notes_extended())]
+    return out
+
+
+def write_clip(song, params):
+    """Create a MIDI clip or change one, and write notes, as one undo step."""
+    track_ref = params.get("track")
+    slot_index = params.get("slot")
+    mode = params.get("mode") or "replace"
+    if mode not in ("replace", "add"):
+        raise CommandError("bad_params", "mode must be replace or add")
+    track, slot, where = _slot(song, track_ref, slot_index)
+    if not getattr(track, "has_midi_input", False):
+        raise CommandError("bad_target", f"{where}: {track.name} is not a MIDI track")
+
+    notes, rejected = parse_notes(params.get("notes") or [])
+    length = _beats(params.get("length_beats"), "length_beats", allow_zero=True)
+    name = params.get("name") or ""
+
+    with undo_step(song):
+        created = not slot.has_clip
+        if created:
+            slot.create_clip(length or fit_length(song, notes))
+        clip = slot.clip
+        if not clip.is_midi_clip:
+            raise CommandError("bad_target", f"{where} holds an audio clip")
+        if length and not created:
+            _set_length(clip, length)
+        removed = 0
+        if mode == "replace":
+            old = list(clip.get_all_notes_extended())
+            if old:
+                clip.remove_notes_by_id(tuple(n.note_id for n in old))
+            removed = len(old)
+        if notes:
+            clip.add_new_notes(tuple(_note_spec(n) for n in notes))
+        if name:
+            clip.name = name
+
+    out = {
+        "track": objects.track_path(song, track),
+        "slot": slot_index,
+        "created": created,
+        **_clip_info(clip),
+        "notes_added": len(notes),
+        "notes_removed": removed,
+        "notes_total": len(list(clip.get_all_notes_extended())),
+    }
+    late = [i for i, n in enumerate(notes) if n["start"] >= clip.length]
+    if late:
+        out["warning"] = (
+            f"{len(late)} note(s) start after the clip end ({clip.length:g} beats) and "
+            "will not play; give a longer length_beats"
+        )
+    if rejected:
+        out["rejected"] = rejected
+    return out
+
+
+# --- notes -----------------------------------------------------------------
+
+
+def parse_notes(raw):
+    """(good notes, rejected notes). One bad note never rejects the others."""
+    if isinstance(raw, dict):
+        raw = [raw]
+    if not isinstance(raw, list):
+        raise CommandError("bad_params", "notes must be a list of note objects")
+    good, rejected = [], []
+    for i, item in enumerate(raw):
+        try:
+            good.append(parse_note(item))
+        except CommandError as err:
+            rejected.append({"index": i, "note": item, "error": str(err)})
+    return good, rejected
+
+
+def parse_note(item):
+    if not isinstance(item, dict):
+        raise CommandError(
+            "bad_note", "a note must be an object with pitch, start, length"
+        )
+    return {
+        "pitch": parse_pitch(_field(item, "pitch", "note")),
+        "start": _beats(_field(item, "start", "start_beats", "time"), "start", True),
+        "length": _beats(_field(item, "length", "duration", "length_beats"), "length"),
+        "velocity": _velocity(_field(item, "velocity", "vel")),
+        "mute": bool(item.get("mute") or False),
+    }
+
+
+def parse_pitch(value):
+    if value is None or value == "":
+        raise CommandError("bad_note", "pitch is required (60 or C3)")
+    if isinstance(value, bool):
+        raise CommandError("bad_note", "pitch must be a number or a note name")
+    if isinstance(value, (int, float)) or str(value).strip().lstrip("-").isdigit():
+        number = float(value)
+        if number != int(number) or not 0 <= number <= 127:
+            raise CommandError("bad_note", f"pitch {value} is not a MIDI note 0-127")
+        return int(number)
+    return objects.note_number(str(value).strip())
+
+
+def fit_length(song, notes):
+    """Whole bars that hold every note; one bar when there are none."""
+    bar = song.signature_numerator * 4.0 / song.signature_denominator
+    end = max((n["start"] + n["length"] for n in notes), default=0.0)
+    return max(1, math.ceil(end / bar)) * bar
+
+
+def _field(item, *names):
+    for name in names:
+        if item.get(name) not in (None, ""):
+            return item[name]
+    return None
+
+
+def _beats(value, name, allow_zero=False):
+    if value is None or value == "":
+        if allow_zero:
+            return 0.0
+        raise CommandError("bad_note", f"{name} is required (in beats)")
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        raise CommandError("bad_note", f"{name} must be a number of beats") from None
+    if not math.isfinite(number) or number < 0 or (number == 0 and not allow_zero):
+        raise CommandError(
+            "bad_note", f"{name} must be {'0 or more' if allow_zero else 'more than 0'}"
+        )
+    return number
+
+
+def _velocity(value):
+    if value is None or value == "":
+        raise CommandError("bad_note", "velocity is required (1-127)")
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        raise CommandError("bad_note", "velocity must be a number 1-127") from None
+    if not 1 <= number <= 127:
+        raise CommandError("bad_note", f"velocity {value} is outside 1-127")
+    return number
+
+
+def _note_spec(note):
+    return Live.Clip.MidiNoteSpecification(
+        pitch=note["pitch"],
+        start_time=note["start"],
+        duration=note["length"],
+        velocity=note["velocity"],
+        mute=note["mute"],
+    )
+
+
+def _note_out(note):
+    out = {
+        "pitch": objects.note_name(note.pitch),
+        "midi": note.pitch,
+        "start": note.start_time,
+        "length": note.duration,
+        "velocity": note.velocity,
+    }
+    if note.mute:
+        out["mute"] = True
+    return out
+
+
+def _sorted(notes):
+    return sorted(notes, key=lambda n: (n.start_time, n.pitch))
+
+
+# --- clips and slots ---------------------------------------------------------
+
+
+def _slot(song, track_ref, slot_index):
+    if track_ref is None or str(track_ref).strip() == "":
+        raise CommandError("bad_params", "track is required (t0)")
+    track = objects.track(song, track_ref)
+    path = objects.track_path(song, track)
+    if not path.startswith("t"):
+        raise CommandError(
+            "bad_target", f"{path} has no clip slots: use a track t0, t1..."
+        )
+    try:
+        index = int(slot_index)
+    except (TypeError, ValueError):
+        raise CommandError("bad_params", "slot must be a scene number 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}: the Set has {len(slots)} scenes (slots 0-"
+            f"{len(slots) - 1}); add a scene first",
+        )
+    return track, slots[index], f"{path} slot {index}"
+
+
+def _clip_info(clip):
+    out = {
+        "name": clip.name,
+        "type": "midi" if clip.is_midi_clip else "audio",
+        "length_beats": clip.length,
+        "looping": bool(clip.looping),
+    }
+    if clip.looping:
+        out["loop"] = {"start_beats": clip.loop_start, "end_beats": clip.loop_end}
+    return out
+
+
+def _set_length(clip, length):
+    """Make the clip `length` beats long from its loop start."""
+    end = clip.loop_start + length
+    if end > clip.end_marker:
+        clip.end_marker = end
+        clip.loop_end = end
+    else:
+        clip.loop_end = end
+        clip.end_marker = end
+
+
+# --- edit_notes -------------------------------------------------------------
+
+EDIT_ACTIONS = ("delete", "transpose", "shift", "quantize", "velocity", "length")
+
+
+def edit_notes(song, params):
+    """Change the notes in a time and pitch range, as one undo step.
+
+    The range: from_beats (inclusive) to to_beats (exclusive) by note start, and
+    pitches (names or numbers); empty means all notes.
+    """
+    action = params.get("action")
+    if action not in EDIT_ACTIONS:
+        raise CommandError(
+            "bad_params", "action must be one of: " + ", ".join(EDIT_ACTIONS)
+        )
+    track, slot, where = _slot(song, params.get("track"), params.get("slot"))
+    if not slot.has_clip or not slot.clip.is_midi_clip:
+        raise CommandError("not_found", f"{where} has no MIDI clip")
+    clip = slot.clip
+    notes = clip.get_all_notes_extended()
+    chosen = [n for n in notes if _in_range(n, params)]
+    skipped = []
+    with undo_step(song):
+        if action == "delete":
+            if chosen:
+                clip.remove_notes_by_id(tuple(n.note_id for n in chosen))
+        else:
+            change = _change(action, params)
+            for note in chosen:
+                reason = change(note)
+                if reason:
+                    skipped.append(
+                        {
+                            "pitch": objects.note_name(note.pitch),
+                            "start": note.start_time,
+                            "reason": reason,
+                        }
+                    )
+            clip.apply_note_modifications(notes)
+    out = {
+        "track": objects.track_path(song, track),
+        "slot": int(params.get("slot")),
+        "action": action,
+        "notes_matched": len(chosen),
+        "notes_total": len(list(clip.get_all_notes_extended())),
+    }
+    if skipped:
+        out["skipped"] = skipped
+    return out
+
+
+def _in_range(note, params):
+    start, end = params.get("from_beats"), params.get("to_beats")
+    if start not in (None, "") and note.start_time < float(start):
+        return False
+    if end not in (None, "") and note.start_time >= float(end):
+        return False
+    pitches = params.get("pitches")
+    if pitches not in (None, "", []):
+        if not isinstance(pitches, list):
+            pitches = [pitches]
+        if note.pitch not in {parse_pitch(p) for p in pitches}:
+            return False
+    return True
+
+
+def _change(action, params):
+    """A function that changes one note and returns why it could not, or None."""
+    if action == "transpose":
+        steps = int(_number(params, "semitones"))
+
+        def apply(note):
+            if not 0 <= note.pitch + steps <= 127:
+                return "would leave MIDI notes 0-127"
+            note.pitch += steps
+
+    elif action == "shift":
+        beats = _number(params, "beats")
+
+        def apply(note):
+            if note.start_time + beats < 0:
+                return "would start before the clip"
+            note.start_time += beats
+
+    elif action == "quantize":
+        grid = _number(params, "grid_beats")
+        if grid <= 0:
+            raise CommandError(
+                "bad_params", "grid_beats must be more than 0, e.g. 0.25"
+            )
+
+        def apply(note):
+            note.start_time = round(note.start_time / grid) * grid
+
+    elif action == "velocity":
+        velocity = _velocity(params.get("velocity"))
+
+        def apply(note):
+            note.velocity = velocity
+
+    else:  # length
+        length = _beats(params.get("length_beats"), "length_beats")
+
+        def apply(note):
+            note.duration = length
+
+    return apply
+
+
+def _number(params, name):
+    value = params.get(name)
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        raise CommandError("bad_params", f"{name} is required (a number)") from None

tonable/remote_script/Tonable/devices.py

@@ -0,0 +1,188 @@
+"""set_device_params and update_device. Main thread only."""
+
+from . import objects, params, reading
+from .server import CommandError
+from .song import undo_step
+
+
+def set_device_params(song, p):
+    """Write parameters by name or index; one result line per parameter.
+
+    One bad parameter never stops the others. Values are raw numbers or display
+    text ("400 ms", "-6 dB", "On"); each line says what Live shows afterwards.
+    """
+    kind, device, path = objects.resolve(song, p.get("target") or "")
+    if kind != "device":
+        raise CommandError("bad_target", f"{path} is a {kind}, not a device")
+    wanted = _param_list(p.get("params"))
+    if not wanted:
+        raise CommandError(
+            "bad_params",
+            'params is required: [{"param": "Release", "value": "400 ms"}]',
+        )
+    plist = list(device.parameters)
+    results = []
+    with undo_step(song):
+        for item in wanted:
+            results.append(_write_one(plist, item))
+    return {"target": path, "device": device.name, "results": results}
+
+
+def update_device(song, p):
+    """Turn on/off, rename, move, store or recall a variation, show macros, or mute
+    and solo a chain or pad. Only given fields change."""
+    kind, obj, path = objects.resolve(song, p.get("target") or "")
+    results = []
+    with undo_step(song):
+        if kind in ("chain", "pad"):
+            for flag in ("mute", "solo"):
+                if p.get(flag) not in (None, ""):
+                    setattr(obj, flag, _bool(p[flag]))
+                    results.append({"field": flag, "now": bool(getattr(obj, flag))})
+        elif kind == "device":
+            results.extend(_update_device(song, obj, path, p))
+        else:
+            raise CommandError("bad_target", f"{path} is a track: use update_track")
+    if not results:
+        raise CommandError("bad_params", "nothing to change: give at least one field")
+    return {"target": path, "results": results}
+
+
+def _update_device(song, device, path, p):
+    out = []
+    if p.get("on") not in (None, ""):
+        switch = device.parameters[0]
+        switch.value = switch.max if _bool(p["on"]) else switch.min
+        out.append({"field": "on", "now": switch.value > switch.min})
+    if p.get("name") not in (None, ""):
+        device.name = str(p["name"])
+        out.append({"field": "name", "now": device.name})
+    if p.get("visible_macros") not in (None, ""):
+        out.append(_visible_macros(device, int(p["visible_macros"])))
+    variation = p.get("variation")
+    if variation not in (None, ""):
+        out.append(_variation(device, variation))
+    if p.get("move_to") not in (None, ""):
+        out.append(_move(song, device, str(p["move_to"]), p.get("index")))
+    return out
+
+
+def _write_one(plist, item):
+    ref = item.get("param", item.get("name", item.get("index")))
+    value = item.get("value")
+    label = str(ref)
+    param = _find(plist, ref)
+    if param is None:
+        names = [x.name for x in plist]
+        similar = reading._similar(str(ref), plist) if names else []
+        return {"param": label, "error": "no such parameter", "similar": similar}
+    label = param.name
+    if value in (None, ""):
+        return {"param": label, "error": "value is required"}
+    if not param.is_enabled:
+        return {"param": label, "error": "disabled: a macro or modulation controls it"}
+    try:
+        raw, note = params.value_for(param, value)
+        param.value = raw
+    except CommandError as err:
+        return {"param": label, "error": str(err)}
+    except Exception as err:
+        return {"param": label, "error": f"Live refused: {err}"}
+    out = {"param": label, "now": params.display(param), "value": param.value}
+    if note:
+        out["note"] = note
+    if int(getattr(param, "automation_state", 0)) == 1:
+        out["warning"] = (
+            "this parameter has automation, which Live now ignores until "
+            "transport re_enable_automation"
+        )
+    return out
+
+
+def _find(plist, ref):
+    if isinstance(ref, bool) or ref in (None, ""):
+        return None
+    if isinstance(ref, int) or str(ref).strip().isdigit():
+        i = int(ref)
+        return plist[i] if 0 <= i < len(plist) else None
+    wanted = str(ref).strip().casefold()
+    for param in plist:
+        if param.name.casefold() == wanted:
+            return param
+    return None
+
+
+def _param_list(raw):
+    """[{param, value}] from a list, one object, or {"Release": "400 ms"} (also
+    when a client wraps that mapping in a list)."""
+    if raw in (None, ""):
+        return []
+    if isinstance(raw, dict):
+        raw = [raw]
+    out = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        if any(key in item for key in ("param", "name", "index")):
+            out.append(item)
+        else:
+            out.extend({"param": k, "value": v} for k, v in item.items())
+    return out
+
+
+def _visible_macros(rack, count):
+    if not getattr(rack, "can_have_chains", False):
+        return {"field": "visible_macros", "error": "only racks have macros"}
+    try:
+        while rack.visible_macro_count < count:
+            rack.add_macro()
+        while rack.visible_macro_count > count:
+            rack.remove_macro()
+    except Exception as err:
+        return {"field": "visible_macros", "error": f"Live refused: {err}"}
+    return {"field": "visible_macros", "now": rack.visible_macro_count}
+
+
+def _variation(rack, action):
+    if not hasattr(rack, "store_variation"):
+        return {"field": "variation", "error": "only racks have macro variations"}
+    text = str(action).strip().lower()
+    try:
+        if text == "store":
+            rack.store_variation()
+        elif text.isdigit():
+            rack.selected_variation_index = int(text)
+            rack.recall_selected_variation()
+        else:
+            return {
+                "field": "variation",
+                "error": "use store or a variation number from 0",
+            }
+    except Exception as err:
+        return {"field": "variation", "error": f"Live refused: {err}"}
+    return {
+        "field": "variation",
+        "now": {
+            "selected": rack.selected_variation_index,
+            "count": rack.variation_count,
+        },
+    }
+
+
+def _move(song, device, holder_path, index):
+    kind, holder, path = objects.resolve(song, holder_path)
+    if kind not in ("track", "chain"):
+        return {"field": "move_to", "error": f"{path} cannot hold devices"}
+    count = len(list(holder.devices))
+    index = count if index in (None, "", -1) else int(index)
+    try:
+        song.move_device(device, holder, index)
+    except Exception as err:
+        return {"field": "move_to", "error": f"Live refused: {err}"}
+    return {"field": "move_to", "now": f"{path}/d{min(index, count)}"}
+
+
+def _bool(value):
+    if isinstance(value, str):
+        return value.strip().lower() in ("true", "on", "yes", "1")
+    return bool(value)