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

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# 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.
+
+- `ndi-thumbnail`: a JPEG still of an NDI® source every few seconds or on each message, with frame statistics.
+  The message has the same shape as an http request node's reply.
+- `ndi-live`: a live Motion-JPEG preview at `<httpNodeRoot>/ndi-live/<node id>.mjpg` (and one still at `.jpg`).
+  It receives only while someone is watching, encodes each frame once for all viewers, and limits the number of
+  viewers.
+- All NDI work runs in a separate helper process, which is restarted if it crashes or hangs, so Node-RED keeps
+  running. Nodes that show the same source share one connection to it. Tally is never set.
+- Uses the NDI Runtime the user installs (NDI 5 or 6); contains no NDI code. Without the runtime the nodes say
+  "NDI Runtime not installed (see ndi.video)" and do nothing else.
+- macOS (universal) and Windows x64. No npm dependencies.

package/LICENSE.md

@@ -0,0 +1,80 @@
+Copyright (c) 2026 James Breedon
+
+Licensed under the PolyForm Noncommercial License 1.0.0.
+For commercial licensing, contact james@jamesbreedon.com.
+
+---
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# Node-RED NDI Preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node-RED nodes that show NDI® sources:
+
+- **`ndi-thumbnail`**: a JPEG still of a source every few seconds (or on each message), with frame statistics.
+- **`ndi-live`**: a silent, low-latency live preview of a source that any browser can show, for checking a picture.
+
+NDI® is a registered trademark of Vizrt NDI AB. This project is not affiliated with or endorsed by Vizrt NDI AB;
+"NDI" in its name says only what the nodes work with. More about NDI: <https://ndi.video/>.
+
+## Install
+
+In Node-RED: **Manage palette**, **Install**, search for `@jamezjb/node-red-ndi-preview`. Or, in your Node-RED user
+folder (usually `~/.node-red`):
+
+    npm install @jamezjb/node-red-ndi-preview
+
+Then restart Node-RED.
+
+## What you need
+
+- **The NDI Runtime, installed by you, on the computer that runs Node-RED.** This package contains no NDI code.
+  Download the free NDI 6 Runtime, or NDI Tools (which includes it), from <https://ndi.video/tools/>, install it,
+  then restart Node-RED. Without it, the nodes say "NDI Runtime not installed (see ndi.video)" and do nothing
+  else. NDI 5 and 6 runtimes work; NDI 6 is recommended.
+- **macOS** (11 or later, Apple silicon or Intel) or **Windows x64** (10 or 11). Other systems are not supported:
+  the nodes load, and say so.
+- Node-RED 3.1 or later, on Node.js 18 or later.
+
+The package has no npm dependencies.
+
+## The nodes
+
+### ndi-thumbnail
+
+Pick a source by name ("Find sources" lists what the Node-RED computer can see) or give its `ip:port`. Every *N*
+seconds, or whenever a message arrives, it sends:
+
+- `msg.payload`: the JPEG (a Buffer), `msg.statusCode` 200 and `msg.headers['content-type']` `image/jpeg`, the same
+  shape as an http request node's reply, so it can feed flows built for a camera's still-image URL;
+- `msg.ndi`: `{source, width, height, fps, fourCC, bandwidth, lastFrame, runtime, thumbWidth, thumbHeight, bytes,
+  grabMs, connections, framesTotal, framesDropped, connectedForMs}`.
+
+When no picture arrives it sends `payload: null` with `msg.ndi.error`, and warns once per outage. Send `"stop"` (or
+`false`) to pause and disconnect, and `"start"` (or `true`) to resume. `msg.source` / `msg.address` override the
+configured source for one message.
+
+### ndi-live
+
+Serves the source as Motion-JPEG on Node-RED's HTTP node server (the same place as *http in* nodes):
+
+- `<httpNodeRoot>/ndi-live/<node id>.mjpg`: the live picture; show it with `<img src="…">` in any browser or
+  dashboard template;
+- `<httpNodeRoot>/ndi-live/<node id>.jpg`: one still.
+
+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
+one stops, so an unwatched preview uses no network and no processor time. Each frame is encoded once for all
+viewers, and a viewer on a slow connection skips frames instead of falling behind. Send `"stop"` to end every
+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
+  stream, which can be over 100 Mb/s per camera.
+- **One connection per source.** Nodes that show the same source share one NDI connection to it.
+- **Tally is never set**, so a preview never lights a camera's on-air lamp.
+- **Safe for Node-RED.** All NDI work runs in a separate helper process. If the NDI Runtime crashes or hangs, the
+  helper is restarted (with a pause that grows each time), and Node-RED keeps running. After five crashes in a
+  minute it stops trying and the nodes say so, until Node-RED is restarted.
+- **Where the runtime is found.** On Windows, the folder the NDI 6 Runtime installer records in
+  `NDI_RUNTIME_DIR_V6`; on macOS, `/usr/local/lib/libndi.dylib`. To use a runtime somewhere else, set
+  `NDI_PREVIEW_RUNTIME` to the full path of the library before starting Node-RED.
+- **Windows firewall.** The helper asks the NDI Runtime to receive over TCP, which a firewall without an allow rule
+  for Node-RED does not block. Your own NDI settings (groups, discovery server, extra IPs) still apply. If you set
+  `NDI_CONFIG_DIR` yourself, your configuration is used unchanged.
+
+## Building from source
+
+The add-on is a small C file (`native/ndi_preview.c`) using Node-API. It loads the NDI Runtime the user installed
+at run time and links no NDI library. Building it needs the NDI SDK's header files: install the NDI SDK from
+<https://ndi.video/> (it is not part of this repository).
+
+- macOS: `npm run build` (needs the Xcode Command Line Tools; set `NDI_SDK_DIR` if the SDK is not in
+  `/Library/NDI SDK for Apple`).
+- Windows x64: `native/build-win.ps1` (needs the Visual Studio C++ build tools with the Windows SDK, and the NDI SDK
+  for Windows).
+
+Tests: `npm test` runs the unit tests with a synthetic stand-in for NDI, so it needs no NDI and no network.
+`npm run check` also checks the add-on and the package contents and, on macOS, runs an end-to-end test against a
+local test source. That test runs every NDI process in a macOS sandbox that only allows loopback traffic.
+
+## Licence
+
+Copyright (c) 2026 James Breedon. Licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE.md): free for
+noncommercial use.
+
+Third-party code and terms are listed in [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md), including the terms that
+apply to the NDI software this package works with.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,106 @@
+# Third-party notices
+
+## NDI®
+
+NDI® is a registered trademark of Vizrt NDI AB. More about NDI: <https://ndi.video/>.
+
+This package contains no NDI software. It works with the NDI Runtime that you download from <https://ndi.video/>
+and install yourself, and its add-on was built using the NDI SDK's header files. The NDI Runtime and the NDI SDK are
+licensed by Vizrt NDI AB under their own terms, which you accept when you install them. When you use this package
+with NDI software, these terms also apply to you:
+
+- You may not modify the NDI SDK, the NDI Runtime or any other NDI product, or any part of them.
+- You may not reverse engineer, disassemble or recompile the NDI SDK, the NDI Runtime or any other NDI product, or
+  any protocol they use (whether sent or received over a network, or used inside a computer), and you may not try to.
+- You may not circumvent any technical limitation in the NDI SDK, the NDI Runtime or any other NDI product.
+- You may not remove, obscure or alter any proprietary notice or label in the NDI SDK, the NDI Runtime or any other
+  NDI product.
+- Vizrt NDI AB and its licensors give no warranty of any kind for their software, and, as far as the law allows,
+  they are not liable for any damages (direct, indirect, incidental or consequential) arising from the use of this
+  package with their software.
+- You must comply with all relevant export laws and regulations of the United States, so that NDI software is not
+  exported, directly or indirectly, in breach of United States law.
+- The NDI SDK and NDI Runtime are copyright Vizrt NDI AB. All rights reserved.
+- If you use this package to develop products of your own that use NDI, those products must comply with the NDI SDK
+  License Agreement, including its requirement of current and complete NDI compatibility, and their end-user licence
+  must include these terms.
+
+The NDI SDK License Agreement: <https://ndi.link/ndisdk_license>.
+
+Formats such as H.264, H.265 and AAC (used by some NDI|HX sources) may need licences of their own. The NDI Runtime
+decodes them; making sure that use is licensed is your responsibility.
+
+## jpeg-js encoder
+
+`lib/vendor/jpeg-encoder.js` is the JPEG encoder from jpeg-js 0.4.4 (<https://github.com/jpeg-js/jpeg-js>),
+unchanged. Provenance: `lib/vendor/PROVENANCE.md`.
+
+jpeg-js licence (`lib/vendor/jpeg-js.LICENSE`):
+
+```
+Copyright (c) 2014, Eugene Ware
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of Eugene Ware nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY EUGENE WARE ''AS IS'' AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL EUGENE WARE BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+The encoder is itself a port of Adobe's ActionScript 3 JPEG encoder. Its licence, from the header of
+`lib/vendor/jpeg-encoder.js`:
+
+```
+Copyright (c) 2008, Adobe Systems Incorporated
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* Neither the name of Adobe Systems Incorporated nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+## Node.js
+
+The add-on is compiled against Node.js's Node-API header files (MIT licence, Copyright Node.js contributors). No
+Node.js code is included in this package.

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/lib/addon.js

@@ -0,0 +1,43 @@
+"use strict";
+// Where the prebuilt add-on for this computer lives, and loading it. The add-on is only ever loaded inside the NDI
+// host process (lib/host.js), never inside Node-RED itself.
+const path = require("path");
+const fs = require("fs");
+
+const PREBUILDS = path.join(__dirname, "..", "prebuilds");
+
+function platformDir(platform = process.platform, arch = process.arch) {
+  if (platform === "darwin" && (arch === "arm64" || arch === "x64")) return "darwin-universal";
+  if (platform === "win32" && arch === "x64") return "win32-x64";
+  return null;
+}
+
+// -> absolute path of the add-on for this computer, or null when there is none
+function addonPath() {
+  const dir = platformDir();
+  if (!dir) return null;
+  const p = path.join(PREBUILDS, dir, "ndi_preview.node");
+  return fs.existsSync(p) ? p : null;
+}
+
+// -> null when this computer can run the nodes, else a sentence saying why not
+function unsupportedReason() {
+  if (process.env.NDI_PREVIEW_TEST_ADDON) return null;
+  if (!platformDir()) {
+    return `NDI preview is not available on ${process.platform}-${process.arch}: it runs on macOS and on Windows x64`;
+  }
+  if (!addonPath()) return `the NDI preview add-on for ${platformDir()} is missing from this installation`;
+  return null;
+}
+
+// NDI_PREVIEW_TEST_ADDON is for this package's own tests: a JavaScript stand-in with the add-on's API that makes
+// synthetic frames and uses no network.
+function loadAddon() {
+  const fake = process.env.NDI_PREVIEW_TEST_ADDON;
+  if (fake) return require(path.resolve(fake));
+  const p = addonPath();
+  if (!p) throw new Error(unsupportedReason() || "the NDI preview add-on is missing");
+  return require(p);
+}
+
+module.exports = { addonPath, platformDir, unsupportedReason, loadAddon };

package/lib/admin.js

@@ -0,0 +1,72 @@
+"use strict";
+// What both node types share in Node-RED: the editor's admin endpoints and the status texts.
+const { getClient } = require("./host-client");
+
+const NOT_INSTALLED = { fill: "grey", shape: "ring", text: "NDI Runtime not installed (see ndi.video)" };
+const CHECKING = { fill: "grey", shape: "ring", text: "checking for the NDI Runtime" };
+
+function statusForRuntime(rt) {
+  if (rt.ok) return null;
+  if (rt.unsupported) return { fill: "grey", shape: "ring", text: "not available on this computer" };
+  if (rt.failed) return { fill: "red", shape: "ring", text: "NDI helper stopped; restart Node-RED" };
+  if (rt.host) return { fill: "red", shape: "ring", text: "NDI helper not answering; retrying" };
+  return NOT_INSTALLED;
+}
+
+let registered = false;
+let logged = false;
+
+// The runtime check a node does when it starts. The NDI host is started by the first node (or the editor), not
+// when Node-RED loads the palette, so a Node-RED with no NDI nodes deployed runs no extra process.
+// The result is logged once.
+function checkRuntime(RED) {
+  return getClient(RED).runtime().then((rt) => {
+    if (!logged && !rt.host) {
+      logged = true;
+      if (rt.ok) RED.log.info(`[ndi-preview] NDI Runtime ${rt.version} (${rt.path})`);
+      else RED.log.warn(`[ndi-preview] ${rt.error}.${rt.help ? " " + rt.help + "." : ""} The NDI preview nodes stay idle.`);
+    }
+    return rt;
+  });
+}
+
+// The runtime check for one node: calls onResult with each answer. A problem with the NDI host itself (it did not
+// answer, or crashed once) is not final: the check is repeated every 10 s until there is a real answer or the node
+// closes. A missing runtime or a host that has given up is final.
+function watchRuntime(RED, isClosed, onResult) {
+  const attempt = () => {
+    if (isClosed()) return;
+    checkRuntime(RED).then((rt) => {
+      if (isClosed()) return;
+      onResult(rt);
+      if (!rt.ok && rt.host && !rt.failed) { const t = setTimeout(attempt, 10000); t.unref?.(); }
+    });
+  };
+  attempt();
+}
+
+// Registered once, whichever node type loads first.
+function registerAdmin(RED) {
+  if (registered) return;
+  registered = true;
+
+  // Is the NDI Runtime installed on the Node-RED computer? (the editor's banner)
+  RED.httpAdmin.get("/ndi-preview/runtime", RED.auth.needsPermission("ndi-preview.read"), async (req, res) => {
+    const rt = await getClient(RED).runtime({ refresh: req.query.refresh === "1" });
+    res.json({ ok: rt.ok, version: rt.version, error: rt.error, help: rt.help, unsupported: !!rt.unsupported });
+  });
+
+  // One short NDI discovery from the Node-RED computer (the editor's "Find sources" button).
+  RED.httpAdmin.get("/ndi-preview/sources", RED.auth.needsPermission("ndi-preview.read"), async (req, res) => {
+    try {
+      const client = getClient(RED);
+      const rt = await client.runtime();
+      if (!rt.ok) { res.status(503).json({ error: rt.error, help: rt.help }); return; }
+      res.json(await client.sources(2000));
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  });
+}
+
+module.exports = { registerAdmin, checkRuntime, watchRuntime, statusForRuntime, NOT_INSTALLED, CHECKING };

package/lib/frame.js

@@ -0,0 +1,58 @@
+"use strict";
+// Pure-JS frame helpers: any NDI video frame -> RGBA at thumbnail size -> JPEG Buffer.
+// No native code here, so this file is unit-testable without the NDI runtime.
+const encodeJpeg = require("./vendor/jpeg-encoder");   // vendored jpeg-js 0.4.4 encoder (lib/vendor/PROVENANCE.md)
+
+const FOURCC = { UYVY: 1498831189, BGRA: 1095911234, BGRX: 1481787202, RGBA: 1094862674, RGBX: 1480738642 };
+const fourccName = (v) => Object.keys(FOURCC).find((k) => FOURCC[k] === v) || String(v);
+
+// Box-filter (area average) downscale of a packed 4-byte-per-pixel frame straight into RGBA.
+// Handles RGBX/RGBA and BGRX/BGRA (channel swap) and UYVY (4:2:2 -> RGB, BT.709 limited range).
+function toThumbRGBA(frame, outW) {
+  const { xres: W, yres: H, lineStrideBytes: stride, data, fourCC } = frame;
+  const w = Math.max(16, Math.min(outW | 0 || 320, W));
+  const h = Math.max(9, Math.round((H * w) / W));
+  const out = Buffer.alloc(w * h * 4);
+  const bgr = fourCC === FOURCC.BGRX || fourCC === FOURCC.BGRA;
+  const uyvy = fourCC === FOURCC.UYVY;
+  if (!uyvy && !bgr && fourCC !== FOURCC.RGBX && fourCC !== FOURCC.RGBA) {
+    throw new Error(`unsupported pixel format ${fourccName(fourCC)} (ask for colorFormat RGBX_RGBA)`);
+  }
+  const fx = W / w, fy = H / h;
+  // sample a capped grid inside each output cell (≤4×4) — cheap and still smooth for 1080p -> 320
+  const sx = Math.max(1, Math.min(4, Math.floor(fx))), sy = Math.max(1, Math.min(4, Math.floor(fy)));
+  for (let oy = 0; oy < h; oy++) {
+    for (let ox = 0; ox < w; ox++) {
+      let r = 0, g = 0, b = 0, n = 0;
+      for (let j = 0; j < sy; j++) {
+        const y = Math.min(H - 1, Math.floor(oy * fy + ((j + 0.5) * fy) / sy));
+        const row = y * stride;
+        for (let i = 0; i < sx; i++) {
+          const x = Math.min(W - 1, Math.floor(ox * fx + ((i + 0.5) * fx) / sx));
+          if (uyvy) {
+            const p = row + (x >> 1) * 4;                       // U Y0 V Y1
+            const Y = (x & 1 ? data[p + 3] : data[p + 1]) - 16, U = data[p] - 128, V = data[p + 2] - 128;
+            r += 1.164 * Y + 1.793 * V; g += 1.164 * Y - 0.213 * U - 0.533 * V; b += 1.164 * Y + 2.112 * U;
+          } else {
+            const p = row + x * 4;
+            if (bgr) { b += data[p]; g += data[p + 1]; r += data[p + 2]; }
+            else { r += data[p]; g += data[p + 1]; b += data[p + 2]; }
+          }
+          n++;
+        }
+      }
+      const o = (oy * w + ox) * 4;
+      out[o] = clamp(r / n); out[o + 1] = clamp(g / n); out[o + 2] = clamp(b / n); out[o + 3] = 255;
+    }
+  }
+  return { data: out, width: w, height: h };
+}
+const clamp = (v) => (v < 0 ? 0 : v > 255 ? 255 : v | 0);
+
+function frameToJpeg(frame, outW, quality) {
+  const rgba = toThumbRGBA(frame, outW);
+  const q = Math.max(10, Math.min(95, quality | 0 || 70));
+  return { jpeg: encodeJpeg(rgba, q).data, width: rgba.width, height: rgba.height };
+}
+
+module.exports = { toThumbRGBA, frameToJpeg, fourccName, FOURCC };