@jamezjb/node-red-ndi-preview 0.0.0-stage → 0.1.0

package/lib/host-client.js

@@ -0,0 +1,272 @@
+"use strict";
+// Node-RED's side of the NDI host (lib/host.js): starts it, talks to it, and restarts it if it dies or hangs.
+//
+// Safety rules for starting a process:
+//   - the program is named explicitly: this Node.js binary (process.execPath) running the absolute path of
+//     lib/host.js, with no extra Node flags; never "this program again";
+//   - the child carries the NDI_PREVIEW_HOST marker, and this module refuses to start a host from inside a host;
+//   - at most one host per Node-RED; restarts back off (1 s, 2 s, 4 s ... 30 s) and stop altogether after
+//     MAX_CRASHES crashes inside CRASH_WINDOW_MS, with a clear status, until Node-RED is restarted.
+const { fork } = require("child_process");
+const { EventEmitter } = require("events");
+const path = require("path");
+const { prepareNdiConfig } = require("./ndi-config");
+const { unsupportedReason } = require("./addon");
+
+const HOST_SCRIPT = path.join(__dirname, "host.js");
+const MAX_CRASHES = 5;
+const CRASH_WINDOW_MS = 60000;
+const PING_MS = 3000;
+const HEARTBEAT_MS = 10000;
+
+// Every host this process started, so that none outlives Node-RED: a host stuck in native code cannot see its IPC
+// channel close, so it is ended here when Node-RED exits.
+const running = new Set();
+process.once("exit", () => { for (const c of running) { try { c.kill("SIGKILL"); } catch (e) { /* gone */ } } });
+
+const toBuffer = (u8) => (Buffer.isBuffer(u8) ? u8 : Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength));
+
+class HostClient extends EventEmitter {
+  constructor({ configDir, log, maxCrashes = MAX_CRASHES, backoffBaseMs = 1000, marginMs = 10000, heartbeatMs = HEARTBEAT_MS } = {}) {
+    super();
+    if (process.env.NDI_PREVIEW_HOST === "1") throw new Error("refusing to start an NDI host from inside the NDI host");
+    this.configDir = configDir;
+    this.maxCrashes = maxCrashes;
+    this.backoffBaseMs = backoffBaseMs;
+    this.marginMs = marginMs;
+    this.heartbeatMs = heartbeatMs;
+    this.log = log || { info() {}, warn() {} };
+    this.child = null;
+    this.seq = 0;
+    this.pending = new Map();
+    this.live = new Map();           // stream id -> liveStart arguments, replayed after a restart
+    this.crashes = [];
+    this.nextStartAt = 0;
+    this.restartTimer = null;
+    this.failed = null;              // a sentence once the host has given up
+    this.runtimePromise = null;
+    this.stopping = false;
+    this.heartbeat = null;
+    this.setMaxListeners(0);
+  }
+
+  get pid() { return this.child ? this.child.pid : null; }
+
+  // -> the running child, starting it (after any backoff) when needed
+  async _ensure() {
+    if (this.stopping) throw Object.assign(new Error("the NDI host has been stopped"), { code: "EHOSTEXIT" });
+    if (this.failed) throw Object.assign(new Error(this.failed), { code: "EHOSTFAILED" });
+    if (this.child) return this.child;
+    const wait = this.nextStartAt - Date.now();
+    if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+    if (this.stopping) throw Object.assign(new Error("the NDI host has been stopped"), { code: "EHOSTEXIT" });
+    if (this.failed) throw Object.assign(new Error(this.failed), { code: "EHOSTFAILED" });
+    if (!this.child) this._spawn();
+    return this.child;
+  }
+
+  _spawn() {
+    const cfg = this.configDir ? prepareNdiConfig(this.configDir) : { env: {}, applied: false, reason: "no folder" };
+    const env = { ...process.env, ...cfg.env, NDI_PREVIEW_HOST: "1", ELECTRON_RUN_AS_NODE: "1" };
+    const child = fork(HOST_SCRIPT, [], {
+      execPath: process.execPath,
+      execArgv: [],
+      env,
+      serialization: "advanced",
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+      windowsHide: true,
+    });
+    this.child = child;
+    this.log.info(`NDI host started (pid ${child.pid})${cfg.applied ? ", TCP receive on" : ""}`);
+    let lines = 0;
+    const pipe = (stream) => stream.on("data", (d) => {
+      for (const line of String(d).split(/\r?\n/)) {
+        if (line.trim() && lines++ < 200) this.log.warn("NDI host: " + line.trim());
+      }
+    });
+    pipe(child.stdout); pipe(child.stderr);
+    child.on("message", (m) => this._onMessage(m));
+    running.add(child);
+    child.on("error", (e) => {
+      this.log.warn("NDI host error: " + e.message);
+      if (!child.pid || child.exitCode !== null) this._onExit(child, null, null, e.message);   // never started
+    });
+    child.on("exit", (code, signal) => this._onExit(child, code, signal));
+    for (const [id, args] of this.live) this._replay(id, args);
+    this._armHeartbeat();
+  }
+
+  // a live stream that was running before a restart: start it again, and tell its node if that fails
+  _replay(id, args) {
+    this._send({ op: "liveStart", stream: id, ...args }).catch((e) => {
+      if (this.live.get(id) === args) this.emit("liveStatus", id, "error", e.message);
+    });
+  }
+
+  // While live previews run, nothing else may ask the host anything, so a hang would go unnoticed: ping it.
+  _armHeartbeat() {
+    clearInterval(this.heartbeat);
+    this.heartbeat = setInterval(() => {
+      if (this.child && this.live.size) this._checkAlive(this.child);
+    }, this.heartbeatMs);
+    this.heartbeat.unref?.();
+  }
+
+  _onMessage(m) {
+    if (!m || typeof m !== "object") return;
+    if (m.event === "frame") { this.emit("frame", m.stream, toBuffer(m.jpeg), m.meta); return; }
+    if (m.event === "liveStatus") { this.emit("liveStatus", m.stream, m.state, m.error); return; }
+    const p = this.pending.get(m.id);
+    if (!p) return;
+    this.pending.delete(m.id);
+    clearTimeout(p.timer);
+    if (m.ok) {
+      const r = m.result;
+      if (r && r.jpeg) r.jpeg = toBuffer(r.jpeg);
+      p.resolve(r);
+    } else {
+      p.reject(Object.assign(new Error(m.error), { code: m.code }));
+    }
+  }
+
+  _onExit(child, code, signal, error) {
+    running.delete(child);
+    if (this.child !== child) return;
+    this.child = null;
+    clearInterval(this.heartbeat);
+    const why = error ? error : signal ? `signal ${signal}` : `code ${code}`;
+    for (const [, p] of this.pending) { clearTimeout(p.timer); p.reject(Object.assign(new Error(`the NDI host stopped (${why})`), { code: "EHOSTEXIT" })); }
+    this.pending.clear();
+    if (this.stopping) return;
+    const now = Date.now();
+    this.crashes = this.crashes.filter((t) => now - t < CRASH_WINDOW_MS).concat(now);
+    if (this.crashes.length >= this.maxCrashes) {
+      this.failed = `the NDI host stopped ${this.crashes.length} times in a minute, so it is not restarted; restart Node-RED to try again`;
+      this.log.warn(this.failed);
+      this.emit("state", "failed", this.failed);
+      return;
+    }
+    const backoff = Math.min(30000, this.backoffBaseMs * 2 ** (this.crashes.length - 1));
+    this.nextStartAt = now + backoff;
+    this.log.warn(`the NDI host stopped (${why}); restarting in ${Math.round(backoff / 100) / 10} s`);
+    this.emit("state", "restarting", `the NDI host stopped (${why})`);
+    this.runtimePromise = null;
+    if (this.live.size) {
+      clearTimeout(this.restartTimer);
+      this.restartTimer = setTimeout(() => { this._ensure().catch(() => {}); }, backoff);
+      this.restartTimer.unref?.();
+    }
+  }
+
+  _send(msg, timeoutMs = 10000, watch = true) {
+    return new Promise((resolve, reject) => {
+      const child = this.child;
+      if (!child || !child.connected) { reject(Object.assign(new Error("the NDI host is not running"), { code: "EHOSTEXIT" })); return; }
+      const id = ++this.seq;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(Object.assign(new Error("the NDI host did not answer in time"), { code: "ETIMEOUT" }));
+        if (watch) this._checkAlive(child);
+      }, timeoutMs);
+      timer.unref?.();
+      this.pending.set(id, { resolve, reject, timer });
+      try { child.send({ ...msg, id }); } catch (e) {
+        clearTimeout(timer); this.pending.delete(id);
+        reject(Object.assign(new Error("the NDI host is not running"), { code: "EHOSTEXIT" }));
+      }
+    });
+  }
+
+  // a request timed out: if the host does not answer a ping either, it is hung, so end it (it then restarts)
+  _checkAlive(child) {
+    if (child !== this.child || child.checking) return;
+    child.checking = true;
+    this._send({ op: "ping" }, PING_MS, false).then(
+      () => { child.checking = false; },
+      () => {
+        if (child === this.child) {
+          this.log.warn("the NDI host is not responding; ending it");
+          child.kill("SIGKILL");
+        }
+      });
+  }
+
+  async request(op, args = {}, timeoutMs = 10000) {
+    await this._ensure();
+    return this._send({ op, ...args }, timeoutMs);
+  }
+
+  // -> { ok:true, version, path } | { ok:false, error, help?, url? }. Never rejects.
+  runtime({ refresh = false } = {}) {
+    const why = unsupportedReason();
+    if (why) return Promise.resolve({ ok: false, error: why, unsupported: true });
+    if (refresh || !this.runtimePromise) {
+      const p = this.request("hello", {}, 15000).catch((e) => ({ ok: false, error: e.message, host: true, failed: e.code === "EHOSTFAILED" }));
+      this.runtimePromise = p;
+      p.then((rt) => { if (!rt.ok && rt.host && this.runtimePromise === p) this.runtimePromise = null; });
+    }
+    return this.runtimePromise;
+  }
+
+  grab(args) {
+    const timeoutMs = Math.max(200, Number(args.timeoutMs) || 3000);
+    return this.request("grab", args, timeoutMs + this.marginMs);
+  }
+
+  sources(waitMs = 2000) { return this.request("sources", { waitMs }, waitMs + this.marginMs); }
+
+  drop(owner) { return this.child ? this._send({ op: "drop", owner }).catch(() => {}) : Promise.resolve(); }
+
+  async liveStart(stream, args) {
+    this.live.set(stream, args);
+    await this._ensure();
+    // stopped while the host was (re)starting: never start a stream nobody owns any more
+    if (this.live.get(stream) !== args) return { stream, cancelled: true };
+    // (if the host was just started, it already got this stream from the replay; the host treats the repeat as a no-op)
+    return this._send({ op: "liveStart", stream, ...args });
+  }
+
+  liveStop(stream) {
+    this.live.delete(stream);
+    return this.child ? this._send({ op: "liveStop", stream }).catch(() => {}) : Promise.resolve();
+  }
+
+  status() { return this.request("status"); }
+
+  // end the host (Node-RED is stopping, or a test is done)
+  stop() {
+    this.stopping = true;
+    clearTimeout(this.restartTimer);
+    clearInterval(this.heartbeat);
+    this.live.clear();
+    const child = this.child;
+    if (!child) return Promise.resolve();
+    return new Promise((resolve) => {
+      const t = setTimeout(() => { child.kill("SIGKILL"); }, 3000);
+      child.once("exit", () => { clearTimeout(t); resolve(); });
+      try { child.disconnect(); } catch (e) { child.kill("SIGKILL"); }
+    });
+  }
+}
+
+// One host per Node-RED: both node types share it.
+let shared = null;
+function getClient(RED) {
+  if (!shared) {
+    const userDir = (RED && RED.settings && RED.settings.userDir) || require("os").tmpdir();
+    shared = new HostClient({
+      configDir: path.join(userDir, "ndi-preview"),
+      log: { info: (s) => RED.log.info("[ndi-preview] " + s), warn: (s) => RED.log.warn("[ndi-preview] " + s) },
+    });
+  }
+  return shared;
+}
+
+// end the shared host (tests, or a Node-RED that is shutting down its runtime)
+async function stopShared() {
+  const c = shared;
+  shared = null;
+  if (c) await c.stop();
+}
+
+module.exports = { HostClient, getClient, stopShared, HOST_SCRIPT, MAX_CRASHES };

