@m4l-jweb/bridge 0.9.1 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m4l-jweb/bridge",
-  "version": "0.9.1",
+  "version": "0.9.9",
   "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

@@ -168,10 +168,10 @@ export const CHAIN_IN = {
   fetch_error: "fetch_error",
   /** download -> UI: `fetch_progress <requestId> <downloaded> <total>`. */
   fetch_progress: "fetch_progress",
-  /** samples -> UI: `buffer_ready <slot> <sampleRate> <ms> <channels>` - what actually loaded. */
-  buffer_ready: "buffer_ready",
-  /** samples -> UI: `buffer_error <slot> <msg>` - there was no readable file at that path. */
-  buffer_error: "buffer_error",
+  /** download -> UI: `save_done <requestId> <bytes>` - the file is written and verified. */
+  save_done: "save_done",
+  /** download -> UI: `save_error <requestId> <msg>` - the write or atomic place failed. */
+  save_error: "save_error",
 } as const;
 
 /** Selectors the packaged chains RECEIVE from the UI. Requires the `midiout` chain. */
@@ -182,18 +182,16 @@ export const CHAIN_OUT = {
   flush: "flush",
   /** UI -> download: `fetch_to_file <requestId> <url> <destPath>`. */
   fetch_to_file: "fetch_to_file",
-  /** UI -> samples: `buffer_load <slot> <path>` - read a file into that slot's [buffer~]. */
-  buffer_load: "buffer_load",
-  /** UI -> samples: `buffer_play <slot>` - preview it through the track. */
-  buffer_play: "buffer_play",
-  /** UI -> samples: `buffer_stop` - stop the preview. */
-  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",
+  /** UI -> download: `save_begin <requestId> <destPath> <byteCount>` - open a .part file. */
+  save_begin: "save_begin",
+  /** UI -> download: `save_chunk <requestId> <base64>` - one slice of the payload. */
+  save_chunk: "save_chunk",
+  /** UI -> download: `save_end <requestId>` - close, verify size, atomic place. */
+  save_end: "save_end",
 } as const;
 
 /**
@@ -281,15 +279,56 @@ export function sendNote(note: Note): void {
   outlet(CHAIN_OUT.midinote, note.pitch, note.velocity, note.durationMs, note.channel ?? 1, note.delayMs ?? 0);
 }
 
-/** Bind incoming MIDI. Note-offs are filtered out: `makenote` already owns the release. */
-export function onNote(fn: (pitch: number, velocity: number) => void): void {
+/* ------------------------------------------------------------------ *
+ * Incoming MIDI notes
+ *
+ * `bindInlet` keeps ONE handler per selector - a second bind REPLACES the first. So
+ * `onNote` and `onNoteOff` must not each call it: whichever ran last would win and the
+ * other's events would vanish. (They did, and a synth that bound both went deaf to
+ * every note-on.) Instead ONE `notein` binding fans out to two subscriber sets, which
+ * also means two `onNote` callers no longer silently clobber each other.
+ * ------------------------------------------------------------------ */
+
+const noteOnHandlers = new Set<(pitch: number, velocity: number) => void>();
+const noteOffHandlers = new Set<(pitch: number) => void>();
+let noteinBound = false;
+
+function bindNotein(): void {
+  if (noteinBound) return;
+  noteinBound = true;
   bindInlet(CHAIN_IN.notein, (pitch, velocity) => {
-    const v = Number(velocity);
-    if (v === 0) return;
-    fn(Number(pitch), v);
+    const p = Number(pitch);
+    // Max's `midiparse` reports a release as velocity ZERO, not as a distinct message.
+    if (Number(velocity) === 0) for (const fn of noteOffHandlers) fn(p);
+    else for (const fn of noteOnHandlers) fn(p, Number(velocity));
   });
 }
 
+/**
+ * Bind incoming MIDI note-ONS. Note-offs are filtered out, which is what a one-shot
+ * wants: a struck sample (a piano, a drum) decays on its own and a release message
+ * would only cut it short. A SUSTAINING voice needs the other half - see `onNoteOff`.
+ *
+ * Requires the `midiin` chain, and therefore a device of type "instrument" (an audio
+ * effect has no MIDI ports).
+ */
+export function onNote(fn: (pitch: number, velocity: number) => void): void {
+  noteOnHandlers.add(fn);
+  bindNotein();
+}
+
+/**
+ * Bind incoming MIDI note-OFFS - the releases `onNote` drops.
+ *
+ * Bind this when the voice you start SUSTAINS: an oscillator held open by a note-on
+ * rings forever unless something tells it the key came up. Safe to use alongside
+ * `onNote` - they share one binding and split the stream by velocity.
+ */
+export function onNoteOff(fn: (pitch: number) => void): void {
+  noteOffHandlers.add(fn);
+  bindNotein();
+}
+
 /**
  * Release every note the chain is currently holding.
  *
@@ -349,149 +388,72 @@ export function fetchToFile(url: string, destPath: string, onProgress?: (downloa
   });
 }
 
-/* ------------------------------------------------------------------ *
- * Samples - the `samples` chain
- * ------------------------------------------------------------------ */
-
-/** What a slot actually holds, once the read completed. Reported by [info~], not assumed. */
-export interface LoadedSample {
-  /** The FILE's sample rate, which need not be Live's. */
-  sampleRate: number;
-  durationMs: number;
-  /** The file's channel count. `replace` adopts it - a slot is not mono by wishing. */
-  channels: number;
-  /** Derived from the two above. Nobody counted them. */
-  frames: number;
+/**
+ * Base64-encode raw bytes in slices, so a multi-megabyte buffer does not blow the
+ * call stack (`String.fromCharCode(...hugeArray)` does). btoa wants a binary string;
+ * we build it 32 KB at a time. No newlines, so the result is one safe Max symbol
+ * once re-sliced by SAVE_B64_CHUNK.
+ */
+export function encodeBytesBase64(bytes: ArrayBuffer): string {
+  const view = new Uint8Array(bytes);
+  const SLICE = 0x8000; // 32 KB per fromCharCode call
+  let binary = "";
+  for (let o = 0; o < view.length; o += SLICE) {
+    binary += String.fromCharCode(...view.subarray(o, o + SLICE));
+  }
+  return btoa(binary);
 }
 
-const sampleResolvers = new Map<string, { resolve: (s: LoadedSample) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
-let samplesBound = false;
+const SAVE_B64_CHUNK = 8192; // base64 chars per message; well under Max atom limits
+
+const saveResolvers = new Map<string, { resolve: (v: { bytes: number }) => void; reject: (e: Error) => void }>();
+let saveBound = false;
 
 /**
- * Read a file from disk into a slot's [buffer~], and resolve with WHAT LANDED.
- *
- * Requires the `samples` chain, and the file must already be on disk - that is what
- * `fetchToFile()` is for. The bytes never cross the bridge in either direction: Max
- * reads the file, and what comes back is a description of it.
- *
- * WAV, AIFF OR NEXT/SUN - NOT MP3. That is [buffer~]'s list, from its reference page,
- * and it is shorter than Max's: MP3, OGG, FLAC and M4A belong to [sfplay~], which
- * streams from disk rather than filling a buffer. Handing this an MP3 gets you an
- * error in the Max console, no reply, and the timeout below - the file downloads
- * perfectly and simply never becomes audio.
- *
- * The resolved value is measured, not assumed. `replace` adopts the file's channel
- * count and sample rate, so a stereo file in a slot you think of as mono is a stereo
- * slot - and a frame count is not proof of a read, because a FAILED read leaves the
- * previous contents of the buffer exactly where they were. The chain only replies
- * when [buffer~] says the read completed; a file Max cannot read produces an error in
- * the Max console and NO reply at all, which is what the timeout below is for. There
- * is no bang for failure to bind to.
+ * Write raw bytes straight to disk via the `download` chain's [js] wrapper.
+ *
+ * The inverse of `fetchToFile`: instead of Max pulling a URL, the UI hands the bytes
+ * over base64 in slices and the wrapper writes them to a `.part` file, then atomically
+ * places it at `destPath` via [maxurl] (the same move fetchToFile phase 2 uses). The
+ * bytes travel base64 because Max splits messages on spaces/commas and base64 has
+ * neither. Requires the `download` chain in the device manifest.
+ *
+ * @param destPath Absolute path (or device-relative, resolved wrapper-side) to write.
+ * @param bytes The payload. A per-cycle WAV is ~350 KB => ~60 messages.
+ * @returns Resolves with the verified byte count once the file is placed.
  */
-export function loadSample(slot: string, path: string, timeoutMs = 10_000): Promise<LoadedSample> {
-  if (!samplesBound) {
-    samplesBound = true;
-    bindInlet(CHAIN_IN.buffer_ready, (id, sampleRate, ms, channels) => {
-      const p = sampleResolvers.get(String(id));
-      if (!p) return;
-      sampleResolvers.delete(String(id));
-      clearTimeout(p.timer);
-      const sr = Number(sampleRate);
-      const durationMs = Number(ms);
-      const chans = Number(channels);
-      // An empty buffer is a read that "worked" and gave us nothing. Do not hand the
-      // app a slot it will play in silence and blame itself for.
-      if (!(sr > 0) || !(durationMs > 0) || !(chans > 0)) {
-        p.reject(new Error(`slot "${id}" loaded empty: ${durationMs} ms, ${chans} channels at ${sr} Hz`));
-        return;
+export function saveToFile(destPath: string, bytes: ArrayBuffer): Promise<{ bytes: number }> {
+  if (!saveBound) {
+    saveBound = true;
+    bindInlet(CHAIN_IN.save_done, (id, n) => {
+      const p = saveResolvers.get(String(id));
+      if (p) {
+        p.resolve({ bytes: Number(n) });
+        saveResolvers.delete(String(id));
       }
-      p.resolve({ sampleRate: sr, durationMs, channels: chans, frames: Math.round((durationMs / 1000) * sr) });
     });
-    // The failure the wrapper CAN see - no file, or an empty one - arrives at once,
-    // rather than as ten seconds of silence. The failure it cannot see (a file Max
-    // will not decode) still has no event: [buffer~] says nothing, and the timeout is
-    // the only thing that ever will.
-    bindInlet(CHAIN_IN.buffer_error, (id, msg) => {
-      const p = sampleResolvers.get(String(id));
-      if (!p) return;
-      sampleResolvers.delete(String(id));
-      clearTimeout(p.timer);
-      p.reject(new Error(String(msg)));
+    bindInlet(CHAIN_IN.save_error, (id, msg) => {
+      const p = saveResolvers.get(String(id));
+      if (p) {
+        p.reject(new Error(String(msg)));
+        saveResolvers.delete(String(id));
+      }
     });
   }
 
   return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      sampleResolvers.delete(slot);
-      reject(new Error(`slot "${slot}": [buffer~] never reported a completed read of "${path}" (${timeoutMs} ms). See the Max console.`));
-    }, timeoutMs);
-    sampleResolvers.set(slot, { resolve, reject, timer });
-    outlet(CHAIN_OUT.buffer_load, slot, path);
+    const requestId = Math.random().toString(36).substring(2, 10);
+    saveResolvers.set(requestId, { resolve, reject });
+    const b64 = encodeBytesBase64(bytes);
+    outlet(CHAIN_OUT.save_begin, requestId, destPath, bytes.byteLength);
+    for (let o = 0; o < b64.length; o += SAVE_B64_CHUNK) {
+      outlet(CHAIN_OUT.save_chunk, requestId, b64.slice(o, o + SAVE_B64_CHUNK));
+    }
+    outlet(CHAIN_OUT.save_end, requestId);
   });
 }
 
-/**
- * Play a loaded slot, once, from the beginning - THROUGH THE TRACK.
- *
- * That last part is the whole reason this exists. Audio a page plays for itself goes
- * to the OS output device: [jweb] has no signal outlets, so it bypasses the track,
- * the fader and the monitor cue. A preview Live can hear has to be [buffer~] in the
- * patcher, which is this.
- */
-export function playSample(slot: string): void {
-  outlet(CHAIN_OUT.buffer_play, slot);
-}
 
-/** Stop the preview. One voice, so this stops whichever slot is sounding. */
-export function stopSample(): void {
-  outlet(CHAIN_OUT.buffer_stop);
-}
-
-/* ------------------------------------------------------------------ *
- * Instrument - the `instrument` chain ([poly~] voices)
- * ------------------------------------------------------------------ */
-
-/** One played note, handed to the `instrument` chain's [poly~]. The app times it; Max allocates a voice. */
-export interface Voice {
-  /**
-   * Which slot's buffer to play, as a 0-based INDEX into the device's `slots` (the
-   * order declared in the manifest). The instrument is a keymap of named buffers, so a
-   * note names its sample; the app owns the slot order and passes the index.
-   */
-  slot: number;
-  /**
-   * Playback RATE. 1 plays the buffer at its recorded pitch; 2 is an octave up, 0.5 an
-   * octave down. EXPLICIT, so the app decides whether a note plays a dedicated sample
-   * (rate 1) or a repitched one - the chain does no pitch arithmetic.
-   */
-  rate: number;
-  /** 1-127. Scaled to amplitude in the voice. */
-  velocity: number;
-  /** How long to HOLD the voice, in ms - after which [poly~] frees it for re-use. */
-  durationMs: number;
-  /**
-   * That slot's channel count, as reported by `loadSample`'s `buffer_ready`. A mono
-   * buffer (1) is folded to both ears in the voice; pass what you measured, not what
-   * you hoped for. Defaults to 2 (no fold).
-   */
-  channels?: number;
-}
-
-/**
- * Play one note through the `instrument` chain's [poly~].
- *
- * Requires the note's slot already loaded (via `loadSample`, the same call the sampler
- * uses). Polyphony and voice-stealing are Max's job: send as many overlapping notes as
- * you like - across any slots - and [poly~] hands each to a free voice, or steals the
- * oldest. A chord is several `playVoice()` calls in the same tick.
- *
- * The note is a control-plane message, not audio: it says which sample, at what rate,
- * how loud and how long to hold the voice, and Max makes the sound sample-accurately.
- * Pass the `channels` you learned from `loadSample` so a mono sample folds to both ears.
- */
-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)