# 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: {% code overflow="wrap" %} ``` // 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); } ``` {% endcode %} ## 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. {% code overflow="wrap" %} ``` 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); ``` {% endcode %} **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”
tally-on-programIs this NDI sender on program?booltrue, false
tally-on-previewIs this NDI sender on preview?booltrue, false
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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ndi.video/all/developing-with-ndi/sdk/ndi-sender-discovery-and-monitor/ndi-sender-event-monitoring.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.