package/lib/host.js

@@ -0,0 +1,219 @@
+"use strict";
+// The NDI host: a child process that does all the NDI work for one Node-RED, so that a crash or a hang in the NDI
+// Runtime can never take Node-RED down. It loads the add-on and the user's NDI Runtime, keeps the shared receivers,
+// grabs frames and encodes the JPEGs. Node-RED talks to it over the IPC channel (lib/host-client.js).
+//
+// This process never starts another process. It exits when Node-RED goes away (the IPC channel closes).
+
+if (process.env.NDI_PREVIEW_HOST !== "1" || typeof process.send !== "function") {
+  // Only lib/host-client.js may start this file, with the marker and an IPC channel. Anything else (a test runner,
+  // a user typing `node host.js`) gets a refusal, never a running host.
+  process.stderr.write("lib/host.js is started by Node-RED NDI Preview itself and cannot be run on its own.\n");
+  process.exit(2);
+}
+
+const { loadAddon } = require("./addon");
+const { ReceiverPool } = require("./receivers");
+const { frameToJpeg, fourccName } = require("./frame");
+
+const RUNTIME_HELP = "Install the NDI 6 Runtime (or NDI Tools) from https://ndi.video/tools/ on the Node-RED computer, then restart Node-RED";
+
+let addon = null;
+let runtime = null;
+let pool = null;
+
+function loadRuntime() {
+  if (runtime && runtime.ok) return runtime;
+  try {
+    if (!addon) addon = loadAddon();
+    const r = addon.load(process.env.NDI_PREVIEW_RUNTIME || undefined);
+    runtime = r.ok ? r : { ...r, help: RUNTIME_HELP };
+  } catch (e) {
+    runtime = { ok: false, error: "could not load the NDI preview add-on: " + ((e && e.message) || e), help: RUNTIME_HELP };
+  }
+  if (runtime.ok && !pool) pool = new ReceiverPool(addon);
+  return runtime;
+}
+
+// process.send that never throws: the channel can close at any moment (Node-RED stopping)
+function send(msg, cb) {
+  try {
+    if (process.connected) { process.send(msg, cb ? () => cb() : undefined); return; }
+  } catch (e) { /* channel closed */ }
+  if (cb) cb();
+}
+
+class HostError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+
+function needRuntime() {
+  const rt = loadRuntime();
+  if (!rt.ok) throw new HostError("ENORUNTIME", rt.error);
+  return rt;
+}
+
+const clampInt = (v, lo, hi, dflt) => {
+  const n = Math.round(Number(v));
+  return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) : dflt;
+};
+
+function sourceOf(m) {
+  const name = typeof m.source?.name === "string" ? m.source.name.trim() : "";
+  const address = typeof m.source?.address === "string" ? m.source.address.trim() : "";
+  if (!name && !address) throw new HostError("ENOSOURCE", "no NDI source set");
+  return { name, address };
+}
+
+function frameMeta(f) {
+  return {
+    width: f.xres, height: f.yres,
+    fps: f.frameRateD ? Math.round((f.frameRateN / f.frameRateD) * 100) / 100 : null,
+    fourCC: fourccName(f.fourCC),
+    lastFrame: f.timestamp > 0 ? new Date(Math.round(f.timestamp / 10000)).toISOString() : new Date().toISOString(),
+  };
+}
+
+// ---- operations -------------------------------------------------------------------------------------------------
+
+async function opGrab(m) {
+  const rt = needRuntime();
+  const source = sourceOf(m);
+  const bandwidth = m.bandwidth === "highest" ? "highest" : "lowest";
+  const width = clampInt(m.width, 32, 1920, 320);
+  const quality = clampInt(m.quality, 10, 95, 70);
+  const timeoutMs = clampInt(m.timeoutMs, 200, 60000, 3000);
+  const idleMs = clampInt(m.idleMs, 0, 3600000, 30000);
+  const owner = String(m.owner || "anonymous");
+  const r = pool.get(source, bandwidth, m.label);
+  const token = Symbol("grab");
+  pool.hold(r, token);                                  // not swept while we wait for the first frame
+  const t0 = Date.now();
+  try {
+    const f = await r.waitFrame(timeoutMs);
+    const j = frameToJpeg(f, width, quality);
+    return {
+      jpeg: j.jpeg,
+      meta: {
+        ...frameMeta(f), bandwidth, runtime: rt.version,
+        thumbWidth: j.width, thumbHeight: j.height, bytes: j.jpeg.length, grabMs: Date.now() - t0, ...r.stats(),
+      },
+    };
+  } finally {
+    pool.keep(r, owner, idleMs);
+    pool.release(r, token);
+  }
+}
+
+async function opSources(m) {
+  needRuntime();
+  const waitMs = clampInt(m.waitMs, 200, 10000, 2000);
+  const f = addon.findOpen();
+  try {
+    await new Promise((res) => setTimeout(res, waitMs));
+    return addon.findSources(f).map((s) => ({ name: s.name, address: s.address || "" }));
+  } finally {
+    addon.findClose(f);
+  }
+}
+
+// ---- live previews ----------------------------------------------------------------------------------------------
+
+const streams = new Map();   // stream id -> { r, timer, ... }
+let inflight = 0;            // frame messages not yet handed to the IPC channel
+
+function stopStream(id) {
+  const s = streams.get(id);
+  if (!s) return false;
+  clearInterval(s.timer);
+  streams.delete(id);
+  pool.release(s.r, s.holder, false);
+  return true;
+}
+
+function opLiveStart(m) {
+  const rt = needRuntime();
+  const id = String(m.stream || "");
+  if (!id) throw new HostError("EBADARG", "no stream id");
+  const source = sourceOf(m);
+  const bandwidth = m.bandwidth === "highest" ? "highest" : "lowest";
+  const fps = clampInt(m.fps, 1, 15, 10);
+  const width = clampInt(m.width, 32, 1280, 640);
+  const quality = clampInt(m.quality, 10, 95, 60);
+  const noVideoMs = clampInt(m.timeoutMs, 1000, 60000, 5000);
+  const params = JSON.stringify([source, bandwidth, fps, width, quality, noVideoMs, m.label || ""]);
+  const running = streams.get(id);
+  if (running && running.params === params) return { stream: id, fps, width, quality, bandwidth };   // already running
+  stopStream(id);
+  const r = pool.get(source, bandwidth, m.label);
+  const s = { r, holder: Symbol(id), params, lastTs: null, lastNewAt: Date.now(), state: "starting", frames: 0 };
+  pool.hold(r, s.holder);
+  const status = (state, error) => {
+    if (s.state === state) return;
+    s.state = state;
+    send({ event: "liveStatus", stream: id, state, error: error || null });
+  };
+  s.timer = setInterval(() => {
+    let f;
+    try { f = r.poll(); } catch (e) { status("error", (e && e.message) || String(e)); return; }
+    const now = Date.now();
+    if (!f || f.timestamp === s.lastTs) {
+      if (now - s.lastNewAt > noVideoMs) {
+        const { connections } = r.stats();
+        status("novideo", connections ? "connected, but no video is arriving" : "source not found, or it did not answer");
+      }
+      return;
+    }
+    s.lastTs = f.timestamp;
+    s.lastNewAt = now;
+    if (inflight >= 2) return;                       // Node-RED is behind: skip this frame, never queue
+    let j;
+    try { j = frameToJpeg(f, width, quality); } catch (e) { status("error", (e && e.message) || String(e)); return; }
+    s.frames++;
+    status("live");
+    inflight++;
+    send({ event: "frame", stream: id, jpeg: j.jpeg, meta: { ...frameMeta(f), thumbWidth: j.width, thumbHeight: j.height, bytes: j.jpeg.length, bandwidth, runtime: rt.version } },
+      () => { inflight--; });
+  }, Math.round(1000 / fps));
+  streams.set(id, s);
+  return { stream: id, fps, width, quality, bandwidth };
+}
+
+function opLiveStop(m) { return { stopped: stopStream(String(m.stream || "")) }; }
+
+function opDrop(m) { if (pool) pool.drop(String(m.owner || "")); return {}; }
+
+function opStatus() {
+  return { runtime, receivers: pool ? pool.openCount() : 0, streams: streams.size, pid: process.pid };
+}
+
+const OPS = {
+  hello: () => loadRuntime(),
+  ping: () => ({ pong: Date.now() }),
+  grab: opGrab,
+  sources: opSources,
+  liveStart: opLiveStart,
+  liveStop: opLiveStop,
+  drop: opDrop,
+  status: opStatus,
+};
+
+process.on("message", async (m) => {
+  if (!m || typeof m !== "object" || m.id === undefined) return;
+  const fn = OPS[m.op];
+  try {
+    if (!fn) throw new HostError("EBADOP", `unknown operation ${m.op}`);
+    const result = await fn(m);
+    send({ id: m.id, ok: true, result });
+  } catch (e) {
+    send({ id: m.id, ok: false, code: e.code || "EFAIL", error: (e && e.message) || String(e) });
+  }
+});
+
+function shutdown() {
+  for (const id of [...streams.keys()]) stopStream(id);
+  if (pool) pool.closeAll();
+  process.exit(0);
+}
+process.on("disconnect", shutdown);         // Node-RED went away: never linger
+process.on("SIGTERM", shutdown);

