Snapshot Service Plugin

The Snap plugin provides video stream snapshot services, supporting on-demand snapshots, MJPEG single-frame output, historical snapshot queries, and watermark overlay. It uses FFmpeg under the hood to extract keyframes from streams and encode them as images.

Enabling the Plugin

features = ["snap"]

# If MJPEG streaming output is also needed
features = ["mjpeg"]  # Automatically enables snap

Configuration

snap:
  enable: true
  ffmpeg_path: "ffmpeg"             # FFmpeg binary path
  output_path: "./snapshots"        # Snapshot file storage directory
  format: "jpg"                     # Default format: jpg / png / webp
  quality: 85                       # Default quality (1-100)
  width: 0                          # Default width (0 = keep original)
  height: 0                         # Default height (0 = keep original)
  query_time_delta: 60              # Snapshot query time tolerance (seconds)
  # Watermark configuration
  watermark_enabled: false
  watermark_text: ""
  watermark_font: ""
  watermark_font_size: 24
  watermark_position: "bottom-right"  # top-left / top-right / bottom-left / bottom-right / center
  watermark_color: "white"

API Endpoints

Real-time Snapshot

GET /snap/api/{stream_path}?format=jpg&quality=85&width=1280&height=720

Take a real-time snapshot of the specified stream. Default configuration can be overridden via query parameters.

Parameter	Type	Default	Description
`format`	string	`jpg`	Image format: jpg / png / webp
`quality`	int	`85`	Image quality (1-100)
`width`	int	`0`	Output width (0 = original)
`height`	int	`0`	Output height (0 = original)

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "stream_path": "live/camera01",
    "snap_time": "2026-03-18T14:30:25Z",
    "format": "jpg",
    "quality": 85,
    "width": 1920,
    "height": 1080,
    "file_size": 245760,
    "file_path": "./snapshots/live_camera01_20260318143025.jpg",
    "file_name": "live_camera01_20260318143025.jpg",
    "download_url": "/snap/download/live_camera01_20260318143025.jpg"
  }
}

Legacy Snapshot Endpoint

GET /snap/take/{stream_path}
POST /snap/take/{stream_path}

A simplified snapshot endpoint compatible with older versions, using default parameters.

Response example:

{
  "status": "success",
  "file_path": "./snapshots/live_camera01_20260318143025.jpg",
  "stream_path": "live/camera01",
  "width": 1920,
  "height": 1080,
  "file_size": 245760,
  "format": "jpg"
}

Query Snapshot History

GET /snap/query/{stream_path}?start_time=...&end_time=...&page=1&page_size=20

Paginated query of historical snapshots by stream path and time range.

Parameter	Type	Description
`start_time`	RFC3339	Start time
`end_time`	RFC3339	End time
`page`	int	Page number (default 1)
`page_size`	int	Items per page (default 20, max 100)

Response example:

{
  "code": 0,
  "message": "success",
  "data": {
    "stream_path": "live/camera01",
    "total": 42,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": 1,
        "stream_path": "live/camera01",
        "timestamp": "2026-03-18T14:30:25Z",
        "file_path": "./snapshots/live_camera01_20260318143025.jpg",
        "file_name": "live_camera01_20260318143025.jpg",
        "mode": "Manual"
      }
    ]
  }
}

View All History

GET /snap/history
GET /snap/history/{stream_path}

Without a path parameter, returns all historical records. With a path parameter, returns history for the specified stream.

Clear History

DELETE /snap/history

Clear all snapshot historical records.

JPEG Single Frame Output

GET /snap/frame.jpeg?src={stream_path}&width=640&height=480&quality=75

Returns raw JPEG image binary data (Content-Type: image/jpeg), suitable for embedding in <img> tags to achieve low-frequency refresh surveillance previews.

Parameter	Type	Description
`src`	string	Required, stream path
`width`	int	Output width
`height`	int	Output height
`quality`	int	JPEG quality

MJPEG Stream Output (Reserved)

GET /snap/stream.mjpeg?src={stream_path}&width=640&height=480&fps=15&quality=75

MJPEG continuous stream output endpoint. Not fully supported in the current version; it is recommended to use /snap/frame.jpeg with client-side periodic refresh as an alternative.

Get Configuration

GET /snap/config

Returns the current plugin runtime configuration.

Watermark Feature

When watermarks are enabled, the FFmpeg drawtext filter is automatically applied during snapshot capture to overlay watermark text:

snap:
  watermark_enabled: true
  watermark_text: "Monibuca V6"
  watermark_font: "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
  watermark_font_size: 24
  watermark_position: "bottom-right"
  watermark_color: "white"

Watermark position options: top-left, top-right, bottom-left, bottom-right, center.