vios-deep-rtsp-sensor git:20260603.14e198cA

Immutable. This exact content is served forever at /api/v1/blob/5e4a05da861b328a.

---
description: "Deep reference: RTSP server proxy module and sensor management module"
globs: "src/modules/rtsp_server/**,src/modules/sensor_management/**"
alwaysApply: false
---

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# RTSP Server Module

## Key Classes

| Class | File | Role |
|-------|------|------|
| RtspServerManager | `rtsp_server/rtspservermanager.h` | Top-level IVstModule, owns RtspLoadBalancer |
| RtspServer | `rtsp_server/rtspserver.h` | Single RTSP server instance, proxy creation, Live555 event loop |
| RtspLoadBalancer | `rtsp_server/RtspLoadBalancer.h` | Round-robin + DB port affinity |
| AppProxyServerMediaSession | `rtsp_server/rtspserver.h` | ProxyServerMediaSession subclass, SDP parsing, codec detection |
| DynamicRTSPServer | `rtsp_server/DynamicRTSPServer.hh` | Live555 server, lookup for live/vod/webrtc/file streams |
| NvMediaServer/NvMediaSource | `rtsp_server/NvMedia*.h` | VoD subsession and media source |
| VodOverlayManager | `rtsp_server/VodOverlayManager.hh` | VoD overlay rendering |

## Proxy Creation Flow

1. POST `/api/v1/proxy/stream/add` -> `RtspLoadBalancer::addProxyStream()`
2. `getRtspServerFromDbList()` for DB affinity, else round-robin
3. `RtspServer::createProxy()` -> Live555 scheduler -> `AppProxyServerMediaSession::createNew()`
4. `sdpReady()`: parse SDP for codec, send `camera_streaming` notification, register with StreamMonitor

## Load Balancer

Round-robin: `m_currentServerIndex++` modulo `m_serversCount`. DB affinity: `m_streamListDb` maps streamId -> port.

## VoD

Separate server on `startPort + serversCount`. `DynamicRTSPServer::lookupServerMediaSession()` handles `vod/{stream_id}` with `NvFileServerMediaSubsession`.

# Sensor Management Module

## Key Classes

| Class | File | Role |
|-------|------|------|
| SensorManagement | `sensor_management.h` | Discovery, add/remove, proxy URL assignment, DB |
| SensorMonitoring | `sensor_monitoring.h` | ISensorDiscoveryEvent, onSensorFound/Changed/Removed |
| SensorControl | `sensor_control.h` | Adaptor wrapper for encode/image/PTZ/time sync |
| SensorManagementApis | `sensor_management_apis.h` | REST API handlers |

## Sensor Lifecycle

1. **Discovery**: `SensorMonitoring::start()` -> `ISensorDiscoveryInterface::start()`
2. **Found**: `onSensorFound()` -> `addSensorManually()` -> `getAndAddProxyUrl()`
3. **Configure**: `setStreamDefaultSettings()`, add RTSP proxy or send `camera_proxy` event
4. **Monitor**: StreamMonitor `addStream()` on streaming
5. **Remove**: `deleteSensor()` -> notify offline, remove from recorder/decoder/RTSP/StreamMonitor/DB

## QoS

`StreamMonitor::qosMeasurementTask()` periodic: creates `QosRtspClient` per stream, collects packets/bitrate/loss, publishes to Prometheus. API: GET `/api/v1/sensor/qos`.

## PTZ

POST `/api/v1/sensor/{id}` action `ptz` -> `SensorControl::setPTZ()` -> `m_adaptor->setPTZ()`.