grandi 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,21 @@
+Grandi
+
+Copyright (c) 2025 Grandi contributors
+
+This product includes software developed by Streampunk Media Ltd. and is
+derived in part from the project "Grandiose":
+  https://github.com/Streampunk/grandiose
+licensed under the Apache License, Version 2.0.
+
+Portions Copyright (c) 2018 Streampunk Media Ltd.
+
+This project also retains and extends features originating from community forks,
+including (but not limited to):
+  - https://github.com/rse/grandiose
+  - https://github.com/danjenkins/grandiose
+  - https://github.com/ianshade/grandiose
+These upstream materials are used under the terms of the Apache License, Version 2.0.
+
+NDI is a trademark of NewTek, Inc. NewTek NDI SDK headers/libraries are subject
+to their respective licenses as provided by NewTek (see the repository's
+license exceptions and the contents of the ndi/lib/ folder).

package/README.md

@@ -0,0 +1,402 @@
+# Grandi
+Grandi is a TypeScript-first native Node.js binding for NewTek NDI™  6. It exposes the full NDI 6 SDK surface area through a Promise-based API, providing strongly typed helpers for sending and receiving professional video, audio, metadata, and tally data from Node.js applications. For more information on NDI™ , see <https://www.ndi.tv/>.
+
+## Why this fork?
+Grandi is a maintained fork of [Streampunk Grandiose](https://github.com/Streampunk/grandiose). The original `steampunk/grandiose` repository and the corresponding `grandiose` package on npm have not been updated since 2023, and major functionality such as data sending never landed upstream. This fork modernizes the build, rewrites the bindings in TypeScript, and delivers the outstanding features required for production projects while keeping a familiar API. Meaningful contributions were also carried forward from community forks:
+
+- TypeScript-focused rewrite with complete binding coverage.
+- Improved NDI SDK handling (versioning, download/packaging, and portability improvements).
+- Added utilities to make common workflows easier.
+- Audio frame sending support from the [rse/grandiose](https://github.com/rse/grandiose) fork.
+- Ad-hoc download of NDI SDK assets.
+- Portability fixes for Windows, macOS, and Linux drawn from multiple forks.
+- Sender, routing, and type-definition improvements from [ianshade/grandiose](https://github.com/ianshade/grandiose) and [hopejr/grandiose](https://github.com/hopejr/grandiose).
+
+## Why “Grandi”?
+
+NDI™ was conceived as a grand vision for IP media transport. The earliest bindings leaned into that idea with the tongue‑in‑cheek name “gra‑NDI‑ose”. **Grandi** preserves the homage: it nods to “[grandiose](https://github.com/Streampunk/grandiose)”, itself drawn from the French word *grandi* (“grown”).
+
+## Capabilities
+- Native NDI™  6 bindings written in modern TypeScript with out-of-the-box type definitions.
+- Send and receive video, audio, metadata, and tally (program/preview) data streams.
+- Promise-based API that keeps heavy lifting off the Node.js event loop.
+- Helpers for working with choice of color formats, bandwidth limits, and audio layouts.
+- Finder utilities for discovering sources on the local network or specified subnets.
+- Built-in routing helpers for switching NDI sources without dropping frames.
+
+### Missing & future work
+- PTZ camera control APIs introduced in newer NDI SDK releases are not exposed yet.
+- NDI receiver discovery (added in SDK v6.2) still needs bindings; today only sender discovery is available.
+- Pull requests tackling these gaps (or other NDI 6.x+ features) are very welcome.
+
+## Supported platforms
+Grandi currently ships prebuilt binaries for the same platforms supported by the original project. Additional platforms can be compiled from source if the NDI SDK supports them.
+
+| Operating system | Architectures | Status | Notes |
+| --- | --- | --- | --- |
+| Windows | x86, x64 | ✅ Prebuilt | Visual Studio 2013 C runtime only needed when building locally; prebuilt binaries include the required DLLs. |
+| macOS | Universal (x64 + arm64) | ✅ Prebuilt | Ships with the official universal NDI™ driver, so Intel and Apple Silicon hosts run natively. |
+| Linux | x86, x64, armv7l, arm64 | ✅ Prebuilt | Built against the glibc-based NDI™ SDK; requires `libavahi-common.so.3`, `libavahi-client.so.3`, and the `avahi-daemon` service. |
+
+## Installation
+Install [Node.js](http://nodejs.org/) for your platform (tested against the current Long Term Support release). Then add the dependency to your project:
+
+```bash
+npm install grandi
+# or
+pnpm add grandi
+# or
+yarn add grandi
+```
+
+On Windows, you only need the Visual Studio 2013 C run-times when building from source (e.g., running `npm install` without matching prebuilds). You can grab them from <https://www.microsoft.com/en-us/download/details.aspx?id=40784>, but end users consuming the published prebuilt binaries do **not** need to install them.
+
+Grandi is designed to be `require`d or `import`ed from your own applications:
+
+```typescript
+import grandi from "grandi";
+// or
+const grandi = require("grandi");
+```
+
+## Build & distribution
+The project uses [prebuildify](https://github.com/prebuild/prebuildify) to prebuild the Node.js addon and bundle the NDI SDK libraries for the supported targets shown above. Those prebuilds are resolved at runtime via [node-gyp-build](https://github.com/prebuild/node-gyp-build), so consumers do not need a compiler toolchain in most cases. When no prebuild matches the running platform, `node-gyp-build` falls back to compiling locally, letting advanced users add additional architectures.
+
+## Using Grandi
+This module allows a Node.js program to find, receive, and send NDI™ video, audio, metadata, and tally streams over IP networks. All calls are asynchronous and use JavaScript promises with all of the underlying work of NDI running on separate threads from the event loop. The following sections recap the most common workflows; for complete runnable demos, see `examples/simple-receiver.mjs` and `examples/simple-sender.mjs`.
+
+### Finding streams
+`grandi.find` resolves to a finder handle that can block for network updates and expose the discovered sources:
+
+```javascript
+import { setTimeout as sleep } from "node:timers/promises";
+import grandi from "grandi";
+
+async function pickSource() {
+  const finder = await grandi.find({ showLocalSources: true });
+  try {
+    for (let attempts = 0; attempts < 20; attempts++) {
+      finder.wait(250); // block for up to 250 ms of new announcements
+      const sources = finder.sources();
+      if (sources.length > 0) return sources[0];
+      await sleep(250);
+    }
+    throw new Error("No NDI sources found on the network.");
+  } finally {
+    finder.destroy();
+  }
+}
+```
+
+`find` accepts a single options object. Common filters:
+
+```javascript
+await grandi.find({
+  showLocalSources: true,                 // include sources on the same machine
+  groups: "studio3",                      // comma-separated list of group names
+  extraIPs: "192.168.1.122,mixer.local",  // comma-separated IPs/hosts outside mDNS
+});
+```
+
+### Receiving streams
+First, find a stream or construct a `Source` object:
+
+```javascript
+const grandi = require("grandi");
+const source = { name: "<source_name>", urlAddress: "<ip>:<port>" };
+```
+
+Create a receiver:
+
+```javascript
+const receiver = await grandi.receive({ source });
+```
+
+Example receiver object:
+
+```javascript
+{
+  embedded: [External],
+  video: [Function],
+  audio: [Function],
+  metadata: [Function],
+  data: [Function],
+  source: { name: "LEMARR (Test Pattern)", urlAddress: "169.254.82.1:5961" },
+  colorFormat: 100, // grandi.COLOR_FORMAT_FASTEST
+  bandwidth: 100,   // grandi.BANDWIDTH_HIGHEST
+  allowVideoFields: true
+}
+```
+
+Configure receivers via options:
+
+```javascript
+const receiver = await grandi.receive({
+  source,
+  colorFormat: grandi.COLOR_FORMAT_UYVY_RGBA,
+  bandwidth: grandi.BANDWIDTH_AUDIO_ONLY,
+  allowVideoFields: true,
+  name: "rooftop"
+});
+
+```
+
+#### Video
+
+```javascript
+const timeout = 5000;
+try {
+  for (let i = 0; i < 10; i++) {
+    const frame = await receiver.video(timeout);
+    console.log(frame);
+  }
+} catch (err) {
+  console.error(err);
+}
+```
+
+Example frame:
+
+```javascript
+{
+  type: "video",
+  xres: 1920,
+  yres: 1080,
+  frameRateN: 30000,
+  frameRateD: 1001,
+  pictureAspectRatio: 1.7777777910232544,
+  timestamp: [1538569443, 717845600],
+  frameFormatType: grandi.FORMAT_TYPE_INTERLACED,
+  timecode: [0, 0],
+  lineStrideBytes: 3840,
+  data: <Buffer 80 10 80 10 ... >
+}
+```
+
+#### Audio
+
+```javascript
+const audioFrame = await receiver.audio(
+  {
+    audioFormat: grandi.AUDIO_FORMAT_INT_16_INTERLEAVED,
+    referenceLevel: 0
+  },
+  8000
+);
+```
+
+Example result:
+
+```javascript
+{
+  type: "audio",
+  audioFormat: grandi.AUDIO_FORMAT_INT_16_INTERLEAVED,
+  referenceLevel: 0,
+  sampleRate: 48000,
+  channels: 4,
+  samples: 4800,
+  channelStrideInBytes: 9600,
+  timestamp: [1538578787, 132614500],
+  timecode: [0, 800000000],
+  data: <Buffer 00 00 00 00 ... >
+}
+```
+
+#### Metadata
+
+```javascript
+const metadataFrame = await receiver.metadata();
+```
+
+Returns a `{ type: "metadata", data: string, ... }` frame, typically XML.
+
+#### Next available data
+
+```javascript
+const prefs = { audioFormat: grandi.AUDIO_FORMAT_FLOAT_32_SEPARATE };
+const payload = await receiver.data(prefs, 1000); // 1s timeout
+if (payload.type === "video") {
+  // handle video frame
+} else if (payload.type === "metadata") {
+  console.log(payload.data);
+}
+```
+
+### Sending streams
+Sending is fully supported. Call `grandi.send` with a `SendOptions` object to create a `Sender` instance capable of video, audio, metadata, and tally interactions:
+
+```javascript
+const sender = await grandi.send({
+  name: "grandi-demo",
+  groups: "studio3",
+  clockVideo: true,
+  clockAudio: true
+});
+
+const timecode = process.hrtime.bigint() / 100n;
+const timestampNs = process.hrtime.bigint();
+const timestamp = [
+  Number(timestampNs / 1_000_000_000n),
+  Number(timestampNs % 1_000_000_000n),
+];
+
+// Prepare frame payloads (see examples/simple-sender.mjs for helpers)
+
+await sender.video({
+  xres: 1280,
+  yres: 720,
+  frameRateN: 30,
+  frameRateD: 1,
+  pictureAspectRatio: 16 / 9,
+  frameFormatType: grandi.FORMAT_TYPE_PROGRESSIVE,
+  lineStrideBytes: 1280 * 4,
+  data: whiteBuffer, // BGRA pixels
+  fourCC: grandi.FOURCC_BGRA,
+  timecode,
+  timestamp,
+});
+
+await sender.audio({
+  sampleRate: 48_000,
+  noChannels: 2,
+  noSamples: 1600,
+  channelStrideBytes: 1600 * 4,
+  data: silentAudioBuffer,
+  fourCC: grandi.FOURCC_FLTp,
+  timecode,
+  timestamp,
+});
+
+# Example metadata, that explicitly enable hardware acceleration in receiver
+sender.metadata("<ndi_video_codec type=\"hardware\"/>");
+
+const tally = sender.tally();
+console.log(tally.on_program, tally.on_preview);
+```
+
+Destroy senders and receivers explicitly when finished to release NDI resources.
+
+### Other helpers
+- `grandi.version()` returns the NDI SDK version string (e.g. `NDI SDK LINUX 10:24:11 Aug 21 2025 6.2.1.0`).
+- `grandi.isSupportedCPU()` checks whether the host CPU can run the NDI SDK.
+- `grandi.initialize()` / `grandi.destroy()` control the lifetime of the underlying library in advanced scenarios.
+
+## Contributing
+Ready to hack on Grandi? Here’s the typical workflow.
+
+1. **Install prerequisites**
+	- Node.js ≥ 20.19.5 and a working C/C++ toolchain for your platform.
+	- Git LFS is *not* required; the NDI SDK is fetched dynamically.
+2. **Download the NDI SDK + install deps**
+	- Run `npm install` (or `pnpm install`/`yarn install`). The `scripts/preinstall.mjs` hook downloads and unpacks the official NDI SDK into `ndi/`, then `node-gyp-build` compiles the native addon for your host platform. Re-run `npm install` after deleting `ndi/` if you need to refresh the SDK.
+	- To force-download all prebuild assets for release testing, run `npm run prebuild:download`.
+	- Set `NDI_FORCE=1` if you need to run the downloader in an unpacked tarball (normally it only runs inside the git repo).
+3. **TypeScript build**
+	- `npm run build` compiles `src/` via `tsdown`, emitting ESM/CJS bundles and declaration files in `dist/`.
+	- `npm run prebuild` packages native binaries for distribution (requires the SDK assets fetched earlier).
+4. **Native addon rebuild**
+	- If you change C/C++ files under `lib/`, recompile with `npx node-gyp-build` (or simply re-run `npm install`). This uses the same loader that consumers invoke at runtime.
+5. **Testing**
+	- `npm test` runs the full Vitest suite (unit + integration stubs).
+	- `npm run test:unit` focuses on pure JS/TS tests.
+	- `RUN_NDI_TESTS=1 npm run test:integration` exercises the native bindings against a real NDI environment; ensure you have available senders/receivers before running.
+  - `npm run test:coverage` provides coverage data via `@vitest/coverage-v8`.
+6. **Linting & formatting**
+	- `npm run lint` / `npm run format` cover the TypeScript/JavaScript sources via Biome.
+	- `npm run format:cpp` formats the native sources with `clang-format`.
+7. **Manual verification**
+	- `node examples/simple-sender.mjs` and `node examples/simple-receiver.mjs` are quick smoke tests for the send/receive API.
+	- Use `NDI_FORCE=1 npm install` if you need to reassemble the NDI SDK artifacts even when they are already present.
+
+Before opening a pull request, make sure the linter, formatter, and tests all pass, and include context for any platform-specific considerations (e.g., SDK versions, OS dependencies).
+
+## API reference
+This section documents every exported method and type surfaced by the module. Refer to `src/index.ts` and `src/types.ts` for authoritative definitions.
+
+### Module exports
+- `find(options?: FindOptions): Promise<Finder>` — discover available NDI sources, optionally filtering by groups, local visibility, or explicit IPs. Resolves to a finder handle whose `sources()` method returns the latest snapshot.
+- `receive(options: ReceiveOptions): Promise<Receiver>` — create a receiver bound to a specific `Source`. Customize color format, bandwidth caps, interlaced support, and a friendly name.
+- `send(options: SendOptions): Promise<Sender>` — create a sender that can push video, audio, metadata, and tally updates into the NDI network.
+- `routing(params: { name?: string; groups?: string }): Promise<Routing>` — build an NDI router that can switch downstream destinations to new sources via `routing.change`.
+- `initialize(): boolean` / `destroy(): boolean` — manually initialize or tear down the shared NDI state. Automatically handled when using `send`/`receive`, but exposed for completeness.
+- `version(): string` — report the bundled NDI SDK version.
+- `isSupportedCPU(): boolean` — guard call that reports whether the host CPU meets the NDI SDK requirements.
+- Enum exports: `ColorFormat`, `AudioFormat`, `Bandwidth`, `FrameType`, `FourCC`.
+- Default export: the `grandi` object containing the methods above plus constant aliases such as `COLOR_FORMAT_FASTEST`, `BANDWIDTH_HIGHEST`, etc.
+
+### Receiver interface
+`Receiver` instances expose:
+
+- `video(timeoutMs?: number): Promise<ReceivedVideoFrame>` — obtain the next video frame.
+- `audio(optionsOrTimeout?: AudioReceiveOptions | number, timeoutMs?: number): Promise<ReceivedAudioFrame>` — fetch audio, optionally overriding format or reference level per call.
+- `metadata(timeoutMs?: number): Promise<ReceivedMetadataFrame>` — resolve metadata frames (strings, typically XML).
+- `data(optionsOrTimeout?: AudioReceiveOptions | number, timeoutMs?: number): Promise<ReceiverDataFrame>` — return whichever payload (video, audio, metadata, source change, status change) arrives first.
+- `tally(state: ReceiverTallyState): boolean` — push tally states (program/preview) upstream to the sender.
+- `destroy(): boolean` — release the underlying NDI receiver.
+- Properties: `embedded`, `source`, `colorFormat`, `bandwidth`, `allowVideoFields`, `name`.
+
+### Sender interface
+`Sender` instances surface:
+
+- `video(frame: VideoFrame): Promise<void>` — send a video frame.
+- `audio(frame: AudioFrame): Promise<void>` — send an audio frame.
+- `metadata(data: string): boolean` — send metadata strings (XML).
+- `tally(): SenderTally` — retrieve current tally state (program/preview booleans plus `changed` flag).
+- `connections(): number` — how many actively connected receivers see this sender.
+- `sourcename(): string` — fully qualified source name visible on the network.
+- `destroy(): boolean` — dispose the sender and release network resources.
+- Properties: `embedded`, `name`, `groups`, `clockVideo`, `clockAudio`.
+
+### Routing interface
+- `change(source: Source): boolean` — switch destinations to a new source.
+- `clear(): boolean` — disconnect the current source.
+- `connections(): number` — monitor downstream subscriptions.
+- `sourcename(): string` — current routed source name.
+- `destroy(): boolean` — cleanly shut down.
+
+### Finder interface
+- `sources(): Source[]` — latest snapshot of discovered sources.
+- `wait(timeoutMs?: number): boolean` — block for network updates up to the given timeout.
+- `destroy(): boolean` — dispose the finder and associated background threads.
+
+### Options and helper types
+- `Source` — `{ name: string; urlAddress?: string }`.
+- `FindOptions` — `{ showLocalSources?: boolean; groups?: string; extraIPs?: string; }`.
+- `ReceiveOptions` — `{ source: Source; colorFormat?: ColorFormat; bandwidth?: Bandwidth; allowVideoFields?: boolean; name?: string; }`.
+- `SendOptions` — `{ name: string; groups?: string; clockVideo?: boolean; clockAudio?: boolean; }`.
+- `AudioReceiveOptions` — `{ audioFormat?: AudioFormat; referenceLevel?: number; }` used when calling `receiver.audio` or `receiver.data`.
+- `ReceiverTallyState` — `{ onProgram?: boolean; onPreview?: boolean; }`, used by `receiver.tally`.
+- `SenderTally` — `{ changed: boolean; on_program: boolean; on_preview: boolean; }`, returned by `sender.tally`.
+- `PtpTimestamp` — `[seconds, nanoseconds]` tuple aligning with the NDI SDK timestamp APIs.
+- `Timecode` — `bigint | number | PtpTimestamp`, matching how timecodes are expressed throughout the SDK.
+
+### Frame payload types
+- `VideoFrame` — describes outbound frames: resolution, frame rate (`frameRateN`, `frameRateD`), aspect ratio, `fourCC`, `frameFormatType`, `lineStrideBytes`, `data`, optional `timecode`, `timestamp`, `metadata`.
+- `ReceivedVideoFrame` — extends `VideoFrame` with guaranteed `type: "video"` plus non-optional `timecode`/`timestamp`.
+- `AudioFrame` — outbound audio payload (sample rate, number of channels/samples, stride, `data`, `fourCC`, optional timing/metadata).
+- `ReceivedAudioFrame` — inbound audio payload including `audioFormat`, `referenceLevel`, `timecode`, `timestamp`.
+- `ReceivedMetadataFrame` — metadata payloads (`type: "metadata"`, `length`, `timecode`, `timestamp`, `data` string).
+- `ReceiverDataFrame` — discriminated union of `ReceivedVideoFrame | ReceivedAudioFrame | ReceivedMetadataFrame | SourceChangeEvent | StatusChangeEvent`.
+- `SourceChangeEvent` / `StatusChangeEvent` — internal notifications delivered via `receiver.data` when the remote sender changes or becomes unavailable.
+
+### Enum reference
+- `ColorFormat` — enumerates `BGRX_BGRA`, `UYVY_BGRA`, `RGBX_RGBA`, `UYVY_RGBA`, `Fastest`, `Best`, and `BGRX_BGRA_FLIPPED`. The `grandi.COLOR_FORMAT_*` constants map to these values.
+- `AudioFormat` — `Float32Separate`, `Float32Interleaved`, `Int16Interleaved`. Access via `grandi.AUDIO_FORMAT_*`.
+- `Bandwidth` — `MetadataOnly`, `AudioOnly`, `Lowest`, `Highest`. Access via `grandi.BANDWIDTH_*`.
+- `FrameType` — `Interlaced`, `Progressive`, `Field0`, `Field1`. Access via `grandi.FORMAT_TYPE_*`.
+- `FourCC` — common pixel/audio format codes (`UYVY`, `UYVA`, `P216`, `PA16`, `YV12`, `I420`, `NV12`, `BGRA`, `BGRX`, `RGBA`, `RGBX`, `FLTp`). Helper constants exist on the default export.
+
+## Status, support, and further development
+Support for sending and receiving streams across Windows, macOS, and Linux platforms is actively maintained. Contributions are welcome via pull requests, and enhancements or bug reports can be filed as GitHub issues.
+
+## License
+Apart from the exceptions below, this software is released under the Apache 2.0 license. See [LICENSE](./LICENSE) for details. Attribution: this project remains a maintained fork of Streampunk Grandiose, and portions derive from that project and community forks. See [NOTICE](./NOTICE) for attributions.
+
+### License exceptions
+The software uses libraries provided under a royalty-free license from NewTek, Inc. (see the [NDI SDK License](https://ndi.link/ndisdk_license) for full terms):
+
+- The `ndi/include` includes files are licensed separately by NewTek under the MIT license.
+- The DLL and library files are provided for installation convenience and are covered by the NewTek license in the `prebuild/` folder.
+
+## Trademarks
+NDI™  is a trademark of NewTek, Inc.