Recording Pipeline

The recording pipeline is the core of Meridian VMS. It continuously ingests video from IP cameras and writes it to disk as indexed segments, providing the foundation for playback, timeline queries, and event correlation.

Pipeline Overview

IP Camera ──RTSP──> Stream Relay ──────> Recording Engine ──────> Segment Files
                        │                                              │
                        │                                       Segment Index
                   WebRTC live                                         │
                   streaming                                  Management Server
                                                             (timeline + playback)

Each camera on a recording server runs through this pipeline independently. The pipeline preserves the original camera stream exactly as-is — video is never re-encoded at any point in the recording process.

Stage 1: Stream Ingestion

The stream relay ingests each camera’s RTSP stream and makes it available locally. All downstream processes connect to the relay rather than directly to cameras.

This design ensures:

• Single camera connection — Only one RTSP connection is made to each camera, regardless of how many consumers need the stream. Many IP cameras can only handle a small number of concurrent connections.
• Consistent source — Recording, detection, and live streaming all use the same local relay as their source, simplifying management and troubleshooting.
• Sub-stream support — If a camera provides both a high-resolution main stream and a lower-resolution sub-stream, the system can use each for the appropriate purpose (recording vs. live viewing).

Stage 2: Continuous Recording

The recording engine captures the stream from the local relay and writes it to disk as time-based segment files.

Key Characteristics

• Stream copy — The original camera bitstream is written directly to disk with no transcoding or re-encoding. This preserves full video quality and requires minimal CPU resources, allowing a single server to record many cameras simultaneously.
• Segment-based storage — Video is divided into fixed-duration segments (configurable, typically 10 minutes). Each segment is a self-contained video file.
• Clock-aligned segments — Segments are aligned to wall-clock boundaries (e.g., a segment might cover 14:00 to 14:10, then 14:10 to 14:20). This makes it easy to locate footage for a specific time.
• Date-organised directories — Segments are automatically organised into a date-based directory structure on disk for efficient storage management.

Self-Healing

The recording engine automatically handles failures:

• If a camera stream drops or a recording process crashes, it is automatically restarted.
• Restarts use exponential backoff (increasing delay between retries) to avoid overwhelming a camera that is experiencing issues.
• Once a stable connection is re-established, the backoff resets and normal recording resumes.
• Per-camera status is reported to the management server with every heartbeat so that operators can see which cameras are recording, in error, or offline.

Stage 3: Segment Indexing

As each recording segment completes, its metadata is automatically reported to the management server:

• Camera and server identification
• Start and end timestamps
• File size

The management server stores this index in its database. This index is what makes playback and timeline queries possible — when a user requests footage for a specific time range, the management server looks up the index to find exactly which segments contain the requested footage.

Indexing is designed to be resilient:

• Segments are submitted in batches for efficiency.
• If submission fails (e.g., due to a temporary network issue), segments are retried automatically.
• Duplicate submissions are handled gracefully — re-indexing a segment after a restart is safe.

Retention

Recordings are automatically managed by a retention policy:

• A background task runs periodically on each recording server.
• Segments older than the configured retention period are deleted from disk.
• The corresponding index entries are removed from the management server’s database.
• Retention can be configured at the system level or overridden per camera (for example, keeping entrance camera footage longer than corridor cameras).

Recording Health

The system continuously monitors recording health:

• Each recording server reports per-camera status every 30 seconds via its heartbeat.
• Camera status is visible in the web interface dashboard and camera list.
• The system detects cameras that have not produced new segments recently, flagging potential issues.

Status	Meaning
Recording	Stream is being captured and segments are being written normally
Error	The recording process has failed and is being restarted
Offline	The camera is unreachable or the stream is not available

Configuration Options

Setting	Description
Segment duration	Length of each recording segment (default: 10 minutes)
Retention period	How long recordings are kept before automatic deletion (default: 10 days, configurable per camera)
Storage location	Root directory for recording storage on each server