# How to Configure Deep Learning Streamer Video Pipeline ## Video Pipeline Configuration in UI Camera Calibration Page (in Kubernetes Deployment) When Scenescape is deployed in a Kubernetes environment, you can configure Deep Learning Streamer (DL Streamer) video pipelines directly through the camera calibration web interface. This provides a user-friendly way to generate and customize GStreamer pipelines for your cameras without manually editing configuration files. ### Accessing the Camera Calibration Page 1. Navigate to your Scenescape web interface. 2. Select a scene from the main dashboard. 3. Click an existing camera or create a new one. 4. Open the camera calibration page to access pipeline configuration options. ### Available Configuration Fields In Kubernetes deployments, the camera calibration form provides access to a subset of camera configuration fields that are specifically relevant to pipeline generation: #### Core Pipeline Fields - **Camera (Video Source)**: Specifies the video source command. Supported formats: - RTSP streams: `rtsp://camera-ip:554/stream` (raw H.264). - HTTP/HTTPS streams: `http://camera-ip/mjpeg` (MJPEG). - V4L2 (Video4Linux2) local USB camera devices: `/dev/video0` (path to device). Allowed paths: `/dev/video` (default device), `/dev/videoX`, `/dev/mediaX` and symbolic links: `/dev/v4l/by-id/xxx`, `/dev/v4l/by-path/xxx`. - File sources are not directly mountable in Kubernetes camera pipelines - to use a video file, serve it over RTSP yourself instead, see [Using Your Own Video Files](#using-your-own-video-files) below. - **Camera Chain**: defines the sequence or combination of AI models to chain together in the pipeline using their short identifiers (e.g., "retail"). Models can be chained serially (one after another). For details on chaining syntax, available models, and usage examples, see the [Model Chaining](#model-chaining) section below. - **Camera Pipeline**: The generated or custom GStreamer pipeline string #### Model Chaining Model chaining allows you to combine multiple AI models in a single pipeline to create more sophisticated video analytics workflows. For example, you can chain a person detection model with a re-identification model to first detect people in the video and then generate unique identifiers for tracking. ##### Prerequisites By default, only a limited number of models is downloaded during helm chart installation, which limits the possibilities of model chaining. To enable all models: 1. Configure desired model precisions (e.g., `initModels.modelPrecisions=FP16`) in `kubernetes/scenescape-chart/values.yaml`. 2. (Re)deploy Scenescape to download the supported models. ##### Chaining Syntax - **Serial chaining**: Use the `+` operator to chain models sequentially (e.g., `retail+reid`). - **Device specification**: Optionally specify the inference device using `=` syntax: - Use `GPU` (e.g., `retail=GPU`) for systems with a single GPU device or for **automatic GPU device selection**. - Use [OpenVINO naming convention](https://docs.openvino.ai/2026/openvino-workflow/running-inference/inference-devices-and-modes/gpu-device.html#device-naming-convention) to **select a specific GPU device**. Only Intel GPU devices are supported. - Use `NPU` (e.g., `retail=NPU`) to run the inference on NPU (Neural Processing Unit). - **Default device**: If no device is specified, CPU is used as the default. > **Note:** On systems with Intel GPU (either integrated or discrete), it is highly recommended to run both the decoding and the inference on GPU, so that other Scenescape services can fully benefit from available CPU cores. GPU inference typically provides better performance for complex models. **Example**: `retail=GPU+reid=GPU` runs person detection on GPU, then feeds the results to person re-identification also running on GPU. ##### Available Models Use the following short names to refer to each model in the chain: | Category | Full Model Name | Short Name | Description | | -------------------- | -------------------------------------------- | ---------- | ----------------------------------------- | | **Person Detection** | person-detection-retail-0013 | retail | General person detection | | | person-vehicle-bike-detection-crossroad-1016 | pvbcross16 | Crossroad multi-class detection | | **Person Analysis** | person-reidentification-retail-0277 | reid | Person re-identification | | | person-attributes-recognition-crossroad-0238 | personattr | Person attributes (age, gender, clothing) | | | age-gender-recognition-retail-0013 | agegender | Age and gender classification | | **Vehicle Analysis** | vehicle-attributes-recognition-barrier-0042 | vehattr | Vehicle attributes (color, type) | | **Pose Estimation** | yolo11n-pose | pose | Person pose estimation with keypoints | | **ReID (Public)** | mars-small128 | marsreid | Lightweight person re-identification | ##### Common Chaining Patterns **Person Analytics Workflows:** ```text # Basic person detection with re-identification retail+reid # Person detection with attributes analysis retail+personattr # Person detection with age/gender classification retail=GPU+agegender=GPU ``` **Pose Estimation Workflows:** ```text # Pose estimation with re-identification pose+marsreid ``` > **Note**: The `yolo11n-pose` and `mars-small128` models are not included in the default model set. They must be downloaded separately using the DL Streamer `download_public_models.sh` script and copied into the Models Volume. See the [DL Streamer Pipeline Server documentation](/dlstreamer-pipeline-server/README.md#enable-pose-estimation) for setup instructions. > **Note**: To enable pose-based bounding box adjustment in the Scene Controller, set the `--pose-adjustment` flag or `CONTROLLER_ENABLE_POSE_ADJUSTMENT=true` environment variable. See the [Scene Controller documentation](../microservices/controller/controller.md) for details. > **Note**: Cameras using pose estimation pipelines with `gvatrack` + `gvainference` (e.g., `pose+marsreid`) cannot use `reidPolicy` as the metadata generation policy — `detectionPolicy` must be used. The `--pose-adjustment` controller flag is also incompatible with Extended ReID (cross-camera re-identification via the configured vector backend). **Vehicle Analytics Workflows:** ```text # Vehicle detection with re-identification pvbcross16=GPU+reid=GPU # Vehicle detection with attributes pvbcross16+vehattr ``` **Multi-Class Detection:** ```text # Detect people, vehicles, and bikes pvbcross16=GPU # Multi-class detection with re-identification pvbcross16=GPU+reid=GPU ``` #### Advanced Configuration - **Decode Device**: video decoding device settings (`AUTO`, `GPU` or `CPU`). It is highly recommended to use the `AUTO` or `GPU` (only on systems with GPU) setting, as the `CPU` setting forces the pipeline to use software codecs that have significantly lower performance than hardware accelerators. When `AUTO` is set, the pipeline will automatically choose GPU as the decode device if it is available on the system and fall back to CPU otherwise. If the user sets `GPU` on the system without GPU, the pipeline will not work. - **Detection Labels**: allows you to filter which object categories are processed and published by the video analytics pipeline. When specified, only detected objects matching the configured labels will be published to Scenescape. If left empty, all detected objects from the AI model will be published (default behavior). This feature is useful for focusing on specific object types and reducing data volume. **Supported formats:** - One label per line (newline-separated): ```text car pedestrian trolley ``` - Space-separated labels: ```text car pedestrian trolley ``` - Comma-separated labels: ```text car, pedestrian, trolley ``` All three formats will produce the same result. Choose the format that best suits your workflow. - **Model Config**: references a model configuration file. Model configuration files are managed in the Models page and stored in the folder `Models/models/model_configs`. You can upload custom model configuration files or modify existing ones using the Models page. The Models page is accessible in the top menu of the Scenescape UI. - **Use Camera Pipeline**: when enabled, directly applies the Camera Pipeline string in the camera VA pipeline instead of generating it automatically from camera settings on saving the camera configuration. When disabled (default), the system automatically generates the pipeline from other form fields. > **Note:** The `AUTO` setting for decode device does not assume the optimal setting in each possible case. There might be cases when the optimal configuration can be achieved by setting the decode device manually. > **Note:** The Model Config field references configuration files that define AI model parameters and processing settings. The default configuration file `model_config.json` is auto-generated for the models downloaded by the Scenescape model installer. See [Model Configuration File Format](model-configuration-file-format.md) for more details on the file format and when/how it should be updated. > **Note:** When the **Use Camera Pipeline** checkbox is enabled, the values of camera settings from other form fields ('Camera', 'Camera Chain', 'Decode Device', 'Undistort', 'Model Config') do not impact the effective Visual Analytics pipeline. Enable the checkbox only when you want to use a custom pipeline that should not be auto-generated and remember to update it manually when needed. #### Camera Intrinsics and Distortion - **Intrinsics**: camera focal lengths (fx, fy) and principal point coordinates (cx, cy). - **Distortion Coefficients**: k1, k2, k3, p1, p2 for lens distortion correction. ### Generating a Pipeline Preview The camera calibration page provides an automated pipeline generation feature: 1. **Fill in Required Fields**: enter the necessary camera configuration parameters: - Set the **Camera (Video Source)** (e.g., `rtsp://camera-ip:554/stream` or `/dev/video0`). - Configure **Camera Chain** settings, if needed. - Select the appropriate **Model Config**. 2. **Generate Pipeline Preview**: click the **"Generate Pipeline Preview"** button. - The system will automatically generate a GStreamer pipeline based on your configuration. - The generated pipeline appears in the **Camera Pipeline** text area. - You can review the pipeline structure and elements. 3. **Review Generated Pipeline**: the generated pipeline will include: - Video source configuration based on your Camera (Video Source) field. - AI model integration using the selected Model Config. - Camera intrinsics and distortion correction, if configured. - Metadata publishing for Scenescape integration. ### Customizing the Generated Pipeline After generating a pipeline preview, you can make manual adjustments: 1. **Edit Pipeline String**: modify the generated pipeline in the Camera Pipeline text area. - Add or remove GStreamer elements as needed. - Adjust element parameters for specific requirements. - Ensure the pipeline maintains compatibility with Scenescape - do not modify `gvapython` or `cameraundistort` elements. 2. **Common Customizations**: - **Video Source**: change input source type (RTSP, HTTP, device). - **Model Parameters**: fine-tune AI model inference settings either in model config file or the **Camera Pipeline** field. 3. **Enable Use Camera Pipeline**: check the **Use Camera Pipeline** checkbox to apply your custom pipeline string directly instead of auto-generation from form fields. 4. **Validation**: when you save the configuration or generate the pipeline preview, the system performs preliminary checks of the pipeline and reports an error if pipeline generation is not possible. However, it does not validate pipeline correctness in terms of GStreamer pipeline syntax and its functionality. You need to verify that the pipeline performs as expected. ### Saving and Applying Configuration 1. **Save Camera Configuration**: click **"Save Camera"** to apply your pipeline configuration. - The system automatically generates the camera pipeline if the field is empty. - Configuration is stored and deployed to the Kubernetes cluster. - The camera deployment is updated with the new pipeline. 2. **Automatic Pipeline Generation**: if you save the form with **Use Camera Pipeline** checkbox disabled, the system automatically generates a pipeline based on other form fields, following best practices and standards for Scenescape. This ensures every camera has a valid pipeline configuration. 3. **Error Handling**: If pipeline generation fails, the form remains open for correction and error messages are displayed. Common issues include missing model configurations or invalid command syntax. ### Best Practices - **Start with Generated Pipeline**: use the "Generate Pipeline Preview" button to create a baseline configuration. - **Test Incrementally**: make small changes and test each modification. - **Validate Model Config**: ensure your selected Model Config file exists and is properly formatted. - **Monitor Performance**: check camera performance after applying pipeline changes. - **Backup Configurations**: save working pipeline configurations for future reference. ### Adding custom models You can upload custom models and use them in DL Streamer Video Pipeline. These are stored in the Models Volume. You can upload custom models to the Models Volume using the Models page. The Models page is accessible in the top menu of the Scenescape UI. Alternatively, use the instructions in the [How to Manage Files in Volumes](./how-to-manage-files-in-volumes.md) guide to do it from the command line. 1. Upload the model in OpenVINO IR format with desired precision(s). 2. Update the model configuration file or upload a new one so that it includes the newly added model(s). See [Model Configuration File Format](./model-configuration-file-format.md) for more details on the file format and when/how it should be updated. 3. Reference the model in the camera pipeline configuration: use the short model name in the **Camera Chain** and the custom model configuration file name in the **Model Config** field. ### Using Your Own Video Files The Helm chart does not deploy any media/RTSP server, and camera pipeline Pods have no video-file volume mounted, so the **Camera (Video Source)** field cannot point at a local file the way it can in a Docker Compose deployment. To use a video file as a camera source, serve it over RTSP yourself from anywhere reachable by the cluster - for example a small standalone stack pairing an RTSP server such as `mediamtx` with an `ffmpeg` process that reads your file and republishes it as a stream. The bundled Retail and Queuing demo scenes use exactly this pattern; see [compose.retail-video.yml](/sample_data/demo_scenes/Retail/compose.retail-video.yml) and [compose.queuing-video.yml](/sample_data/demo_scenes/Queuing/compose.queuing-video.yml) for one working example. Once you have an RTSP source reachable from the cluster: 1. Set the **Camera (Video Source)** field to that RTSP URL (e.g. `rtsp://:/`). 2. If the RTSP source runs outside the cluster (e.g. on a separate Docker host), make sure it's reachable from cluster Pods first - see [Video Source (sample/demo camera feeds)](/kubernetes/README.md#video-source-sampledemo-camera-feeds) for how this is wired up for the demo scenes, as one example of exposing an external RTSP source to the cluster. ### Limitations - Only serial chaining of detectors with classification or re-identification models is supported in the **Camera Chain** field, where the ROI from the detection model serves as input to the classification or re-identification model in the chain. Serial chaining of two or more detectors is not supported (e.g. vehicle detector → license plate detector → OCR). Parallel inference on multiple models is not yet supported. - Distortion correction is temporarily disabled due to a bug in DL Streamer Pipeline Server. - Explicit frame rate and resolution configuration is not available yet. - Network instability and camera disconnects are not handled gracefully for network-based streams (RTSP/HTTP/HTTPS) and may cause the pipeline to fail. - File-based video sources are not supported for Kubernetes camera pipelines - the per-camera pipeline Pod has no video-file volume mounted. Serve your video over RTSP instead, see [Using Your Own Video Files](#using-your-own-video-files). - Cross-stream batching is not supported since in Scenescape Kubernetes deployment each camera pipeline is running in a separate Pod. - Direct selection of a specific GPU as decode device on systems with multiple GPUs is not supported. As a workaround, use specific GStreamer elements in the **Camera Pipeline** field according to [DL Streamer documentation](https://docs.openedgeplatform.intel.com/2026.3/edge-ai-libraries/dlstreamer/dev_guide/gpu_device_selection.html). - MP4 input files are not reliably supported. This is due to a GStreamer limitation: the combination of `multifilesrc` and `decodebin3` elements may fail because MP4 container metadata is unavailable when data is provided as discrete file fragments. As a workaround, convert MP4 files to a streaming-friendly format such as MPEG-TS (.ts). - Pose estimation pipelines using `gvatrack` + `gvainference` (e.g. `yolo11n-pose` + `mars-small128`) are not compatible with `reidPolicy`. These cameras must use `detectionPolicy`. Additionally, the controller `--pose-adjustment` flag cannot be used together with Extended ReID. ### Troubleshooting - **Pipeline Generation Errors**: check that all required fields are filled correctly. - **Model Config Issues**: verify the model configuration file exists in the Models page and model(s) used in the **Camera Chain** field are defined in the model config file. - **Video Source Problems**: ensure the Camera (Video Source) field contains a valid video source URL or a device path. - **Deployment Failures**: if the camera goes offline after an update or creation, check the Kubernetes logs of the corresponding video pipeline Pod for detailed error information. Video pipeline Pod names follow the format `-videoppl----`. Look for log entries containing `ERROR`, for example: `kubectl logs -n scenescape scenescape-release-1-videoppl-atag-qcam1-de57f-bdc45859c-mfjpn | grep ERROR`. ## Manual Video Pipeline Configuration (in Docker Compose deployment) Scenescape uses DL Streamer Pipeline Server as the Video Analytics microservice. The video-source compose files [compose.retail-video.yml](/sample_data/demo_scenes/Retail/compose.retail-video.yml) and [compose.queuing-video.yml](/sample_data/demo_scenes/Queuing/compose.queuing-video.yml) show how a DL Streamer Pipeline Server docker container is configured to stream video analytics data for consumption by Scenescape. It leverages DL Streamer pipelines definitions in [queuing-config.json](/sample_data/demo_scenes/Queuing/queuing-config.json) and [retail-config.json](/sample_data/demo_scenes/Retail/retail-config.json). > **Note:** To run DL Streamer Pipeline Server pipelines on hardware accelerators (GPU or NPU), see the DL Streamer Pipeline Server service [user documentation](/dlstreamer-pipeline-server/README.md). ### Video Pipeline Configuration The following is the GStreamer command that defines the video processing pipeline. It specifies how video frames are read, processed, and analyzed using various GStreamer elements and plugins. Each element in the pipeline performs a specific task, such as decoding, object detection, metadata conversion, and publishing, to enable video analytics in the Scenescape platform. ``` "pipeline": "rtspsrc location=rtsp://mediaserver:8554/queuing-cam1 add-reference-timestamp-meta=true latency=200 ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! video/x-raw,format=BGR ! sscape_timestamp_capture name=timesync ntp-server=ntpserv ! gvadetect model=/home/pipeline-server/models/omz/person-detection-retail-0013/FP32/person-detection-retail-0013.xml model-proc=/home/pipeline-server/models/object_detection/person/person-detection-retail-0013.json ! gvametaconvert add-tensor-data=true name=metaconvert ! sscape_post_inference_data_publish name=datapublisher ! gvametapublish name=destination method=file file-path=/dev/null ! appsink sync=true", ``` This example is taken from the bundled Queuing demo scene: its `mediaserver` service republishes the sample video files over RTSP (see [compose.queuing-video.yml](/sample_data/demo_scenes/Queuing/compose.queuing-video.yml)), and the pipeline above consumes that RTSP stream. `multifilesrc` (reading a video file directly, see [Adding custom video files](#adding-custom-video-files) below) is also supported for a fully custom pipeline. #### Breakdown of gstreamer command `rtspsrc` is a GStreamer element that connects to an RTSP video source; the `location` parameter is the stream URL. The `add-reference-timestamp-meta=true` parameter attaches NTP timing metadata used by `use_frame_ntp_timestamp` (see [Parameters](#parameters)). `rtph264depay`, `h264parse`, and `avdec_h264` extract, parse, and decode the H.264 elementary stream. `videoconvert` converts the video stream into a raw format suitable for further processing. In this case, it ensures the video is in the BGR format required by downstream elements. `sscape_timestamp_capture` is a custom GStreamer element that captures timestamps for each video frame. The `ntp-server` parameter specifies the NTP server to synchronize timestamps, and the `use-frame-ntp-timestamp` parameter determines whether to use the NTP timestamp embedded in the RTSP frame metadata or the post-decode system time. `sscape_post_inference_data_publish`, processes frames after inference and publishes metadata in Scenescape detection format as described in [metadata.schema.json](/controller/src/schema/metadata.schema.json) `gvadetect` performs object detection using a pre-trained deep learning model. The `model` parameter specifies the path to the model file, and the `model-proc` parameter points to the model's preprocessing configuration. `gvametaconvert` converts inference metadata into a format suitable for publishing. The `add-tensor-data=true` parameter ensures tensor data is included in the metadata. `gvametapublish` publishes the metadata to a specified destination. In this pipeline, it sends the data to an `appsink` element for further processing or storage. `appsink` is the final element in the pipeline, which consumes the processed video and metadata. The `sync=true` parameter ensures the pipeline operates in sync with the video stream. Read the [DL Streamer Pipeline Server documentation](https://docs.openedgeplatform.intel.com/2026.3/edge-ai-libraries/dlstreamer-pipeline-server/index.html) for details on how to further configure DL Streamer pipeline and learn how to customize: - Input sources (video files, USB, RTSP streams) - Processing parameters - Output destinations - Model-specific settings - Camera intrinsics #### Parameters This section describes the metadata schema and the format that the payload needs to align to. ``` "parameters": { "type": "object", "properties": { "ntp_server": { "element": { "name": "timesync", "property": "ntp-server" }, "type": "string" }, "use_frame_ntp_timestamp": { "element": { "name": "timesync", "property": "use-frame-ntp-timestamp" }, "type": "boolean" }, "cameraid": { "element": { "name": "datapublisher", "property": "cameraid" }, "type": "string" }, "metadatagenpolicy": { "element": { "name": "datapublisher", "property": "metadatagenpolicy" }, "type": "string", "description": "One of detectionPolicy (default), detection3DPolicy, reidPolicy, classificationPolicy, ocrPolicy" }, "publish_image": { "element": { "name": "datapublisher", "property": "publish-image" }, "type": "boolean", "description": "Publish annotated JPEG to scenescape/image/camera/ each frame" }, "detection_labels": { "element": { "name": "datapublisher", "property": "detection-labels" }, "type": "string", "description": "Comma-separated allow-list of detection categories (e.g. \"person,car\"). Empty publishes all." }, "live_view_width": { "element": { "name": "datapublisher", "property": "live-view-width" }, "type": "integer", "description": "Maximum width in pixels of the Live View preview (default 960)" }, "live_view_quality": { "element": { "name": "datapublisher", "property": "live-view-quality" }, "type": "integer", "description": "JPEG quality (1-100) of the Live View preview (default 65)" } } }, ``` ##### Breakdown of parameters - **ntp_server** (string): Specifies the NTP server to synchronize time with. - **use_frame_ntp_timestamp** (boolean): Configuration for using the NTP timestamp embedded in RTSP frame metadata as the frame timestamp. This is an alternative to using the post-decode system clock timestamp. When the RTSP source is configured with `add-reference-timestamp-meta=true`, GStreamer attaches NTP reference timestamp metadata to each buffer. When `true`, the NTP timestamp extracted from the RTSP frame metadata (`GstReferenceTimestampMeta`, caps `timestamp/x-ntp`) is used as the frame timestamp instead of the post-decode system time. This can improve timing accuracy when camera and server clocks are synchronized to the same NTP server. Defaults to `false`. If the metadata is absent on a given frame, the pipeline falls back to the system clock automatically. - **cameraid** (string): Unique identifier for the camera. - **metadatagenpolicy** (string): Policy for generating metadata. Possible values: - `detectionPolicy` (default): Metadata for object detection. When a pose estimation model is used (e.g. `yolo11n-pose`), also includes `keypoints` (e.g. joints) with normalized x/y coordinates and `keypoint_connections` (e.g. skeleton bone pairs) in each detection object. - `reidPolicy`: Metadata for re-identification. - `classificationPolicy`: Metadata for classification. - **publish_frame** (boolean): Indicates whether to publish the video frame to MQTT. - **detection_labels** (array of strings): Optional list of detection labels to filter. When specified, only detected objects matching these labels will be published. If omitted or empty, all detected objects are published. In the UI, labels can be provided as newline-separated, space-separated, or comma-separated values. In JSON configuration, provide as an array. Example: `["person", "car"]`. - **live_view_width** (integer): Optional. Maximum width in pixels of the Live View preview published to `scenescape/image/camera/`. Wider frames are downscaled to this width, narrower ones are sent as they are. Defaults to `960`. The message's `resolution` field still reports the native frame size, and calibration images are never downscaled. - **live_view_quality** (integer): Optional. JPEG quality (1-100) of the Live View preview. Lower values reduce the payload size. Defaults to `65`. The payload section is the actual values for the specific pipeline being configured: ``` "payload": { "destination": { "frame": { "type": "rtsp", "path": "atag-qcam1" } }, "parameters": { "ntp_server": "ntpserv", "use_frame_ntp_timestamp": false, "cameraid": "atag-qcam1", "metadatagenpolicy": "detectionPolicy", "detection_labels": "person" } } ``` #### Track GID labels on camera images The `sscape_post_inference_data_publish` element can add scene track GID labels to the annotated JPEG returned for `getimage`. This is disabled by default and works with Scene Controller + Analytics or C++ Tracker + Analytics, using Analytics with `visibility_topic=regulated`. Enable it on the existing publisher element in a custom camera pipeline: ```text sscape_post_inference_data_publish name=datapublisher annotate-track-ids=true track-topic=scenescape/regulated/scene/ ``` Keep the other elements and properties in your pipeline unchanged. Alternatively, the Manager pipeline config generator accepts `annotate_track_ids: true` in its camera settings and maps it to the publisher property through DLSPS parameters. Generated pipelines select the camera's scene topic when its `scene_uid` is available, so updates from other scenes cannot clear its labels. For manually managed pipelines, set `track-topic` explicitly as above when running multiple scenes; the wildcard default does not isolate scene caches. It does not add a camera form field. For a manually managed DLSPS configuration, add this entry to `parameters.properties`: ```json { "annotate_track_ids": { "element": { "name": "datapublisher", "property": "annotate-track-ids" }, "type": "boolean" } } ``` Then set `"annotate_track_ids": true` in `payload.parameters`. | Element property | Default | Description | | ------------------ | ---------------------------- | -------------------------------------------------- | | annotate-track-ids | false | Enable GID labels on requested images | | track-topic | scenescape/regulated/scene/+ | Analytics topic filter; select one scene if needed | | track-wait-ms | 300 | Maximum wait for tracks, from 0 to 2000 ms | | track-max-age-ms | 1000 | Allowed timestamp difference, from 0 to 5000 ms | The publisher caches the latest track snapshot and waits at most `track-wait-ms` for one at or after the captured frame's timestamp, within `track-max-age-ms`. At timeout it also accepts an older snapshot within that same tolerance. Newer empty snapshots clear previous labels. If no usable snapshot exists, the image retains its normal detector annotation without GID labels. Enabled image messages on `scenescape/image/camera/` include `track_ids`, the full GIDs drawn on the JPEG, or `[]` when none were drawn. Visible labels show the first eight characters with a black outline and white fill. Disabled image messages remain unchanged and omit `track_ids`. Labels use Analytics' `camera_bounds`, which requires calibrated cameras and track sizes. Positions are projected and can differ from detector boxes; track and image timestamps are matched approximately. Publication adds up to the configured wait plus image processing time. Only requested images are affected; calibration/localization images and continuous video output are unchanged. Use a concrete scene topic when multiple scenes publish bounds for the same camera. The default wildcard assumes a single relevant scene. The initial implementation supports only `visibility_topic=regulated`. With custom broker ACLs, grant the DLSPS client read access to the selected track topic in addition to its existing camera command access. The bundled Compose and Kubernetes broker configurations do not impose topic ACL restrictions. #### Cross stream batching DL Streamer Pipeline Server supports grouping multiple frames into a single batch submission during model processing. This can improve throughput when processing multiple video streams with the same pipeline configuration. `batch-size` is an optional parameter which specifies the number of input frames grouped together in a single batch. Read the instructions on how to configure cross stream batching in [DL Streamer Pipeline Server documentation](https://docs.openedgeplatform.intel.com/2026.3/edge-ai-libraries/dlstreamer-pipeline-server/advanced-guide/detailed_usage/how-to-advanced/cross-stream-batching.html) ### Adding custom models or input video files to Docker volumes You can upload custom models to the Models Volume, and add your own input video files by bind-mounting them into your compose setup. #### Uploading custom models to Docker volumes You can upload custom models to the Models Volume using the command line. Use the instructions in the [How to Manage Files in Volumes](./how-to-manage-files-in-volumes.md) guide. 1. Upload the model in OpenVINO IR format with desired precision(s). 2. Reference the model in the video pipeline inference element (e.g. `gvadetect`). #### Adding custom video files There is no shared volume for video files; bind-mount your own video folder directly into a service in your compose file instead, following the pattern used by the bundled demo scenes ([compose.queuing-video.yml](/sample_data/demo_scenes/Queuing/compose.queuing-video.yml), [compose.retail-video.yml](/sample_data/demo_scenes/Retail/compose.retail-video.yml)): 1. Bind-mount your video folder into a `mediamtx`-based `mediaserver` service plus an `ffmpeg` looper that republishes the file(s) over RTSP (recommended, matches the bundled demos), or bind-mount it directly into the DL Streamer Pipeline Server container for a `multifilesrc`-based setup. 2. Reference the resulting source (RTSP URL or file path) in the video pipeline source element (`rtspsrc` or `multifilesrc`).