NDI RECV Event Monitoring and Commands

In addition to the NDI Recv Advertiser and NDI Recv Listener APIs available in the standard SDK, the Advanced SDK introduces enhanced APIs that expand capabilities for event monitoring and command execution on registered receivers. These extended functions enable developers to subscribe to and listen to receiver events in real time, as well as send commands to manage receiver behavior more effectively.

This functionality is essential for real-time monitoring and control of NDI receivers, enabling developers to build sophisticated NDI-based applications with dynamic event-driven behavior.

Beyond the standard functions—NDIlib_recv_advertiser_create and NDIlib_recv_listener_create—available in the standard SDK, the Advanced SDK offers extended versions of this function calls:

• NDIlib_recv_advertiser_create_ex

• NDIlib_recv_listener_create_ex

These extended functions accept configuration settings as JSON strings, providing greater flexibility for managing network configurations of both the receiver and listener.

The use of receiver event monitoring and command APIs in NDI 6.2 requires a special vendor ID. If you do not have a vendor ID, please contact the NDI Support Team to obtain one. Without a valid vendor ID, the API will not function properly.

Subscribing to Receiver Events

To subscribe to receive monitoring events from a specified receiver, use the following function,

void NDIlib_recv_listener_subscribe_events(NDIlib_recv_listener_instance_t p_instance, const char* p_receiver_uuid);

This function requires the following parameters:

• p_instance: The receiver listener instance (NDIlib_recv_listener_instance_t).

• p_uuid: The unique identifier of the receiver.

The receiver’s UUID is part of the NDIlib_receiver_t structure, which is generated by the SDK. You can retrieve the list of receivers using the NDIlib_recv_listener_get_receivers function, which will provide the necessary UUID for each receiver.

Unsubscribing from Receiver Events

To unsubscribe from receiving events from a specific receiver, use the following function,

NDIlib_recv_listener_unsubscribe_events(NDIlib_recv_listener_instance_t p_instance, const char* p_receiver_uuid);

This function requires the following parameters:

• p_instance: The receiver listener instance (NDIlib_recv_listener_instance_t).

• p_uuid: The unique identifier of the receiver.

Example Code:

The following example demonstrates how to create a receiver listener, retrieve the list of advertised receivers, subscribe to events, and unsubscribe when finished:

// Create an instance of the receiver listener.
NDIlib_recv_listener_instance_t pNDI_recv_listener =
NDIlib_recv_listener_create_ex(nullptr, p_ndi_config); 
if (!pNDI_recv_listener) {
 // Handle error
}

// Get the list of advertised receivers.
uint32_t num_receivers = 0;
const NDIlib_receiver_t* p_receivers =
NDIlib_recv_listener_get_receivers(pNDI_recv_listener, &num_receivers);

// Display the found receivers.
printf("Network receivers (%u found).\n", num_receivers);
for (uint32_t i = 0; i < num_receivers; i++) {
 printf("%u. %s\n", i + 1, p_receivers[i].p_name);
 
// If the receiver is not currently subscribed, subscribe to it.
if (!p_receivers[i].events_subscribed) {
NDIlib_recv_listener_subscribe_events(pNDI_recv_listener, p_receivers[i].p_uuid);
}

// Perform operations with the subscribed receiver...
 
// Unsubscribe from the receiver after processing.
NDIlib_recv_listener_unsubscribe_events(pNDI_recv_listener, p_receivers[i].p_uuid);
}

Receiver Monitoring Events

The NDIlib_recv_listener_get_events function allows you to fetch the list of monitoring events from the receiver that you have previously subscribed to using the NDIlib_recv_listener_subscribe_events function. It returns an array of NDIlib_recv_listener_event structures containing the event details.

const NDIlib_recv_listener_event* NDIlib_recv_listener_get_events(NDIlib_recv_listener_instance_t p_instance, uint32_t* p_num_events, uint32_t timeout_in_ms);

Parameters:

• p_instance (NDIlib_recv_listener_instance_t): The instance of the receiver listener.

• p_num_events (uint32_t*): A pointer to the variable that will receive the number of events returned by the function.

• timeout_in_ms (uint32_t): The timeout value in milliseconds, determining how long the function will wait for events. A value of 0 returns immediately with any current pending events, and -1 waits indefinitely until an event is received and .

