> This page is for version Dev. > For other versions, use one of these documentation indexes: > - 3.3.0 (default): https://docs.nvidia.com/vss/3.3.0/llms.txt > - Dev: https://docs.nvidia.com/vss/dev/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/vss/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/vss/_mcp/server. # VIOS Microservices ## Overview **Video IO & Storage (VIOS) Microservice** provides an efficient way to manage cameras and videos, especially in scenarios where AI is the main functionality. VIOS features hardware-accelerated video decoding, streaming, and storage. VIOS is easy to integrate with your video analytics application, through its REST API. It also includes a reference web UI for efficient management of your devices. ## Key Features VIOS auto-discovers ONVIF-S compliant IP cameras, and allows use of custom IP stream as video source. It then allows for video to be stored, played back at various speeds, or paused at any frame: 1. Support ONVIF S-profile devices, ONVIF profile-T for H.265 encoding devices, ONVIF discovery with control and data flow. 2. Manage devices manually by IP address and/or RTSP URLs. 3. Video storage and recording with aging policy. 4. RTSP proxy URL in pass-through and multi-cast mode. 5. Media streaming using hardware-accelerated WebRTC and DASH protocols for live and recorded videos. 6. Recorded playback supported with 2x,4x,8x FF, overlay & snapshot support. 7. Supports both H.264 and H.265 video formats. 8. Video wall feature which provides composite view of multiple webrtc streams. 9. Provide REST APIs to write client application to control and configure VIOS. 10. Support Redis/Kafka message bus to publish device add/remove events. 11. Support outbound HTTP webhooks to deliver the same device events to external services (refer to [Notification Config](/system-components/middleware/video-io-storage-vios/vios-microservices#notification-config)). 12. Prometheus/Grafana integration for publishing VIOS statistics. 13. Derive insights about the current status of VIOS. 14. Cloud native. Deploy as a container. 15. Supports milestone adaptor for fetching data from milestone VMS. We included binary for a web-based client that allows to view live and recorded content, as well as to modify camera and stream configuration (Web-UI Viewer). ![VIOS Overview](/vss/_fern-img/a47aff479269623ad5cf2c188c85e0313c6c25bc84a9f128504b9a752966a891.webp) ### VIOS Modular Diagram VIOS is built as a collection of cooperating microservices that together provide a unified platform for video streaming and processing. It integrates RTSP proxying, WebRTC and DASH streaming, recording, and storage into a single solution capable of real-time video ingestion, low-latency playback, and long-term archival. The following diagram illustrates the high-level architecture of VIOS. Each service is responsible for a specific aspect of the system, and the list that follows describes the role of each component. * **Sensor Management Service**: A comprehensive system designed to facilitate the administration and control of sensor-related functionalities. It handles sensor discovery, configuration, and stream management through dedicated sensor services and adaptors, and provides efficient management of sensors across the network. This service exclusively owns the sensor REST API surface — [Sensor Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-sensor-management-api) (prefixed with `/v1/sensor`). * **Unified Stream Processing MS**: A unified microservice that consolidates RTSP proxying, live and replay (recorded) WebRTC/DASH streaming, recording, and media storage into a single service. It handles video stream transformation, file ingestion, content download from ingested files, routing, and protocol conversion for real-time video ingestion, low-latency playback, and long-term archival. It exposes every stream- and media-related REST API in VIOS — [Proxy Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-proxy-stream-management-api) (`/v1/proxy`), [Live Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-live-stream-management-api) (`/v1/live`), [Record Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-record-stream-management-api) (`/v1/record`), [Replay Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-replay-stream-management-api) (`/v1/replay`), and [Storage Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-storage-management-api) (`/v1/storage`) — covering the entire VIOS API surface except the sensor APIs, which are owned by the Sensor Management Service. * **Storage Layer**: Multi-tier storage system supporting Redis for caching, PostgreSQL for metadata, and local filesystem object storage for video content. * **Client Interfaces**: Support for various client types including web applications, perception services, computer vision applications, and the VSS UI. * **Ingress**: A service that handles the ingress of the HTTP requests to the VIOS microservices. * **SDR Agent**: A service that handles the workload distribution and service discovery for the scalable Unified Stream Processing MS instances. * **Envoy**: A service that handles the Envoy proxy for load balancing and routing requests to the scalable Unified Stream Processing MS instances. ![VIOS Modular Diagram](/vss/_fern-img/ca09478c4a2b63e52fa3b0e7a34a47f02d8d350aba393c7907a19d13b3e5b5ff.webp) ### VIOS MS Horizontal Scaling The Unified Stream Processing MS is designed to scale horizontally to handle increased workloads and provide high availability. The Sensor Management Service runs as a single instance and is not part of the horizontal-scaling fleet. **Horizontal Scaling Capabilities:** * **Multiple Stream Processing instances**: Deploy multiple Unified Stream Processing MS replicas behind the SDR Agent and Envoy proxy to distribute the workload. * **Load Distribution**: Camera streams and video processing are distributed across the Stream Processing MS replicas. * **High Availability**: Continuous operation is preserved even if individual Stream Processing MS instances fail. * **Shared Storage**: All Stream Processing MS replicas access the same shared storage backend (local filesystem). * **Centralized Database**: A single PostgreSQL database provides centralized configuration and metadata management shared by all Stream Processing MS replicas and the Sensor Management Service. The diagram below illustrates the horizontal scaling architecture: ![VIOS MS Horizontal Scaling Architecture](/vss/_fern-img/50865ec63a67bf0c75dde6e6ec9551a179036e5bbe1be063c528330d06a56851.webp) ### VIOS Microservices The following table lists the microservices and containers that make up the VIOS Docker Compose deployment.
Microservice Name Container Name Functionality
Postgres `vss-vios-postgres` Centralized PostgreSQL database for sensor configurations, stream metadata, and system state shared across all VIOS services.
Sensor `vss-vios-sensor` Sensor Management Service: handles camera/sensor discovery, registration, configuration, and stream monitoring. Exposes the Sensor Management API ( `/v1/sensor` ).
Unified Stream Processing MS `vss-vios-streamprocessing` Unified Stream Processing MS that consolidates RTSP proxying, live and replay WebRTC streaming, recording, and media storage. Exposes the Proxy ( `/v1/proxy` ), Live ( `/v1/live` ), Record ( `/v1/record` ), Replay ( `/v1/replay` ), and Storage ( `/v1/storage` ) APIs.
Ingress (NGINX) `vss-vios-ingress` NGINX reverse proxy that terminates external HTTP/HTTPS traffic and routes requests to the appropriate VIOS microservices.
SDR `vss-vios-sdr` Sensor Distribution and Routing agent. Handles workload distribution and service discovery for the scalable Unified Stream Processing MS instances.
Envoy Proxy `vss-vios-envoy` Envoy proxy that provides load balancing and routing across the scalable Unified Stream Processing MS instances registered with SDR.
**Notes:** 1\) The container names shown above apply to the Docker Compose deployment of VIOS. 2\) The Sensor and Unified Stream Processing MS share a single container name across all four deployment profile variants. ### Storage Calculation The required storage can be calculated using the following formula: ```text Storage (GB) = (Bitrate (Mbps) × Duration (seconds)) / 8 / 1024 ``` **Example Calculation for 1 stream at 8 Mbps for 1 day:** * Bitrate: 8 Mbps * Duration: 1 day = 24 hours × 60 minutes × 60 seconds = 86,400 seconds * Storage = (8 × 86,400) / 8 / 1024 = **84.375 GB per stream per day** **General Formula:** ```text Storage (GB/day) = Bitrate (Mbps) × 10.546875 ``` For multiple streams, multiply by the stream count: ```text Total Storage (GB) = Number of Streams × Bitrate (Mbps) × Days × 10.546875 ``` > **Note** > > For operational planning, actual storage requirements may vary based on encoding efficiency, variable bitrate settings etc. So add a buffer of \~10–20% to the calculated storage requirements. To configure required storage, set the `total_video_storage_size_MB` parameter in the `vst_storage.json` file, refer to [Storage Config](/system-components/middleware/video-io-storage-vios/vios-microservices#storage-config). ### Cameras Tested in VIOS | Manufacturer | Model | | ------------ | ---------------------- | | ANNKE | C500 | | ANNKE | NC400 | | AMCREST | IP8M-2493EW | | AMCREST | IP8M-T2499E | | AMCREST | IP8M-2496E | | AMCREST | IP2M-841W-V3 | | AMCREST | IP4M-1026E | | AMCREST | IP5M-T1179E | | AXIS | P3301 | | BOSCH | Flexidome_IP_4000I | | CP PLUS | CP-UNC-TB41L3-MDS-0360 | | JIDETECH | IPC-3C1-5MP | | HANWHA | QND-6012R | | HANWHA | QND-6072R | | QSEE | QTN8083B | | QSEE | QTN8098B-N | | SONY | SNV-VB640 | | SONY | SNC-VB770 | | SONY | SNC-XM632 | | SONY | SNC-EM630 | | HIKVISION | DS-2CD2043G0-I | | HIKVISION | DS-2CD2T43G0-I5 | | HIKVISION | DS-2CD2045FWD-I | | HIKVISION | DS-2CD3121G0-I | | HIKVISION | DS-2CD3023G0E-I | ## Usage & Configuration ### Reference Web App Default URL: `http://:30888/vst/` VIOS deployment can be verified using a web-based application binary. Please note: at this point the web-based application is only available for Chrome browser running on Linux, Windows or macOS. The UI can be accessed on any viewing machine on local subnet. The following instructions refer to same host. Substitute 'localhost' with IP address of your viewing machine. 1. Launch Chrome browser 2. In the address bar enter `http://:30888/vst/` The VIOS web-based UI allows for seamless and hassle-free discovery of most ONVIF-S compliant cameras. Although a relatively short list of models are guaranteed to work with VIOS release, any fully ONVIF-S compliant camera you might already have purchased should work with this release as well. Contact us if your cameras are not working. VIOS will auto-discover, and attempt to communicate with any ONVIF-S camera attached downstream of the host. Once discovered, VIOS will attempt to communicate with the camera, to retrieve its settings and parameters, and populate the web UI. There is a good chance that your camera has been secured by a custom username and password prior to the first VIOS use. In such a case (even though the camera would be discovered) VIOS might not be able to communicate with it immediately. This short guide will explain how to ensure that you can see live and recorded content from new or previously used ONVIF-S cameras. #### Dashboard Open a web browser (Chrome is required for best video streaming experience) at `http://:30888/vst/`. Enter `admin` for username and password if prompted otherwise ignore it. The following page will be displayed upon successful login: ![VIOS WebUI Login](/vss/_fern-img/c6a779ae1dcb8655287044336f6468ac3fdfcf7c65427080d3cf80c9f1042f60.webp) As the page opens, it shows overall health of VIOS, information about VIOS Devices, Sensors discovered, Record Size. Also, it shows the vital information about sensors such as Record Status, Sensor Status etc., > **Note** User options like Home, Profile, Settings, etc., are not implemented in current release. #### Sensor management Cameras that had been discovered will be listed. If VIOS discovered the camera, but was not able to communicate with it, the camera status indicates a lock icon. If the lock icon appears, navigate to 'Sensor Management' tab, and click on 'Sensor Credentials' section as displayed in the following image: ![VIOS WebUI Login](/vss/_fern-img/7c0d97f4952de31f3a26eeb555ce87dcfd3ce7d1ea675966e12d00b0be133cce.webp) * It should now be possible to stream from all the cameras attached to VIOS. * If you do not remember your camera's custom username or password, you might need to perform a hardware factory reset for that camera, re-start VIOS, and consult that camera's guide to set its username and password again. * VIOS is now aware of usernames and passwords for all cameras, and is ready to stream live video from the auto-discovered ONVIF-S sources. ##### Add sensors * **Add Cameras/Streams from VIOS webUI:** To manually add camera into VIOS, navigate to **Sensor Management** tab, and go to **Add device manually** option. To Add ONVIF compliant camera using IP option click on IP button then provide ip address, username, password fields. Remaining fields are optional. If you want to add directly RTSP url, click on RTSP option and provide RTSP url, username, password. * **Add Cameras/Streams from NVStreamer:** To add streams from NVStreamer, VIOS provides a mechanism with the help of [RTSP Stream Config](/system-components/middleware/video-io-storage-vios/vios-microservices#rtsp-stream-config) file. You can provide the NVStreamer endpoint. * **Add Cameras/Streams using RTSP URLs:** To add streams from RTSP URLs, VIOS provides a mechanism with the help of [RTSP Stream Config](/system-components/middleware/video-io-storage-vios/vios-microservices#rtsp-stream-config) file. You can provide the RTSP URL, username, password. You can see a screen as displayed in the following image: ![VIOS WebUI camera add.](/vss/_fern-img/182b102616f193bfd4dca17efb44919accc3b1585062257633bcc45af7fd07f0.webp) ##### Remove sensors To remove the sensor from VIOS, navigate to **Sensor Management** tab, and go to **Remove sensor** option. Select the sensor from dropdown list and click on Remove button as displayed in the following image: ![VIOS WebUI camera remove.](/vss/_fern-img/84b23cfa63c6c2d2fd08edf90ccd5259b84460715e9509ac6fd8b309d49adcac.webp) ##### Live streams Navigate back to the **Live Streams** tab, click on the center drop-down list, and select the first camera on the list. A black rectangle will appear on the UI, and the camera's IP address will be displayed on top of the drop-down list. Repeat the same with up to max cameras supported. You should see a screen similar to the following: ![VIOS WebUI camera stream.](/vss/_fern-img/d140443d7c71dc7c550b4dae0273607c2f211d8bf84aa10496873118dae0281d.webp) > **Note** > > * It can take a few seconds for the VIOS to commence live streaming. If you see a constantly revolving crescent for a prolonged amount of time - please try to restart the browser. > * VIOS has been tested extensively with Chrome and we are aware of existing problems while streaming through alternative browsers. #### Recording management ##### Setting Now that you are able to stream live video, it is time to try out recording. Navigate to the **Record Setting** tab, and select camera from drop down list: > **Note** All recordings will be saved to your local storage; older recordings will be overwritten with newer ones automatically should VIOS run out of the disk space. ![VIOS WebUI camera record setting.](/vss/_fern-img/32cc9257812955d26134acc774564a131aa90254cb88bbf6205d211f19879ad2.webp) ##### Playback recordings Now that you are able to record video, it is time to try out recorded playback feature of VIOS. To playback the recordings, navigate to **Recorded Streams** tab and select a video stream. Some options: * It provides options such as pause, fast playback 2x,4x,8x etc. * Snapshot option to take screenshot of currently playing frame. * Other options like overlay, time-range playback, quality selection etc. ![VIOS Recorded Playback](/vss/_fern-img/7616599f16940d11bb1e5d383ad5af585800c62efafb6e6762c9edfee3a8be4a.webp) ##### Playback overlay on Live and Recorded Streams Now that you are able to playback recorded video, it is time to try out Overlay Feature of VIOS in Live and Recorded Streams. To enable bounding boxes on the video, navigate to **Recorded Streams** tab or **Live Streams** tab and select a video stream then select overlay option from the video player and enable it. Some options: * **Analytics Overlay Settings** tab is used to enable / disable Bounding Boxes, Debug Mode * **Proximity Settings** tab is used to set the proximity classes and entrant classes of the objects, along with the area factor and proximity animation. * **Color Settings** tab is used to set the color of the bounding boxes for different object classes also the proximity bubble colors. ![VIOS Overlay Settings](/vss/_fern-img/6464a9d26cfc57d54d3ae41857c9fd729e2bcbf3e99f909aa092c693b78a9789.webp) ![VIOS Overlay Settings](/vss/_fern-img/81c4c81412de90074d2d570ab38d544b5c38a9fc1d6ac4cdcb18311107cd82f4.webp) ![VIOS Overlay Live Video](/vss/_fern-img/5f61bcae0637d8f2712df26f45f6593b64dade75c7d57416351ca29109c5acfd.webp) ##### Display Object IDs in Warehouse Profiles Enable the video player's analytics overlay, then open **Analytics Overlay Settings**. Object ID display depends on the warehouse profile: | Warehouse Profile | Object ID Display Settings | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 2D and 2D with Agents | Enable **Show Bounding Boxes** and **Show Object ID** under **Object ID Display**. Debug Mode is optional and adds diagnostic overlays. | | 3D and MV3DT | Object IDs are displayed by default when **Debug Mode** is enabled. | Click **Save Settings** to apply the changes. In the 2D settings, leave **Specific Object IDs** empty to show all objects, or enter a comma-separated list to filter the displayed objects. ![VST Analytics Overlay Settings with Show Bounding Boxes and Show Object ID enabled for a warehouse 2D profile](/vss/_fern-img/215ce395ba651943eed05c543b7daed1db3724271165488c77b1da0c4d1887a7.webp) ##### Playback overlay on Video Wall Now that you are able to enable Overlay Feature of VIOS in Live and Recorded Streams, it is time to extend the Overlay Feature of VIOS in Video Wall. To enable bounding boxes on the video, navigate to **Video Wall** tab and select streams from the dropdown list and enable overlay option from the video player and enable it. For warehouse object ID display settings, see [Display Object IDs in Warehouse Profiles](#display-object-ids-in-warehouse-profiles). Some options: * **Analytics Overlay Settings** tab is used to enable / disable Bounding Boxes, Debug Mode, Include Floor Plan and setting the thickness of the bounding boxes. * **Proximity Settings** tab is used to set the proximity classes and entrant classes of the objects, along with the area factor and proximity animation. * **Color Settings** tab is used to set the color of the bounding boxes for different object classes also the proximity bubble colors. Features: * **Proximity Alert Bubble** : a proximity bubble is drawn around the object of `Proximity class`, the color of the bubble changes according to the distance of the object from the `Entrant class` object. The default color of the bubble is **green** marking as safe zone and turns **orange** when the object is in the close proximity of the threshold and turns **red** when the object is in the danger zone. * **Proximity Alert Line** : when an object is in the close proximity of the threshold or in the danger zone, a proximity line with approximate distance is drawn between the object of `Proximity class`, and the object of `Entrant class`. ![VIOS Overlay Settings](/vss/_fern-img/1eee4572567759e2307f504cb4323e8863e417148d1052bbd3d57df7bdaccafc.webp) ![VIOS Overlay Settings](/vss/_fern-img/a59a1b4ddad6778cdcca5cb4ba883944284d064e270458edbc3ad0907fc0c6f0.webp) ##### Proximity Alert Bubble and Lines in Video Wall ![VIOS Overlay Live Video](/vss/_fern-img/b0617277cceda3b9146634a1528e440e5a885526c24c6e6b1014788c6918c893.webp) ##### Proximity Alert Bubble and Line in Live Stream ![VIOS Overlay Live Video](/vss/_fern-img/860acbb660a792152689e2584c4bdb3caff94d7e56bb6f1f587e9777cef6a4f8.webp) ##### Floor Plan in Video Wall To display a floor plan in the Video Wall, enable **Include Floor Plan** in the Analytics Overlay Settings. Set the floor plan image path in `vst_config.json` using the `floor_map_file_path` field. The supported image formats are PNG, JPEG, and SVG. ![VIOS Overlay Floor Plan in Video Wall](/vss/_fern-img/5ab8b23c6f43c17c95627ce4b152232c02ac3bfb959c75e2f1696bc501f2af16.webp) ##### Upload media To upload media, navigate to **Upload Media** option in **Media Management** tab. You can drag and drop files or choose files to be uploaded with several optional configurations: * **Transcode**: Enable video transcoding if needed * **Metadata Info**: Add metadata information such as: * Sensor ID * Timestamp * Event Info * Stream Name * Tag * Checksum * **Enable multi-part upload**: Enable this option for large file uploads ![VIOS WebUI Upload Media](/vss/_fern-img/2ba1016d83f0a6eef0bc8590fe4f1535bc85dca03f0d3a392f1c0fb563951c6a.webp) ###### Configuring upload file size limit The maximum upload file size in VIOS is controlled by two settings. The effective upload limit is the **minimum** of these two values, so both must be configured to allow larger uploads. 1. **Stream-processor NGINX configuration** (`client_max_body_size`): Controls the maximum request body size accepted by the NGINX reverse proxy in the stream-processor. The default value is 500 MB. To allow larger uploads (for example, 10–20 GB), increase this value before deployment: ```nginx client_max_body_size 20G; ``` 2. **VIOS configuration** (`nv_streamer_max_upload_file_size_MB`): Controls the maximum file size accepted for upload in both VIOS and NVStreamer. The default value is 1000 MB. To allow larger uploads, set this parameter in the `data` section of the VIOS configuration file (refer to [VIOS Config](/system-components/middleware/video-io-storage-vios/vios-microservices#vios-config)): ```json { "data": { "nv_streamer_max_upload_file_size_MB": 10000 } } ``` > **Note** > > Both settings are configurable pre-deployment. Set them according to your upload size requirements. The effective upload limit is determined by whichever value is lower. ##### Download recordings To download recorded video, select **Download videos** option in **Media Management** tab. Then choose the device and corresponding timeline. > **Note** > > * In case video download fails then you need to redeploy the VIOS with VST_INSTALL_ADDITIONAL_PACKAGES set to true ![VIOS WebUI Download Option](/vss/_fern-img/c4c3fce47e0a02d4225e33bd2abe4761bd6cc2276760eec957bd1bc7ae602deb.webp) ##### Storage utilization You can examine the amount of disk space used by clicking on **Dashboard** tab: ![VIOS WebUI diskspace](/vss/_fern-img/2e1f5105d6a7d7c4eaa55ba81c6ffc35c09b6fabf61c45ed52ef026741cb78b7.webp) #### Configuration The active VIOS configuration can be viewed from the **Settings** tab: ![VIOS WebUI VIOS Settings](/vss/_fern-img/039e5e575b43b1b132fba048fc269eeb5c6724d54074641d7e97342e4669f734.webp) #### Experimental Finally, the **Experimental** tab will allow you to create and examine a debug package. It will come handy if you ever need to contact us. Enjoy the VIOS experience! ![VIOS WebUI Experimental tab](/vss/_fern-img/f793e1736254cce2fdc981afd392b679936e23e3bfb2bdb61cd835cc1d4a54e5.webp) #### Milestone VMS **What is Milestone VMS?** Milestone XProtect is a professional Video Management System (VMS) that provides centralized management of IP cameras and video streams. VIOS integrates with Milestone VMS through the ONVIF Bridge, enabling seamless access to cameras managed by Milestone. **Using Milestone VMS with VIOS** VIOS uses the Open Network Video Interface Forum (ONVIF) Bridge and AI Bridge from Milestone VMS to provide the following capabilities: * Retrieve RTSP live and Video on Demand (VOD) RTSP streams from Milestone VMS * Play live and VOD video streams * Download Video clips * Capture snapshots (download pictures) **Milestone VMS Configuration** To configure VIOS in MMS (Milestone Management System) mode, you need to: **Step 1: Adaptor Configuration** Add the following adaptor configuration to enable Milestone VMS integration (refer to [Adaptor Config](/system-components/middleware/video-io-storage-vios/vios-microservices#adaptor-config) for complete configuration details): ```json { "enabled": true, "id": "", "name": "milestone_onvif", "type": "mms", "ip": "", "user": "", "password": "", "port": "580", "need_rtsp_server": true, "need_stream_monitoring": true, "need_recording": true, "need_storage_management": true, "control_adaptor_lib_path": "prebuilts/arch/onvif_client.so", "media_adaptor_lib_path": "prebuilts/arch/vms_media.so" } ``` **Configuration Parameters:** * **enabled**: Set to `true` to enable the adaptor * **id**: Unique identifier for the adaptor (UUID format) * **name**: Name of the adaptor (e.g., `"milestone_onvif"`) * **type**: Set to `"mms"` for Milestone VMS integration * **ip**: IP address of the Milestone XProtect server * **user**: ONVIF username configured in Milestone * **password**: ONVIF password for authentication * **port**: Port number for ONVIF communication (typically `"580"`) * **need_rtsp_server**: Enable RTSP server for video streaming * **need_stream_monitoring**: Enable stream health monitoring * **need_recording**: Enable recording capabilities * **need_storage_management**: Enable storage management features * **control_adaptor_lib_path**: Path to the ONVIF client control library * **media_adaptor_lib_path**: Path to the VMS media library **Environment Variables for Deployments Using Milestone VMS** For deployments using Milestone VMS, set the following environment variables: ```bash VST_ADAPTOR=milestone_onvif NGINX_MODE=mms ADAPTOR_IP="" ADAPTOR_USER="" ADAPTOR_PASSWORD="" AI_BRIDGE_ENDPOINT="" ``` **Step 2: AI Bridge Endpoint Configuration** Add the AI Bridge endpoint to the network section of your VIOS configuration (refer to [VIOS Config](/system-components/middleware/video-io-storage-vios/vios-microservices#vios-config) for complete configuration details): ```json { "ai_bridge_endpoint": "http://:/api/bridge/graphql" } ``` **Step 3: (Optional) Add AI Bridge Domain to Hosts File** If the AI Bridge domain is not resolvable via DNS, add an entry to the `/etc/hosts` file: ```bash ``` Once configured, VIOS will connect to Milestone VMS through the ONVIF Bridge and provide access to all cameras and recordings managed by the VMS. ### Remote Access Options #### Installation of STUN / TURN Server Installation and configuration of these servers are mandatory for WebRTC streaming. Below are the NAT type requirements for STUN/TURN: | Case | NAT types | STUN/TURN requirement | | ---- | ------------------------------------ | -------------------------------- | | 1 | Symmetric to Symmetric | TURN | | 2 | Symmetric to Port-Restricted Cone | TURN | | 3 | Symmetric to Address-Restricted Cone | STUN (but probably not reliable) | | 4 | Symmetric to Full Cone | STUN | | 5 | Everything else | STUN | Depending on your network type, you may choose to install STUN and/or TURN servers: * You can set the STUN server using `stunurl` config parameter. * You can set the TURN server using `turnurl` config parameter. VIOS web UI is verified with [coturn](http://github.com/coturn/coturn) server. To install, run the following command: ``` sudo apt-get install coturn ``` > **Note** > > TURN server is not mandatory, this is required only if Client and Server are in different networks. * VIOS configuration details can be found here: [VIOS Config](/system-components/middleware/video-io-storage-vios/vios-microservices#vios-config). * VIOS Storage Config details can be found here: [Storage Config](/system-components/middleware/video-io-storage-vios/vios-microservices#storage-config). * VIOS Notification Config details can be found here: [Notification Config](/system-components/middleware/video-io-storage-vios/vios-microservices#notification-config). * RTSP streams config file details can be found here: [RTSP Stream Config](/system-components/middleware/video-io-storage-vios/vios-microservices#rtsp-stream-config). ### VIOS Config Following table describes the parameters in VIOS config file, which should be provided as command-line option deploying helm chart: **VIOS config file** | Key | Description | Typical Value | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **network** | **Section to define all Network related parameters** | | | server_domain_name | Server domain name | vst-service | | stunurl_list | STUN server address | \["stun.l.google.com:19302"] | | static_turnurl_list | TURN server address | \[] | | coturn_turnurl_list_with_secret | Coturn Turnurl list with secret | \[] | | use_coturn_auth_secret | Enable/Disable Coturn Auth secret | FALSE | | use_twilio_stun_turn | Enable/Disable Twilio | FALSE | | twilio_account_sid | Twilio Account Sid | `'""'` | | rx_socket_buffer_size | RX socket buffer size | 1000000 | | tx_socket_buffer_size | TX socket buffer size | 1000000 | | twilio_auth_token | Auth token for Twilio | `'""'` | | ntp_servers | NTP server address | \["time.google.com"] | | use_sensor_ntp_time | If true then forward camera/nvstreamer ntp time in SR reports to the clients. Otherwise provide current ntp time in SR report. | TRUE | | max_webrtc_out_connections | Max number of webrtc output connections at a given time | 8 | | webservice_access_control_list | An Access Control List allows restrictions to be put on the list of IP addresses which have access to the web server. The ACL is a comma separated list of IP subnets, where each subnet is pre-pended by either a - or a + sign. A plus sign means allow, where a minus sign means deny. If a subnet mask is omitted, such as -1.2.3.4, this means to deny only that single IP address. | +10.42.0.0/32 | | rtsp_server_port | User given rtsp port number | 8554 | | rtsp_preferred_network_iface | Preferred network interface for RTSP streaming | eth1 | | rtsp_streaming_over_tcp | Enable / Disable RTSP Streaming over TCP | FALSE | | rtsp_server_reclamation_client_timeout_sec | Timeout for RTSP Server reclamation client | 10 | | stream_monitor_interval_secs | Stream Monitor interval in seconds | 2 | | webrtc_latency_ms | Latency for webrtc in milliseconds | 500 | | enable_frame_drop | Enable/Disable frame drop | TRUE | | webrtc_video_quality_tunning | webRTC video quality tuning | `{"resolution_2160":{"bitrate_start":20000,"bitrate_range":[15000,25000],"qp_range_I":[0,30],"qp_range_P":[0,51]},"resolution_1440":{"bitrate_start":10000,"bitrate_range":[8000,15000],"qp_range_I":[10,30],"qp_range_P":[10,30]},"resolution_1080":{"bitrate_start":5000,"bitrate_range":[3000,8000],"qp_range_I":[10,30],"qp_range_P":[10,30]},"resolution_720":{"bitrate_start":3000,"bitrate_range":[2000,5000],"qp_range_I":[10,30],"qp_range_P":[10,30]},"resolution_480":{"bitrate_start":1000,"bitrate_range":[800,3000],"qp_range_I":[10,30],"qp_range_P":[10,30]}}` | | webrtc_peer_conn_timeout_sec | Timeout duration in seconds for peer connection establishment | 10 | | remote_vst_address | Cloud VIOS Address | 13.0.0.1:30000 | | webrtc_port_range | Min and Max Port Range for WebRTC | `''{"min": 0, "max": 0}''` | | enable_websocket_pingpong | Enable/Disable websocket ping pong messages | FALSE | | websocket_keep_alive_ms | Timeout for websocket to keep alive | 5000 | | ai_bridge_endpoint | AI Bridge endpoint URL | `''http://:/api/bridge/graphql''` | | dash | Section to define all DASH streaming parameters, nested under `network` | | | max_live_sessions | Maximum number of concurrent DASH sessions, live and replay combined | 8 | | segment_duration_sec | Target media segment length in seconds, which is also the manifest update period, i.e. how often a player re-fetches the MPD | 2 | | playlist_length | Number of entries the muxer keeps in its playlist | 8 | | idle_timeout_sec | Inactivity timeout after which a session is closed and its segments deleted. Refreshed by every manifest or segment request. | 45 | | output_root | Output directory for manifests and segments, relative to the webroot | dash | | bitrate_kbps | Encoder target bitrate. 0 derives it from picture height (2000/5000/10000/20000 kbps for below 1080p/1080p/1440p/2160p). | 0 | | always_encode | Encode every session instead of republishing the source bitstream, so VIOS controls the segment length rather than inheriting the camera's keyframe interval | TRUE | | **onvif** | **Section to define all ONVIF related parameters** | | | device_discovery_timeout_secs | Device discovery timeout to receive probe match message from device | 10 | | onvif_request_timeout_secs | Timeout to receive ONVIF command response from device | 10 | | device_discovery_freq_secs | device discovery frequency in secs | 15 | | device_discovery_interfaces | Network interface for device discovery e.g eth0, eth1 | \[] | | max_devices_supported | Limiting maximum number of devices | 16 | | onvif_sensor_time_sync_interval_secs | Interval in seconds for syncing time between the ONVIF sensor and VIOS | 60 | | onvif_sensor_time_sync_compensation_ms | Compensation in milliseconds applied to time-sync requests with the ONVIF sensor | 20 | | **data** | **Section to define all VIOS data related parameters** | | | storage_config_file | Path to storage configuration JSON file | ./configs/vst_storage.json | | storage_threshold_percentage | % value of storage occupancy when aging policy triggers | 95 | | storage_monitoring_frequency_secs | Monitor storage usage with frequency in seconds | 2 | | supported_video_codecs | Video codec supported for video recording | \["h264","h265"] | | supported_audio_codecs | Audio codec supported for audio recording and decode | \["pcmu","pcma","mpeg4-generic"] | | nv_streamer_max_upload_file_size_MB | Maximum file upload size in MB. Applicable for file upload in both VIOS and NVStreamer. | 1000 | | max_video_download_size_MB | Limiting the maximum video download size | 1000 | | always_recording | Enable/Disable always ON recording | FALSE | | use_software_path | Enable allows processing on CPU otherwise on GPU | FALSE | | webrtc_sender_quality | webrtc input quality | pass_through | | enable_rtsp_server_sei_metadata | Enable SEI support for rtsp server | TRUE | | enable_proxy_server_sei_metadata | Enable SEI support for proxy server | TRUE | | gpu_indices | GPU indices | \[] | | webrtc_out_enable_insert_sps_pps | webRTC Out Enable / Disable SPS PPS insertion | TRUE | | webrtc_out_set_iframe_interval | webRTC Out set I-Frame Interval | 30 | | webrtc_out_set_idr_interval | webRTC Out set IDR Interval | 256 | | webrtc_out_min_drc_interval | webRTC Out minimum interval between DRC requests | 5 | | device_name | Device Name for edge VIOS | VST_EDGE | | device_location | Device Location for edge VIOS | 6th_Floor | | enable_dec_low_latency_mode | Enable/Disable low latency in decoder | FALSE | | use_centralize_local_db | Enable/Disable Centralized local db | TRUE | | restore_rtsp_streams_on_startup | When enabled, on container startup previously configured RTSP proxy streams are re-read from the central database and re-registered on the RTSP server, so that previously added streams survive restarts. | TRUE | | max_network_db_connections | Maximum number of connections to the centralized network database | 10 | | default_file_expiry_minutes | Default file expiry time in minutes (e.g., 60 = 1 hour) | 60 | | download_files_timeout_secs | Timeout in seconds for video download operations | 120 | | picture_api_timeout_secs | Timeout in seconds for picture (snapshot) API operations | 20 | | **debug** | **Section to define all Debug related parameters** | | | enable_perf_logging | Enable/Disable perf logging | TRUE | | enable_qos_monitoring | Enable/Disable QOS logging | TRUE | | qos_logfile_path | QOS log file path | /root/vst_release/webroot/log/ | | qos_data_capture_interval_sec | QOS log capture interval | 1 | | qos_data_publish_interval_sec | QOS log publish interval | 5 | | enable_gst_debug_probes | Enable/Disable gstreamer probes | TRUE | | enable_prometheus | Enable/Disable stats update on prometheus | FALSE | | prometheus_port | prometheus port number | 8080 | | enable_highlighting_logs | Enable certain logs highlighting by special colors | TRUE | | enable_debug_apis | Enable/Disable Debug apis | TRUE | | dump_webrtc_input_stats | Enable/Disable webRTC IN stats | FALSE | | enable_frameid_in_webrtc_stream | Enable/Disable frameid in webRTC Stream | FALSE | | enable_network_bandwidth_notification | Enable/Disable network bandwidth notification | FALSE | | enable_latency_logging | Enable/Disable latency logging | FALSE | | update_record_details_in_sec | Update record details in seconds | 70 | | **overlay** | **Section to define all overlay related parameters** | | | video_metadata_server | Server to fetch Metadata from | 10.0.0.1:9200/mdx-raw\* | | video_metadata_query_batch_size_num_frames | Size of metadata to fetch | 300 | | video_metadata_query_max_threads | Maximum concurrent Elasticsearch slice queries used to prefetch overlay metadata for downloads (clamped from 1 to 10) | 2 | | video_metadata_wait_timeout_ms | Per-frame wait for in-flight overlay metadata during video downloads, in milliseconds | 1000 | | use_video_metadata_protobuf | Use Protobuf spec for metadata parsing | TRUE | | enable_gem_drawing | Enable/Disable GEM drawing | TRUE | | calibration_file_path | Path to calibration file | /home/vst/vst_release/configs/calibration.json | | calibration_mode | Calibration mode | synthetic | | use_camera_groups | Enable/Disable camera groups | TRUE | | enable_recentering | Enable/Disable recentering | FALSE | | floor_map_file_path | Path to floor map file | /home/vst/vst_release/configs/Top.png | | 3d_overlay_sensor_name | 3D overlay sensor name | bev-sensor-1 | | bbox_tolerance_ms | Bounding box tolerance in milliseconds | 0 | | analytic_server_address | Analytic server address | | | overlay_color_code | Overlay color code | | | halo_safety_udp_port | UDP port for halo safety communication | -1 | | halo_safety_proximity_class | Proximity class for halo safety detection | Forklift | | halo_safety_active_text | Text displayed in halo safety active mode | Standard Mode | | halo_safety_active_text_color | Text color in halo safety active mode | black | | halo_safety_active_text_bg_color | Background color for text in halo safety active mode | white | | halo_safety_inactive_text | Text displayed in halo safety inactive mode | Efficient Mode | | halo_safety_inactive_text_color | Text color in halo safety inactive mode | green | | halo_safety_inactive_text_bg_color | Background color for text in halo safety inactive mode | white | | halo_safety_text_size | Text size for halo safety display | 16 | | overlay_text_font_type | Font type used for overlay text rendering | DejaVuSansMono.ttf | | enable_overlay_skip_frame | Enable/Disable frame skipping in the overlay rendering pipeline | FALSE | | **security** | **Section to define all security related parameters** | | | use_https | Enable/Disable https | FALSE | | use_rtsp_authentication | Enable/Disable RTSP proxy stream authentication | TRUE | | use_http_digest_authentication | Enable/Disable HTTP user authentication | TRUE | | nv_org_id | NGC ORG ID | ngc_org_id | | nv_ngc_key | NGC Key | ngc_key | | **observability** | **Section to define all observability / telemetry parameters** | | | enable_telemetry | Enable/Disable OpenTelemetry tracing | FALSE | | otlp_endpoint | OTLP endpoint URL for OpenTelemetry trace export | [http://localhost:4318/v1/traces](http://localhost:4318/v1/traces) | > **Note** > > When the Unified Stream Processing MS is scaled to multiple replicas, set `restore_rtsp_streams_on_startup` to `false`. Otherwise, on container restart or redeploy every replica will independently re-read the previously configured RTSP proxy streams from the central database and re-register them on the RTSP server, resulting in duplicate registrations and conflicts across replicas. Leave it set to `true` only when running a single Stream Processing replica. ### Notification Config Following table describes the parameters in VIOS notification config file (`configs/notification_config.json`): **VIOS notification config file** | Key | Description | Typical Value | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | **message_broker** | **Section to define all message broker notification parameters** | | | enable_notification | Enable notification of device events on message broker | FALSE | | use_message_broker | Message Broker to use (Kafka/Redis) | kafka | | message_broker_topic | Topic/event used in message broker | vst.event | | enable_notification_consumer | Enable/Disable notification consumer | TRUE | | use_message_broker_consumer | Message Broker to use (Kafka/Redis) | kafka | | message_broker_topic_consumer | Topic/event used in message broker | mdx-bev | | message_broker_payload_key | Payload key used in message broker | sensor.id | | redis_server_env_var | Redis server address:port | REDIS_SVC_SERVICE_HOST:6379 | | kafka_server_address | Kafka server address and port | 10.0.0.1:9092 | | message_broker_metadata_topic | Topic used by the message broker for metadata events | mdx-raw | | mqtt_broker_address | MQTT broker address used for notifications | tcp\://172.17.0.1:1883 | | **webhooks** | **Section to define all outbound HTTP webhook parameters** | | | enabled | Master switch for the webhook notifier. When FALSE, no webhook is loaded or delivered, regardless of the per-webhook `enabled` flags. | FALSE | | items | Array of webhook definitions. Each entry is described in the table below. | \[] | #### Webhooks Webhooks deliver the same device notifications VIOS publishes on the message broker to arbitrary HTTP endpoints, so an external service can react to camera events without subscribing to Redis, Kafka, or MQTT. The two delivery paths are independent. The message broker is enabled by `message_broker.enable_notification` and webhooks by `webhooks.enabled`, and either, both, or neither may be active. Each path keeps its own queue and worker thread, so a slow or unreachable webhook endpoint does not delay publishing on the broker. When an event is raised, it is matched against every entry in `webhooks.items[]`. An entry matches when its trigger key names the event's alert type and the configured value matches the corresponding event field: `"camera_status_change": "camera_add"` fires only on camera-add events. Every matching entry then delivers to all of the receivers in its `request[]` array, so one event can reach several endpoints. A receiver's `camera_type` list narrows this further, skipping delivery when the event's camera type is not listed. Delivery is asynchronous. Each receiver is attempted, retried, and given up on independently, following its own `timeout_ms` and `retry` settings, so one failing endpoint does not hold up or fail the others. By default the request body is the notification event as JSON, with the entry's `id` added as a `webhook_id` field. Setting `user_defined_metadata` merges extra fields into that body's `event.metadata` object, and setting `body` replaces the whole body with a rendered template. Header and query parameter values may also reference event fields using the `{{event.}}` form. **`webhooks.items[]` — webhook definition** | Key | Description | Typical Value | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | enabled | Enable/Disable this individual webhook | FALSE | | id | Unique identifier for the webhook, used in log messages | webhook-camera-add-id | | camera_status_change | Camera status event this webhook fires on. One of `camera_add`, `camera_streaming`, or `camera_remove`. | camera_add | | request | Array of receivers this webhook delivers to. Each entry is described in the table below. | \[] | | auth | Authentication block, for example `{"type": "hmac-sha256", "secret": "{{secrets.signing_key}}", "header_name": "X-VIOS-Signature"}`. Reserved for future use; requests are currently sent unsigned and a warning is logged when `type` is set. | `{}` | **`webhooks.items[].request[]` — receiver definition** | Key | Description | Typical Value | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | url | Destination URL for the HTTP request. Required; the receiver is skipped if missing. | `http://127.0.0.1:18088/webhooks/camera/add` | | method | HTTP method used for the request. Required; the receiver is skipped if missing. | POST | | headers | HTTP headers sent with the request. A value is either literal text or a whole-value `{{event.}}` placeholder that copies a field from the event. Placeholders that cannot be resolved cause the header to be omitted. | `{"Content-Type": "application/json", "x-stream-id": "{{event.camera_id}}"}` | | query_params | Query parameters appended to the URL. Uses the same literal-or-`{{event.}}` value form as `headers`. | `{"change": "{{event.change}}"}` | | camera_type | Only deliver to this receiver when the event's camera type is in this list. Omit the key to deliver for every camera type. | \["rtsp", "file"] | | timeout_ms | Per-request timeout in milliseconds | 10000 | | retry.max_attempts | Maximum number of delivery attempts, including the first. Values below 1 are clamped to 1. | 1 | | retry.backoff_ms | Delay in milliseconds before each retry. The last entry is reused if there are more retries than entries; an empty list falls back to 1000 ms. | \[1000, 5000, 15000] | | retry.retry_on_status | HTTP status codes that trigger a retry. An empty or absent list retries on any non-2xx response. | \[408, 429, 500, 502, 503, 504] | | user_defined_metadata | Arbitrary JSON object whose keys are merged into the `event.metadata` object of the default notification body, not into the body's top level. Receivers must read these fields from `event.metadata`. Ignored when `body` is set. | `{"model": "some_model_name", "chunk": 123}` | | body | Optional custom JSON body template. When absent, the default notification body is sent. When present, the rendered template is the complete request body, so default fields and `user_defined_metadata` are not added. Presence, not emptiness, selects custom rendering: `body: {}` sends `{}`. | `{"query": {"term": {"sensor.id.keyword": "{{event.camera_id}}"}}}` | #### Custom body templates A `body` value is a JSON template. Any string whose complete value has the form `{{path.to.value}}` is replaced with the value at that path in the notification, for example `{{alert_type}}`, `{{created_at}}`, or `{{event.camera_id}}`. The original JSON type is preserved, so a number stays a number and an object stays an object. A well-formed placeholder whose path is not present in the notification renders as an empty string (`""`). Braces are reserved. A string containing `{{` or `}}` must be exactly a full-wrap placeholder. An embedded placeholder such as `camera-{{event.camera_id}}`, an unterminated placeholder, or braces in an object property name are configuration errors. Templates nested deeper than 32 levels are also invalid. Invalid receiver entries are skipped at config load with a log line naming the webhook and receiver; valid sibling receivers continue to load and deliver. **Example** ```json { "webhooks": { "enabled": true, "items": [ { "enabled": true, "id": "camera-remove-cleanup", "camera_status_change": "camera_remove", "request": [ { "url": "http://elasticsearch:9200/mdx-embed/_delete_by_query", "method": "POST", "headers": { "Content-Type": "application/json" }, "query_params": { "conflicts": "proceed", "refresh": "true" }, "camera_type": ["rtsp", "file"], "timeout_ms": 5000, "retry": { "max_attempts": 3, "backoff_ms": [1000, 5000, 15000], "retry_on_status": [408, 429, 500, 502, 503, 504] }, "body": { "query": { "term": { "sensor.id.keyword": "{{event.camera_id}}" } } } } ] } ] } } ``` ### Adaptor Config Following table describes the parameters in VIOS adaptor config file: **VIOS adaptor config file** | Key | Description | Typical Value | | ------------------------ | -------------------------------------------------- | ------------------------------------ | | enabled | Enable/Disable the adaptor | true | | id | Unique identifier for the adaptor | 8ada39c7-5e93-43c5-ae5e-21451c8a8d1b | | name | Name of the adaptor | milestone_onvif | | type | Type of the adaptor (e.g., mms) | mms | | ip | IP address of the adaptor server | `` | | user | Username for adaptor authentication | `` | | password | Password for adaptor authentication | `` | | port | Port number for adaptor connection | 580 | | need_rtsp_server | Enable/Disable RTSP server for this adaptor | true | | need_stream_monitoring | Enable/Disable stream monitoring for this adaptor | true | | need_recording | Enable/Disable recording for this adaptor | true | | need_storage_management | Enable/Disable storage management for this adaptor | true | | control_adaptor_lib_path | Path to the control adaptor library | prebuilts/arch/onvif_client.so | | media_adaptor_lib_path | Path to the media adaptor library | prebuilts/arch/vms_media.so | ### Storage Config Following table describes the parameters in VIOS storage config file: **VIOS storage config file** | Key | Description | Typical Value | | --------------------------- | ------------------------------------------------------ | ------------- | | data_path | Path where VIOS related data files are created | ./vst_data/ | | video_path | Path to root folder where recorded videos to be stored | ./vst_video/ | | total_video_storage_size_MB | Total size available to store recorded videos | 1000000 | ### RTSP Stream Config Following table describes the parameters in RTSP Streams config file: **RTSP Streams config file** | Key | Description | Typical Value | | ---------------- | ----------------------------------- | ----------------------------------------- | | **streams** | **Array of streams in JSON format** | `'""'` | | enabled | Enable / Disable stream | TRUE / FALSE | | stream_in | Actual RTSP URL of camera | `'"rtsp://admin:admin@10.xx.xx.xx/h264"'` | | name | Stream Name | Camera_Front_Door | | Nvstreamer | Nvstreamer configuration | | | enabled | Enable / Disable Nvstreamer | TRUE / FALSE | | endpoint | Nvstreamer endpoint | `'"localhost:31000"'` | | api | Nvstreamer API | `'"/api/v1/sensor/streams"'` | | max_stream_count | Maximum number of streams | 4 | ``` { "streams": [ { "enabled":false, "stream_in":"rtsp://admin:admin@10.xx.xx.xx/h264", "name":"Camera_1" }, { "enabled":false, "stream_in":"rtsp://admin:admin@10.xx.xx.xx/h265", "name":"Camera_2" } ], "Nvstreamer": [ { "enabled": false, "endpoint": "10.xx.xx.xx:31000", "api": "/api/v1/sensor/streams", "max_stream_count": 4 }, { "enabled": false, "endpoint": "10.yy.yy.yy:31000", "api": "/api/v1/sensor/streams", "max_stream_count": 4 } ] } ``` ## APIs VIOS microservice API documentation can be found in the following VIOS API references: * [Sensor Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-sensor-management-api) * [Live Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-live-stream-management-api) * [Replay Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-replay-stream-management-api) * [Record Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-record-stream-management-api) * [Proxy Stream Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-proxy-stream-management-api) * [Storage Management API](/system-components/middleware/video-io-storage-vios/vst-api-reference/vst-storage-management-api) ## Components & Customization ### Adaptor Architecture ![Adaptor architecture](/vss/_fern-img/ca09478c4a2b63e52fa3b0e7a34a47f02d8d350aba393c7907a19d13b3e5b5ff.webp) Adaptor architecture has 3 interfaces. All the interfaces can be loaded automatically by the Adaptor loader in VIOS microservices — the Sensor Management Service (for sensor discovery and control adaptors) and the Unified Stream Processing MS (for media and storage adaptors). #### 1) Device Discovery Interface This adaptor interface is used to discover devices, for example, ONVIF Protocol or UPnP Protocol: * A new Device Discovery Adaptor should implement ***ISensorDiscoveryInterface*** Class (refer to the `include/sensor_discovery_adaptor.h` header file from VIOS container) * Implement the following methods to create and destroy adaptor object: ``` typedef ISensorDiscoveryInterface* createDiscoveryObject(); typedef void destroyDiscoveryObject ( ISensorDiscoveryInterface* object ); ``` #### 2) Device Control Interface This adaptor interface controls the devices, for example, ONVIF Control Protocol: * A new Device Control Adaptor should implement `ISensorControlInterface` Class (refer to the `include/sensor_control_adaptor.h` header file from VIOS container) * Implement the following methods to create and destroy adaptor object: ``` typedef ISensorControlInterface* createObject(); typedef void destroyObject( ISensorControlInterface* object ); ``` #### 3) Milestone Media Interface This adaptor interface to get media(snapshot and video recordings) from Milestone VMS using grpc protocol: * A new Milestone Media Adaptor should implement `IMediaInterface` Class (refer to the `include/vms_media_interface.h` header file from VIOS container) * Implement the following methods to get media(snapshot and video recordings) from Milestone VMS server using grpc protocol: ``` typedef IMediaInterface* createMediaObject(); typedef void destroyMediaObject( IMediaInterface* object ); ``` ## KPI For detailed VIOS performance benchmarks including stream profiling, per-replica stream counts, and per-request latency benchmarks, see [VIOS Performance](/appendix/performance/microservices/vios-performance). ### Troubleshooting #### Common Issues ##### Container fails to start Check for the following issues: 1. Examine container logs for error messages: ```console $ docker logs ``` 2. Verify GPU access: Ensure NVIDIA Container Toolkit is installed and `nvidia-smi` command works properly ##### Container reboots or becomes unresponsive after long period This issue can be resolved by configuring Docker to use the cgroupfs driver. **Configuration Steps:** 1. Add or confirm the following entry in `/etc/docker/daemon.json`: ```json { "data-root": "/var/lib/docker", "default-address-pools": [ { "base": "192.168.2.0/16", "size": 24 } ], "default-runtime": "nvidia", "runtimes": { "nvidia": { "path": "/usr/bin/nvidia-container-runtime", "runtimeArgs": [] } }, "exec-opts": ["native.cgroupdriver=cgroupfs"] } ``` 2. Apply the configuration by running the following commands: ```console $ sudo systemctl daemon-reload $ sudo systemctl restart docker ``` ##### Uploads succeed but files are not visible Check available disk space on the storage backend. Ideally, maintain more than 5% of total disk space free to avoid automatic file deletion. VST uses the `storage_threshold_percentage` configuration parameter (default: 95) to control when aging policy triggers file deletion. When disk space consumption reaches the threshold (e.g., 95%), VST automatically deletes old files to maintain storage limits, which may include recently uploaded files. **Aging Policy Configuration:** The aging policy can be configured using these VST storage configuration parameters (see [Storage Config](/system-components/middleware/video-io-storage-vios/vios-microservices#storage-config)): * `storage_threshold_percentage` - Disk usage percentage threshold for aging policy * `storage_monitoring_frequency_secs` - Frequency of storage monitoring checks * `total_video_storage_size_MB` - Total storage size allocated for videos > **Note** > > It is best to leave these values as default unless absolutely necessary to change them. Monitor storage utilization from the Dashboard tab to track available space. ##### Download or video URL generation fails The `disableAudio` query parameter is required in VST video download REST API calls for video download and URL generation to work properly. **Verification Steps:** 1. Check the Stream Processing MS logs when the download API is called: ```console $ docker logs vss-vios-streamprocessing | grep downloadVideoFile ``` 2. Look for a log line similar to: ```text [YYYY-MM-DDTHH:mm:ss.sssZ:THREAD_ID:video_download.cpp:184: downloadVideoFile] Params: container: mp4, transcode: full, disable_audio: true, enable_overlay: true, is_cloud_stream: 0 ``` 3. Check `disable_audio` in the log output: * Default (`ENABLE_AUDIO=false` in the VSS profile `.env`): expect `disable_audio: true`. * Nemotron Omni / audio-aware agent (`ENABLE_AUDIO=true`): expect `disable_audio: false`. 4. If the value does not match your profile, confirm the effective `ENABLE_AUDIO` value from the profile `.env` and any `user-overrides.env` file passed later to Docker Compose. Upload the video **after** enabling audio, then retry the operation. ##### VST services are up but common functionalities do not work This issue is typically related to Redis connectivity problems. **Diagnostic Steps:** 1. Check if Redis is running properly: ```console $ docker ps | grep redis $ docker logs ``` 2. If Redis keeps restarting, check for port conflicts (Redis port may be blocked due to another process): ```console $ sudo netstat -tulpn | grep ``` **Verify Redis Connectivity:** Check all VST container logs for successful Redis connection messages: ```console $ docker logs | grep redis_init ``` You should see a log line similar to: ```text [YYYY-MM-DDTHH:mm:ss.sssZ:THREAD_ID:redis_publisher.cpp:215: redis_init] Redis connect success. ``` Ensure all VIOS containers (`vss-vios-sensor` and `vss-vios-streamprocessing`) show successful Redis connection logs. Restart the Redis container if necessary after resolving port conflicts. ##### VST APIs do not respond even after waiting several minutes post-deployment VST installs required packages during every deployment. If apt package servers are slow or experiencing high latency, package downloads may take considerable time, delaying service readiness. The package installation script is mounted to all VST containers: ```text deployments/vst/scripts/user_additional_install.sh ``` **Monitoring Installation Progress:** 1. Check container logs to monitor package installation progress: ```console $ docker logs -f ``` 2. Verify package installation is complete by checking all VST container logs for the confirmation message: ```text Installation completed successfully! ``` 3. Wait for this message to appear in all VST containers before attempting to use VST APIs **Configurable Installation Parameters:** If installation times out frequently, you can adjust the following parameters in `user_additional_install.sh`: * `APT_UPDATE_TIMEOUT=$((60 + RANDOM % 41))` - Timeout for apt-get update (60-100 seconds) * `PKG_INSTALL_TIMEOUT=$((100 + RANDOM % 101))` - Timeout for package installation (100-200 seconds) * `MAX_RETRIES=3` - Maximum number of retry attempts for failed installations Increase these values if your network or apt servers are consistently slow. ##### Image capture failure The VIOS replay service has a known issue: when an RTSP stream encoded with H265 is removed from VIOS, the image capture API may not operate as intended. #### Handling time drift in ONVIF cameras Time drift in ONVIF cameras can cause incorrect timestamps on recorded video, challenges correlating frames across multiple cameras, and difficulties during incident investigation. It typically arises from the following: * The camera's internal clock lacks high precision. * Irregular or absent synchronization with a Network Time Protocol (NTP) server. * Network latency or instability. * Power outages or firmware-related issues. **Recommended approach:** Use a dual-pronged strategy to mitigate time drift: 1. **Disable sensor NTP time in VIOS** -- By default, the configuration parameter `use_sensor_ntp_time` is set to `true`. In this mode, VIOS uses the SenderReport and RTP-timestamp provided by the camera and forwards the same timestamp to downstream services such as Perception. However, if time drift is observed between the camera clock and the system clock, set `use_sensor_ntp_time` to `false`: ```json { "data": { "use_sensor_ntp_time": false } } ``` When this option is disabled, VIOS ignores the SenderReport and RTP-timestamp from the camera and assigns its own system timestamp when forwarding frames to downstream services like Perception. This ensures consistent and reliable timestamps based on the system clock, helping mitigate issues caused by camera time drift. 2. **Enable NTP synchronization on the camera** -- Configure each ONVIF camera to synchronize with a reliable NTP server (for example, `pool.ntp.org` or a local enterprise NTP server). Set synchronization to occur at regular intervals (for example, every hour) to minimize drift. Most ONVIF cameras allow NTP setup through their web interface (typically under **Admin Settings** > **Time Settings** > **NTP Configuration**) or via the ONVIF Device Management API. Ensure the NTP server address is reachable by the camera and that the time zone and Daylight Saving Time settings are correct. > **Note** > > NTP synchronization alone may not be precise or frequent enough for time-sensitive applications. Disabling `use_sensor_ntp_time` remains the preferred and more reliable approach for maintaining accurate timing. **If the camera does not support NTP or cannot sync correctly:** * Set `use_sensor_ntp_time` to `false` so that VIOS applies the system timestamp to each frame when received. * If feasible, replace the camera with one that fully supports NTP and ONVIF time configuration. **If the cameras are already well-synchronized and show no drift:** Developers can choose to enable the following VIOS configuration to propagate the original camera timestamp to downstream services: ```json { "data": { "use_sensor_ntp_time": true } } ```