@m4l-jweb/bridge 0.6.5 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/bridge",
-  "version": "0.6.5",
+  "version": "0.9.0",
   "description": "m4l-jweb: the browser-side bridge connecting a device's web UI to Max for Live.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -190,6 +190,10 @@ export const CHAIN_OUT = {
   buffer_stop: "buffer_stop",
   /** UI -> instrument: `voice_play <pitch> <vel> <durMs> <channels>` - play one poly~ voice. */
   voice_play: "voice_play",
+  /** UI -> remote: `remote_bind <slot> <lomId>` - point a live.remote~ at a Live parameter. */
+  remote_bind: "remote_bind",
+  /** UI -> remote: `remote_val <slot> <value>` - the next value for that slot, ramped. */
+  remote_val: "remote_val",
 } as const;
 
 /**
@@ -212,6 +216,41 @@ export const STATE_OUT = {
   sync_state: "sync_state",
 } as const;
 
+/** Selectors the WRAPPER answers about this device's own Live parameters. */
+export const PARAM_OUT = {
+  /** UI -> wrapper: `get_param_id <id>` - what is this parameter's LOM id? Reply on `param_id`. */
+  get_param_id: "get_param_id",
+} as const;
+
+/** ...and the reply. */
+export const PARAM_IN = {
+  /** wrapper -> UI: `param_id <id> <lomId>` - 0 means no parameter of that name resolved. */
+  param_id: "param_id",
+} as const;
+
+/**
+ * Selectors the WRAPPER handles for reading and writing the CLIP on this device's
+ * track (`read_notes`/`write_clip` in liveapi.ts). Wrapper-owned, like DEVICE_IN -
+ * no chain is involved, so a device that reads clips needs `unmatchedTo: "js"` so the
+ * bare selector reaches `[js]`. `readClip()` / `writeClip()` below are the shaped API.
+ */
+export const CLIP_OUT = {
+  /** UI -> wrapper: read this TRACK's playing (else first) clip, ignoring the selection. Reply on `notes`. */
+  read_notes: "read_notes",
+  /** UI -> wrapper: read the clip the CURSOR is on (Live's highlighted slot). Reply on `notes`. */
+  read_selected_clip: "read_selected_clip",
+  /** UI -> wrapper: `write_clip <lengthBeats> <n> <pitch start duration velocity> ...` - fill the first empty slot. */
+  write_clip: "write_clip",
+} as const;
+
+/** ...and the reply from a read. */
+export const CLIP_IN = {
+  /** wrapper -> UI: `notes <loopEndBeats> <n> <pitch start duration> ...`. Velocity is not read back. */
+  notes: "notes",
+  /** wrapper -> UI: there was no clip on this track to read. */
+  read_error: "read_error",
+} as const;
+
 /** A note handed to the `midiout` chain. Max does the placing; you do the timing. */
 export interface Note {
   /** MIDI pitch, 0-127. */
@@ -454,6 +493,193 @@ export function playVoice(v: Voice): void {
   outlet(CHAIN_OUT.voice_play, v.slot, v.rate, v.velocity, v.durationMs, v.channels ?? 2);
 }
 
+/* ------------------------------------------------------------------ *
+ * Remote - the `remote` chain (live.remote~ modulation)
+ * ------------------------------------------------------------------ */
+
+/**
+ * Point a `remote` slot at a Live parameter, by LOM id.
+ *
+ * The slot is an index into the device's declared `remotes: <n>`; the id is a LiveAPI
+ * object id for a `DeviceParameter` - `new LiveAPI(...).id`, whatever the app resolved
+ * it from. Until a slot is bound it modulates nothing, which is the safe resting state.
+ *
+ * **Re-bind on every load, and never persist the id.** LOM ids are handles into the
+ * running set, not names: they are not stable across a set reload, so an id saved
+ * yesterday points at whatever occupies that slot today - or at nothing. Persist how
+ * you FOUND the parameter (the device's position, the parameter's name) and resolve it
+ * again; that is the same rule Translate mode's reconciler follows (doc/TODO.md item 1).
+ */
+export function bindRemote(slot: number, lomId: number | string): void {
+  outlet(CHAIN_OUT.remote_bind, slot, lomId);
+}
+
+/**
+ * What is this device's own parameter's LOM id? - the id `bindRemote` needs.
+ *
+ * `id` is a surface parameter id, the same name you passed to `useParam()`: the build
+ * wrote it into the patcher as the Live parameter's `parameter_longname`, so the two
+ * cannot drift. Resolves to 0 if no parameter of that name is on the device, which is
+ * a programming error rather than a runtime condition - check it.
+ *
+ * ASK AGAIN AFTER EVERY LOAD, and never persist what comes back. A LOM id is a handle
+ * into the running set: it is not stable across a set reload, and an id from last time
+ * points at whatever occupies that slot now. This call is cheap; a stale binding is a
+ * filter sweep on someone else's device.
+ */
+export function resolveParamId(id: string, timeoutMs = 2000): Promise<number> {
+  if (!paramIdBound) {
+    paramIdBound = true;
+    bindInlet(PARAM_IN.param_id, (which, lomId) => {
+      const p = paramIdResolvers.get(String(which));
+      if (!p) return;
+      paramIdResolvers.delete(String(which));
+      clearTimeout(p.timer);
+      p.resolve(Number(lomId));
+    });
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      paramIdResolvers.delete(id);
+      reject(new Error(`parameter "${id}": the wrapper never answered get_param_id (${timeoutMs} ms). See the Max console.`));
+    }, timeoutMs);
+    paramIdResolvers.set(id, { resolve, timer });
+    outlet(PARAM_OUT.get_param_id, id);
+  });
+}
+
+const paramIdResolvers = new Map<string, { resolve: (id: number) => void; timer: ReturnType<typeof setTimeout> }>();
+let paramIdBound = false;
+
+/**
+ * Send a slot's next value. Ramped, not stepped.
+ *
+ * Call this on the transport tick with the pattern's value for that moment. The chain
+ * ramps to it over ~20 ms (`REMOTE_RAMP_MS`) rather than jumping, so a control-rate
+ * stream of values comes out of Max as continuous modulation - see the `remote` chain
+ * for why that ramp is the whole point.
+ *
+ * THE VALUE IS NOT IN THE PARAMETER'S OWN UNITS - measured in Live, not read
+ * anywhere. live.remote~ treats it as a LINEAR position across the parameter's
+ * range and applies the knob's `exponent` curve on top, as if the number had
+ * grabbed the dial by its travel. For an exponent-1 parameter the two notions
+ * coincide and raw units work; for a curved one (a filter cutoff at exponent 4)
+ * the app must pre-warp: aim the travel at norm(v)^(1/e) so Live's ^e lands on v.
+ * See m4l-strudel's useModulation.toRemote for the worked inverse.
+ */
+export function writeRemote(slot: number, value: number): void {
+  outlet(CHAIN_OUT.remote_val, slot, value);
+}
+
+/* ------------------------------------------------------------------ *
+ * Clip I/O - read and write the MIDI clip on this device's track
+ *
+ * The wrapper does the LiveAPI work (`read_notes`/`write_clip` in liveapi.ts); these
+ * are the shaped API over it. No chain and no `[node.script]` - a clip is note data,
+ * which is control-plane, so it crosses the bridge as a message. Needs
+ * `unmatchedTo: "js"` in the manifest so the bare selector reaches `[js]`.
+ * ------------------------------------------------------------------ */
+
+/** One note in a clip. Times are in BEATS, from the clip's start. */
+export interface ClipNote {
+  pitch: number;
+  /** Start, in beats from the clip's start. */
+  start: number;
+  /** Length, in beats. */
+  duration: number;
+  /** 1-127. Only WRITTEN - a read does not return it. */
+  velocity: number;
+}
+
+/** What a clip read returns: the loop length and the notes (velocity is not read back). */
+export interface ReadClip {
+  /** The clip's loop end, in beats - its musical length. */
+  loopEnd: number;
+  notes: Omit<ClipNote, "velocity">[];
+}
+
+const readClipResolvers: { resolve: (c: ReadClip) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }[] = [];
+let clipReadBound = false;
+
+/** Bind the shared reply path once - both read paths answer on `notes` / `read_error`. */
+function bindClipRead(): void {
+  if (clipReadBound) return;
+  clipReadBound = true;
+  // One reply per outstanding read, in order - Live answers a read with one `notes`
+  // (or one `read_error`), and reads are not interleaved in practice.
+  bindInlet(CLIP_IN.notes, (...args) => {
+    const p = readClipResolvers.shift();
+    if (!p) return;
+    clearTimeout(p.timer);
+    const loopEnd = Number(args[0]);
+    const n = Number(args[1]);
+    const notes: Omit<ClipNote, "velocity">[] = [];
+    for (let k = 0; k < n; k++) {
+      const o = 2 + k * 3;
+      notes.push({ pitch: Number(args[o]), start: Number(args[o + 1]), duration: Number(args[o + 2]) });
+    }
+    p.resolve({ loopEnd, notes });
+  });
+  bindInlet(CLIP_IN.read_error, (reason) => {
+    const p = readClipResolvers.shift();
+    if (!p) return;
+    clearTimeout(p.timer);
+    // The wrapper says WHY: "no_clip" (track has none) or "no_selection" (highlighted
+    // slot is empty). Either way there is nothing to read.
+    p.reject(new Error(String(reason) === "no_selection" ? "no clip in the highlighted slot - click a clip first" : "no clip on this track - create or play a MIDI clip first"));
+  });
+}
+
+function requestClipRead(selector: string, timeoutMs: number): Promise<ReadClip> {
+  bindClipRead();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const i = readClipResolvers.findIndex((r) => r.timer === timer);
+      if (i >= 0) readClipResolvers.splice(i, 1);
+      reject(new Error(`the wrapper never answered ${selector} (${timeoutMs} ms). See the Max console.`));
+    }, timeoutMs);
+    readClipResolvers.push({ resolve, reject, timer });
+    outlet(selector);
+  });
+}
+
+/**
+ * Read the MIDI clip on this device's TRACK - the PLAYING one, or the first found,
+ * regardless of the selection. Rejects if the track has no clip, or if the wrapper does
+ * not answer inside `timeoutMs`. This is the right call for a device that operates on
+ * its own track's pattern; for the clip the user has CLICKED, use `readSelectedClip()`.
+ *
+ * The bytes are notes, not audio, so unlike a sample they DO cross the bridge: the
+ * wrapper reads them with LiveAPI's `get_notes_extended` and sends
+ * `notes <loopEnd> <n> <pitch start duration> ...`.
+ */
+export function readClip(timeoutMs = 2000): Promise<ReadClip> {
+  return requestClipRead(CLIP_OUT.read_notes, timeoutMs);
+}
+
+/**
+ * Read the clip the CURSOR is on - Live's highlighted clip slot, whichever track and
+ * scene. An empty highlighted slot rejects with "no clip in the highlighted slot", so
+ * clicking an empty slot reads nothing rather than falling back to another clip. Same
+ * resolved shape as `readClip()`.
+ */
+export function readSelectedClip(timeoutMs = 2000): Promise<ReadClip> {
+  return requestClipRead(CLIP_OUT.read_selected_clip, timeoutMs);
+}
+
+/**
+ * Write a clip into the first empty slot on this device's track.
+ *
+ * `lengthBeats` is the clip's length; the notes' `start`/`duration` are in beats
+ * within it. The message is a flat list (`write_clip <lengthBeats> <n> <p s d v> ...`)
+ * because Max has no nested arguments - the wrapper reads it back four atoms at a time.
+ */
+export function writeClip(lengthBeats: number, notes: readonly ClipNote[]): void {
+  const flat: number[] = [lengthBeats, notes.length];
+  for (const nt of notes) flat.push(nt.pitch, nt.start, nt.duration, nt.velocity);
+  outlet(CLIP_OUT.write_clip, ...flat);
+}
+
 /**
  * Max splits messages on commas and semicolons, so any structured payload -
  * JSON, code, a filesystem path - must be encoded before it crosses the bridge.