This is the open-source SDK for discovering, interrogating and controlling NTV2 professional video I/O devices from AJA Video Systems, Inc. All code herein is licensed under the MIT license.

1. Branch Overview
2. Directory Layout
3. Obtaining libajantv2
4. Building libajantv2
5. Building the Kernel Module Driver (Linux)
6. Verifying the Kernel Module Driver (Linux)
7. Customizing libajantv2
8. SDK Forward & Backward Compatibility
9. Driver Compatibility
10. Firmware and Device Features
11. libajantv2 Dynamic (Shared) Libary

This branch is only updated for official, tested releases of AJA’s “retail” software.

Example: NTV2_17_0 This branch tracks weekly changes to the 17.0.x major release branch of the SDK. In this example, you can find changes in the NTV2_17_0 branch that are slated to be included in future v17.0.x releases. This code has only had minimal testing and should be considered alpha code.

This is the “bleeding edge” development branch. Changes are synced weekly and is to be considered unstable. No QA testing has been done on this branch.

The libajantv2 folder contains the following items:

• ajaanc — Classes for encoding & decoding SDI ancillary data packets.
• ajabase — Utility classes (e.g. threads, mutexes, files, etc.).
• ajantv2 — Principal classes, especially CNTV2Card.
  • includes — Header files.
  • src — Source files.
  • test — Unit test source code.
  • utilityfiles — Additional sources needed to build some command-line utilities.
• ci — Continuous integration (CI) scripts.
• cmake — Cmake build-related stuff.
• container — Docker-related stuff.
• demos — Demonstration programs and applications.
• driver — Platform-specific device drivers.
• plugins — Dynamically-loadable libraries that augment SDK behavior.
• thirdparty — Required non-AJA packages (e.g. doctest)
• tools — Useful command-line utilities.

Clone the libajantv2 repository from GitHub:

> git clone git@github.com:aja-video/libajantv2.git

Starting in the NTV2 SDK version 17.0, AJA has standardized on CMake for describing how to build the libraries, demonstration applications, command-line tools, unit tests, and plugins. AJA requires CMake version 3.15 or later.

The instructions for building the default static library are generally the same on each supported platform (Windows, macOS, Linux). Note that the default "CMake Generator" varies by platform.

NOTE: By default — absent any parameters — all standard targets are built (static library, demos, tools, tests, plugins).

To prevent building certain targets, these CMake variables can be set to 'ON' in your CMake build environment:

• AJANTV2_DISABLE_DEMOS — If ON, prevents building the demonstration programs (e.g. ntv2capture, ntv2player, …).
  Demo apps are normally built by default.
• AJANTV2_DISABLE_TOOLS — If ON, prevents building the command-line tools (e.g. ntv2thermo, regio, supportlog, …).
  Command-line tools are normally built by default.
• AJANTV2_DISABLE_TESTS — If ON, prevents building the unit test(s).
  The test programs are normally built by default.
• AJANTV2_DISABLE_PLUGINS — If ON, builds the standard NTV2 plugins (i.e. nublegacy, swdevice, …).
  The standard NTV2 plugins are normally built by default.

Please follow the instructions below to build libajantv2 on the supported platform and development environment of your preference.

Follow these instructions to build libajantv2 from a Developer Command Prompt for Visual Studio:

1. Open a command prompt window (cmd) and initialize your Visual Studio environment by running the vcvarsall.cmd script from the desired Microsoft Visual Studio directory. The location of vcvarsall.cmd may vary depending on the version of Visual Studio installed on the development system.

   For example, if using Visual Studio 2019 Community Edition:

   > SET VS_YEAR=2019
   > SET VS_EDITION=Community
   > call "C:\Program Files (x86)\Microsoft Visual Studio\%VS_YEAR%\%VS_EDITION%\VC\Auxiliary\Build\vcvarsall.bat" x64
   

2. Run cmake to generate the libajantv2 Visual Studio Solution file in a directory called build:

   > cd libajantv2
   > cmake -S . -B build
   

3. Build libajantv2 from the command line, via the generated Visual Studio Solution:

   > cmake --build build
   

