The functions NDIlib_initialize and NDIlib_destroy can be called to initialize or de-initialize the library. Although never absolutely required, it is recommended that you call these (Internally, all objects are reference-counted; the libraries are initialized on the first object creation and destroyed on the last, so these calls are invoked implicitly.)

In the latest version of NDI on platforms where the application has permissions, it will attempt to configure the firewall settings for the application to allow it to perform video communication over NDI.

The only negative side-effect of this behavior is that more work will be done than is required if you repeatedly create and destroy a single object. These calls allow that to be avoided. There is no scenario under which these calls can cause a problem, even if you call NDIlib_destroy while you still have active objects. NDIlib_initialize will return false on an unsupported CPU.

At times you might prefer not to link directly against the NDI libraries, loading them dynamically at run time instead. This can be of value in Open-Source projects.

There is a structure that contains all the NDI entry points for a particular SDK version; calling a single entry point in the library will recover all these functions. The basic procedure is relatively simple, and an example is provided with the SDK.

Locating the Library

You can, of course, include the NDI runtime within your application folder. Alternatively, on Windows, you can install the NDI runtime and use an environment variable to locate it on disk. If you are unable to locate the library on disk, you may ask users to perform a download from a standardized URL. System dependent #defines are provided to make this a simple process:

• NDILIB_LIBRARY_NAME is a C #define to represent the dynamic library name (as, for example, the dynamic library Processing.NDI.Lib.x64.dll).

• NDILIB_REDIST_FOLDER is a C #define variable that references an environment variable to the installed NDI runtime library (for example, C:\Program Files\NDI\NDI 5 Runtime\).

On the Mac, it is not possible to specify global environment variables, and so there is no standard way for the application to specify a path. For this reason, the redistributable on MacOS is installed within /usr/local/lib. It is our intent to make the process of cross-platform loading of the run times easier for the next version of NDI.

Recovering the Function Pointers

Once you have located the library, you can look for a single exported function NDIlib_v5_load(). This function returns a structure of type NDIlib_v5 that gives you a reference to every NDI function.

Calling NDI Functions

Once you have a pointer to NDIlib_v5, you can replace every function with a simple new reference. For instance, to initialize a sender you can replace a call to NDIlib_find_create_v2 in the following way:

NDIlib_find_create_v2(...) becomes p_NDILib->NDIlib_find_create_v2(...)

To clarify which files may be distributed with your applications, the following are the files and the distribution terms under which they may be used for the SDK.

Header Files (NDI_SDK_DIR\INCLUDE\*.H)

These files may be distributed with open-source projects under the terms of the MIT license and may be included in open-source projects (see “Dynamic Loading” section for preferred mechanism). However, the requirements of these projects in terms of visual identification of NDI shall be as outlined within the License section above.

Binary Files (NDI_SDK_DIR\BIN\*.*)

You may distribute these files within your application if your EULA terms cover the specific requirements of the NDI SDK EULA, and your application covers the terms of the License section above.

❗Redistributables (NDI_SDK_DIR\REDIST\*.EXE)

You may distribute the NDI redistributable and install them within your own installer. However, you must make all reasonable efforts to keep the versions you distribute up to date. You may use the command line with /verysilent to install without any user intervention, but if you do, then you must ensure that the terms of the NDI license agreement are fully covered elsewhere in your application.

An alternative is to provide a user link to the NDI-provided download of this application at . At runtime, the location of the NDI runtime DLLs can be determined from the environment variable NDI_RUNTIME_DIR_V5.

❗Content Files (NDI_SDK_DIR\LOGOS\*.*)

You may distribute all files in this folder as you need and use them in any marketing, product, or web material.

Libraries

Components included in the SDK provide support for finding (find), receiving (recv), and sending (send). These share common structures and conventions to facilitate development and may all be used together.

NDI-SEND

This is used to send video, audio, and metadata over the network. You establish yourself as a named source on the network, and then anyone may see and use the media that you are providing.

Video can be sent at any resolution and framerate in RGB(+A) and YCbCr color spaces, and any number of receivers can connect to an individual NDI-Send.

NDI-FIND

This is used to locate all of the sources on the local network that are serving media capabilities for use with NDI.

NDI-RECEIVE

This allows you to take sources on the network and receive them. The SDK internally includes all the requisite codecs and handles all the complexities of reliably receiving high-performance network video.

