grandi 1.0.0 → 1.2.0

package/dist/index.d.mts

@@ -12,7 +12,7 @@ declare enum ColorFormat {
   UYVY_RGBA = 3,
   Fastest = 100,
   Best = 101,
-  BGRX_BGRA_FLIPPED = 200,
+  BGRX_BGRA_FLIPPED = 1000,
 }
 declare enum AudioFormat {
   Float32Separate = 0,
@@ -57,6 +57,10 @@ interface VideoFrame {
   lineStrideBytes: number;
   data: Buffer;
   timecode?: Timecode;
+  /**
+   * Receive-only timestamp filled by the NDI SDK (UTC time, 100ns units under the hood).
+   * NDI ignores this field when sending.
+   */
   timestamp?: PtpTimestamp;
   metadata?: string;
 }
@@ -75,6 +79,10 @@ interface AudioFrame {
   data: Buffer;
   fourCC: FourCC;
   timecode?: Timecode;
+  /**
+   * Receive-only timestamp filled by the NDI SDK (UTC time, 100ns units under the hood).
+   * NDI ignores this field when sending.
+   */
   timestamp?: PtpTimestamp;
   metadata?: string;
 }
@@ -104,7 +112,10 @@ interface SourceChangeEvent {
 interface StatusChangeEvent {
   type: "statusChange";
 }
-type ReceiverDataFrame = ReceivedVideoFrame | ReceivedAudioFrame | ReceivedMetadataFrame | SourceChangeEvent | StatusChangeEvent;
+interface TimeoutEvent {
+  type: "timeout";
+}
+type ReceiverDataFrame = ReceivedVideoFrame | ReceivedAudioFrame | ReceivedMetadataFrame | SourceChangeEvent | StatusChangeEvent | TimeoutEvent;
 interface AudioReceiveOptions {
   audioFormat?: AudioFormat;
   referenceLevel?: number;
@@ -158,6 +169,31 @@ interface Routing {
   connections(): number;
   sourcename(): string;
 }
+interface FrameSyncAudioOptions {
+  sampleRate?: number;
+  noChannels?: number;
+  noSamples?: number;
+}
+interface FrameSync {
+  embedded: unknown;
+  /**
+   * Captures a video frame using NDI frame-synchronization (time base correction).
+   * Always returns immediately.
+   *
+   * If no video has ever been received, resolves with `{ type: "timeout" }`.
+   */
+  video(fieldType?: FrameType): Promise<ReceivedVideoFrame | TimeoutEvent>;
+  /**
+   * Captures audio using NDI frame-synchronization (resampled to match your calls).
+   * Always returns immediately and may insert silence if no audio is present.
+   */
+  audio(options?: FrameSyncAudioOptions): Promise<ReceivedAudioFrame>;
+  /**
+   * Returns an approximate depth of the internal audio queue in samples.
+   */
+  audioQueueDepth(): number;
+  destroy(): boolean;
+}
 interface Finder {
   sources(): Source[];
   wait(timeoutMs?: number): boolean;
@@ -172,6 +208,10 @@ interface ReceiveOptions {
   source: Source;
   colorFormat?: ColorFormat;
   bandwidth?: Bandwidth;
+  /**
+   * If `colorFormat` is `ColorFormat.Fastest` or `ColorFormat.Best`, the NDI SDK
+   * implicitly enables video fields and this option is forced to `true`.
+   */
   allowVideoFields?: boolean;
   name?: string;
 }
@@ -181,79 +221,424 @@ interface SendOptions {
   clockVideo?: boolean;
   clockAudio?: boolean;
 }
-interface GrandiAddon {
+interface Grandi {
+  /**
+   * Gets the NDI SDK version string (e.g. `"NDI SDK 6.0.0.0"`).
+   * @returns The NDI SDK version string.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * console.log(grandi.version());
+   * ```
+   */
   version(): string;
+  /**
+   * Checks if the current CPU architecture is supported by NDI.
+   * @returns `true` when NDI is supported on this CPU/platform.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * if (!grandi.isSupportedCPU()) throw new Error("NDI unsupported here");
+   * ```
+   */
   isSupportedCPU(): boolean;
+  /**
+   * Initializes the NDI library. Must be called before using any other NDI functions.
+   * Call this once per process, before creating senders/receivers/finders.
+   * @returns `true` if initialization was successful.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * if (!grandi.initialize()) throw new Error("NDI init failed");
+   * ```
+   */
   initialize(): boolean;
+  /**
+   * Destroys the NDI library instance and cleans up resources.
+   * Should be called when done using NDI to free resources.
+   * @returns `true` if destruction was successful.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * grandi.destroy();
+   * ```
+   */
   destroy(): boolean;
-  find(params: FindOptions): Promise<Finder>;
-  receive(params: ReceiveOptions): Promise<Receiver>;
+  /**
+   * Creates an NDI sender for transmitting video and audio over the network.
+   * @param params Sender options.
+   * @returns A promise that resolves to a Sender instance.
+   * @throws {Error} Promise rejects on unsupported platform/CPU or if sender creation fails.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * grandi.initialize();
+   * const sender = await grandi.send({ name: "My Source" });
+   * ```
+   */
   send(params: SendOptions): Promise<Sender>;
+  /**
+   * Creates an NDI receiver for receiving video and audio from an NDI source.
+   * @param params Receiver options.
+   * @returns A promise that resolves to a Receiver instance.
+   * @throws {Error} Promise rejects on unsupported platform/CPU or if receiver creation fails.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * grandi.initialize();
+   * const finder = await grandi.find({ showLocalSources: true });
+   * finder.wait(1000);
+   * const source = finder.sources()[0];
+   * finder.destroy();
+   * const receiver = await grandi.receive({ source });
+   * const frame = await receiver.video(1000);
+   * receiver.destroy();
+   * ```
+   */
+  receive(params: ReceiveOptions): Promise<Receiver>;
+  /**
+   * Creates an NDI frame-synchronizer (time base corrector) backed by an existing receiver.
+   * Use this when you want smooth playback clocked to your own render/audio loop.
+   *
+   * Note: destroy the frame-sync before destroying the receiver.
+   */
+  framesync(receiver: Receiver): Promise<FrameSync>;
+  /**
+   * Creates an NDI router for switching between different NDI sources.
+   * @param params Router options.
+   * @returns A promise that resolves to a Routing instance.
+   * @throws {Error} Promise rejects on unsupported platform/CPU or if routing creation fails.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * grandi.initialize();
+   * const router = await grandi.routing({ name: "My Router" });
+   * // router.change(source) to route a discovered source
+   * router.destroy();
+   * ```
+   */
   routing(params: {
     name?: string;
     groups?: string;
   }): Promise<Routing>;
-}
-//#endregion
-//#region src/index.d.ts
-declare function find(params?: FindOptions): Promise<Finder>;
-declare const version: () => string;
-declare const isSupportedCPU: () => boolean;
-declare const initialize: () => boolean;
-declare const destroy: () => boolean;
-declare const send: (params: SendOptions) => Promise<Sender>;
-declare const receive: (params: ReceiveOptions) => Promise<Receiver>;
-declare const routing: (params: {
-  name?: string;
-  groups?: string;
-}) => Promise<Routing>;
-declare const grandi: {
-  version: () => string;
-  isSupportedCPU: () => boolean;
-  initialize: () => boolean;
-  destroy: () => boolean;
-  send: (params: SendOptions) => Promise<Sender>;
-  receive: (params: ReceiveOptions) => Promise<Receiver>;
-  routing: (params: {
-    name?: string;
-    groups?: string;
-  }) => Promise<Routing>;
-  find: typeof find;
+  /**
+   * Creates a finder to discover NDI sources on the network.
+   * @param params Discovery options.
+   * @returns A promise that resolves to a Finder instance.
+   * @throws {Error} Promise rejects on unsupported platform/CPU or if the finder cannot be created.
+   *
+   * @example
+   * ```js
+   * import grandi from "grandi";
+   * grandi.initialize();
+   * const finder = await grandi.find({ showLocalSources: true });
+   * finder.wait(1000);
+   * console.log(finder.sources());
+   * finder.destroy();
+   * ```
+   */
+  find(params?: FindOptions): Promise<Finder>;
+  /**
+   * Enum: receiver video color formats.
+   */
   ColorFormat: typeof ColorFormat;
+  /**
+   * Enum: supported raw audio formats for helpers/receive conversions.
+   */
   AudioFormat: typeof AudioFormat;
+  /**
+   * Enum: receiver bandwidth modes.
+   */
   Bandwidth: typeof Bandwidth;
+  /**
+   * Enum: video frame format types (progressive/interlaced/fields).
+   */
   FrameType: typeof FrameType;
+  /**
+   * Enum: FourCC pixel/audio formats used in frames.
+   */
   FourCC: typeof FourCC;
+  /**
+   * Alias of `ColorFormat.BGRX_BGRA`.
+   */
   COLOR_FORMAT_BGRX_BGRA: ColorFormat;
+  /**
+   * Alias of `ColorFormat.UYVY_BGRA`.
+   */
   COLOR_FORMAT_UYVY_BGRA: ColorFormat;
+  /**
+   * Alias of `ColorFormat.RGBX_RGBA`.
+   */
   COLOR_FORMAT_RGBX_RGBA: ColorFormat;
+  /**
+   * Alias of `ColorFormat.UYVY_RGBA`.
+   */
   COLOR_FORMAT_UYVY_RGBA: ColorFormat;
+  /**
+   * Alias of `ColorFormat.Fastest`.
+   */
   COLOR_FORMAT_FASTEST: ColorFormat;
+  /**
+   * Alias of `ColorFormat.BGRX_BGRA_FLIPPED` (Windows-only).
+   */
   COLOR_FORMAT_BGRX_BGRA_FLIPPED: ColorFormat;
+  /**
+   * Alias of `Bandwidth.MetadataOnly`.
+   */
   BANDWIDTH_METADATA_ONLY: Bandwidth;
+  /**
+   * Alias of `Bandwidth.AudioOnly`.
+   */
   BANDWIDTH_AUDIO_ONLY: Bandwidth;
+  /**
+   * Alias of `Bandwidth.Lowest`.
+   */
   BANDWIDTH_LOWEST: Bandwidth;
+  /**
+   * Alias of `Bandwidth.Highest`.
+   */
   BANDWIDTH_HIGHEST: Bandwidth;
+  /**
+   * Alias of `FrameType.Progressive`.
+   */
   FORMAT_TYPE_PROGRESSIVE: FrameType;
+  /**
+   * Alias of `FrameType.Interlaced`.
+   */
   FORMAT_TYPE_INTERLACED: FrameType;
+  /**
+   * Alias of `FrameType.Field0`.
+   */
   FORMAT_TYPE_FIELD_0: FrameType;
+  /**
+   * Alias of `FrameType.Field1`.
+   */
   FORMAT_TYPE_FIELD_1: FrameType;
+  /**
+   * Alias of `AudioFormat.Float32Separate`.
+   */
   AUDIO_FORMAT_FLOAT_32_SEPARATE: AudioFormat;
+  /**
+   * Alias of `AudioFormat.Float32Interleaved`.
+   */
   AUDIO_FORMAT_FLOAT_32_INTERLEAVED: AudioFormat;
+  /**
+   * Alias of `AudioFormat.Int16Interleaved`.
+   */
   AUDIO_FORMAT_INT_16_INTERLEAVED: AudioFormat;
+  /**
+   * Alias of `FourCC.UYVY`.
+   */
   FOURCC_UYVY: FourCC;
+  /**
+   * Alias of `FourCC.UYVA`.
+   */
   FOURCC_UYVA: FourCC;
+  /**
+   * Alias of `FourCC.P216`.
+   */
   FOURCC_P216: FourCC;
+  /**
+   * Alias of `FourCC.PA16`.
+   */
   FOURCC_PA16: FourCC;
+  /**
+   * Alias of `FourCC.YV12`.
+   */
   FOURCC_YV12: FourCC;
+  /**
+   * Alias of `FourCC.I420`.
+   */
   FOURCC_I420: FourCC;
+  /**
+   * Alias of `FourCC.NV12`.
+   */
   FOURCC_NV12: FourCC;
+  /**
+   * Alias of `FourCC.BGRA`.
+   */
   FOURCC_BGRA: FourCC;
+  /**
+   * Alias of `FourCC.BGRX`.
+   */
   FOURCC_BGRX: FourCC;
+  /**
+   * Alias of `FourCC.RGBA`.
+   */
   FOURCC_RGBA: FourCC;
+  /**
+   * Alias of `FourCC.RGBX`.
+   */
   FOURCC_RGBX: FourCC;
+  /**
+   * Alias of `FourCC.FLTp`.
+   */
   FOURCC_FLTp: FourCC;
-};
+}
+//#endregion
+//#region src/index.d.ts
+interface GrandiAddon {
+  version(): string;
+  isSupportedCPU(): boolean;
+  initialize(): boolean;
+  destroy(): boolean;
+  find(params?: FindOptions): Promise<Finder>;
+  receive(params: ReceiveOptions): Promise<Receiver>;
+  framesync(receiver: Receiver): Promise<FrameSync>;
+  send(params: SendOptions): Promise<Sender>;
+  routing(params: {
+    name?: string;
+    groups?: string;
+  }): Promise<Routing>;
+}
+/**
+ * Creates a finder to discover NDI sources on the network.
+ * @param {FindOptions} [params={}] - Options for finding sources.
+ * @param {boolean} [params.showLocalSources] - Whether to show local sources.
+ * @param {string} [params.groups] - Multicast groups to search in.
+ * @param {string} [params.extraIPs] - Additional IP addresses to search.
+ * @returns {Promise<Finder>} A promise that resolves to a Finder instance for discovering sources.
+ * @throws {Error} Promise rejects on unsupported platform/CPU or if the finder cannot be created.
+ *
+ * @example
+ * ```js
+ * import { find, initialize } from "grandi";
+ * initialize();
+ * const finder = await find({ showLocalSources: true });
+ * finder.wait(1000);
+ * console.log(finder.sources());
+ * finder.destroy();
+ * ```
+ */
+declare function find(params?: FindOptions): Promise<Finder>;
+/**
+ * Gets the version of the NDI SDK.
+ * @returns {string} The NDI SDK version string.
+ */
+declare const version: () => string;
+/**
+ * Checks if the current CPU architecture is supported by NDI.
+ * @returns {boolean} True if the CPU is supported, false otherwise.
+ */
+declare const isSupportedCPU: () => boolean;
+/**
+ * Initializes the NDI library. Must be called before using any other NDI functions.
+ * @returns {boolean} True if initialization was successful, false otherwise.
+ *
+ * @example
+ * ```js
+ * import { initialize } from "grandi";
+ * if (!initialize()) throw new Error("NDI init failed");
+ * ```
+ */
+declare const initialize: () => boolean;
+/**
+ * Destroys the NDI library instance and cleans up resources.
+ * Should be called when done using NDI to free resources.
+ * @returns {boolean} True if destruction was successful, false otherwise.
+ *
+ * @example
+ * ```js
+ * import { destroy } from "grandi";
+ * destroy();
+ * ```
+ */
+declare const destroy: () => boolean;
+/**
+ * Creates an NDI sender for transmitting video and audio over the network.
+ * @param {SendOptions} params - Options for creating the sender.
+ * @param {string} params.name - The name of the NDI source.
+ * @param {string} [params.groups] - Multicast groups to send to.
+ * @param {boolean} [params.clockVideo] - Whether to clock video frames.
+ * @param {boolean} [params.clockAudio] - Whether to clock audio frames.
+ * @returns {Promise<Sender>} A promise that resolves to a Sender instance for transmitting data.
+ * @throws {Error} Promise rejects on unsupported platform/CPU or if sender creation fails.
+ *
+ * @example
+ * ```js
+ * import { initialize, send } from "grandi";
+ * initialize();
+ * const sender = await send({ name: "My Source" });
+ * // sender.video(...) / sender.audio(...)
+ * sender.destroy();
+ * ```
+ */
+declare const send: (params: SendOptions) => Promise<Sender>;
+/**
+ * Creates an NDI receiver for receiving video and audio from an NDI source.
+ * @param {ReceiveOptions} params - Options for creating the receiver.
+ * @param {ReceiveOptions["source"]} params.source - The NDI source to connect to.
+ * @param {ReceiveOptions["colorFormat"]} [params.colorFormat] - The color format for received video.
+ * @param {ReceiveOptions["bandwidth"]} [params.bandwidth] - The bandwidth limitation for the connection.
+ * @param {boolean} [params.allowVideoFields] - Whether to allow video fields.
+ * @param {string} [params.name] - The name for the receiver.
+ * @returns {Promise<Receiver>} A promise that resolves to a Receiver instance for receiving data.
+ * @throws {Error} Promise rejects on unsupported platform/CPU or if receiver creation fails.
+ *
+ * @example
+ * ```js
+ * import { find, initialize, receive } from "grandi";
+ * initialize();
+ * const finder = await find({ showLocalSources: true });
+ * finder.wait(1000);
+ * const source = finder.sources()[0];
+ * finder.destroy();
+ * const receiver = await receive({ source });
+ * const frame = await receiver.video(1000);
+ * receiver.destroy();
+ * ```
+ */
+declare const receive: (params: ReceiveOptions) => Promise<Receiver>;
+/**
+ * Creates an NDI frame-synchronizer (time base corrector) backed by an existing receiver.
+ * Use this when you want smooth playback clocked to your own render/audio loop.
+ *
+ * Note: destroy the frame-sync before destroying the receiver.
+ * @param {Receiver} receiver - The receiver instance to frame-sync.
+ * @returns {Promise<FrameSync>} A promise that resolves to a FrameSync instance.
+ * @throws {Error} Promise rejects on unsupported platform/CPU or if framesync creation fails.
+ *
+ * @example
+ * ```js
+ * import grandi from "grandi";
+ * grandi.initialize();
+ * const receiver = await grandi.receive({ source });
+ * const fs = await grandi.framesync(receiver);
+ * const frame = await fs.video(grandi.FrameType.Progressive);
+ * fs.destroy();
+ * receiver.destroy();
+ * ```
+ */
+declare const framesync: (receiver: Receiver) => Promise<FrameSync>;
+/**
+ * Creates an NDI router for switching between different NDI sources.
+ * @param {Object} params - Options for creating the router.
+ * @param {string} [params.name] - The name for the router.
+ * @param {string} [params.groups] - Multicast groups for the router.
+ * @returns {Promise<Routing>} A promise that resolves to a Routing instance for source switching.
+ * @throws {Error} Promise rejects on unsupported platform/CPU or if routing creation fails.
+ *
+ * @example
+ * ```js
+ * import { initialize, routing } from "grandi";
+ * initialize();
+ * const router = await routing({ name: "My Router" });
+ * // router.change(source)
+ * router.destroy();
+ * ```
+ */
+declare const routing: (params: {
+  name?: string;
+  groups?: string;
+}) => Promise<Routing>;
+declare const grandi: Grandi;
 //#endregion
-export { AudioFormat, type AudioFrame, type AudioReceiveOptions, Bandwidth, ColorFormat, type FindOptions, type Finder, FourCC, FrameType, type GrandiAddon, type PtpTimestamp, type ReceiveOptions, type ReceivedAudioFrame, type ReceivedMetadataFrame, type ReceivedVideoFrame, type ReceiverDataFrame, type ReceiverTallyState, type Routing, type Sender, type SenderTally, type Source, type SourceChangeEvent, type StatusChangeEvent, type Timecode, type VideoFrame, grandi as default, destroy, find, initialize, isSupportedCPU, receive, routing, send, version };
+export { AudioFormat, type AudioFrame, type AudioReceiveOptions, Bandwidth, ColorFormat, type FindOptions, type Finder, FourCC, type FrameSync, type FrameSyncAudioOptions, FrameType, type Grandi, GrandiAddon, type PtpTimestamp, type ReceiveOptions, type ReceivedAudioFrame, type ReceivedMetadataFrame, type ReceivedVideoFrame, type ReceiverDataFrame, type ReceiverTallyState, type Routing, type Sender, type SenderTally, type Source, type SourceChangeEvent, type StatusChangeEvent, type Timecode, type TimeoutEvent, type VideoFrame, grandi as default, destroy, find, framesync, initialize, isSupportedCPU, receive, routing, send, version };
 //# sourceMappingURL=index.d.mts.map