4. If the build completes without errors, the static library should be output to out\build\<arch>-<build type>\ajantv2 under the libajantv2 directory.

   Other build target outputs (demos, tools, etc.) will be available in subdirectories under the build directory mirroring their original location in the libajantv2 source tree.

   For example, the ntv2enumerateboards.exe demo app will be located in: out\build\demos\ntv2enumerateboards.

Alternatively, the generated Visual Studio solution from build/libajantv2.sln may be opened in Visual Studio, where libajantv2 can be built via the usual mechanisms.

Follow these instructions to build libajantv2 via the Microsoft Visual Studio CMake integration. This requires Visual Studio 2019 or 2022.

1. Open Microsoft Visual Studio 2019.

2. From the initial splash page, select "Open a local folder..." and navigate to the libajantv2 repo directory.

3. If CMake is installed and configured properly, the Output window should show the CMake configuration logs and end with a message saying "CMake generation finished".

4. To reconfigure the build with custom settings for certain CMake variables, additional CMake or build flags, etc. go to the Project menu and select "CMake settings for libajantv2". Make any changes to the build flags, CMake flags, variables, etc. and then save the CMakeSettings.json document. The CMake configure step should automatically be re-run upon saving.

   _NOTE: To manually re-run the CMake configure step with new settings, go to the Project menu and select "Configure libajantv2". If you've added libajantv2 as a sub-folder in another project you may see a different project name in the Configure menu item.

5. From the Build menu select "Build All".

6. If the build completes without errors, the static library should be output to out\build\<arch>-<build type>\ajantv2 under the libajantv2 directory.

   Other build target outputs (demos, tools, etc.) will be available in subdirectories under the build directory mirroring their original location in the libajantv2 source tree.

   For example, the ntv2enumerateboards.exe demo app will be located in: out\build\demos\ntv2enumerateboards.

1. Open a Terminal and generate the XCode project files:

   $ cd libajantv2
   $ cmake -S . -B build -G Xcode
   

2. Build libajantv2 static library from the terminal, via the generated XCode Project:

   $ cmake --build build
   

   NOTE: It is also possible to build the generated XCode Project via the typical xcrun command:

   $ xcrun xcodebuild -project build/libajantv2.xcodeproj -target ALL_BUILD
   

3. If the build completes without errors, the static library should be output to build/ajantv2/<Debug|Release>/libajantv2d.a under the libajantv2 directory.

   Other build target outputs (demos, tools, etc.) will be available in subdirectories under the build directory mirroring their original location in the libajantv2 source tree.

   For example, the ntv2enumerateboards demo app will be located in: build/demos/ntv2enumerateboards.

Alternatively, the generated XCode project from build/libajantv2.xcodeproj may be opened in XCode, where the static library can be build via the usual mechanisms.

1. Open a Terminal window and run cmake to generate the GNU Makefiles in a directory called build.

   $ cd libajantv2
   $ cmake -S . -B build
   

2. Build the libajantv2 static library from the generated GNU Makefiles:

   $ cmake --build build
   

3. If the build completes without errors, the static library should be output to out\build\<arch>-<build type>\ajantv2 under the libajantv2 directory.

   Other build target outputs (demos, tools, etc.) will be available in subdirectories under the build directory mirroring their original location in the libajantv2 source tree.

   For example, the ntv2enumerateboards demo app will be located in: out\build\demos\ntv2enumerateboards.

If Ninja Build is installed in the PATH it is possible to generate .ninja build configuration files with CMake.

Ninja Build is available from GitHub, or via the package manager of your preference.

Download: https://github.com/ninja-build/ninja/releases

NOTE: The compiler toolset used by Ninja Build will vary depending which compiler CMake finds in the PATH by default. On macOS and Linux this is clang or gcc, and on Windows this is usually the cl compiler available under the current Developer Command Prompt for Visual Studio Environment.

1. Open a Terminal or Command Prompt window and run cmake with the Ninja generator specified, to created .ninja files in a directory called build.

   $ cd libajantv2
   $ cmake -S . -B build -GNinja
   