Utilities

To make the library easy to use, the SDK includes several utilities that can be used to convert between common formats. For instance, conversion between different audio formats is provided as a service.

Command Line Tools

There are also several important command line tools within the SDK, including a discovery server implementation and a command line application that can be used for recording.

Our latest release brings an update to the NDI SDK terms, bringing these in line with our commitment to the health and growth of the NDI ecosystem. The NDI SDK remains royalty-free, subject to the SDK terms and conditions. For more details including a full explanation and updated list of exclusions please consult the terms and conditions by downloading the NDI 6.2.1 SDK.

These changes apply to the NDI SDK only and are not applicable to the NDI Advanced SDK.

You may use this SDK in accordance with its License Agreement, which is available for review in the root level of the SDK folder. Your use of any part of the SDK for any purpose is an acknowledgment that you agree to these license terms. For distribution, you must implement this SDK within your applications respecting the following requirements:

• Your application must provide a link to ndi.video in a location close to all locations where NDI is used/selected within the product, on your website, and in its documentation. This link will point to a landing page that provides information about NDI and access to the tools we provide, along with updates and news.

• You may not distribute the NDI tools; if you wish to make these accessible to your users, you may provide a link to .

• NDI is a registered trademark of Vizrt NDI AB and should be used only with the ® as follows: NDI®, along with the statement “NDI® is a registered trademark of Vizrt NDI AB” located on the same page near the mark where it is first used, or at the bottom of the page in footnotes. You are required to use the registered trademark designation only on the first use of the word NDI within a single document.

• Your application’s About Box and any other locations where trademark attribution is provided should also specifically indicate that “NDI® is a registered trademark of Vizrt NDI AB”. If you have questions, please do let us know.

• You should include the NDI DLLs as part of your own application and keep them in your application folders so that there is no chance that NDI DLLs installed by your application might conflict with other applications on the system that also use NDI. Please do not install your NDI DLLs into the system path for this reason. If you are distributing the NDI DLLs, you need to ensure that your application complies with the License Agreement, this section, and the license terms outlined in “3rd party rights” towards the end of this manual.

We are very interested in how our technology is being used and would like to maintain a full list of applications using NDI technology. Please let us know about your commercial application (or an interesting non-commercial one) using NDI by reaching out to the . If you have any questions, comments, or requests, please do not hesitate to let us know. Our goal is to provide you with this technology and encourage its use while ensuring that both end-users and developers enjoy a consistent high-quality experience.

This documentation is paramount for developers and integrators seeking to consistently embed the full potential of NDI technology into their products.

This comprehensive guide aims to provide a clear roadmap to understanding and implementing NDI within your applications, systems, and workflows. Whether you're a seasoned developer or a newcomer to NDI, it will empower you to seamlessly leverage the capabilities of NDI, enabling your products to seamlessly connect with other NDI-enabled products and transmit high-quality, low-latency video and audio over IP networks.

From setup and configuration to advanced usage scenarios, this SDK documentation is your go-to resource to unlock our connectivity tech, facilitating innovation and efficiency across a broad spectrum of applications.

This documentation is continuously updated to match the most recent version of our Core Technology. We now offer NDI 6.3 You can check the most meaningful updates in our

NDI Lib is heavily optimized (much of it is written in assembly). While it detects available architecture and uses the best path it can, the minimum required SIMD level is (introduced by Intel in 2005).

The NDI library running on ARM platforms requires NEON support. To the degree possible, hardware acceleration of streams uses GPU-based fixed function pipelines for decompression and is supported on Windows, macOS, iOS, and tvOS platforms; all GPUs on these platforms are supported with special case-optimized support for Intel QuickSync and nVidia.

However, this is not required, and we will always fall back to software-based compression and decompression.

The NDI SDK includes many examples including examples that show the sending, and receiving of data, finding sources, use of 10-bit video, and many more. To get you started check out the following articles.

If you have any problems or doubts about this documentation or any utilization of the SDK, please sign up on our , and we will do our best to support you.

The NDI libraries make minor use of other third-party libraries, for which we are very grateful to the authors. If you are distributing NDI DLLs yourself, it is important that your distribution is compliant with the licenses for these third-party libraries. For the sake of convenience, we have combined these licenses within a single file that you should include, Processing.NDI.Lib.Licenses.txt, which is included beside the NDI binary files.

