Reference and Troubleshooting#
Configuration reference, internals, limitations and troubleshooting for the Nx Witness integration.
Configuration reference#
setup.sh generates config/config.yaml from config/base.yaml and the fragments of the
selected VMS and apps. For this integration, the Nx Witness instance is in
vms_shim/nxwitness/vap-config.yaml, Loitering Detection in
analytics_app_shim/object_detection/vap-config.yaml, and Live Video Captioning in
analytics_app_shim/lvc/vap-config.yaml. Edit the fragments, not config/config.yaml, and
run ./setup.sh --vms nx --apps <apps> again.
Environment variables#
Variable |
Default |
Description |
|---|---|---|
|
— |
Nx Witness Server address. |
|
— |
Administrator account VAP signs in with. Also used in the RTSP URLs given to the pipelines. |
|
|
Verify the Nx Witness Server’s TLS certificate. |
|
empty |
CA certificate path inside the backend container, when |
|
|
VAP dashboard port. |
The Loitering Detection and LVC variables are described in Run Loitering Detection and Run Live Video Captioning.
Nx Witness instance#
Key |
Default |
Description |
|---|---|---|
|
|
Instance name. Must start with |
|
|
Nx Witness REST API. |
|
|
TLS verification of the REST API. |
|
from |
Administrator account. |
|
|
Authentication type. |
|
bundled |
Integration manifest. Defaults to |
vendor_options of the Nx Witness instance:
Key |
Default |
Description |
|---|---|---|
|
— |
Category → Nx object type, overriding the default |
|
|
Nx object type of the drawn loitering zone. |
|
|
Minimum time the Desktop Client keeps drawing a box. |
|
|
Added to the measured detection latency to decide how long a box is drawn. |
|
|
Maximum time the Desktop Client keeps drawing a box. |
Loitering Detection app settings#
These keys of the object_detection app matter for Nx Witness:
Key |
Description |
|---|---|
|
Name of the app’s group in the camera settings. |
|
Pipeline for each device. At least one is required. The Device field lists the devices set here. |
|
Detector label → category. Nx Witness shows the category as |
|
Boxes drawn on the video as |
|
Default value of the Loitering Zone field, as normalized |
|
Push only the objects the pipeline reports in a zone. Off by default, so every detection is drawn. |
|
Threshold sent to the pipeline (on-video text color). |
|
Add a bookmark for each loitering row. |
|
MQTT topic suffix of the loitering rows. Must match the recipe’s |
|
MQTT topic prefix. Must match the recipe’s |
Live Video Captioning app settings#
Key |
Description |
|---|---|
|
Name of the app’s group in the camera settings. |
|
LVC backend. |
|
MediaMTX, for the VAP dashboard’s video player. |
|
LVC MQTT broker. If |
|
TLS to the LVC MQTT broker. |
How it works#
Registration#
On startup, VAP compares its database with the integrations in Nx Witness:
VAP database |
Nx Witness |
What VAP does |
|---|---|---|
No record |
No integration |
Registers the integration, approves it, and stores the integration user’s credentials. Logs |
Record |
Integration |
Reuses the stored credentials. Logs |
No record |
Integration |
Stops, and logs |
Record |
No integration |
Stops, and logs |
When it registers, VAP adds to the bundled manifest:
The object types of each app, from its
label_mapcategories andzones, so Nx Witness accepts the detections.A settings group for each app, with its fields: the enable checkbox, Device, and Loitering Zone or Prompt.
Registration needs Accept API Integrations registration requests turned on in Nx
Witness. Because the object types and the settings are fixed at registration, changing the
selected apps or the label_map categories needs a new registration; see
Register the integration again.
Pipeline control from the camera settings#
Every 5 seconds, VAP lists the cameras and reads each camera’s integration settings. For each app:
The checkbox turned on, and no pipeline running: VAP starts one.
A field changed while the pipeline runs: VAP restarts it with the new values.
The checkbox turned off: VAP stops the pipeline.
Starting from the camera settings does not need camera discovery in the VAP dashboard.
Camera streams#
VAP gives each pipeline the camera’s Nx Witness RTSP URL:
rtsp://<NX_USERNAME>:<NX_PASSWORD>@<NX_HOST>:7001/<device-uuid>?onvif_replay=true
Loitering Detection pipeline#
When a pipeline starts, VAP:
Sends
POST <DLS base_url>/pipelines/user_defined_pipelines/<pipeline>to the DL Streamer Pipeline Server, with the RTSP URL as source and the device indetection-properties.Scales the Loitering Zone to the camera’s resolution, read from Nx Witness, and sends it as
analytics-properties.zones. Pipelines that declareroi-propertiesalso get the zone’s bounding rectangle as their region of interest.Sends the threshold as
loitering-watermark-properties.loitering-threshold, to pipelines that declare it.Asks the pipeline to publish on
<metadata_topic_prefix>/nx:<device-uuid>, by defaultobject_tracking/nx:<device-uuid>.
Detections#
VAP subscribes to <metadata_topic_prefix>/+. For each frame, it translates the DL Streamer
metadata into Nx analytics objects and posts them to
/rest/v4/analytics/engines/<engine>/deviceAgents/<device-uuid>/metadata/object, as the
integration user. On the first push for a camera, VAP enables the camera’s device agent.
Detections reach Nx Witness after the video, because of inference, MQTT and REST latency.
VAP sets how long the Desktop Client keeps drawing each box from the measured latency, within
metadata_min_duration_ms and metadata_max_duration_ms.
Bookmarks#
Loitering rows (topic <metadata_topic_prefix>/nx:<device-uuid>/<event_topic_suffix>) and LVC
captions become bookmarks, posted to /rest/v4/devices/<device-uuid>/bookmarks. The bookmark
name is the event or caption text, up to 500 characters, and it lasts 30 seconds.
Limitations#
One kind of result per camera view. The Desktop Client shows either the Object Search boxes or the bookmarks in a camera view, not both.
Views opened before the pipeline started. Boxes do not render in a camera view that was open before the pipeline started. Close the view, stop and start the pipeline, and open the camera again. This is tracked with Network Optix in the developer forum.
One bookmark per loitering row. Loitering events are not throttled: a person who stays in the zone adds about one bookmark per second.
Settings fixed at registration. Adding or removing an app, or changing the
label_mapcategories, needs a new registration.Pipelines are not restarted when an app restarts. If an analytics app restarts, its pipelines stop, but the checkbox stays on. Uncheck and check it again.
Digest authentication. The pipelines need digest authentication for the VAP user.
Troubleshooting#
VAP and Nx Witness#
Symptom |
Cause and fix |
|---|---|
|
VAP cannot reach Nx Witness. Check |
No cameras discovered |
Check the checks in Set Up Nx Witness, Step 6, and that the user can see the cameras. Check |
|
The integration exists in Nx Witness, but VAP’s database has no record of it, for example after |
|
The integration was deleted from Nx Witness. Register the integration again. |
|
The stored integration has no password, so VAP cannot push detections. Register the integration again. |
Integration not in System Administration → Integrations |
Accept API Integrations registration requests is off; see Set Up Nx Witness, Step 5. Turn it on, and register the integration again. |
An app’s group is missing from the camera settings |
The integration was registered before the app was selected. Register the integration again. |
Pipeline and detections#
Symptom |
Cause and fix |
|---|---|
Pipeline fails at once, DL Streamer logs |
Digest authentication is off for the VAP user; see Set Up Nx Witness, Step 4. |
Pipeline fails with RTSP connection errors |
The Nx Witness host is not reachable from the analytics app. If the host uses a proxy, add |
|
Check |
|
Nx Witness reports no resolution for the camera, so the pipeline uses its own default zone. |
No boxes, |
Check that the integration is on for the camera (Camera Settings → Integrations), and that its credentials are stored (no |
No boxes, no MQTT messages |
Check that VAP reaches the broker at |
No boxes, pipeline and MQTT working |
Close the camera view, stop and start the pipeline, and open the camera again; see Limitations. |
No boxes but bookmarks appear, camera has recording on |
Stop and start the pipeline to recover. If recording was just enabled for this camera for the first time, also check Camera Settings → Recording and configure the schedule as desired. A newly enabled schedule is not always configured correctly, and detections are not seen until it is corrected. |
Boxes labelled |
The model’s labels are not in |
Loitering events and captions#
Symptom |
Cause and fix |
|---|---|
No |
Check |
|
|
LVC form does not render in the dashboard |
VAP could not read the LVC schema at startup. Check |
No captions |
Check that the run is active ( |
Dashboard video does not play |
Check |
Register the integration again#
In the Desktop Client, open Main Menu → System Administration → Integrations, and remove VAP Analytics Integration.
Delete VAP’s record of it:
docker compose exec postgres psql -U vms -d vms_plugin -p 5434 \ -c "DELETE FROM nx_analytics_integrations WHERE vms_name = 'nx-main';"
Use your
PG_USERandPG_PORTif you changed them.Restart the backend:
docker compose restart backend
VAP registers the integration again, and logs nx_integration_autoregistered. Turn the
integration on again for each camera.