This function returns a pointer to an array of NDIlib_recv_listener_event structures containing event details. If no events are received within the specified timeout period, the function returns NULL. The returned events should be freed using the NDIlib_recv_listener_free_events function.

Example Code:

uint32_t num_events;
const NDIlib_recv_listener_event* events = NDIlib_recv_listener_get_events(p_instance, &num_events, 1000);
 
if (events != NULL) {
 for (uint32_t i = 0; i < num_events; ++i) {
 printf("Event UUID: %s\n", events[i].p_uuid);
 printf("Event Name: %s\n", events[i].p_name);
 printf("Event Value: %s\n", events[i].p_value);
}
 
// Free the events after processing
NDIlib_recv_listener_free_events(events);
} else {
 printf("No events received within the timeout period.\n");
}

The following table lists the receiver monitoring events currently supported in the first release. These events provide dynamic information about an NDI receiver's state, source, and media properties.

Event Name	Description	Type	Example Event Values
source-name	The name of the NDI source that the receiver is currently configured to be connected to.	string	"Camera_1"
source-url	The URL of the NDI source that the receiver is currently configured to be connected to.	string	"ndi://192.168.1.10/Camera_1"
connection- state	The state of the main TCP connection to the configured NDI source.	string	"connected", "disconnected"
audio-present	Indicates if audio has been detected from the NDI source.	bool	true, false
audio-codec	The audio codec in use.	string	"pcm", "aac", "opus"
audio-channels	The number of audio channels within the audio stream.	int	1, 2, 6, 8
audio-sample- rate	The sample rate of the audio stream.	int	44100, 48000
audio-receive- mode	Specifies how the audio is being received.	string	"single-tcp", "multi-tcp", "udp-unicast", "udp-multicast", "rudp"
video-present	Indicates if video has been detected from the NDI source.	bool	true, false
video-codec	The video codec in use.	string	"shq0", "shq2", "shq7", "h264", "h265"
video- resolution	The resolution of the video frames, in “WxH” format, where W is the width and H is the height.	string	"1920x1080", "1280x720", "3840x2160"
video-frame- rate	The frame rate of the video stream, in “N/D” format, where N is the numerator and D is the denominator.	string	"30/1", "60/1"
video-frame- type	The type of fielding format in use by the video stream.	string	"progressive", "interlaced"
video-has- alpha	Indicates if the video stream contains an alpha channel.	bool	true, false
video-color- primaries	The color primaries of the video stream.	string	"bt_601", "bt_709", "bt_2020", "bt_2100"
video-transfer- function	The transfer function of the video stream.	string	"bt_601", "bt_709", "bt_2020", "bt_2100_hlg", "bt_2100_pq"
video-matrix- coefficients	The matrix coefficients of the video stream.	string	"bt_601", "bt_709", "bt_2020", "bt_2100"
video-receive- mode	Specifies how the video is being received.	string	"single-tcp", "multi-tcp", "udp-unicast", "udp-multicast", "rudp"

These monitoring events allow tracking of both transient and persistent properties of an NDI receiver. Additional properties will be supported in future SDK versions.

Receiver Commands

The NDIlib_recv_listener_send_connect function triggers the "connect" command to be sent from the listener to the receiver.

bool NDIlib_recv_listener_send_connect(NDIlib_recv_listener_instance_t p_instance, const char* p_receiver_uuid, const char* p_source_name);

Parameters:

• p_instance (NDIlib_recv_listener_instance_t): The instance of the receiver listener.

• p_receiver_uuid (const char*): The unique identifier (UUID) of the receiver.

• p_source_name (const char*): The name of the source to connect to. If an empty string is passed, it indicates that the receiver should disconnect from its current source.

This function returns true if successful i.e. it could establish a connection to the specified NDI source. The function would return false if the command could not be sent, the receiver is unknown, or another error occurred during the operation.

If the p_source_name parameter is NULL, it indicates that the receiver should disconnect from its current source. This function should only be called for a receiver that supports the NDIlib_receiver_command_connect command.

Example Code:

bool result = NDIlib_recv_listener_send_connect(p_instance, "receiver-uuid", "source- name");

if (result) {
    printf("Receiver successfully connected to the source.\n");
} else {
    printf("Failed to connect the receiver to the source.\n");
}

We recommend referring to the NDI Advanced SDK example code (NDIlib_Recv_Listener_Advanced), which offers a straightforward demonstration of how to implement these APIs effectively.