Substreams

ForgeVis supports dual-stream configuration: main stream (high quality) and substream (lower quality).

Use Case

• Main stream: 1080p @ 4 Mbps → recording
• Substream: 480p @ 1 Mbps → restreaming to video wall/mobile clients

Configuration

cameras:
  camera_001:
    source: "rtsp://user:pass@camera/main"      # Main stream (required)
    sub: "rtsp://user:pass@camera/main/sub"     # Substream (optional)

RTSP Endpoints

Main Stream

rtsp://localhost:8554/camera_001

Uses the source URL from configuration.

Substream

rtsp://localhost:8554/camera_001/sub

Uses the sub URL from configuration.

If sub is not configured, returns 404 Not Found.

Recording

Only main stream is recorded. Substreams are used exclusively for restreaming.

cameras:
  camera_001:
    source: "rtsp://..."  # Recorded to disk
    sub: "rtsp://..."     # Only for RTSP clients, not recorded
    record: true          # Applies to main stream only

Idle Timeout

Each stream (main and substream) maintains its own connection and idle timeout.

• Main stream connection is kept alive if recording is enabled
• Substream disconnects after idle_timeout_sec when no RTSP clients connected

rtsp:
  idle_timeout_sec: 10  # Applies to both main and sub

Architecture

┌──────────────┐
│ Camera       │
│              │
│ Main: 1080p  │─────┐
│ Sub:  480p   │──┐  │
└──────────────┘  │  │
                  │  │
                  ▼  ▼
            ┌──────────────┐
            │  StreamHub   │
            │              │
            │ camera_001   │ (main)
            │ camera_001/sub│
            └──────────────┘
                  │  │
          ┌───────┘  └────────┐
          ▼                   ▼
    ┌──────────┐        ┌────────────┐
    │ Recorder │        │ RTSP       │
    │ (main)   │        │ Clients    │
    │          │        │ (main/sub) │
    └──────────┘        └────────────┘

Example: Video Wall Setup

Scenario: 100 cameras, video wall displays 16 camera feeds simultaneously

Configuration:

cameras:
  camera_001:
    source: "rtsp://camera/main"    # 1080p recording
    sub: "rtsp://camera/sub"        # 480p for video wall
  # ... camera_002 to camera_100

Video Wall Application:

# Connect to substreams for lower bandwidth
ffplay rtsp://forgevis:8554/camera_001/sub
ffplay rtsp://forgevis:8554/camera_002/sub
# ... up to 16 simultaneous streams

Benefits:

• Reduced bandwidth: 16 × 1 Mbps = 16 Mbps (vs 64 Mbps for main streams)
• Camera load: Still only 1 connection per camera
• Quality: Substream is sufficient for video wall preview

Implementation Notes

StreamHub Keys

• Main stream: camera_001
• Substream: camera_001/sub

These are independent streams with separate connections to the camera.

URI Parsing

The RTSP server parses the request URI:

• /camera_001 → looks up cameras.camera_001.source
• /camera_001/sub → looks up cameras.camera_001.sub

URL Format

Substream URL follows camera manufacturer conventions:

• Hikvision: rtsp://camera/Streaming/Channels/102 (main: 101, sub: 102)
• Dahua: rtsp://camera/cam/realmonitor?channel=1&subtype=1 (main: subtype=0, sub: subtype=1)
• Generic: Often /main and /sub suffixes