2. Build all configured libajantv2 targets:

   $ cmake --build build
   

3. If the build completes without errors, the libajantv2 static library should be available in build/ajantv2.

   Other build target outputs (demos, tools, etc.) will be available in subdirectories under the build directory mirroring their original location in the libajantv2 source tree.

The libajantv2 repository can be opened as a directory in Visual Studio Code and built with the optional Microsoft CMake Extension for VSCode.

1. Launch Visual Studio Code

2. From the File menu select Open (or Open Folder on macOS) and navigate to the libajantv2 repo directory.

3. In the left-hand sidebar click on the Extensions button or press Ctrl+Shift+P (Cmd+Shift+P on macOS) to open the Command Palette and search for "Extensions: Install Extensions".

4. In the left-hand sidebar search for the "cmake" extension from developer "twxs" (also available in the CMake Tools extension from Microsoft) and install it.

5. Open the Command Palette once again and search for "CMake: Configure".

6. If the configuration completes successfully, open the Command Palette and search for "CMake: Build".

7. If the build completes without errors, the libajantv2 static library should be available in build/ajantv2.

   Other build target outputs (demos, tools, etc.) will be available in subdirectories under the build directory mirroring their original location in the libajantv2 source tree.

The libajantv2 repository can be opened as a directory in Qt Creator and built with the Qt Creator CMake integration.

Before building the driver please ensure that you have installed the Linux kernel headers for your current distro:

$ sudo apt install -y linux-headers-$(uname -r) linux-tools-$(uname -r)

$ sudo yum install -y kernel-devel kernel-devel-$(uname -r)

1. Open a terminal window and cd into the linux driver directory:

$ cd libajantv2/driver/linux

2. Run make to build the driver

$ make clean && make

3. If the kernel module build succeeds, the ajantv2.ko file will appear in libajantv2/driver/bin.

4. The driver can be installed/uninstalled in 2 ways, the manual method:

Install the kernel module using insmod:

$ sudo insmod ajantv2.ko

Note that on hosts with Secure Boot enabled, you’ll need to sign the ajantv2.ko kernel module after it’s been built. Check your Linux distro’s documentation for Secure Boot information.

Uninstall the kernel module using rmmod (all applications using the driver must be closed):

$ sudo rmmod ajantv2

5. The alternate way to install the driver is via DKMS

Install the kernel module using DKMS:

$ make dkms-install

Uninstall the kernel module using DKMS:

$ make dkms-uninstall

To confirm that the driver is loaded and running on a host that has an AJA NTV2 device installed or connected, issue an lsmod command, and look for ajantv2 in the list. You can also issue an ls /dev command, and look for devices with names that start with ajantv2.

If lsmod doesn’t report the device, or it doesn’t appear in /dev:

• Try disabling any/all “fast boot” options in the host BIOS.
• Try disabling any/all power management options in the host BIOS (e.g. ASPM).
• Be sure the AJA device shows up in lspci -nn -d f1d0:.
• Be sure the installed AJA board(s) each have two green LEDs lit after host power-on.
• Check the dmesg log for error messages from the AJA NTV2 kernel driver.
• Try installing the AJA device in a different PCIe slot on the host motherboard.

There are a number of macros that control certain aspects of NTV2:

