@jamezjb/node-red-ndi-preview 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.1 (13 November 2026)
+
+- Example flows for both nodes, under **Import**, **Examples** in Node-RED.
+- `ndi-live` sends its message again whenever what it knows about the NDI Runtime changes, so a flow is not left
+  showing an old answer: for example when the NDI helper answers late after Node-RED starts, or stops.
+  `msg.ndi.error` is now also set when the NDI helper has stopped.
+
 ## 0.1.0 (13 November 2026)
 
 First version.

package/README.md

@@ -53,8 +53,10 @@ Serves the source as Motion-JPEG on Node-RED's HTTP node server (the same place
   dashboard template;
 - `<httpNodeRoot>/ndi-live/<node id>.jpg`: one still.
 
-It sends the path once when the flow starts and in reply to every message. Defaults: 10 frames a second (at most
-15), 640 pixels wide, at most 4 viewers. It is a preview, not a programme monitor: no sound, a fraction of a second
+It sends the path when the flow starts, again whenever what it knows about the NDI Runtime changes, and in reply to
+every message. `msg.ndi.runtime` is the runtime's version, or `null` when there is none yet; `msg.ndi.error` says why
+the preview cannot work (no NDI Runtime, or the NDI helper has stopped). `null` with no error means it is still being
+checked. Defaults: 10 frames a second (at most 15), 640 pixels wide, at most 4 viewers. It is a preview, not a programme monitor: no sound, a fraction of a second
 behind live.
 
 The connection to the source opens when the first viewer starts watching and closes a few seconds after the last
@@ -65,6 +67,14 @@ viewer and refuse new ones, `"start"` to allow them again.
 **Who can watch:** the endpoints sit behind Node-RED's `httpNodeAuth` if your settings set it. Without it, anyone
 who can reach Node-RED's HTTP endpoints can watch.
 
+### Examples
+
+In Node-RED: **Import**, **Examples**, `@jamezjb/node-red-ndi-preview`. Each example shows one node on a small web page
+made with core nodes only: *thumbnail-still-on-a-web-page* serves the newest still at
+`<httpNodeRoot>/ndi-example/still.jpg`, and *live-preview-on-a-web-page* shows the live preview at
+`<httpNodeRoot>/ndi-example/live`. Pick your source in the NDI node after importing; the source name in the examples
+is made up.
+
 ### Both nodes
 
 - **Network use.** *Proxy* (the default) asks the sender for its low-bandwidth stream. *Full* asks for the full

package/examples/live-preview-on-a-web-page.json