The NDIlib_send_advertiser_create function creates an instance of the sender advertiser. This function returns an instance of type NDIlib_send_advertiser_create_t (or NULL if it fails), representing the sender advertiser instance.

The function takes parameters defined by NDIlib_send_advertiser_create_t, as follows:

Once the structure is filled out, NDIlib_send_advertiser_create will create an instance for you. The sender advertiser instance is destroyed by passing it into NDIlib_send_advertiser_destroy.

Adding a Sender for Advertising

To add your NDI sender for advertising, call the following function:

This function adds the sender to the list of senders being advertised. It returns false if the sender has been previously registered.

Parameters:

• p_instance: The sender advertiser instance from the NDIlib_send_advertiser_create call.

• p_sender: An already instantiated NDI sender instance from the NDIlib_send_create call.

Removing a Sender from Advertising

To remove the sender from the list of senders being advertised, call the corresponding function:

This function returns false if the sender was not previously advertised.

Example Code:

The following code illustrates how to add/register a sender and remove it from the advertiser. Note: A full example is provided with the SDK that illustrates registering a sender for advertisement (we will not reproduce that code here).

This example demonstrates the creation, registration, and destruction of an NDI sender and its associated advertiser.

NDI SDK v6 supports 16-bit data formats and standardizes metadata elements to specify wide gamut color primaries and HDR transfer functions, including HLG and PQ. This enables broadcasting high bit depth, wide color gamut, and high dynamic range video, with brightness up to 10000 nits when using the PQ transfer function.

The specific HDR capabilities available to your system will vary depending on your license and the SDK you use, as described next.

This is provided to locate sources available on the network and is normally used in conjunction with NDI-Receive. Internally, it uses a cross-process P2P mDNS implementation to locate sources on the network. (It commonly takes a few seconds to locate all the sources available since this requires other running machines to send response messages.)

Although discovery uses mDNS, the client is entirely self-contained; Bonjour (etc.) is not required. mDNS is a P2P system that exchanges located network sources and provides a highly robust and bandwidth-efficient way to perform discovery on a local network.

On mDNS initialization (often done using the NDI-FIND SDK), a few seconds might elapse before all sources on the network are located. Be aware that some network routers might block mDNS traffic between network segments.

The Windows version of the NDI SDK includes a DirectShow audio and video filter. This is particularly useful for people wishing to build simple tools and integrate NDI video into WPF applications.

Both x86 and x64 versions of this filter are included in the SDK. If you wish to use them, you must first register those filters using regsvr32. The SDK install will register these filters for you. The redistributable NDI installer will also install and register these filters, which can be downloaded by users here. You may, of course, include the filters in your own application installers under the terms of the NDI license agreement.

Once the filter is registered, you can instantiate it by using the GUID:

DEFINE_GUID(CLSID_NdiSourceFilter, 0x90f86efc, 0x87cf, 0x4097, 
            0x9f, 0xce, 0xc, 0x11, 0xd5, 0x73, 0xff, 0x8f);

The filter name is “NDI Source”. The filter presents audio and video pins you may connect to. Audio is supported in floating-point and 16-bit, and video is supported in UYVY and BGRA.

The filter can be added to a graph and will respond to the IFileSourceFilter interface. This takes “filenames” in the form ndi://computername/source. This will connect to the “source” on a particular “computer name“. For instance, to connect to an NDI source called “MyComputer (Video 1)”, you must escape the characters and use the following URL: ndi://MyComputer/Video+1

To receive just the video stream, use the audio=false option as follows:

NDI://computername/source?audio=false

Use the video=false option to receive just the audio stream, as in the example below:

NDI://computername/source?video=false

Additional options may be specified using the standard method to add to URLs, for example:

NDI://computername/source?low_quality=true NDI://computername/source?audio=false&low_quality=true&force_aspect=1.33333&rgb=true

Of course, all platforms are slightly different, and the location of configuration files and the settings can differ slightly between platforms. On all platforms, if there is an environment variable NDI_CONFIG_DIRset before initializing the SDK, then we will load the ndi-config.v1.json from this folder when the library is used.

Windows

The Windows platform is fully supported and provides high performance in all paths of NDI. As with all operating systems, the x64 version provides the best performance. All modern CPU feature sets are supported. Please note that the next major version of NDI will deprecate support for 32-bit Windows platforms.