• NTV2_USE_CPLUSPLUS11 (in ajantv2/includes/ajatypes.h) — If defined (the default), assumes a C++11 compiler (or later) is being used, and C++11 language features will be used in 'ajantv2'. Note that this macro will automatically be defined or undefined as necessary by CMake depending on the CMAKE_CXX_STANDARD that's in use at build-time. Also note that if this macro is defined, so must AJA_USE_CPLUSPLUS11 (see below) … and vice-versa.
• AJA_USE_CPLUSPLUS11 (in ajabase/common/types.h) — If defined (the default), assumes a C++11 compiler (or later) is being used, and C++11 language features will be used in 'ajabase'. Note that this macro will automatically be defined or undefined as necessary by CMake depending on the CMAKE_CXX_STANDARD that's in use at build-time. Also note that if this macro is defined, so must NTV2_USE_CPLUSPLUS11 (see above) … and vice-versa.
• NTV2_NULL_DEVICE (in ajantv2/includes/ajatypes.h) — If defined, removes all linkage to the NTV2 kernel driver. This is used, for example, to build a “sandboxed” MacOS X application with no linkage to Apple’s IOKit framework. This has the side effect of having CNTV2DriverInterface::OpenLocalPhysical always fail, thus permitting only remote devices to be accessed. This macro is undefined by default.
• NTV2_NUB_CLIENT_SUPPORT (in ajantv2/includes/ajatypes.h) — If defined (the default), the SDK will load plugins (DLLs, dylibs, .so’s) as necessary to connect to remote or virtual devices. For applications requiring higher security, this macro can be undefined to prevent dynamic plugin loading.
• NTV2_WRITEREG_PROFILING (in ajantv2/includes/ajatypes.h) — If defined (the default), the WriteRegister profiling API in CNTV2Card is available.
• NTV2_ALLOW_OPEN_UNSUPPORTED (in ajantv2/includes/ajatypes.h) — If defined, the SDK won’t check if the host-attached device being opened is supported; otherwise (the default), the SDK will fail the Open call if the host-attached device being opened is “unsupported”. (See the NTV2GetSupportedDevices function in ntv2utils.h.)

The NTV2 source files originated many years ago from some of the earliest hardware products produced by AJA. These products ceased being dependent on NTV2 many years ago, but unfortunately, their legacy symbols remained in the SDK.

In addition, when the first NTV2 SDK was released, the video capture/playout devices it supported were circuit boards fixed in a specific motherboard slot with barely enough I/O capability to handle a single stream of 4:2:2 YUV SD video. Today’s devices are hot-pluggable, support multiple channels, each with its own signal format, up to 4:4:4 8Kp60 and beyond. As the SDK expanded over the years to support newer, faster devices, the older functions, data types and constants remained, which resulted in a very unwieldy and confusing SDK that made it difficult for OEM developers to quickly get up to speed.

Starting with the 11.3 SDK, AJA introduced the first NTV2_DEPRECATE macro, and gathered many of the obsolete SDK functions, data types and constants under preprocessor #ifdef blocks:

#if !defined(NTV2_DEPRECATE)
    . . .
    // Obsolete constants, data types and functions
    . . .
#endif  //  !defined(NTV2_DEPRECATE)

This means that if the NTV2_DEPRECATE macro is undefined, then existing code that relies on the old APIs will continue to compile, link and run. If the NTV2_DEPRECATE macro is defined, then the obsolete APIs disappear from the compilation, and build errors will result if they’re used.

To build the ajantv2 library to include a deprecated API, comment out or remove its corresponding #define NTV2_DEPRECATE… line in ajatypes.h, then rebuild the library.

Note: It’s best to undefine macros from oldest-to-newest SDKs in contiguous blocks or unexpected results may occur. For example, do this:

    #define NTV2_DEPRECATE
    #define NTV2_DEPRECATE_15_5
    //#define NTV2_DEPRECATE_15_6
    //#define NTV2_DEPRECATE_15_7

… and not this:

    #define NTV2_DEPRECATE
    //#define NTV2_DEPRECATE_15_5
    //#define NTV2_DEPRECATE_15_6
    #define NTV2_DEPRECATE_15_7

AJA may jettison all deprecated symbols and APIs in a future SDK. Please prepare for this by porting your code to the latest SDK. AJA developer partners are encouraged to use the NTV2 SDK Porting Guide, available at sdksupport.aja.com.

The NTV2 SDK contains its version information as symbols defined in ajaversion.h (located inside libajantv2/ajantv2/includes). It defines the following symbols:

