NVIDIA Networked Media Open Specifications Library

Introduction

The Networked Media Open Specifications (NMOS) enable the registration, discovery and management of Media Nodes.

The NVIDIA NMOS control plane library, NvNmos, provides the APIs to create, destroy and internally manage an NMOS Node for a Media Node application. It is intended to be integrated with an ST 2110 data plane library such as NVIDIA Rivermax or NVIDIA DeepStream.

The library can automatically discover and register with an NMOS Registry on the network using the AMWA IS-04 Registration API.

The library provides callbacks for NMOS events such as AMWA IS-05 Connection API requests from an NMOS Controller. These callbacks can be used to update running DeepStream pipelines with new transport parameters, for example.

NvNmos currently supports Senders and Receivers for uncompressed Video and Audio, i.e., SMPTE ST 2110-20 and SMPTE ST 2110-30 streams.

The NvNmos library supports the following specifications, using the Sony nmos-cpp implementation internally:

• AMWA IS-04 NMOS Discovery and Registration Specification v1.3
• AMWA IS-05 NMOS Device Connection Management Specification v1.1
• AMWA IS-09 NMOS System Parameters Specification v1.0
• AMWA BCP-002-01 Natural Grouping of NMOS Resources v1.0
• AMWA BCP-002-02 NMOS Asset Distinguishing Information v1.0
• AMWA BCP-004-01 NMOS Receiver Capabilities v1.0
• AMWA BCP-006-01 NMOS With JPEG XS v1.0
• Session Description Protocol conforming to SMPTE ST 2110-20, -22, -30, -40, and ST 2022-7

Supported Platforms

The library is intended to be portable to different environments. The following operating systems and compilers have been tested.

• Ubuntu 24.04 with GCC 13
• Windows 10 with Visual Studio 2022

Usage

NvNmos consists of a single shared library (libnvnmos.so on Linux, nvnmos.dll on Windows). The API is specified by the nvnmos.h header file.

The nvnmos-example application demonstrates use of the library.

Docker-Based Build

A Dockerfile is provided which builds, packages and tests the library and application from source.

docker build -t nvnmos .

The package can then be copied directly to the host system.

docker create --name nvnmos-test nvnmos
docker cp nvnmos-test:/nvnmos-ubuntu-24.04.tar.gz .
docker rm nvnmos-test

The container also has an entrypoint.sh which demonstrates how to install the run-time requirements and run the application.

docker run -it nvnmos /bin/bash

Dockerfile Build Arguments

The following build arguments are available.

Argument	Explanation
BASE_IMAGE	Controls the base container image and therefore the compatibility of the created package. Default is ubuntu:24.04.
PACKAGE_SUFFIX	Controls the package filename, which will be nvnmos<suffix>.tar.gz. Default is based on the base image, e.g. -ubuntu-24.04.
USE_CONAN_LOCK	Controls whether the conan.lock file is used to ensure reproducible dependencies, even when new versions are available. Default is 1 (on).

If this isn't sufficient for your purposes, read on for manual build instructions.

Pre-Build Requirements

Python

Having Python 3 isn't an absolute requirement but it makes the subsequent steps to install the dependencies easier.

Linux

Use the system package manager to install Python 3 and the venv module (on Debian and Ubuntu the package is python3-venv). A system-wide python3-pip install is optional if you follow the recommended virtual environment below: the virtual environment gets its own pip, which avoids touching the distribution's managed environment (PEP 668).

💬 Note: The -y option allows apt install to run non-interactively.

sudo apt install -y python3 python3-venv

Windows

Download the Python 3 installer from python.org and run it manually, or use the following PowerShell commands. Python 3.14.4 (64-bit Windows, latest stable release at the time) has been tested.

💬 Note: The ` is the PowerShell line continuation character.

Invoke-WebRequest `
  https://www.python.org/ftp/python/3.14.4/python-3.14.4-amd64.exe `
  -OutFile python-3.14.4-amd64.exe

./python-3.14.4-amd64.exe /quiet PrependPath=1 Include_tcltk=0 Include_test=0

Confirm this Python is available on the PATH. Try closing and reopening the terminal if not.

python --version

Python Virtual Environment

For manual builds, a virtual environment in the repository root (for example, .venv) is recommended. It isolates the Python environment used for Conan and other pip-installed build tools from the system interpreter, pins compatible tool versions on PATH, and on Linux avoids PEP 668 "externally managed" errors when using the system Python.

Linux

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

Windows

From PowerShell, use the following commands.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
# If PowerShell reports that "running scripts is disabled on this system"
# you can adjust the execution policy as follows and try again.
# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
python -m pip install --upgrade pip

Or use Command Prompt instead.

python -m venv .venv
.\.venv\Scripts\activate.bat
python -m pip install --upgrade pip

To exit the virtual environment later, run deactivate (same on Linux and Windows).

CMake

The project requires CMake 3.17 or higher; dependencies may require a higher version.

There are x86_64 and arm64 packages for CMake 3.30.0 on the Python Package Index (PyPI) which have been tested.

Linux

pip install cmake~=3.17

Windows

pip install cmake~=3.17

Conan

Using Conan simplifies fetching, building, and installing the required C++ dependencies from Conan Center.

The project requires Conan 2.2 or higher; dependencies may require a higher version. Conan 2.28.0 (latest release at the time) has been tested.

Linux

pip install conan~=2.2 --upgrade
conan profile detect

The detected profile is displayed, along with some WARN messages. For example, the following profile has been tested.

[settings]
arch=x86_64
build_type=Release
compiler=gcc
compiler.cppstd=gnu17
compiler.libcxx=libstdc++11
compiler.version=13
os=Linux