We have found that on some computer systems, if you install "WireShark" to monitor network traffic, a virtual device driver called "NPCap Loopback Driver" installs can interfere with NDI, potentially causing it to fail to communicate. This is also a potential performance problem for networking since it is designed to intercept network traffic. This driver is not required or used by modern versions of Wireshark. If you find it is installed on your system, we recommend that you go to your network settings and use the context menu on the adapter to disable it.

The NDI Tools bundle for Windows includes “Access Manager”, a user interface for configuring most of the settings outlined above. These settings are also stored in C:\ProgramData\NDI\ndi-config.v1.json.

Windows UWP

Unfortunately, the Universal Windows Platform imposes significant restrictions that can negatively affect NDI, and about which you need to be aware. These are listed below.

• The UWP platform does not allow the receiving of network traffic from Localhost. This means that any sources on your local machine will not be able to be received by a UWP NDI receiver.

• The current Windows 10 UWP mDNS discovery library has a bug that will not correctly remove an advertisement from the network after the source is no longer available; this source will eventually “time out” on other finders; however, this might take a minute or two.

• Due to sandboxing, UWP applications cannot load external DLLs. This makes it unlikely that NDI|HX will work correctly.

MacOS

The Mac platform is fully supported and provides high performance in all paths of NDI. As with all operating systems, the x64 version provides the best performance. Reliable UDP support requires macOS 10.14 or later, which enables IPv6 socket properties; NDI will work on earlier versions, but Reliable UDP will not be used.

Because of recent changes made within macOS in regard to the signing of libraries, if you wish NDI HX version 1 to work within your applications, you should locate the options in XCode under “Targets->Signing & Capabilities” and ensure that the option “Hardened Runtime -> Disable Library Validation” is checked.

In iOS 14 and XCode 12, a new setting was introduced to enable support for mDNS and Bonjour. Under “Bonjour Services”, one should assign “Item 0” as being “_ndi._tcp.” in order for NDI discovery to operate correctly.

The configuration settings are stored in $HOME/.ndi/ndi-config.v1.json.

Android

Because Android handles discovery differently than other NDI platforms, some additional work is needed. The NDI library requires the use of the “NsdManager” from Android, and there is no way for a third-party library to do this on its own. As long as an NDI sender, finder, or receiver is instantiated, an instance of the NsdManager will need to exist to ensure that Android’s Network Service Discovery Manager is running and available to NDI.

This is normally done by adding the following code to the beginning of your long-running activities:

private NsdManager m_nsdManager;

At some point before creating an NDI sender, finder, or receiver, instantiate the NsdManager:

m_nsdManager = (NsdManager)getSystemService(Context.NSD_SERVICE);

You will also need to ensure that your application is configured to have the correct privileges required for this functionality to operate.

iOS

iOS supports NDI finding, sending, and receiving.

In iOS 14 and XCode 12, a new setting was introduced to enable support for mDNS and Bonjour. Under “Bonjour Services”, one should assign “Item 0” as being “_ndi._tcp.” In order for NDI discovery to operate correctly. It is also required to enable networking in the App sandbox settings.

The configuration settings are stored in $HOME/.ndi/ndi-config.v1.json.

Linux

The Linux version is fully supported and provides high performance in all paths of NDI. The NDI library on Linux depends on two 3rd party libraries:

libavahi-common.so.3

libavahi-client.so.3

The usage of these libraries depends on the avahi-daemon service to be installed and running.

The configuration settings are stored in $HOME/.ndi/ndi-config.v1.json.

Using NDI routing, you can create an output on a machine that looks just like a ‘real’ video source to all remote systems. However, rather than producing actual video frames, it directs sources watching this output to receive video from a different location.

For instance: if you have two NDI video sources - Video Source 1 and Video Source 2 – you can create an NDI_router called Video Routing 1 and direct it at Video Source 1. Video Routing 1 will be visible to any NDI receivers on the network as an available video source. When receivers connect to “Video Routing 1”, the data they receive will actually be from “Video Source 1”.

NDI routing does not actually transfer any data through the computer hosting the routing source; it merely instructs receivers to look at another location when they wish to receive data from the router. Thus, a computer can act as a router exposing potentially hundreds of routing sources to the network – without any bandwidth overhead. This facility can be used for large-scale dynamic switching of sources at a network level.

