LogoLogo
🛠️ Tools🗂️ SDK📄 White Paper
  • Getting Started
    • 🟣What is NDI?
    • 🆕Release Notes
    • 📄White Paper
      • Discovery & Registration
        • mDNS
        • Discovery Service
        • Manual Connection
        • NDI Groups
      • NDI Protocols
        • Reliable UDP - NDI 5
        • Multipath TCP - NDI 4
        • UDP with Forward Error Correction – NDI 3
        • Single TCP – NDI 1
      • NDI Related Network Ports
      • Getting video across the network
      • Network Layout
      • Bandwidth
        • NDI High Bandwidth based on SpeedHQ2 (8bit 4:2:2)
        • NDI High Bandwidth based on SpeedHQ7 (8bit 4:2:2:4)
        • NDI HX2 h.264 (8bit 4:2:0)
        • NDI HX2 h.265 (8bit 4:2:0)
        • NDI HX3 h.264 (8bit 4:2:0)
        • NDI HX3 h.265 (8bit 4:2:0)
        • NDI Proxy and bandwidth optimization
      • Network Interface Settings
      • NIC Selection
      • Encoding and Decoding
      • Multicast
      • NDI Administrative Settings
      • Synchronization
      • NDI in the Cloud
    • Glossary
      • NDI Terminology
      • Industry Terminology
  • Using NDI
    • Introduction
    • NDI for Video
      • Digital Video Basics
      • NDI Video Codecs and Format Matrix
      • NDI Encoding Support Matrix
        • Practical NDI Receivers Format Support
        • Practical NDI Transmitters Support
        • Summary Table
      • Interoperability Scenarios
    • NDI for Audio
      • Digital Audio Fundamentals
      • Audio Over IP
      • Technical Facts About NDI for Audio
      • Use Cases
      • Products Using NDI for Audio
    • ⚒️NDI Tools
      • Release Notes
      • Installing NDI Tools
        • Software License Agreement
        • Privacy Policy
      • NDI Tools Launcher
      • NDI Tools for Windows
        • Access Manager
        • Bridge
          • NDI Bridge automation
          • Configuring Port Forwarding
          • Bridge Tool Logging
        • Remote
        • Router
        • Screen Capture
        • Screen Capture HX
        • Studio Monitor
        • Test Patterns
        • Webcam Input
        • Discovery
          • Getting Started with Discovery
          • Discovery Server Additional Information
      • NDI Tools for Mac
        • Access Manager
        • Scan Converter
        • Router
        • Test Patterns
        • Video Monitor
        • Virtual Input
        • Discovery
          • Getting Started with Discovery Service
          • Discovery Server Additional Information
          • Launch Discovery Server using Command Line for MacOS
      • Plugins
        • NDI for After Effects
        • NDI for Premiere Pro
        • NDI Output for Final Cut Pro
        • NDI for VLC
        • Audio Direct
        • OBS
    • Utilities
      • Analysis
    • Using NDI with Software
      • Getting Started with NDI in OBS for Windows or Mac
      • Using OBS Studio as a Commentary System
      • Using NDI Tools as a virtual camera in Mac
      • Using NDI and Dante on the same Network
      • Use OBS video + audio on Zoom with macOS
    • Using NDI with Hardware
      • NDI HX upgrades for cameras
      • How to Activate Panasonic Cameras for NDI HX1 — Step-by-Step
      • Recommended Network Switch Settings for NDI
  • Developing with NDI
    • Introduction
    • 📂SDK
      • Release Notes
      • Licensing
      • Software Distribution
        • Header Files
        • Binary Files
        • Redistributables
        • Content Files
        • Libraries
        • NDI-SEND
        • NDI-FIND
        • NDI-RECEIVE
        • Utilities
        • Command Line Tools
      • CPU Requirements
      • Dynamic Loading of NDI Libraries
      • Performance and Implementation
      • Startup and Shutdown
      • Example Code
      • Port Numbers
      • 🔧Configuration Files
      • Platform Considerations
      • NDI-SEND
      • NDI-FIND
      • NDI-RECV
      • NDI-Recv Discovery, Monitor, and Control
      • NDI Routing
      • HDR
      • Command Line Tools
      • Frame Types
        • Video Frames
        • Audio Frames
        • Metadata Frames
      • Windows DirectShow Filter
      • 3rd Party Rights
      • Support
    • Advanced SDK
      • Release Notes
      • Licensing
      • Overview
      • Configuration Files
      • NDI SDK Review
        • Sending
          • Asynchronous Sending Completions
          • NDI Sending On High Latency Connections
        • Receiving
          • Custom Allocators
            • Video Allocators
            • Audio Allocators
          • Dynamic Bandwidth Adjustment
          • NDI RECV Event Monitoring and Commands
        • Finding
        • Video Formats
          • Receiver Codec Support Level
          • Frame Synchronization
      • Genlock
      • AV Sync
        • Guidelines
        • Creating and Destroying Devices
        • Recovering Audio
      • Using H.264, H.265, and AAC Codecs
        • Sending Audio Frames
        • Sending Video Frames
        • H.264 Support
        • H.265 Support
        • AAC Support
        • OPUS Support
        • Latency of Compressed Streams
        • Stream Validation
      • External Tally Support
      • KVM Support
      • NDI Advanced SDK FPGA Example Designs
        • Prebuilt uSD Images
        • NDI FPGA Reference Design
          • FPGA Projects
            • Changelog
          • C++ Application Code
            • Changelog
          • linux_kernel
            • Changelog
          • uSD Image Builder
            • Changelog
        • Changelog
    • Utilities
      • Unreal Engine SDK
        • Release Notes
        • Licensing
        • NDI Plugin Installation
        • Simple Setup of Broadcast and Receivers
        • NDI Broadcast Actor
        • NDI Receiver Actor
        • NDI Media Assets
        • Getting Started with Example Blueprint Projects
        • Advanced
      • Free Audio
      • Bridge Service
        • Installation
          • Silent Installation
        • Configuration
          • Web UI
          • Configuration File
          • Manual API Key Management
        • Webhooks
        • WebSockets
        • API
    • NDI Certified
      • Certification Guidelines
        • Interoperability Requirements
        • Technical Requirements
      • Certification Process
        • Pre-certification Checklist
        • Device Testing Methods
          • Camera
          • HDMI Encoder
          • SDI Encoder
          • Decoder
          • NDI Controller
          • NDI Monitor
          • Multicast Testing
        • Detailed process
    • Metadata
      • Metadata Sources
      • Metadata for XML
      • XML Validation
      • Metadata Elements
      • Proposed New Metadata Messages
      • PTZ and Control Messages
      • Undocumented Mysteries
  • Developer Guides
    • Decoding with NDI
    • NDI Bridge Deployment
    • Receiver Discoverability, Monitoring, and Control Overview
  • FAQ
    • Index
    • NDI Tools
      • What is the NDI Analysis Tool and where do I get it from?
      • Why does my NDI connection stay active once the source is offline?
      • Why are my changes to the NDI JSON configuration file not being saved?
      • Why is the license for my Panasonic camera not active?
      • How does registration for NDI Tools work?
      • The time code on my file is incorrect, how do I change it?
      • How can I make NDI Tools launch automatically?
      • What is the NDI ECCN?
      • How Do I Uninstall NDI Software?
      • Does Discovery Server support Command Line on MacOS?
      • How do I use NDI output with Microsoft Teams
      • Where is Screen Capture (HX) for Mac?
    • NDI Certified
      • What is the NDI Certification Program?
      • Why did you start this certification program?​
      • What happens to my device after it's certified?
      • Is certification mandatory to be a partner of NDI?​
      • I am an OEM manufacturer, can my products be certified?​
      • How long does the certification process take?
      • How do I become certified?​
      • What happens if my product doesn’t meet the requirements for Certification?​
      • Are there any fees to become NDI Certified?
    • Common Issues
      • I'm having trouble getting multicast set up.
      • I'm having trouble with my NDI HX License
      • Why can't I find my Android 14-based NDI devices on my network?
      • Why won’t NDI Tools install on my Windows PC?
      • How do I enable NDI in “New” Microsoft Teams (Windows only)?
      • Why can’t HX Capture display the full resolution of my iPad or iPhone?
      • The NDI HX Camera app won't launch on older phones and iOS
      • Why won't MacOS Sonoma (14.1) recognize NDI Tools as a virtual camera?
      • I'm having issues with Virtual Input for macOS
      • I'm having issues with Final Cut Pro
      • NDI Camera App Issue
    • SDK
      • Where can I find the source code for the FPGA board?
      • What system resources are required to support a design including the NDI FPGA Codecs?
      • Why can’t my h264/265 video be received by an NDI receiver when using the embedded SDK?
      • I haven't received the email with the download.
      • Can I use the Unreal SDK on Mac?
      • What are the Differences Between the NDI SDK and the NDI Advanced SDK
    • ✨NDI 6
      • Do I need to upgrade to NDI 6 if I'm not using the new features?
      • Is there a fee to upgrade to NDI 6
      • Why doesn't my existing Vendor ID work with NDI 6?
      • How can I get a previous version of NDI Tools or the SDK?
    • NDI HX License Upgrades
      • What is happening with NDI HX Upgrades?
      • Will my existing HX-upgraded camera be affected?
      • I bought a camera before June 30, 2025, but didn't buy an HX license. Can I still get one?
      • I bought a license and a camera but didn't redeem it until after. Can I still get an HX license?
      • If my HX upgrade fails can I transfer the license?
      • Can I sell my upgraded HX camera and keep the license?
      • Will my NDI version work with my current HX license?
      • What does the HX upgrade sunset program mean for camera manufacturers?
      • What will NDI Support do for licenses after the sunset date?
      • I factory reset my camera and forgot the license. Can you help me get it back?
