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
  • Subscribing to Receiver Events
  • Unsubscribing from Receiver Events
  • Receiver Monitoring Events
  • Receiver Commands

Was this helpful?

Export as PDF
  1. Developing with NDI
  2. Advanced SDK
  3. NDI SDK Review
  4. Receiving

NDI RECV Event Monitoring and Commands

In addition to the NDI Recv Advertiser and NDI Recv Listener APIs available in the standard SDK, the Advanced SDK introduces enhanced APIs that expand capabilities for event monitoring and command execution on registered receivers. These extended functions enable developers to subscribe to and listen to receiver events in real time, as well as send commands to manage receiver behavior more effectively.

This functionality is essential for real-time monitoring and control of NDI receivers, enabling developers to build sophisticated NDI-based applications with dynamic event-driven behavior.

Beyond the standard functionsβ€”NDIlib_recv_advertiser_create and NDIlib_recv_listener_createβ€”available in the standard SDK, the Advanced SDK offers extended versions of this function calls:

  • NDIlib_recv_advertiser_create_ex

  • NDIlib_recv_listener_create_ex

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

The use of receiver event monitoring and command APIs in NDI 6.2 requires a special vendor ID. If you do not have a vendor ID, please contact the NDI Support Team to obtain one. Without a valid vendor ID, the API will not function properly.

Subscribing to Receiver Events

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

void NDIlib_recv_listener_subscribe_events(NDIlib_recv_listener_instance_t p_instance, const char* p_receiver_uuid);

This function requires the following parameters:

  • p_instance: The receiver listener instance (NDIlib_recv_listener_instance_t).

  • p_uuid: The unique identifier of the receiver.

The receiver’s UUID is part of the NDIlib_receiver_t structure, which is generated by the SDK. You can retrieve the list of receivers using the NDIlib_recv_listener_get_receivers function, which will provide the necessary UUID for each receiver.

Unsubscribing from Receiver Events

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

NDIlib_recv_listener_unsubscribe_events(NDIlib_recv_listener_instance_t p_instance, const char* p_receiver_uuid);

This function requires the following parameters:

  • p_instance: The receiver listener instance (NDIlib_recv_listener_instance_t).

  • p_uuid: The unique identifier of the receiver.

Example Code:

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

// Create an instance of the receiver listener.
NDIlib_recv_listener_instance_t pNDI_recv_listener =
NDIlib_recv_listener_create_ex(nullptr, p_ndi_config); 
if (!pNDI_recv_listener) {
 // Handle error
}

// Get the list of advertised receivers.
uint32_t num_receivers = 0;
const NDIlib_receiver_t* p_receivers =
NDIlib_recv_listener_get_receivers(pNDI_recv_listener, &num_receivers);

// Display 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);
 
// If the receiver is not currently subscribed, subscribe to it.
if (!p_receivers[i].events_subscribed) {
NDIlib_recv_listener_subscribe_events(pNDI_recv_listener, p_receivers[i].p_uuid);
}

// Perform operations with the subscribed receiver...
 
// Unsubscribe from the receiver after processing.
NDIlib_recv_listener_unsubscribe_events(pNDI_recv_listener, p_receivers[i].p_uuid);
}

Receiver Monitoring Events

The NDIlib_recv_listener_get_events function allows you to fetch the list of monitoring events from the receiver that you have previously subscribed to using the NDIlib_recv_listener_subscribe_events function. It returns an array of NDIlib_recv_listener_event structures containing the event details.

const NDIlib_recv_listener_event* NDIlib_recv_listener_get_events(NDIlib_recv_listener_instance_t p_instance, uint32_t* p_num_events, uint32_t timeout_in_ms);

Parameters:

  • p_instance (NDIlib_recv_listener_instance_t): The instance of the receiver 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_recv_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_recv_listener_free_events function.

Example Code:

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

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

Event Name
Description
Type
Example Event Values

source-name

The name of the NDI source that the receiver is currently configured to be connected to.

string

"Camera_1"

source-url

The URL of the NDI source that the receiver is currently configured to be connected to.

string

"ndi://192.168.1.10/Camera_1"

connection- state

The state of the main TCP connection to the configured NDI source.

string

"connected", "disconnected"

audio-present

Indicates if audio has been detected from the NDI source.

bool

true, false

audio-codec

The audio codec in use.

string

"pcm", "aac", "opus"

audio-channels

The number of audio channels within the audio stream.

int

1, 2, 6, 8

audio-sample- rate

The sample rate of the audio stream.

int

44100, 48000

audio-receive- mode

Specifies how the audio is being received.

string

"single-tcp", "multi-tcp", "udp-unicast", "udp-multicast", "rudp"

video-present

Indicates if video has been detected from the NDI source.

bool

true, false

video-codec

The video codec in use.

string

"shq0", "shq2", "shq7", "h264", "h265"

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"

video-frame- type

The type of fielding format in use by the video stream.

string

"progressive", "interlaced"

video-has- alpha

Indicates if the video stream contains an alpha channel.

bool

true, false

video-color- primaries

The color primaries of the video stream.

string

"bt_601", "bt_709", "bt_2020", "bt_2100"

video-transfer- function

The transfer function of the video stream.

string

"bt_601", "bt_709", "bt_2020", "bt_2100_hlg", "bt_2100_pq"

video-matrix- coefficients

The matrix coefficients of the video stream.

string

"bt_601", "bt_709", "bt_2020", "bt_2100"

video-receive- mode

Specifies how the video is being received.

string

"single-tcp", "multi-tcp", "udp-unicast", "udp-multicast", "rudp"

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

Receiver Commands

The NDIlib_recv_listener_send_connect function triggers the "connect" command to be sent from the listener to the receiver.

bool NDIlib_recv_listener_send_connect(NDIlib_recv_listener_instance_t p_instance, const char* p_receiver_uuid, const char* p_source_name);

Parameters:

  • p_instance (NDIlib_recv_listener_instance_t): The instance of the receiver listener.

  • p_receiver_uuid (const char*): The unique identifier (UUID) of the receiver.

  • p_source_name (const char*): The name of the source to connect to. If an empty string is passed, it indicates that the receiver should disconnect from its current source.

This function returns true if successful i.e. it could establish a connection to the specified NDI source. The function would return false if the command could not be sent, the receiver is unknown, or another error occurred during the operation.

If the p_source_name parameter is NULL, it indicates that the receiver should disconnect from its current source. This function should only be called for a receiver that supports the NDIlib_receiver_command_connect command.

Example Code:

bool result = NDIlib_recv_listener_send_connect(p_instance, "receiver-uuid", "source- name");

if (result) {
    printf("Receiver successfully connected to the source.\n");
} else {
    printf("Failed to connect the receiver to the source.\n");
}

We recommend referring to the NDI Advanced SDK example code (NDIlib_Recv_Listener_Advanced), which offers a straightforward demonstration of how to implement these APIs effectively.

PreviousDynamic Bandwidth AdjustmentNextFinding

Last updated 2 days ago

Was this helpful?