Windows

pip install conan~=2.2 --upgrade
conan profile detect

The detected profile is displayed, along with some WARN messages. For example, the following profile has been tested.

[settings]
arch=x86_64
build_type=Release
compiler=msvc
compiler.cppstd=14
compiler.runtime=dynamic
compiler.version=193
os=Windows

Building the NvNmos Library

Linux

Prepare a build directory adjacent to the src directory.

mkdir build

To install the dependencies using Conan, use the following command.

💬 Note: Replace <Release-or-Debug> with the necessary value. Passing --lockfile=src/conan.lock pins dependency versions per src/conan.lock, matching the default Dockerfile and GitHub Actions behaviour.

conan install src \
  -g CMakeToolchain \
  --settings:all build_type=<Release-or-Debug> \
  --build=missing \
  --output-folder=src/conan \
  --lockfile=src/conan.lock

Use the following CMake command to configure the build.

💬 Note: Replace <Release-or-Debug> with the necessary value. The CMAKE_TOOLCHAIN_FILE path is resolved relative to the top-level src directory passed as the last argument.

cmake -B build \
  -DCMAKE_TOOLCHAIN_FILE=conan/conan_toolchain.cmake \
  -DCMAKE_BUILD_TYPE=<Release-or-Debug> \
  src

Build the library and example application.

cmake --build build --parallel

Windows

Prepare a build directory adjacent to the src directory.

mkdir build

To install the dependencies using Conan, use the following command.

💬 Note: The ` is the PowerShell line continuation character. In the Windows command prompt, use ^ instead. Replace <Release-or-Debug> with the necessary value. Passing --lockfile=src/conan.lock pins dependency versions per src/conan.lock, matching the default Dockerfile and GitHub Actions behaviour.

conan install src `
  -g CMakeToolchain `
  --settings:all build_type=<Release-or-Debug> `
  --build=missing `
  --output-folder=src/conan `
  --lockfile=src/conan.lock

Repeat the command for both Debug and Release if required.

Use the following CMake command to configure the build.

cmake -B build `
  -G "Visual Studio 17 2022" `
  -DCMAKE_TOOLCHAIN_FILE="conan/conan_toolchain.cmake" `
  -DCMAKE_CONFIGURATION_TYPES="Debug;Release" `
  src

Build the library and application with the following command or manually using the generated Visual Studio solution.

💬 Note: Replace <Release-or-Debug> with the necessary value.

cmake --build build --config <Release-or-Debug> --parallel

Run-Time Requirements

Linux

Install and run the Avahi Daemon.

apt update
apt install -y dbus avahi-daemon

/etc/init.d/dbus start
/etc/init.d/avahi-daemon start

💬 Note: Since Ubuntu 24.04, an init script is not provided for the Avahi daemon; run avahi-daemon --daemonize instead.

Windows

Install and start the Bonjour Service.

See Download Bonjour Print Services for Windows v2.0.2.

Running the Example Application

Starting the Example Application

Run the nvnmos-example app specifying host name, port, IP address, and optionally a log level.

For example:

nvnmos-example nmos-api.local 8080 192.0.2.0

The host name can be a .local name, in which case the Node will attempt to discover a Registry being advertised via multicast DNS-SD (mDNS). When a fully-qualified domain name is specified, e.g. "api.example.com", the NMOS Node will instead use unicast DNS-SD discovery in the relevant domain, e.g. "example.com".

The port is used to serve the HTTP APIs.

The IP address identifies the interface to be used for the mock Senders and Receivers created by the nvnmos-example application.

The log level ranges between -40 (most verbose) and 40 (least verbose), as per the NvNmos API. Values greater than zero are warnings and errors. Values less than zero are debugging or trace messages.

The nvnmos-example app runs through the following steps which are output independent of the log level:

Creating NvNmos server...
Removing some senders and receivers...
Adding back some senders and receivers...
Activating senders and receivers...
Deactivating senders and receivers...
Destroying NvNmos server...
Finished

After each step, the app prompts before moving on to the next step:

Continue ([y]/n)?

If the app runs successfully to completion, the process exits with code 0. If any step fails, or the user responds negatively to a prompt, the process exits immediately with code 1.

Accessing the NMOS APIs

While the app is running, the IS-04 Node API, the IS-05 Connection API, etc., are available for an NMOS Controller to use. The HTTP APIs can be accessed at:

http://<host-address>:<port>/

Troubleshooting

Address already in use

When running multiple NMOS Node instances, each process must be configured to use different ports, i.e., with a unique port value. When the port is already in use, at start-up, the application may show a message like the following:

asio listen error: system:98 (Address already in use)

Apple Bonjour compatibility warnings

When using Avahi for DNS-SD, shortly after start-up the following lines may be displayed in the log. They do not indicate a problem and can be ignored.

*** WARNING *** The program 'nvnmos-example' uses the Apple Bonjour compatibility layer of Avahi.
*** WARNING *** Please fix your application to use the native API of Avahi!
*** WARNING *** For more information see <http://0pointer.de/blog/projects/avahi-compat.html>

DNSServiceRegister and DNSServiceBrowse errors

The application may show messages like the following shortly after start-up:

DNSServiceRegister reported error: -65537 while registering advertisement for: nmos-cpp_node_192-168-1-194:12345._nmos-node._tcp
DNSServiceBrowse reported error: -65537

In this case, the NMOS Node will not be able to discover or register with the NMOS Registry.

One reason for these errors is that the DNS-SD daemon/service is not running.

Linux

When using Avahi, check that the avahi-daemon is running.

Windows

When using mDNSResponder/Bonjour, check that the Bonjour Service is running.