package/lib/ndi-config.js

@@ -0,0 +1,47 @@
+"use strict";
+// A private copy of the user's NDI configuration with TCP receive switched on, for the NDI host process only.
+//
+// Why: by default the NDI Runtime receives video over reliable UDP. On Windows, the firewall drops that for a
+// program it has no allow rule for, and Node-RED usually has none, so a receiver connects but gets no video. TCP
+// receive avoids that. Everything else in the user's configuration (groups, discovery server, extra IPs) is kept.
+//
+// The copy is used only by the NDI host process (through its environment), never by Node-RED itself. If
+// NDI_CONFIG_DIR is already set, the user (or a test) has chosen a configuration, and it is left alone.
+const os = require("os");
+const path = require("path");
+const fs = require("fs");
+
+function userConfigCandidates(env = process.env) {
+  const c = [];
+  if (process.platform === "win32") c.push(path.join(env.ProgramData || "C:\\ProgramData", "NDI", "ndi-config.v1.json"));
+  c.push(path.join(os.homedir(), ".ndi", "ndi-config.v1.json"));
+  return c;
+}
+
+function withTcpReceive(cfg) {
+  const out = cfg && typeof cfg === "object" && !Array.isArray(cfg) ? { ...cfg } : {};
+  const ndi = out.ndi && typeof out.ndi === "object" ? { ...out.ndi } : {};
+  ndi.tcp = { ...(ndi.tcp || {}), recv: { ...((ndi.tcp || {}).recv || {}), enable: true } };
+  ndi.rudp = { ...(ndi.rudp || {}), recv: { ...((ndi.rudp || {}).recv || {}), enable: false } };
+  ndi.multicast = { ...(ndi.multicast || {}), recv: { ...((ndi.multicast || {}).recv || {}), enable: false } };
+  out.ndi = ndi;
+  return out;
+}
+
+// -> { env: { NDI_CONFIG_DIR } | {}, applied, dir?, reason? }. Never throws.
+function prepareNdiConfig(dir, env = process.env) {
+  if (env.NDI_CONFIG_DIR) return { env: {}, applied: false, reason: "NDI_CONFIG_DIR is already set" };
+  try {
+    let cfg = {};
+    for (const c of userConfigCandidates(env)) {
+      try { cfg = JSON.parse(fs.readFileSync(c, "utf8").replace(/^\uFEFF/, "")); break; } catch (e) { /* try the next */ }
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "ndi-config.v1.json"), JSON.stringify(withTcpReceive(cfg), null, 2));
+    return { env: { NDI_CONFIG_DIR: dir }, applied: true, dir };
+  } catch (e) {
+    return { env: {}, applied: false, reason: String((e && e.message) || e) };
+  }
+}
+
+module.exports = { prepareNdiConfig, withTcpReceive };