Powered by GitBook

2024 @ NDI Vizrt AB.

On this page
  • Introduction
  • NDI RECV Advertiser
  • Adding a Receiver for Advertising
  • Removing a Receiver from Advertising
  • NDI RECV Listener
  • Key Functions:
  • Check Connection Status
  • Retrieve Server URL
  • Wait for Receivers
  • Receiver Information Structure

Was this helpful?

Export as PDF
  1. Developing with NDI
  2. SDK

NDI-Recv Discovery, Monitor, and Control

Updated as of Version 6.2

PreviousNDI-RECVNextNDI Routing

Last updated 1 day ago

Was this helpful?

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:

Parameter
Description

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.

Adding a Receiver for Advertising

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

bool NDIlib_recv_advertiser_add_receiver( 
    NDIlib_recv_advertiser_instance_t p_instance, 
    NDIlib_recv_instance_t p_receiver,
    bool allow_controlling, bool allow_monitoring,
    const char* p_input_group_name NDILIB_CPP_DEFAULT_VALUE(NULL)
);

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.

Removing a Receiver from Advertising

To remove the receiver from the list of receivers being advertised, call the corresponding function:

bool NDIlib_recv_advertiser_del_receiver( 
    NDIlib_recv_advertiser_instance_t p_instance, 
    NDIlib_recv_instance_t p_receiver
);

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

