Skip to main content

Streaming Flows

What This Page Covers​

This page describes the runtime flows for live streaming, recording, clip creation and playback within the Video Management Capability. It traces each operation from client request through the cloud infrastructure to storage, showing how the components interact at each step.

For camera setup and channel creation prerequisites, see Camera Configuration. For storage layout and retention, see Media Storage.

Live Stream Initialization​

Starting a live stream is a multi-step handshake between the client, Cloud VMS, Local Agent and NVR Worker. The stream token carries all the information the Local Agent needs to establish the connection.

Flow​

Step-by-Step​

  1. Channel creation — The client creates a channel on the Cloud NVR via the VMS API (one-time setup per camera).

  2. Token request — The client requests a streaming token for the channel. The token encodes:

    • The NVR URL to connect to
    • A stream authorization session ID (sid) that identifies the channel

  3. Stream start — The client sends the token and the camera's IP address to the Local Agent running on the Zipato Hub or Zipatile.

  4. NVR handshake — The Local Agent contacts the Cloud NVR with the sid. The NVR validates the session and upgrades the connection to a WebSocket.

  5. Worker assignment — Over the WebSocket, the Cloud NVR provides the NVR Worker URL where the stream should be pushed.

  6. Stream active — The Local Agent pulls the stream from the camera (typically via RTSP) and pushes it to the NVR Worker over the WebSocket. The NVR Worker notifies the Cloud NVR that streaming has started.

  7. Stream end — When the stream is stopped (by client request or timeout), the NVR Worker notifies the Cloud NVR.

Recording While Streaming​

Once a live stream is active, the NVR Worker automatically segments and uploads recordings to S3. No additional client action is needed — recording begins as soon as the stream starts.

Flow​

Step-by-Step​

  1. Stream reception — The NVR Worker receives the live stream from the Local Agent via WebSocket.

  2. Segmentation — Every 30 seconds, the NVR Worker creates a recording segment from the stream buffer.

  3. S3 upload — The segment is uploaded to the S3 recordings bucket using rclone.

  4. Dual notification — Two notification paths fire in parallel:

    • S3 sends an event to an SQS queue (used by clip creation)
    • The NVR Worker directly notifies the Cloud NVR of the upload

  5. Metadata persistence — The Cloud NVR saves recording metadata (channel, time range, S3 path) to the database.

NVR Worker Design​

The NVR Worker is stateless and horizontally scalable:

ComponentRole
MediaMTXStream protocol handling and processing
tmpfsTemporary storage for segments before upload
rcloneS3 upload with retry and checksum verification

Multiple worker instances can run simultaneously, each handling independent streams.

Recording Playback​

Playback uses presigned S3 URLs, meaning the client downloads recordings directly from S3 without routing through the VMS infrastructure.

Flow​

Step-by-Step​

  1. Request — The client requests recordings for a channel, optionally filtered by time range.

  2. Metadata lookup — The Cloud NVR queries the database for recording entries matching the channel and time range.

  3. URL presigning — For each recording, the Cloud NVR generates a presigned S3 GET URL with a limited expiration time.

  4. Direct download — The client uses the presigned URLs to download recordings directly from S3. No further authorization is needed — the presigned URL carries its own credentials.

Clip Creation​

A clip is a user-defined time range extracted from continuous recordings. Clip creation is asynchronous because the requested time range may extend into the present — the Cloud NVR must wait for recordings that haven't been uploaded yet.

Flow​

Step-by-Step​

  1. Clip request — The client specifies a channel and time range (start and end timestamp). The end time may be in the future.

  2. Entry creation — The Cloud NVR creates a clip entry in the database with status: in_progress and returns the clip ID immediately.

  3. Existing recordings — The NVR queries the database for recordings that already exist within the time range and appends them to the clip.

  4. Waiting for uploads — If the time range includes the present or near-future, the NVR listens on the SQS queue for new recording upload notifications. As each relevant recording arrives, it is appended to the clip.

  5. Completion — Once all segments within the time range are accounted for, the clip status is set to finished. The clip is now accessible via presigned S3 URLs, same as individual recordings.

Clip Lifecycle​

StatusMeaning
in_progressClip is being assembled — some recordings may still be uploading
finishedAll recordings within the time range are included

The client can poll the clip status or be notified when it transitions to finished.

Snapshot Upload​

Snapshots are single-frame captures stored in S3. The upload uses a presigned PUT URL, allowing the client (or Local Agent) to upload directly to S3 without passing image data through the VMS.

Flow​

Step-by-Step​

  1. Entry creation — The client requests a snapshot entry for the channel. The Cloud NVR creates it in the database and presigns an S3 PUT URL.

  2. Direct upload — The client (or Local Agent on the hub) uploads the image directly to S3 using the presigned URL.

  3. Access — The snapshot can later be retrieved through the same presigned-URL mechanism used for recordings.

RTSP Proxy​

For browser clients that cannot directly access cameras behind NAT, the platform provides an RTSP proxy:

The proxy translates HTTP requests into RTSP protocol and relays the stream back to the browser. This allows live viewing without requiring the Local Agent path.

Protocol Summary​

Stream PathProtocolPurpose
Camera → Local AgentRTSP (typically)Pull from camera
Local Agent → NVR WorkerWebSocketPush to cloud
NVR Worker → S3rclone (HTTPS)Upload segments
S3 → ClientHTTPS (presigned)Playback and download
Camera → RTSP Proxy → BrowserRTSP over HTTPDirect browser viewing
Camera → YouTubeRTMPPublic broadcasting

Where to Continue​

GoalPage
Understand camera setup and channel creationCamera Configuration
Learn about recording, clip and snapshot storageMedia Storage
See the full video management modelOverview
Last updated on