Command Line Tools
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.
Still better, if you lock the clock between multiple computer systems using NTP, recordings done independently on all computer systems will always be automatically synchronized.
The complexities of discontinuous and unlocked sources are handled correctly. The recorder will handle cases in which audio and/or video are discontinuous or not on the same clock. It should correctly provide audio and video synchronization in these cases and adapt correctly even when poor input signals are used.
High Performance. Using asynchronous block-based disk writing without any video compression in most cases means that the number of streams written to disk is largely limited only by available network bandwidth and the . On a fast system, even a large number of 4K streams may be recorded to disk!
And much more... Having worked with a large number of companies wanting recording capabilities, we realized that providing a reference implementation that handles a lot of the edge cases and problems of recording would be hugely beneficial. Allowing all sources to be synchronized makes NDI a fundamentally more powerful and useful tool for video in all cases.
The implementation provided is cross-platform and may be used under the SDK license in commercial and free applications. Note that audio is recorded in floating-point and so is never subject to audio clipping at record time.
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:
-i "source-name"
Required option. The NDI source name to record.
-o "file-name"
Required option. The filename you wish to record into. Please note that if the filename already exists, a number will be appended to it to ensure that it is unique.
-u "url"
Optional. This is the URL of the NDI source if you wish to have recording start slightly quicker or if the source is not currently visible in the current group or network.
-nothumbnail
Optional. Specify whether a proxy file should be written. By default, this option is enabled.
-noautochop
Optional. When specified, this specifies that if the video properties change (resolution, framerate, aspect ratio), the existing file is chopped, and a new one starts with a number appended. When false, it will simply exit when the video properties change, allowing you to start it again with a new file name should you want. By default, if the video format changes, it will open a new file in that format without dropping any frames.
-noautostart
Optional. This command may be used to achieve frame-accurate recording as needed. When specified, the record application will run and connect to the remote source; however, it will not immediately start recording. It will then start immediately when you send a <start/> message to stdin.
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.
<start/>
Start recording at this moment; this is used in conjuction with the “-noautostart” command line.
<exit/> or <quit/>
This will cancel recording and exit the moment that the file is completely on disk.
<record_level gain="1.2"/>
This allows you to control the current recorded audio levels in decibels. 1.2 would apply 1.2 dB of gain to the audio signal while recording to disk.
<record_agc enabled="true"/>
Enable (or disable) automatic gain control for audio, which will use an expander/compressor to normalize the audio while it is being recorded.
<record_chop/>
Immediately stop recording, then restart another file without dropping frames.
<record_chop filename="another.mov"/>
Immediately stop recording, and start recording another file in potentially a different location without dropping frames. This allows a recording location to be changed on the fly, allowing you to span recordings across multiple drives or locations.
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 NDI-Recv Discovery, Monitor and Control.
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 ndi.video 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 NDI Tools bundle) 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.
It is, of course, recommended that you have a static IP address so that any clients configured to access it will not lose connections if the IP is dynamically re-assigned.
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
-help : Displays available command-line options.
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
Windows:
C:\ProgramData\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.“NDI Discovery Service.exe” stop: Stops 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.
Last updated
Was this helpful?