The NDIlib_send_listener_create function creates an instance of the sender listener. This function returns an instance of type NDIlib_send_listener_instance_t (or NULL if it fails), representing the sender listener instance. The parameters of the structure NDIlib_send_listener_instance_t are documented below.

Once the structure is filled out, NDIlib_send_listener_create will create an instance for you. The sender listener instance can be destroyed by passing it into the NDIlib_send_listener_destroy function.

Key Functions:

Check Listener Connection Status

To check if the sender listener is actively connected to the configured NDI Discovery server, call the following function:

bool NDIlib_send_listener_is_connected(NDIlib_send_listener_instance_t p_instance);

This function returns true if connected, otherwise false.

Retrieve Server URL

To retrieve the URL address of the NDI Discovery server that the sender listener is connected to, call:

const char* NDIlib_send_listener_get_server_url(NDIlib_recv_listener_instance_t p_instance);

This function returns NULL if the sender instance pointer is invalid.

Wait for Senders

To wait until the set of online senders has changed, call

bool NDIlib_send_listener_wait_for_senders(NDIlib_send_listener_instance_t p_instance, uint32_t timeout_in_ms);

This function takes a timeout in milliseconds. If a new sender is found or removed before the timeout elapses, the function returns true immediately. If no new senders are seen before the timeout, it returns false.

Example Code:

The following code will create an NDI sender listener instance and then retrieves the current list of advertised senders that are registered with the NDI Sender Advertiser API.

It uses the NDIlib_send_listener_wait_for_senders to sleep until new senders are found and, when they are seen, calls NDIlib_send_listener_get_senders to get the current list of senders:

The call to NDIlib_send_listener_get_senders will give you a list of the advertised senders. The returned structure NDIlib_sender_t is only valid until the next call to NDIlib_send_listener_get_senders or until NDIlib_send_listener_destroy is called.

For a given NDIlib_send_listener_instance_t, do not call NDIlib_send_listener_get_senders asynchronously.

Sender Information Structure

The structure for NDIlib_sender_t is documented below, which describes a sender that has been discovered.

We recommend reviewing the NDI SDK example code (NDIlib_Send_Advertiser and NDIlib_Send_Listener), which provides a simple illustration of how to implement these API’s.

The NDI configuration settings are stored in JSON files. The location of these files varies per platform and is described in the next section of the manual.

Please pay extra attention to the value types, as it is important that these match what is listed here (e.g., true rather than “true”). Also, please note that all these parameters have default values that are the recommended best configuration for most machines; we only suggest you change these values if there is a very specific need for your installation.

Introduction

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.

The NDI SDK now includes two additional header files:

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."

NDI RECV Advertiser

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:

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.

Adding a Receiver for Advertising

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.

Removing a Receiver from Advertising

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.

NDI RECV Listener

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.

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.

Key Functions:

Check Connection Status

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.

Retrieve Server URL

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.

Wait for Receivers

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.

Receiver Information Structure

The structure for NDIlib_receiver_t is documented below, which describes a receiver that has been discovered.

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.

Upgrading Your Applications

The libraries (DLLs) for the latest version of NDI should be entirely backward compatible with NDI v4 and, to the degree possible, even earlier versions. In many cases, you should be able to simply update these in your application to get most of the benefits of the new version – without a single code change.

NDI 6.3 expands the NDI SDK by introducing APIs for registering NDI senders, mirroring the functionality already available for receivers (added in version 6.2). These APIs enable sender discovery and monitoring when used with the NDI Discovery Server. This new method does not break compatibility with the original sender advertising system (which we refer to as legacy senders advertisement); both will coexist. The key advantage of the new source advertisers is that they allow a listener to monitor most of their events and properties, a capability unavailable with the legacy method.

The NDI SDK now includes two additional header files:

• Processing.NDI.SendAdvertiser.h – Provides the API for advertising NDI senders within the Discovery Service, ensuring they can be discovered by other systems.

• Processing.NDI.SendListener.h – Offers the API for retrieving a list of advertised senders, enabling the monitoring of sender events.

These APIs provide a powerful method for discovering, monitoring senders in real time. The NDI Sender Advertiser API and NDI Sender Listener API are both included as part of the Standard SDK.

For more advanced functionality, the Advanced SDK includes additional APIs, such as:

• Sender Event Subscription – For monitoring sender events.

The full details of the Advanced APIs can be found in the manual under the section NDI Sender Event Monitoring

Recording

