This guide explains how the Media Server loads plugins, how to configure experimental loading options, and how to troubleshoot loading issues.

Plugin loading workflow

Nx Witness Server scans specific default installation directories to identify and load plugins.

Standard directories

Depending on your operating system, the server searches these default paths:

• Linux: /opt/networkoptix/mediaserver/bin/plugins 

• Windows: C:\Program Files\Network Optix\Nx Witness\MediaServer\plugins

Plugins can exist in either of two formats within these paths:

• Standalone dynamic library: A single .dll (Windows) or .so (Linux) file. Use this format when your plugin does not require external files.

• Plugin home directory: A subfolder containing a dynamic library and optional support files (such as runtime configuration files or dependent libraries).

  The folder name must match the plugin libName (the filename without the lib prefix on Linux and without the file extension). For example:

  /mediaserver/bin/plugins/my_vms_plugin/libmy_vms_plugin.so

  To obtain this folder path at runtime, call IUtilityProvider::homeDir() on the object supplied by the server to IPlugin::setUtilityProvider().

Loading sequence

When Nx Witness Server starts, it executes the following sequence:

1. Scans for dynamic libraries: The server searches the default installation paths for .dll or .so files.

2. Finds the entry point function: The server inspects each library for one of the following exported functions:

   • nx::sdk::IPlugin* createNxPlugin() (Used in Metadata SDK; standard function for all future SDKs)

   • nxpl::PluginInterface* createNXPluginInstance() (Used in Video Source SDK and Storage SDK)

3. Instantiates the plugin object: The server calls the entry point function, which returns a main plugin object implementing the required interface.

4. Shuts down gracefully: When the server stops, it releases the plugin object reference, destroying the object.

Configure experimental loading options

You can passlist or blocklist specific plugins by editing the vms_server_plugins.ini configuration file.

Set up the configuration file

1. Navigate to your server installation folder and create an empty file named vms_server_plugins.ini.

2. Restart the Media Server to populate the file with default values and documentation.

3. Edit the settings in vms_server_plugins.ini.

4. Restart the Media Server to apply your changes.

Passlist optional plugins

To load plugins from a secondary plugins_optional folder (located next to the default plugins directory) without moving files:

1. Open vms_server_plugins.ini.

2. Set enabledNxPluginsOptional to a comma-separated list of plugin libName values, or use an asterisk (*) to load all optional plugins:

   enabledNxPluginsOptional="stub_analytics_plugin, sample_analytics_plugin"

3. Save the file and restart the server.

Blocklist disabled plugins

To prevent the Media Server from loading specific plugins from the default plugins directory during testing:

1. Open vms_server_plugins.ini.

2. Set disabledNxPlugins to a comma-separated list of plugin libName values, or use an asterisk (*) to disable all plugins in the main directory:

   disabledNxPlugins="*"

3. Save the file and restart the server.

Modify Windows DLL lookup behavior

By default, the Media Server alters Windows dependency search paths depending on where the plugin resides:

• Standalone DLLs: Searches using default Windows search order, excluding the current process directory.

• Home directory DLLs: Searches inside the plugin home directory first.

If you encounter Windows API conflicts or obscure loading errors, revert to the standard Windows search behavior:

1. Open vms_server_plugins.ini.

2. Add or update the following setting:

   disablePluginLinkedDllLookup=true

3. Save the file and restart the server.

Troubleshoot plugin loading issues

If a plugin fails to appear in the Desktop Client or Camera Settings, please review the following steps to isolate the issue.

Check common failure reasons

• The plugin file resides in an incorrect directory.

• The plugin is blocked by the disabledNxPlugins setting in vms_server_plugins.ini.

• The operating system cannot resolve missing shared dependencies.

• The dynamic library lacks a valid exported entry point function.

• The entry point function returns an unexpected or null object.

• The plugin loaded successfully, but it does not claim support for the connected camera model.

Review server logs and REST API

1. Open the main server log file.

2. Filter for log messages containing the tag PluginManager with severity levels INFO or ERROR.

3. Alternatively, check plugin status directly in a web browser by navigating to:

   http://localhost:7001/ec2/pluginInfo/

4. To troubleshoot Windows DLL directory search issues specifically, check PluginManager logs set to DEBUG or ERROR containing the string GetDllDirectoryW.

Verify missing dependencies

When an operating system fails to load a dynamic library due to missing dependencies, log messages can be vague. Manually inspect the file dependencies:

• Windows: Open the plugin .dll in a dependency analysis tool, such as Dependency Walker.

• Linux: Run the ldd command against your .so file in the terminal:

  ldd libmy_plugin.so