NDI-Recv Discovery, Monitor, and Control
Updated as of Version 6.2
Last updated
Was this helpful?
Updated as of Version 6.2
Last updated
Was this helpful?
With NDI 6.2, the NDI SDK introduces a comprehensive set of APIs that enable the registration of NDI receivers for discovery, monitoring, and control when configured with the NDI Discovery Server. Previously, the NDI Discovery Server was solely responsible for NDI source discovery, detecting sources across the network. However, with this update, the discovery server's functionality has been extended to also support NDI receiver advertisement and discovery, allowing for advanced monitoring and control of NDI receivers. We have ensured the new Discovery Server is backward compatible with existing NDI sources. However, to fully utilize the new NDI receiver discovery, monitoring, and control features, you will need to use NDI 6.2.
Processing.NDI.RecvAdvertiser.h – Provides the API for advertising NDI receivers within the Discovery Service, ensuring they can be discovered by other systems.
Processing.NDI.RecvListener.h – Offers the API for retrieving a list of advertised receivers, enabling the monitoring of receiver events and the control of the sources connected to those receivers.These APIs provide a powerful method for discovering, monitoring, and controlling receivers in real time. The NDI Receiver Advertiser API and NDI Receiver Listener API are both included as part of the Standard SDK.
For more advanced functionality, the includes additional APIs, such as:
Receiver Event Subscription – For monitoring receiver events.
Command Requests – For controlling receivers by sending connection or disconnection commands to the sources they are connected to.
The full details of the Advanced APIs can be found in the manual under the section "NDI Recv Event Monitoring and Commands."
The NDIlib_recv_advertiser_create
function creates an instance of the receiver advertiser. This function returns an instance of type NDIlib_recv_advertiser_instance_t
(or NULL
if it fails), representing the receiver advertiser instance.
The function takes parameters defined by NDIlib_recv_advertiser_create_t
, as follows:
p_url_address (const char*)
This parameter represents the URL address of the NDI Discovery Server to connect to. If NULL
, the default NDI discovery server will be used. If no discovery server is available, the receiver advertiser will not be instantiated, and the create function will return NULL
. The format of this field is expected to be the hostname or IP address, optionally followed by a colon and a port number. If the port number is not specified, port 5959 will be used.
For example: 127.0.0.1:5959, 127.0.0.1, or hostname:5959. This field can also specify multiple addresses separated by commas for redundancy support.
Once the structure is filled out, NDIlib_recv_advertiser_create
will create an instance for you. The receiver advertiser instance is destroyed by passing it into NDIlib_recv_advertiser_destroy
.
To add your NDI receiver for advertising, call the following function:
This function adds the receiver to the list of receivers being advertised. It returns false if the receiver has been previously registered.
Parameters:
p_instance
: The receiver advertiser instance from the NDIlib_recv_advertiser_create
call.
p_receiver
: An already instantiated NDI receiver instance from the NDIlib_recv_create
call.
allow_controlling
: A flag to allow controlling of the receiver.
allow_monitoring
: A flag to allow monitoring of the receiver.
p_input_group_name
: An optional input group name for the receiver. This can be used to associate two separate receivers (e.g., a video receiver and an audio receiver) with a common input name.
To remove the receiver from the list of receivers being advertised, call the corresponding function:
This function returns false if the receiver was not previously advertised.
Example Code:
The following code illustrates how to add/register a receiver and remove it from the advertiser. Note: A full example is provided with the SDK that illustrates registering a receiver for advertisement (we will not reproduce that code here).
This example demonstrates the creation, registration, and destruction of an NDI receiver and its associated advertiser.
The NDIlib_recv_listener_create
function creates an instance of the receiver listener. This function returns an instance of type NDIlib_recv_listener_instance_t
(or NULL
if it fails), representing the receiver listener instance. The parameters of the structure NDIlib_recv_listener_instance_t
are documented below.
p_url_address (const char*)
This parameter represents the URL address of the NDI Discovery Server to connect to. If NULL, the default NDI discovery server will be used. If no discovery server is available, the receiver listener will not be instantiated, and the create function will return NULL. The format of this field is expected to be the hostname or IP address, optionally followed by a colon and a port number. If the port number is not specified, port 5959 will be used.
For example: 127.0.0.1:5959, 127.0.0.1, or hostname:5959. If this field is a comma-separated list, only the first address will be used.
Once the structure is filled out, NDIlib_recv_listener_create
will create an instance for you. The receiver listener instance can be destroyed by passing it into the NDIlib_recv_listener_destroy
function.
To check if the receiver listener is actively connected to the configured NDI Discovery server, call the following function:
bool NDIlib_recv_listener_is_connected(NDIlib_recv_listener_instance_t p_instance);
This function returns true if connected, otherwise false.
To retrieve the URL address of the NDI Discovery server that the receiver listener is connected to, call:
const char* NDIlib_recv_listener_get_server_url(NDIlib_recv_listener_instance_t p_instance);
This function returns NULL
if the receiver instance pointer is invalid.
To wait until the set of online receivers has changed, call
bool NDIlib_recv_listener_wait_for_receivers(NDIlib_recv_listener_instance_t p_instance, uint32_t timeout_in_ms);
This function takes a timeout in milliseconds. If a new receiver is found or removed before the timeout elapses, the function returns true immediately. If no new sources are seen before the timeout, it returns false.
Example Code:
The following code will create an NDI receiver listener instance and then retrieves the current list of advertised receivers that are registered with the NDI Receiver Advertiser API.
It uses the NDIlib_recv_listener_wait_for_receivers
to sleep until new receivers are found and, when they are seen, calls NDIlib_recv_listener_get_receivers
to get the current list of receivers:
The call to NDIlib_recv_listener_get_receivers
will give you a list of the advertised receivers. The returned structure NDIlib_receiver_t
is only valid until the next call to NDIlib_recv_listener_get_receivers
or until NDIlib_recv_listener_destroy
is called.
For a given NDIlib_recv_listener_instance_t
, do not call NDIlib_recv_listener_get_receivers
asynchronously.
The structure for NDIlib_receiver_t
is documented below, which describes a receiver that has been discovered.
p_uuid (const char*)
The unique identifier for the receiver on the network.
p_name (const char*)
The human-readable name of the receiver.
p_input_uuid (const char*)
The unique identifier for the input group that the receiver belongs to.
p_input_name (const char*)
The human-readable name of the input group that the receiver belongs to.
p_address (const char*)
The known IP address of the receiver.
p_streams (NDIlib_receiver_type_e*)
An array of streams that the receiver can receive from the source it's connected to. The last entry is NDIlib_receiver_type_none. Supported types: NDIlib_receiver_type_metadata
, NDIlib_receiver_type_video
, NDIlib_rec eiver_type_audio
, NDIlib_receiver_type_none
.
num_streams (uint32_t)
The number of elements in the p_streams
array, excluding the NDIlib_receiver_type_none
entry
p_commands (NDIlib_receiv er_command_e*)
An array of commands that the receiver can process. The last entry is NDIlib_receiver_command_none
. Supported commands: NDIlib_receiver_command_connect
, NDIlib_receiver_command_none
.
num_commands (uint32_t)
The number of elements in the p_commands
array, excluding the NDIlib_receiver_command_none
entry.
events_subscribed (bool)
Indicates whether the receiver is currently subscribed to receiving events.
We recommend reviewing the NDI SDK example code (NDIlib_Recv_Advertiser and NDIlib_Recv_Listener)
, which provides a simple illustration of how to implement these API’s.
For monitoring receiver events or controlling receivers, access to the Advanced SDK APIs is required. Refer to the section for more details.