package/lib/receivers.js

@@ -0,0 +1,131 @@
+"use strict";
+// Shared NDI receivers, one per source and bandwidth, inside the NDI host process.
+//
+// Every node that shows the same source (stills and live previews alike) uses the same receiver, so each camera
+// sees one connection from this computer, however many nodes and viewers there are.
+//
+// A receiver stays open while something needs it:
+//   - a live preview HOLDS it for as long as it runs;
+//   - a still grab KEEPS it for that node's idle time after the grab (0 = close straight after).
+// When nothing holds or keeps it, it is closed (the sweep runs every second).
+
+const keyOf = (source, bandwidth) =>
+  JSON.stringify([source.name || "", source.address || "", bandwidth === "highest" ? "highest" : "lowest"]);
+
+class Receiver {
+  constructor(addon, key, source, bandwidth, label) {
+    this.addon = addon;
+    this.key = key;
+    this.opts = { name: source.name || undefined, address: source.address || undefined, bandwidth, label };
+    this.h = null;
+    this.openedAt = 0;
+    this.holders = new Set();           // live streams
+    this.keeps = new Map();             // owner -> keep open until (ms since epoch)
+    this.lastFrame = null;              // the newest frame seen, shared by everyone using this receiver
+    this.lastNewAt = 0;                 // when a frame with a new timestamp last arrived
+  }
+
+  get open() { return !!this.h; }
+
+  ensureOpen() {
+    if (!this.h) { this.h = this.addon.open(this.opts); this.openedAt = Date.now(); this.lastFrame = null; this.lastNewAt = 0; }
+    return this.h;
+  }
+
+  // The newest frame, or null when none has arrived yet. Never waits. NDI's FrameSync repeats the last frame until
+  // a new one arrives (also after the source has gone), so an unchanged frame is not copied again, and lastNewAt
+  // says when the picture last really changed.
+  poll() {
+    const since = this.lastFrame ? this.lastFrame.timestamp : undefined;
+    const f = this.addon.grab(this.ensureOpen(), since);
+    if (f === false) return this.lastFrame;                 // nothing new since the frame we already have
+    if (f) { this.lastFrame = f; this.lastNewAt = Date.now(); }
+    return f;
+  }
+
+  stats() {
+    if (!this.h) return { connections: 0, framesTotal: 0, framesDropped: 0, connectedForMs: 0 };
+    return { ...this.addon.stats(this.h), connectedForMs: Date.now() - this.openedAt };
+  }
+
+  // A current frame: one that arrived within the last timeoutMs, waiting up to timeoutMs for it, so a source that
+  // has stopped is reported instead of its last picture being shown again. Rejects with a readable reason.
+  async waitFrame(timeoutMs) {
+    const t0 = Date.now();
+    for (;;) {
+      const f = this.poll();
+      // fresh, and still connected: a frame seen for the first time can still be the last one a dead source sent
+      if (f && Date.now() - this.lastNewAt <= timeoutMs && this.stats().connections > 0) return f;
+      if (Date.now() - t0 >= timeoutMs) {
+        const { connections } = this.stats();
+        if (f) throw new Error(connections ? `no new video for ${Math.round((Date.now() - this.lastNewAt) / 1000)} s` : "the source has gone");
+        throw new Error(connections ? `connected, but no video arrived within ${timeoutMs} ms` : "source not found, or it did not answer");
+      }
+      await new Promise((r) => setTimeout(r, 25));
+    }
+  }
+
+  needed(now) {
+    if (this.holders.size) return true;
+    for (const until of this.keeps.values()) if (until > now) return true;
+    return false;
+  }
+
+  close() {
+    if (this.h) { try { this.addon.close(this.h); } catch (e) { /* already closed */ } }
+    this.h = null;
+    this.lastFrame = null;
+  }
+}
+
+class ReceiverPool {
+  constructor(addon, { sweepMs = 1000 } = {}) {
+    this.addon = addon;
+    this.receivers = new Map();
+    this.timer = setInterval(() => this.sweep(), sweepMs);
+    this.timer.unref?.();
+  }
+
+  get(source, bandwidth, label) {
+    const bw = bandwidth === "highest" ? "highest" : "lowest";
+    const key = keyOf(source, bw);
+    let r = this.receivers.get(key);
+    if (!r) { r = new Receiver(this.addon, key, source, bw, label || "Node-RED NDI Preview"); this.receivers.set(key, r); }
+    return r;
+  }
+
+  keep(r, owner, idleMs) {
+    const until = Date.now() + Math.max(0, idleMs);
+    r.keeps.set(owner, Math.max(r.keeps.get(owner) || 0, until));
+  }
+
+  hold(r, holder) { r.holders.add(holder); }
+
+  // now = true closes an unneeded receiver at once; otherwise the next sweep (within a second) does, so a stream that
+  // is restarted straight away keeps the same connection to the camera
+  release(r, holder, now = true) { r.holders.delete(holder); if (now) this.sweep(); }
+
+  // forget everything an owner kept open (a node was paused, changed or removed)
+  drop(owner) {
+    for (const r of this.receivers.values()) r.keeps.delete(owner);
+    this.sweep();
+  }
+
+  sweep() {
+    const now = Date.now();
+    for (const [key, r] of this.receivers) {
+      for (const [owner, until] of r.keeps) if (until <= now) r.keeps.delete(owner);
+      if (!r.needed(now)) { r.close(); this.receivers.delete(key); }
+    }
+  }
+
+  openCount() { let n = 0; for (const r of this.receivers.values()) if (r.open) n++; return n; }
+
+  closeAll() {
+    clearInterval(this.timer);
+    for (const r of this.receivers.values()) r.close();
+    this.receivers.clear();
+  }
+}
+
+module.exports = { ReceiverPool, keyOf };

