NDI Sender Event Monitoring

To provide deeper control over NDI sources, the Advanced SDK supplements the standard NDI Send Advertiser and NDI Send Listener APIs with a more powerful toolset. These advanced APIs unlock comprehensive event subscription any registered sender. This extension empowers developers to not only be aware of the sender but also to listen to a sender's real-time event (per request or by default). Such capabilities are fundamental for creating sophisticated NDI ecosystems, allowing for intricate control and real-time monitoring of all NDI sending sources.

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

• NDIlib_send_advertiser_create_ex

• NDIlib_send_listener_create_ex

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

Subscribing to Sender Events

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

void NDIlib_send_listener_subscribe_events(NDIlib_send_listener_instance_t p_instance, const char* p_sender_uuid);

This function requires the following parameters:

• p_instance: The sender listener instance (NDIlib_send_listener_instance_t).

• p_uuid: The unique identifier of the sender.

The sender’s UUID is part of the NDIlib_sender_t structure, which is generated by the SDK. You can retrieve the list of senders using the NDIlib_send_listener_get_senders function, which will provide the necessary UUID for each sender.

Unsubscribing from Sender Events

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

NDIlib_send_listener_unsubscribe_events(NDIlib_send_listener_instance_t p_instance, const char* p_sender_uuid);

This function requires the following parameters:

• p_instance: The sender listener instance (NDIlib_send_listener_instance_t).

• p_uuid: The unique identifier of the sender.

Example Code:

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

// Create an instance of the sender listener. 
NDIlib_send_listener_instance_t pNDI_sender_listener = NDIlib_send_listener_create_ex(nullptr, p_ndi_config); 
if (!pNDI_sender_listener) { 
    // Handle error 
} 

// Get the list of advertised senders. 
uint32_t num_senders = 0; 
const NDIlib_sender_t* p_senders = NDIlib_send_listener_get_senders(pNDI_send_listener, &num_senders); 

// Display the found senders. 
printf("Network senders (%u found).\n", num_senders); 
for (uint32_t i = 0; i < num_senders; i++) { 
printf("%u. %s\n", i + 1, p_senders[i].p_name); 

// If the sender is not currently subscribed, subscribe to it. 
if (!p_sender[i].events_subscribed) { 
        NDIlib_send_listener_subscribe_events(pNDI_send_listener, p_senders[i].p_uuid); 
    } 

// Perform operations with the subscribed sender... 
… 
// Unsubscribe from the sender after processing. 
   NDIlib_send_listener_unsubscribe_events(pNDI_send_listener, p_senders[i].p_uuid); 
} 

Sender Monitoring Events

The NDIlib_send_listener_get_events function allows you to fetch the list of monitoring events from the sender that you have previously subscribed to using the NDIlib_send_listener_subscribe_events function. It returns an array of NDIlib_send_listener_event structures containing the event details.

const NDIlib_send_listener_event*
NDIlib_send_listener_get_events(NDIlib_send_listener_instance_t p_instance, uint32_t* p_num_events, uint32_t timeout_in_ms); 

Parameters:

• p_instance (NDIlib_send_listener_instance_t): The instance of the sender 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_send_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_send_listener_free_events function.

Example Code:

uint32_t num_events; 
const NDIlib_send_listener_event* events = NDIlib_send_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_send_listener_free_events(events); 
} else { 
    printf("No events received within the timeout period.\n"); 
} 

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

Event Name	Description	Type	Example Event Values
source-name	Name of the NDI source.	string	“Camera 2”
source-url	Comma-delimited list of valid URLs for the NDI sender. It would be a list due to having multiple network interfaces being available on the system.	string	“ndi://192.168.1.11/Camera_2”
connection-state	Indicator as to whether the NDI sender has any connected NDI receivers or not. Values can be one of the following: connected disconnected	string	“connected”, “disconnected”
connected-receivers	The number of connected NDI receivers to this NDI sender.	int	“42”
metadata-frames-sent	Number of metadata frames sent by the NDI sender. This would be an aggregate across each NDI receiver that is actively connected.	int64	“1”
metadata-bytes-sent	Number of bytes sent for metadata frames. This would be an aggregate across each NDI receiver that is actively connected.	int64	“2048”
audio-present	Has audio been sent through this NDI sender?	bool	true, false
audio-codec	The audio codec in use. Values can be one of the following: pcm aac opus	string	“pcm”,”aac”,”opus”
audio-channels	The number of audio channels within the audio stream.	int	“8”
audio-sample-rate	The sample rate of the audio stream.	int	“44100”, “48000”
audio-frames-sent	Number of audio frames sent by the NDI sender. This would be an aggregate across each NDI receiver that is actively connected.	int64	“1976”
audio-bytes-sent	Number of bytes sent for audio frames. This would be an aggregate across each NDI receiver that is actively connected.	int64	“300001”
video-present	Has video been sent through this NDI sender?	bool	true, false
video-codec	The video codec in use. Values can be one of the following: shq0 shq2 shq7 h264 h265	string	“shq0”
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”, “30000/1001”
video-frame-type	The type of fielding format in use by the video stream. Values can be one of the following: progressive interlaced	string	“progressive”, “interlaced”
video-has-alpha	Does the video stream contain an alpha channel?	bool	true, false
video-color-primaries	Color primaries of the video stream. Values can be one of the following: bt_601 bt_709 bt_2020 bt_2100	string	“bt_601”, “bt_709”, “bt_2020”, “bt_2100”
video-transfer-function	Transfer function of the video stream. Values can be one of the following: bt_601 bt_709 bt_2020 bt_2100_hlg bt_2100_pq	string	“bt_601”, “bt_709”, “bt_2020”, “bt_2100_hlg”, “bt_2100_pq”
video-matrix-coefficients	Matrix coefficients of the video stream. Values can be one of the following: bt_601 bt_709 bt_2020 bt_2100	string	“bt_601”, “bt_709”, “bt_2020”, “bt_2100”
video-frames-sent	Number of video frames sent by the NDI sender. This would be an aggregate across each NDI receiver that is actively connected.	int64	“600”
video-bytes-sent	Number of bytes sent for video frames. This would be an aggregate across each NDI receiver that is actively connected.	int64	“450001”
sdk-version	Returns the NDI version for the sender.	string	6.3.0.0

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