// Create an unconnected receiver that will be set up for advertising. NDIlib_recv_instance_t pNDI_recv = NDIlib_recv_create_v3();
if (!pNDI_recv) {
 // Handle error
}
 
// Create an instance of the receiver advertiser
NDIlib_recv_advertiser_instance_t pNDI_recv_advertiser = NDIlib_recv_advertiser_create(); 
if (!pNDI_recv_advertiser) {
 // Handle error
}
 
// Register the receiver with the advertiser
NDIlib_recv_advertiser_add_receiver(pNDI_recv_advertiser, pNDI_recv, true, true);
 
// Do stuff
...
 
// Remove the receiver from the advertiser before destroying it
NDIlib_recv_advertiser_del_receiver(pNDI_recv_advertiser, pNDI_recv);
 
// Destroy the receiver advertiser NDIlib_recv_advertiser_destroy(pNDI_recv_advertiser);
 
// Destroy the receiver NDIlib_recv_destroy(pNDI_recv);

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.

Parameter
Description

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.

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:

// Create the descriptor of the object to create 
NDIlib_recv_listener_create_t listener_create;
 
// The URL address of the discovery server to connect to 
listener_create.p_url_address = "127.0.0.1";
 
// Create an instance of the receiver listener

NDIlib_recv_listener_instance_t pNDI_recv_listener = NDIlib_recv_listener_create(&listener_create);
if (!pNDI_recv_listener) { return 0; // Handle error
}
 
// To remember the last connected state 
bool last_connected = false;
 
while (true) { // You would not loop forever in a real application!
 // Check if the listener is currently connected
 bool curr_connected = NDIlib_recv_listener_is_connected(pNDI_recv_listener);
 
 // Has the connection state changed?
 if (last_connected != curr_connected) {
  printf("The listener is now %s.\n", curr_connected ? "connected" : "disconnected");
  last_connected = curr_connected;
}
 
// Wait up to 5 seconds to check for new receivers
if (!NDIlib_recv_listener_wait_for_receivers(pNDI_recv_listener, 5000)) {
  // No new receivers added
  printf("No change to the receivers found.\n");
}
else
{
  // Get the updated list of receivers
  uint32_t num_receivers = 0;
  const NDIlib_receiver_t* p_receivers =
NDIlib_recv_listener_get_receivers(pNDI_recv_listener, &num_receivers);
 
  // Display all of 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);
    }
  }
}
 
// Destroy the receiver listener NDIlib_recv_listener_destroy(pNDI_recv_listener);

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.

Parameters
Description

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.

📂
Advanced SDK
Advanced SDK