A full cross-platform native NDI recording is provided in the SDK. This is provided as a command-line application in order to allow it to be integrated into both end-user applications and scripted environments. All input and output from this application is provided over stdin and stdout, allowing you to read and/or write to these in order to control the recorder.

The NDI recording application implements most of the complex components of file recording and may be included in your applications under the SDK license. The functionality provided by the NDI recorder is as follows:

• Record any NDI source. For full-bandwidth NDI sources, no video recompression is performed. The stream is taken from the network and simply stored on disk, meaning that a single machine will take almost no CPU usage in order to record streams. File writing uses asynchronous block file writing, which should mean that the only limitation on the number of recorded channels is the bandwidth of your disk sub-system and the efficiency of the system network and disk device drivers.

• All sources are synchronized. The recorder will time-base correct all recordings to lock to the current system clock. This is designed so that if you are recording a large number of NDI sources, the resulting files are entirely synchronized with each other. Because the files are written with timecode, they may then be used in a nonlinear editor without any additional work required for multi-angle or multi-source synchronization.

Recording is implemented as a stand-alone executable, which allows it either to be used in your own scripting environments (both locally and remotely), or called from an application. The application is designed to take commands in a structured form from stdin and put feedback out onto stdout.

Command Line Arguments

The primary use of the application would be to run it and specify the NDI source name and the destination file- name. For instance, if you wished to record a source called My Machine (Source 1) into a file C:\Temp\A.mov. The command line to record this would be:

"NDI Record.exe" –I "My Machine (Source 1)" –o "C:\Temp\A.mov"

This would then start recording when this source has first provided audio and video (both are required in order to determine the format needed in the file). Additional command line options are listed below:

Once running, the application can be interacted with by taking input on stdin, and will provide response onto stdout. These are outlined below.

If you wish to quit the application, the preferred mechanism is described in the input settings section. However, one may also press CTRL+C to signal an exit, and the file will be correctly closed. If you kill the recorder process while it is running, the resulting file will be invalid since QuickTime files require an index at the end of the file. The Windows version of the application will also monitor its launching parent process; if that should exit, it will correctly close the file and exit.

Input Settings

While this application is running, a number of commands can be sent to stdin. These are all in XML format and can control the current recording settings. These are outlined as follows.

Output Settings

Output from NDI recording is provided onto stdout. The application will place all non-output settings onto stderr , allowing a listening application to distinguish between feedback and notification messages. For example, in the run log below, different colors are used to highlight what is placed on stderr (blue) and stdout (green).

Once recording starts, it will put out an XML message specifying the filename for the recording and provide you with the framerate.

It then gives you the timecode for each recorded frame and the current audio level in decibels (if the audio is silent, then the dB level will be -inf). If a recording stops, it will give you the final timecode written into the file. Timecodes are specified as UTC time since the Unix Epoch (1/1/1970 00:00) with 100 ns precision.

Error Handling

A number of different events can cause recording errors. The most common is when the drive system that you are recording to is too slow to record the video data being stored on it, or the seek times to write multiple streams end up dominating the performance (note that we do use block writers to avoid this as much as possible).

The recorder is designed to never drop frames in a file; however, when it cannot write to disk sufficiently fast, it will internally “buffer” the compressed video until it has fallen about two seconds behind what can be written to disk. Thus, temporary disk or connection performance issues do not damage the recording.

Once a true error is detected, it will issue a record-error command as follows:

[14:20:24.344]: <record_error error="The error message goes here."/>

If the option for autochop is enabled, the recorder will start attempting to write a new file. This process ensures that each file always has all frames without drops, but if data needs to be dropped because of insufficient disk performance, that data will be missing between files.

Discovery Service

In modern networked media workflows, efficient discovery and management of NDI audio and video sources are critical. The NDI Discovery Service is a dedicated server and protocol designed to replace automatic mDNS-based discovery with a centralized registry for NDI sources and receivers. This approach is particularly beneficial in environments where reducing network traffic is essential or where multicast is not possible or desirable.

The Discovery Service can operate as a remote server-based service or a local application, accepting connections from senders, finders, and receivers. It facilitates seamless device visibility, real-time status updates, and low-latency connections with minimal configuration. NDI 6.2 expands the functionality of the Discovery Service beyond simple source advertising and listing, introducing new capabilities for discovery, monitoring, and control of NDI receivers, enhancing real-time interaction and management.