@@ -0,0 +1,49 @@
+[
+  {
+    "id": "b2c0de0000000001", "type": "comment", "name": "NDI live preview on a web page: read me",
+    "info": "Shows a live, silent preview of an NDI source on a small web page at\n`<httpNodeRoot>/ndi-example/live` (with default settings: http://<node-red>:1880/ndi-example/live).\n\n1. Open the **ndi live** node, press **Find sources** and pick your source (the example name is made up).\n2. Deploy, then open the page. The node connects to the source only while someone is watching.\n3. **stop** ends every viewer and refuses new ones; **start** allows them again.\n\nThe node sends the path of its stream when the flow starts; the page uses that path in an `<img>` tag.\nThe same `<img>` works in any dashboard template.\nAnyone who can reach Node-RED's HTTP endpoints can watch, unless your settings set `httpNodeAuth`.\n\nNeeds the NDI Runtime on the Node-RED computer (https://ndi.video/tools/).",
+    "x": 220, "y": 60, "wires": []
+  },
+  {
+    "id": "b2c0de0000000002", "type": "inject", "name": "stop", "props": [{ "p": "payload" }],
+    "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "topic": "", "payload": "stop", "payloadType": "str",
+    "x": 130, "y": 140, "wires": [["b2c0de0000000004"]]
+  },
+  {
+    "id": "b2c0de0000000003", "type": "inject", "name": "start", "props": [{ "p": "payload" }],
+    "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "topic": "", "payload": "start", "payloadType": "str",
+    "x": 130, "y": 180, "wires": [["b2c0de0000000004"]]
+  },
+  {
+    "id": "b2c0de0000000004", "type": "ndi-live", "name": "", "source": "EXAMPLE-PC (Camera 1)", "address": "",
+    "fps": 10, "width": 640, "quality": 60, "bandwidth": "lowest", "maxViewers": 4, "timeout": 5,
+    "x": 320, "y": 160, "wires": [["b2c0de0000000005", "b2c0de0000000006"]]
+  },
+  {
+    "id": "b2c0de0000000005", "type": "change", "name": "remember the stream path",
+    "rules": [{ "t": "set", "p": "ndiExampleLive", "pt": "flow", "to": "payload", "tot": "msg" }],
+    "action": "", "property": "", "from": "", "to": "", "reg": false,
+    "x": 560, "y": 140, "wires": [[]]
+  },
+  {
+    "id": "b2c0de0000000006", "type": "debug", "name": "preview details", "active": true, "tosidebar": true,
+    "console": false, "tostatus": false, "complete": "ndi", "targetType": "msg", "statusVal": "", "statusType": "auto",
+    "x": 540, "y": 180, "wires": []
+  },
+  {
+    "id": "b2c0de0000000007", "type": "http in", "name": "", "url": "/ndi-example/live", "method": "get",
+    "upload": false, "swaggerDoc": "",
+    "x": 160, "y": 260, "wires": [["b2c0de0000000008"]]
+  },
+  {
+    "id": "b2c0de0000000008", "type": "template", "name": "preview page", "field": "payload", "fieldType": "msg",
+    "format": "html", "syntax": "mustache", "output": "str",
+    "template": "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>NDI preview</title>\n<style>\n  body { margin: 0; background: #111; color: #ddd; font: 14px system-ui, sans-serif; }\n  img { display: block; width: 100%; max-width: 960px; margin: 0 auto; background: #000; }\n  p { text-align: center; }\n</style>\n</head>\n<body>\n{{#flow.ndiExampleLive}}<img src=\"{{{flow.ndiExampleLive}}}\" alt=\"Live NDI preview\">{{/flow.ndiExampleLive}}\n{{^flow.ndiExampleLive}}<p>The preview is not ready yet: deploy the flow, then reload this page.</p>{{/flow.ndiExampleLive}}\n</body>\n</html>\n",
+    "x": 370, "y": 260, "wires": [["b2c0de0000000009"]]
+  },
+  {
+    "id": "b2c0de0000000009", "type": "http response", "name": "",
+    "statusCode": "", "headers": { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" },
+    "x": 570, "y": 260, "wires": []
+  }
+]

package/examples/thumbnail-still-on-a-web-page.json

@@ -0,0 +1,48 @@
+[
+  {
+    "id": "a1c0de0000000001", "type": "comment", "name": "NDI still on a web page: read me",
+    "info": "Takes a JPEG still of an NDI source every 5 seconds and serves the newest one at\n`<httpNodeRoot>/ndi-example/still.jpg` (with default settings: http://<node-red>:1880/ndi-example/still.jpg).\n\n1. Open the **ndi thumbnail** node, press **Find sources** and pick your source (the example name is made up).\n2. Deploy. The debug sidebar shows each still's statistics (`msg.ndi`).\n3. Use **stop** and **start** to pause and resume (stop also disconnects from the source).\n\nWhile no picture arrives, the endpoint answers 503 instead of showing an old picture.\nAnyone who can reach Node-RED's HTTP endpoints can open the still, unless your settings set `httpNodeAuth`.\n\nNeeds the NDI Runtime on the Node-RED computer (https://ndi.video/tools/).",
+    "x": 210, "y": 60, "wires": []
+  },
+  {
+    "id": "a1c0de0000000002", "type": "inject", "name": "stop", "props": [{ "p": "payload" }],
+    "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "topic": "", "payload": "stop", "payloadType": "str",
+    "x": 130, "y": 140, "wires": [["a1c0de0000000004"]]
+  },
+  {
+    "id": "a1c0de0000000003", "type": "inject", "name": "start", "props": [{ "p": "payload" }],
+    "repeat": "", "crontab": "", "once": false, "onceDelay": 0.1, "topic": "", "payload": "start", "payloadType": "str",
+    "x": 130, "y": 180, "wires": [["a1c0de0000000004"]]
+  },
+  {
+    "id": "a1c0de0000000004", "type": "ndi-thumbnail", "name": "", "source": "EXAMPLE-PC (Camera 1)", "address": "",
+    "interval": 5, "width": 320, "quality": 70, "bandwidth": "lowest", "idle": 30, "timeout": 3,
+    "x": 330, "y": 160, "wires": [["a1c0de0000000005", "a1c0de0000000006"]]
+  },
+  {
+    "id": "a1c0de0000000005", "type": "change", "name": "keep the newest still",
+    "rules": [{ "t": "set", "p": "ndiExampleStill", "pt": "flow", "to": "payload", "tot": "msg" }],
+    "action": "", "property": "", "from": "", "to": "", "reg": false,
+    "x": 560, "y": 140, "wires": [[]]
+  },
+  {
+    "id": "a1c0de0000000006", "type": "debug", "name": "still statistics", "active": true, "tosidebar": true,
+    "console": false, "tostatus": false, "complete": "ndi", "targetType": "msg", "statusVal": "", "statusType": "auto",
+    "x": 550, "y": 180, "wires": []
+  },
+  {
+    "id": "a1c0de0000000007", "type": "http in", "name": "", "url": "/ndi-example/still.jpg", "method": "get",
+    "upload": false, "swaggerDoc": "",
+    "x": 170, "y": 260, "wires": [["a1c0de0000000008"]]
+  },
+  {
+    "id": "a1c0de0000000008", "type": "function", "name": "newest still, or 503",
+    "func": "const still = flow.get(\"ndiExampleStill\");\nif (!Buffer.isBuffer(still)) {\n    msg.statusCode = 503;\n    msg.headers = { \"Content-Type\": \"text/plain\", \"Retry-After\": \"5\", \"Cache-Control\": \"no-store\" };\n    msg.payload = \"No picture from the NDI source yet.\";\n    return msg;\n}\nmsg.statusCode = 200;\nmsg.headers = { \"Content-Type\": \"image/jpeg\", \"Cache-Control\": \"no-store\" };\nmsg.payload = still;\nreturn msg;",
+    "outputs": 1, "timeout": 0, "noerr": 0, "initialize": "", "finalize": "", "libs": [],
+    "x": 400, "y": 260, "wires": [["a1c0de0000000009"]]
+  },
+  {
+    "id": "a1c0de0000000009", "type": "http response", "name": "", "statusCode": "", "headers": {},
+    "x": 590, "y": 260, "wires": []
+  }
+]

package/nodes/ndi-live.html

@@ -85,11 +85,14 @@
       <code>true</code> allows them again. Any message is answered with the output below.</dd>
   </dl>
   <h3>Outputs</h3>
-  <p>Once when the flow starts, and for each input:</p>
+  <p>When the flow starts, whenever what the node knows about the NDI Runtime changes, and for each input:</p>
   <dl class="message-properties">
     <dt>payload <span class="property-type">string</span></dt><dd>the path of the live picture.</dd>
     <dt>ndi <span class="property-type">object</span></dt>
-    <dd><code>{source, stream, still, viewers, live, paused, maxViewers, fps, width, bandwidth, runtime}</code>.</dd>
+    <dd><code>{source, stream, still, viewers, live, paused, maxViewers, fps, width, bandwidth, runtime}</code>, and
+      <code>error</code> when the preview cannot work (no NDI Runtime, or the NDI helper has stopped).
+      <code>runtime</code> is the runtime's version, or <code>null</code> when there is none yet; <code>null</code>
+      with no <code>error</code> means it is still being checked.</dd>
   </dl>
   <h3>Details</h3>
   <p><i>Proxy</i> asks the sender for its low-bandwidth stream; <i>Full</i> can put over 100 Mb/s per camera on the

package/nodes/ndi-live.js

@@ -16,6 +16,7 @@ const BOUNDARY = "ndipreviewframe";
 const STOP_GRACE_MS = 5000;
 const FRESH_MS = 2000;
 const STUCK_MS = 10000;          // a viewer that has not taken a frame for this long is disconnected
+const HOST_STOPPED = "the NDI helper has stopped; restart Node-RED";
 const liveNodes = new Map();
 let routed = false;
 
@@ -81,16 +82,29 @@ module.exports = function (RED) {
     }
 
     function info() {
+      const error = hostFailed ? HOST_STOPPED : rt && !rt.ok ? rt.error : null;
       return {
         payload: streamUrl,
         ndi: {
           source: source.name || source.address, stream: streamUrl, still: stillUrl, viewers: viewers.size,
           live: streaming, paused, maxViewers, fps, width, bandwidth, runtime: rt ? rt.version || null : null,
-          ...(rt && !rt.ok ? { error: rt.error } : {}),
+          ...(error ? { error } : {}),
         },
       };
     }
 
+    // The node sends info() when the flow starts, and again whenever what it says about the NDI Runtime changes
+    // (for example the helper answered late, or stopped), so a flow showing it never keeps a stale answer.
+    let announced = null;
+    function announce() {
+      if (closed) return;
+      const { runtime, error } = info().ndi;
+      const key = JSON.stringify([runtime, error || null]);
+      if (key === announced) return;
+      announced = key;
+      node.send(info());
+    }
+
     function startStream() {
       clearTimeout(stopTimer); stopTimer = null;
       if (streaming || paused || closed) return;
@@ -99,7 +113,7 @@ module.exports = function (RED) {
       showStatus();
       client.liveStart(node.id, { source, bandwidth, fps, width, quality, label, timeoutMs }).catch((e) => {
         if (closed) return;
-        if (e.code === "ENORUNTIME") rt = { ok: false, error: e.message };
+        if (e.code === "ENORUNTIME") { rt = { ok: false, error: e.message }; announce(); }
         node.warn(`NDI live "${source.name || source.address}": ${e.message}`);
         stopStream();
         endViewers();
@@ -146,7 +160,7 @@ module.exports = function (RED) {
     }
     function onHostState(s, why) {
       if (closed) return;
-      if (s === "failed") { hostFailed = true; node.error(why); stopStream(); endViewers(); }
+      if (s === "failed") { hostFailed = true; node.error(why); stopStream(); endViewers(); announce(); }
     }
     client.on("frame", onFrame);
     client.on("liveStatus", onLiveStatus);
@@ -223,12 +237,11 @@ module.exports = function (RED) {
 
     liveNodes.set(node.id, node);
     node.status(CHECKING);
-    let announced = false;
     watchRuntime(RED, () => closed, (r) => {
       if (r.ok || !r.host || r.failed) rt = r;               // a host hiccup is not final: it is checked again
       if (r.failed) hostFailed = true;
       if (!r.ok && r.host && !r.failed) node.status(statusForRuntime(r)); else showStatus();
-      if (!announced) { announced = true; node.send(info()); }   // tells the flow where the preview is
+      announce();                                            // tells the flow where the preview is
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamezjb/node-red-ndi-preview",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Node-RED nodes that show NDI® sources: JPEG stills with frame statistics, and a live preview. Needs the NDI Runtime installed separately (ndi.video); contains no NDI code.",
   "keywords": [
     "node-red",
@@ -34,6 +34,7 @@
   "files": [
     "nodes/",
     "lib/",
+    "examples/",
     "prebuilds/darwin-universal/ndi_preview.node",
     "prebuilds/win32-x64/ndi_preview.node",
     "README.md",