grandi 0.1.0 → 1.1.0

package/README.md

@@ -1,4 +1,7 @@
+[![npm version](https://badgen.net/npm/v/grandi)](https://www.npmjs.com/package/grandi) [![CI](https://github.com/tux-tn/grandi/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tux-tn/grandi/actions/workflows/ci.yml)
+
 # 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?
@@ -30,16 +33,16 @@ NDI™ was conceived as a grand vision for IP media transport. The earliest bind
 - 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.
+Grandi publishes per-architecture packages (`@grandi/<os>-<arch>`) that bundle the native addon and the matching NDI SDK runtime. 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. |
+| Windows | x86, x64 | ✅ Published as `@grandi/win32-ia32` and `@grandi/win32-x64`. Visual Studio 2013 C runtime only needed when building locally. |
+| macOS | Universal (x64 + arm64) | ✅ Published as `@grandi/darwin-universal`, built against the official universal NDI™ runtime. |
+| Linux | x86, x64, armv7l, arm64 | ✅ Published as `@grandi/linux-x64`, `@grandi/linux-arm64`, `@grandi/linux-armv7l`. 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:
+Install [Node.js](http://nodejs.org/) for your platform (tested against the current Long Term Support release). The main package automatically pulls the platform-specific optional dependency `@grandi/<os>-<arch>` when it exists, and falls back to building from source otherwise. Add the dependency to your project:
 
 ```bash
 npm install grandi
@@ -49,18 +52,18 @@ pnpm add grandi
 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.
+On Windows, you only need the Visual Studio 2013 C run-times when building from source (e.g., running `npm install` on an unsupported platform). You can grab them from <https://www.microsoft.com/en-us/download/details.aspx?id=40784>; consumers using the published `@grandi/win32-*` packages do **not** need to install them manually.
 
 Grandi is designed to be `require`d or `import`ed from your own applications:
 
-```typescript
+```ts
 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.
+Each platform package under the `@grandi/` scope bundles the native addon (`grandi.node`) and the corresponding NDI SDK runtime for that OS/arch. The root `grandi` package loads the matching optional dependency first and only compiles locally when no published package is available. Maintainers regenerate those packages from the official NDI SDK by running `node scripts/preinstall.mjs` (to download and stage the SDK) followed by a version bump (e.g., `node scripts/bump-version.mjs <version>`).
 
 ## 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`.
@@ -68,7 +71,7 @@ This module allows a Node.js program to find, receive, and send NDI™ video, au
 ### Finding streams
 `grandi.find` resolves to a finder handle that can block for network updates and expose the discovered sources:
 
-```javascript
+```ts
 import { setTimeout as sleep } from "node:timers/promises";
 import grandi from "grandi";
 
@@ -90,7 +93,7 @@ async function pickSource() {
 
 `find` accepts a single options object. Common filters:
 
-```javascript
+```ts
 await grandi.find({
   showLocalSources: true,                 // include sources on the same machine
   groups: "studio3",                      // comma-separated list of group names
@@ -101,20 +104,20 @@ await grandi.find({
 ### Receiving streams
 First, find a stream or construct a `Source` object:
 
-```javascript
+```ts
 const grandi = require("grandi");
 const source = { name: "<source_name>", urlAddress: "<ip>:<port>" };
 ```
 
 Create a receiver:
 
-```javascript
+```ts
 const receiver = await grandi.receive({ source });
 ```
 
 Example receiver object:
 
-```javascript
+```ts
 {
   embedded: [External],
   video: [Function],
@@ -130,7 +133,7 @@ Example receiver object:
 
 Configure receivers via options:
 
-```javascript
+```ts
 const receiver = await grandi.receive({
   source,
   colorFormat: grandi.COLOR_FORMAT_UYVY_RGBA,
@@ -143,7 +146,7 @@ const receiver = await grandi.receive({
 
 #### Video
 
-```javascript
+```ts
 const timeout = 5000;
 try {
   for (let i = 0; i < 10; i++) {
@@ -157,7 +160,7 @@ try {
 
 Example frame:
 
-```javascript
+```ts
 {
   type: "video",
   xres: 1920,
@@ -175,7 +178,7 @@ Example frame:
 
 #### Audio
 
-```javascript
+```ts
 const audioFrame = await receiver.audio(
   {
     audioFormat: grandi.AUDIO_FORMAT_INT_16_INTERLEAVED,
@@ -187,7 +190,7 @@ const audioFrame = await receiver.audio(
 
 Example result:
 
-```javascript
+```ts
 {
   type: "audio",
   audioFormat: grandi.AUDIO_FORMAT_INT_16_INTERLEAVED,
@@ -204,7 +207,7 @@ Example result:
 
 #### Metadata
 
-```javascript
+```ts
 const metadataFrame = await receiver.metadata();
 ```
 
@@ -212,7 +215,7 @@ Returns a `{ type: "metadata", data: string, ... }` frame, typically XML.
 
 #### Next available data
 
-```javascript
+```ts
 const prefs = { audioFormat: grandi.AUDIO_FORMAT_FLOAT_32_SEPARATE };
 const payload = await receiver.data(prefs, 1000); // 1s timeout
 if (payload.type === "video") {
@@ -222,10 +225,31 @@ if (payload.type === "video") {
 }
 ```
 
+### Frame synchronization (pull-based playback)
+If you want smoother playback clocked to your own loop (e.g., GPU vsync) instead of reacting to pushed frames, wrap an existing receiver in an NDI frame-synchronizer:
+
+```ts
+const receiver = await grandi.receive({ source, colorFormat: grandi.ColorFormat.Fastest });
+const fs = await grandi.framesync(receiver);
+
+// Pull video; returns { type: "timeout" } until first frame arrives.
+const video = await fs.video(grandi.FrameType.Progressive);
+
+// Pull audio resampled to your requested cadence.
+const audio = await fs.audio({ sampleRate: 48_000, noChannels: 2, noSamples: 1600 });
+
+fs.destroy();       // destroy frame-sync first
+receiver.destroy(); // then destroy the receiver
+```
+
+Notes:
+- `fs.video()` and `fs.audio()` always return immediately; they may duplicate/drop frames to match your call rate.
+- Always destroy the frame-sync before destroying the receiver it wraps.
+
 ### 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
+```ts
 const sender = await grandi.send({
   name: "grandi-demo",
   groups: "studio3",
@@ -281,32 +305,60 @@ Destroy senders and receivers explicitly when finished to release NDI resources.
 - `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.
 
+## Benchmark
+A loopback benchmark script measures end-to-end send/receive throughput and latency on your machine. It spins up a sender and receiver locally, so a working NDI setup with discovery is required.
+
+- Build first if needed (`npm run build`), then run `npm run bench -- [options]`. The script defaults to 1080p30 with audio and colored output.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--mode realtime|throughput` | `realtime` | `realtime` keeps to the target FPS with clocking enabled; `throughput` sends as fast as possible. |
+| `--duration <sec>` | `5` | Run length in seconds. |
+| `--fps <num>` | `30` | Target frames per second. |
+| `--width <px>` | `1920` | Video width in pixels. |
+| `--height <px>` | `1080` | Video height in pixels. |
+| `--no-audio` | audio on | Disable sending/receiving audio. |
+| `--framesync` | off | Pull frames via the NDI frame-sync API for smoother capture. |
+| `--gc-every <ms>` | `500` | Force `global.gc()` at this interval when `--expose-gc` is enabled. |
+| `--no-color` | color on | Disable ANSI color output. |
+
+`npm run bench` adds `--expose-gc` to keep buffer reuse stable during long runs.
+
+Example (10s, 1080p30, realtime):
+
+```bash
+npm run bench -- --duration 10 --mode realtime --fps 30 --framesync
+```
+
+Example (throughput stress, 720p, video only):
+
+```bash
+npm run bench -- --mode throughput --width 1280 --height 720 --no-audio --no-color
+```
+
 ## 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).
+2. **Download the NDI SDK (maintainers)**
+	- Run `node scripts/build-addon.mjs` to download and unpack the official NDI SDK into `ndi/` and populate the per-arch package folders under `packages/` with the right runtime files.
+	- Consumers don’t need this step; they install the appropriate `@grandi/<os>-<arch>` package from npm automatically.
 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:integration` exercises the native bindings against a real NDI environment;
   - `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).
 
@@ -314,70 +366,91 @@ Before opening a pull request, make sure the linter, formatter, and tests all pa
 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.
+
+| Export | Returns | Purpose |
+| --- | --- | --- |
+| `find(options?: FindOptions)` | `Promise<Finder>` | Discover available NDI sources, optionally filtering by groups, local visibility, or explicit IPs. Resolves to a finder whose `sources()` method exposes the latest snapshot. |
+| `receive(options: ReceiveOptions)` | `Promise<Receiver>` | Create a receiver bound to a specific `Source` with optional color format, bandwidth, interlaced, and naming tweaks. |
+| `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()` / `destroy()` | `boolean` | Manually initialize or tear down the shared NDI state; normally handled automatically by `send`/`receive`. |
+| `version()` | `string` | Report the bundled NDI SDK version. |
+| `isSupportedCPU()` | `boolean` | Guard call to confirm the host CPU meets the NDI SDK requirements. |
+| `ColorFormat`, `AudioFormat`, `Bandwidth`, `FrameType`, `FourCC` | enums | Enumerations re-exported for convenience (also mirrored as constants on the default export). |
+| `default` | `typeof grandi` | 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`.
+| Call | Returns | Purpose |
+| --- | --- | --- |
+| `video(timeoutMs?: number)` | `Promise<ReceivedVideoFrame>` | Resolve with the next available video frame. |
+| `audio(optionsOrTimeout?: AudioReceiveOptions \| number, timeoutMs?: number)` | `Promise<ReceivedAudioFrame>` | Fetch audio, overriding format/reference level per call if desired. |
+| `metadata(timeoutMs?: number)` | `Promise<ReceivedMetadataFrame>` | Receive metadata frames (XML strings). |
+| `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 resources. |
+
+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`.
+| Call | Returns | Purpose |
+| --- | --- | --- |
+| `video(frame: VideoFrame)` | `Promise<void>` | Send a video frame into the NDI network. |
+| `audio(frame: AudioFrame)` | `Promise<void>` | Send an audio frame. |
+| `metadata(data: string)` | `boolean` | Push metadata strings (XML). |
+| `tally()` | `SenderTally` | Retrieve current tally state (program/preview booleans plus `changed`). |
+| `connections()` | `number` | Report how many receivers are actively connected. |
+| `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.
+
+| Call | Returns | Purpose |
+| --- | --- | --- |
+| `change(source: Source)` | `boolean` | Switch downstream 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 the router. |
 
 ### 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.
+
+| Call | Returns | Purpose |
+| --- | --- | --- |
+| `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 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.
+
+| Type | Shape | Notes |
+| --- | --- | --- |
+| `Source` | `{ name: string; urlAddress?: string }` | Identifies an NDI endpoint. |
+| `FindOptions` | `{ showLocalSources?: boolean; groups?: string; extraIPs?: string; }` | Filters applied when discovering sources. |
+| `ReceiveOptions` | `{ source: Source; colorFormat?: ColorFormat; bandwidth?: Bandwidth; allowVideoFields?: boolean; name?: string; }` | Required to create receivers with optional overrides. |
+| `SendOptions` | `{ name: string; groups?: string; clockVideo?: boolean; clockAudio?: boolean; }` | Configure sender identity and sync behavior. |
+| `AudioReceiveOptions` | `{ audioFormat?: AudioFormat; referenceLevel?: number; }` | Used when calling `receiver.audio` or `receiver.data`. |
+| `ReceiverTallyState` | `{ onProgram?: boolean; onPreview?: boolean; }` | Provided to `receiver.tally` to reflect monitoring state. |
+| `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` | Matches 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.
+
+| Type | Description |
+| --- | --- |
+| `VideoFrame` | Outbound frame with resolution, frame rate (`frameRateN`/`frameRateD`), aspect ratio, `fourCC`, `frameFormatType`, `lineStrideBytes`, `data`, optional `timecode`, `timestamp`, `metadata`. |
+| `ReceivedVideoFrame` | `VideoFrame` plus `type: "video"` and non-optional `timecode`/`timestamp`. |
+| `AudioFrame` | Outbound audio payload including sample rate, channels/samples, stride, `data`, `fourCC`, optional timing/metadata. |
+| `ReceivedAudioFrame` | Inbound audio payload with `audioFormat`, `referenceLevel`, `timecode`, `timestamp`. |
+| `ReceivedMetadataFrame` | Metadata payload (`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.
@@ -396,7 +469,7 @@ Apart from the exceptions below, this software is released under the Apache 2.0
 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.
+- The DLL and library files are provided for installation convenience and are covered by the NewTek license in the scoped packages under `packages/` (published as `@grandi/*`).
 
 ## Trademarks
 NDI™  is a trademark of NewTek, Inc.

package/package.json

@@ -1,84 +1,83 @@
 {
-	"name": "grandi",
-	"version": "0.1.0",
-	"description": "Node.JS native bindings to the Newtek NDI SDK.",
-	"homepage": "https://github.com/tux-tn/grandi#readme",
-	"keywords": [
-		"Newtek",
-		"NDI",
-		"network",
-		"device",
-		"interface"
-	],
-	"author": "Sarhan Aissi <npm@tux.tn>",
-	"license": "Apache-2.0",
-	"files": [
-		"binding.gyp",
-		"dist",
-		"lib",
-		"src",
-		"scripts",
-		"LICENSE",
-		"NOTICE",
-		"README.md",
-		"prebuilds"
-	],
-	"main": "./dist/index.mjs",
-	"types": "./dist/index.d.mts",
-	"exports": {
-		".": "./dist/index.mjs",
-		"./package.json": "./package.json"
-	},
-	"gypfile": true,
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/tux-tn/grandi.git"
-	},
-	"bugs": {
-		"url": "https://github.com/tux-tn/grandi/issues"
-	},
-	"dependencies": {
-		"cross-spawn": "7.0.6",
-		"cross-zip": "4.0.1",
-		"execa": "9.6.0",
-		"got": "14.6.3",
-		"node-gyp-build": "^4.8.4",
-		"shelljs": "0.10.0",
-		"tmp": "0.2.5"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "2.3.4",
-		"@types/bindings": "^1.5.5",
-		"@types/cross-zip": "^4.0.2",
-		"@types/node": "^24.10.0",
-		"@types/shelljs": "^0.8.17",
-		"@types/tmp": "^0.2.6",
-		"@vitest/coverage-v8": "^4.0.8",
-		"cross-env": "^10.1.0",
-		"prebuildify": "^6.0.1",
-		"shx": "0.4.0",
-		"standard-version": "^9.5.0",
-		"tsdown": "^0.16.1",
-		"typescript": "^5.9.3",
-		"vitest": "^4.0.8"
-	},
-	"scripts": {
-		"preinstall": "node scripts/preinstall.mjs",
-		"install": "node-gyp-build",
-		"prebuild:download": "cross-env NDI_FORCE=1 node scripts/preinstall.mjs",
-		"build": "tsdown",
-		"prebuild": "prebuildify --napi --strip --target=node@20.19.5",
-		"test": "vitest run",
-		"test:watch": "vitest",
-		"test:unit": "vitest run test/unit",
-		"test:integration": "cross-env RUN_NDI_TESTS=1 vitest run test/integration",
-		"test:coverage": "vitest run --coverage",
-		"format": "biome format",
-		"format:cpp": "clang-format -i lib/*.cc lib/*.h",
-		"lint": "biome lint",
-		"clean": "shx rm -rf ndi build"
-	},
-	"engines": {
-		"node": ">=20.19.5"
-	}
+  "name": "grandi",
+  "version": "1.1.0",
+  "description": "Node.JS native bindings to the Newtek NDI SDK.",
+  "homepage": "https://github.com/tux-tn/grandi#readme",
+  "keywords": [
+    "Newtek",
+    "NDI",
+    "network",
+    "device",
+    "interface"
+  ],
+  "author": "Sarhan Aissi <npm@tux.tn>",
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "gypfile": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tux-tn/grandi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tux-tn/grandi/issues"
+  },
+  "optionalDependencies": {
+    "@grandi/linux-x64": "^1.0.0",
+    "@grandi/linux-arm64": "^1.0.0",
+    "@grandi/linux-armv7l": "^1.0.0",
+    "@grandi/win32-x64": "^1.0.0",
+    "@grandi/win32-ia32": "^1.0.0",
+    "@grandi/darwin-universal": "1.0.0"
+  },
+  "dependencies": {
+    "cross-spawn": "7.0.6",
+    "cross-zip": "4.0.1",
+    "execa": "9.6.1",
+    "got": "14.6.5",
+    "node-gyp-build": "^4.8.4",
+    "shelljs": "0.10.0",
+    "tmp": "0.2.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.9",
+    "@types/bindings": "^1.5.5",
+    "@types/cross-zip": "^4.0.2",
+    "@types/node": "^25.0.2",
+    "@types/shelljs": "^0.10.0",
+    "@types/tmp": "^0.2.6",
+    "@vitest/coverage-v8": "^4.0.15",
+    "cross-env": "^10.1.0",
+    "shx": "0.4.0",
+    "standard-version": "^9.5.0",
+    "tsdown": "^0.18.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "bench": "node --expose-gc scripts/benchmark.mjs",
+    "test:coverage": "vitest run --coverage",
+    "format": "biome format",
+    "format:cpp": "clang-format -i lib/*.cc lib/*.h",
+    "lint": "biome lint",
+    "clean": "shx rm -rf ndi build"
+  },
+  "engines": {
+    "node": ">=20.19.5"
+  }
 }