To support seamless integration with third-party applications, the NDI SDK provides a new set of APIs that allow developers to directly interact with the Discovery Service. These APIs enable querying available sources, subscribing to real-time updates, and efficiently managing connections, ensuring broad interoperability across diverse applications and workflows.

The full details of these APIs can be found in the manual under the section .

By offering a robust alternative to mDNS, the NDI Discovery Service significantly reduces network traffic while maintaining full support for essential NDI features, including NDI Groups.

Server

The NDI Discovery Service can be deployed either as an application by running Bin\Utilities\x64\NDI Discovery Service.exe or as a system service named NDI Discovery Service, offering flexibility for diverse deployment scenarios across different platforms. Both 32-bit and 64-bit versions are available, with the 64-bit version recommended for optimal performance. While the service uses minimal CPU resources, it may require additional RAM and generate network traffic when managing a large number of connections, such as sources, receiver listeners, and receiver advertisers, to effectively coordinate and update source lists.

The NDI Discovery Service is also available as a standalone installer for both Windows and Linux. You can download the respective installers by visiting the website.

Clients

Clients should be configured to connect with the discovery server instead of using mDNS to locate sources. When there is a discovery server, the SDK will use both mDNS and the discovery server for finding and receiving to locate sources on the local network that are not on machines configured to use discovery.

For senders, if a discovery service is specified, that mDNS will not be used; these sources will only be visible to other finders and receivers that are configured to use the discovery server.

Configuration

To configure the discovery server for NDI clients, you can use Access Manager (included in the ) to enter the IP address of the discovery server machine or utilize the NDI Discovery tool, both of which are included in the NDI Tools bundle. The NDI Discovery tool is a new addition to the NDI Tools suite and is available on both Windows and macOS platforms.

Command Line Options

Usage:

"NDI Discovery Service.exe" -bind <ip-address> -port <port_number> -config <json path> - help

It is possible to run the Discovery server with a command line option that specifies which NIC is operating from with:

DiscoveryServer.exe -bind 192.168.1.100

This will ask the discovery server to only advertise on the IP address specified. Likewise, it is possible to specify a port number that will be used for the discovery server using:

DiscoveryServer.exe -port 5400

This allows you to work on a non-default port number or run multiple discovery servers for multiple groups of sources on a single machine. If a port of 0 is specified, then a port number is selected by the operating system and will be displayed at run-time.

General Options (Windows & Linux):

• -bind <ip_address> : This is an optional argument that specifies the IP address to bind the service to (default: 0.0.0.0).

• -port <port_number> : This is an optional argument that sets the port number (default: 5959).

• -config <json path> : This is an optional argument that loads configuration from a JSON file. This option will override both -bind and -port options as it will take precedence

Linux/Unix-Specific Option

• -service : This will run the NDI Discovery in service mode for background execution.

JSON configuration file:

The default paths for the configuration file are:

• Linux:

  • /etc/ndi/ndi-discovery-service.v1.json

  • /usr/local/etc/ndi/ndi-discovery-service.v1.json

An example of the JSON configuration file can be seen below:

Running as a service

On Windows, you can register and manage the NDI Discovery Service as a Windows service using the following command-line options:

• “NDI Discovery Service.exe” install : Installs or reinstalls the service.

• “NDI Discovery Sevice.exe” remove : Uninstalls the service.

• “NDI Discovery Service.exe” start : Starts the service.

These commands should be executed from the command prompt with administrative privileges to properly install, start, or remove the service.

On Linux, to run the NDI Discovery Service as a service, you can utilize systemd or init.d for management. The standalone version of the Discovery server for Linux includes template scripts along with comprehensive documentation. After configuring the scripts, you can launch the NDI Discovery Service in service mode using the following command-line options.

• “NDI Discovery Service.exe” -service : Runs the NDI Discovery in service mode for background execution.

NDI Benchmark

To help gauge your machine performance for NDI, a tool is provided that will initiate one NDI stream per core on your system and measure how many 1080p streams can be decoded in real-time. Note that this number reflects the best-case performance and is designed to exclude any impact of networking and only gauge the system CPU performance.

This can be used to compare performance across machines, and because NDI is highly optimized on all platforms, it is a good measure of the total CPU performance that is possible when all reasonable opportunity is taken to achieve high performance on a typical system. For instance, on Windows, NDI will use all extended vector instructions (SSSE3 and up, including VEX instructions), while on ARM, it will use NEON instructions when possible.