• AJA_NTV2_SDK_VERSION_MAJOR The SDK’s major version number (an unsigned numeric constant).
• AJA_NTV2_SDK_VERSION_MINOR The SDK’s minor version number (an unsigned numeric constant).
• AJA_NTV2_SDK_VERSION_POINT The SDK’s “point” version number (an unsigned numeric constant).
• AJA_NTV2_SDK_BUILD_NUMBER The SDK build number (an unsigned numeric constant).
• AJA_NTV2_SDK_BUILD_DATETIME The date and time the SDK was built, a string literal of the form MM/DD/YYYY +/-Z:hh:mm:ss, where MM is the 2-digit month (01 thru 12), DD is the 2-digit day number, YYYY is the 4-digit year, +/-Z is the number of hours relative to UTC, hh is the 2-digit hour (0 thru 23), mm is the number of minutes past the hour (0 thru 59), and ss is the number of seconds past the minute (0 thru 59).
• AJA_NTV2_SDK_BUILD_TYPE The SDK build type, a string literal containing a single character, where d means “development”, a means “alpha”, b means “beta” and the empty string means “release”.
• AJA_NTV2_SDK_VERSION An unsigned integer value built from the SDK version components that can be reliably compared with other version integer values. There’s also a convenient macro for testing which SDK version is being used at compile-time:
  • AJA_NTV2_SDK_VERSION_AT_LEAST(major, minor) Yields “true” if the major and minor version numbers of the current SDK being compiled are at least (greater than or equal to) the specified major and minor values, respectively. To use this macro, call it with the minimum version of the required SDK:

#if AJA_NTV2_SDK_VERSION_AT_LEAST (16, 2)
  . . .
#endif   //  if NTV2 SDK version >= 12.0

AJA always recommends that NTV2-based applications be built from the same SDK version as the installed driver that will be used.

Warning: While AJA always tries to maintain backward compatibility between newer SDKs and older drivers, AJA cannot guarantee correct operation of applications built from an older SDK running on a newer version driver, nor applications built from a newer SDK running on an older version driver.

For a given SDK release, the CanDoXXXX, GetNumXXXX, etc. Device Features API responses should be correct for all supported devices running the latest firmware available on or after the SDK release date. AJA will do its best to document any exceptions on the SDK’s download page and/or the device firmware page in the Knowledgebase.

Starting in SDK 16.1, AJA started to distribute libajantv2 as a dynamic library both on public forums, and in AJA’s MacOS, Windows, and Linux “retail” desktop software installers.

libajantv2 is publically-distributed as a dynamic library. AJA’s retail desktop installers install the NTV2 dynamic libraries into the following host locations:

• Linux — /opt/aja
  • ajantv2_MM.so (…where MM is a two-digit major version number)
• macOS — /Library/Application Support/AJA
  • ajantv2_MM.dylib
  • ajantv2d_MM.dylib — if present, the debug version of the library
• Windows — …\Program Files\AJA
  • MMAJANTV2.DLL

File Name: The libary’s file name includes the SDK major version number in the name (e.g. ajantv2_16.dylib).

• All public, non-static symbols are exported as intended for “strong” linkage.
• The dynamic library is intended for “tight” integration with client applications. Changing even one NTV2 data type, class definition or function signature without rebuilding both the SDK library and the client application(s) will likely yield dynamic loader failures at launch-time, or unexpected results at runtime (including crashes).

When dynamically loading the NTV2 library at runtime (as opposed to having it automatically loaded by the host operating system at launch time), the library can be queried for more specific version information by two utility functions:

• NTV2GetVersionString – returns a string that starts with “major.minor.point” that includes the major, minor, and point version number values in decimal form.
• NTV2GetSDKVersionComponent – returns any of the major, minor, and point version number values by passing 0, 1, 2 or 3, respectively, for the version component being requested.

NOTE: It is strongly recommended that the SDK client software operates with the SDK dynamic library that has the same version.

WARNING: Do not use an SDK dynamic library whose major version number differs from the SDK major version number when the SDK client was compiled.

To build the libajantv2 dynamic library, set the AJANTV2_BUILD_SHARED CMake variable to 'ON' in your build environment.

• AJANTV2_BUILD_SHARED — If ON, produces the libajantv2 dynamic library.
  By default, the libajantv2 dynamic library is not built.