package/lib/vendor/PROVENANCE.md

@@ -0,0 +1,12 @@
+# Vendored code
+
+| file | from | version | licence | changes |
+|---|---|---|---|---|
+| `jpeg-encoder.js` | jpeg-js `lib/encoder.js` (<https://github.com/jpeg-js/jpeg-js>), itself Andreas Ritter's JavaScript port of Adobe's ActionScript 3 JPEG encoder | 0.4.4 (npm `jpeg-js@0.4.4`, integrity `sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg==`) | BSD-3-Clause (Eugene Ware, `jpeg-js.LICENSE`) and BSD (Adobe Systems, in the file's header) | none: byte-identical to the published file, sha256 `00bde8df2517eca556669ab6fc27b414e9ba3fc52a0a71e1e37ec7c5f19c3d34` |
+| `jpeg-js.LICENSE` | jpeg-js `LICENSE` | 0.4.4 | | none: byte-identical, sha256 `c0a8512eabe960492fefd4f287523eb3b5ca1518ca37ef0ec83344cd7f089cb8` |
+
+The encoder is vendored rather than depended on, so the package has no npm runtime dependencies. It has no
+dependencies of its own and is only ever called with RGBA buffers this package builds itself.
+
+To check it: `npm pack jpeg-js@0.4.4`, unpack, and compare the sha256 of `package/lib/encoder.js` and
+`package/LICENSE` with the values above.