Each NDI connection will require one more port number. Current versions try for these to be in a predictable port range, although if some of this range is taken by other applications, it might need to use higher numbers. The following table describes the used port numbers, their types, and their purpose.

It is recommended that you use the connection types that are the default for the current version of NDI since these represent the best recommendations that we have tested and observed to yield the best performance in the field. Earlier versions of NDI might use ports in the ephemeral range, although modern versions of NDI no longer use these to ensure that the port numbers are more predictable and easier to configure in.

A call to NDIlib_send_create will create an instance of the sender. This will return an instance of the type NDIlib_send_instance_t (or NULL if it fails) representing the sending instance.

Parameters

The set of creation parameters applied to the sender is specified by filling out a structure called NDIlib_send_create_t

Video Frames (NDILIB_VIDEO_FRAME_V2_T)

When running in a YUV color space, the following standards are applied:

For the sake of compatibility with standard system components, Windows APIs expose 8-bit UYVY and RGBA video (common FourCCs used in all media applications).

This is, in fact, the case for every modern format, but does create a problem for two specific older video formats as discussed below:

NTSC 486 Lines

The best way to handle this format is simply to offset the image vertically by one line (p_uyvy_data + uyvy_stride_in_bytes) and reduce the vertical resolution to 480 lines. This can all be done without modification of the data being passed in at all; simply change the data and resolution pointers.

DV NTSC

This format is a relatively rare these days, although still used from time to time. There is no entirely trivial way to handle this other than to move the image down one line and add a black line at the bottom.

Audio Frames (NDILIB_AUDIO_FRAME_V3_T)

NDI Audio is passed to the SDK in floating-point and has a dynamic range without practical limits (without clipping). To define how floating-point values map into real-world audio levels, a sinewave that is 2.0 floating-point units peak-to-peak (i.e., -1.0 to +1.0) is assumed to represent an audio level of +4 dBU, corresponding to a nominal level of 1.228 V RMS.

Two tables are provided below that explain the relationship between NDI audio values for the SMPTE and EBU audio standards.

SMPTE Audio levels - reference Level

If you want a simple ‘recipe’ that matches SDI audio levels based on the SMPTE audio standard, you will want to have 20 dB of headroom above the SMPTE reference level at +4 dBu, which is at +0 dBVU, to correspond to a level of 1.0 in NDI floating-point audio. Conversion from floating-point to integer audio would thus be performed with:

int smpte_sample_16bit = max(-32768, min(32767, (int)(3276.8f*smpte_sample_fp)));

EBU Audio levels - reference Level

If you want a simple ‘recipe’ that matches SDI audio levels based on the EBU audio standard, you will want to have 18 dB of headroom above the EBU reference level at 0 dBu (i.e., 14 dB above the SMPTE/NDI reference level). Conversion from floating-point to integer audio would thus be performed with:

int ebu_sample_16bit = max(-32768, min(32767, (int)(6540.52f*ebu_sample_fp)));

Because many applications provide interleaved 16-bit audio, the NDI library includes utility functions that will convert in and out of floating-point formats from PCM 16-bit formats.

There is also a utility function for sending signed 16-bit audio using NDIlib_util_send_send_audio_interleaved_16s. Please refer to the example projects and the header file Processing.NDI.utilities.h, which lists the available functions.

In general, we recommend the use of floating-point audio since clamping is not possible, and audio levels are well-defined without a need to consider audio headroom.

The audio sample structure is defined as described below.

Metadata Frames (NDILIB_METADATA_FRAME_T)

Metadata is specified as NULL-terminated UTF-8 XML data. The reason for this choice is so that the format can naturally be extended by anyone using it to represent data of any type and length.

XML is also naturally backward and forward compatible because any implementation would happily ignore tags or parameters that are not understood (which, in turn, means that devices should naturally work with each other without requiring a rigid set of data parsing and standard complex data structures).

If you wish to put your own vendor specific metadata into fields, please use XML namespaces. The “NDI” XML namespace is reserved.

If you want specific metadata flags to be standardized, please contact us.

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:

The NDI Receive SDK is how frames are received over the network. It is important to be aware that it can connect to sources and remain “connected” to them even when they are no longer available on the network; it will automatically reconnect if the source becomes available again.