Skip to content

Screenshots

Sapsan can periodically capture JPEG frames from a stream: show a current preview in UIs and store frames in the archive alongside the video.

Configuration

A stream can have several screenshot generators. Each takes frames from one of two sources:

  • http — fetch a ready JPEG over HTTP (e.g. a camera's snapshot URL);
  • keyframe — render a frame from the stream's own video track on keyframes.
streams:
  - name: cam1
    inputs:
    - rtsp:
        url: rtsp://admin:password@10.0.0.5/stream0
    thumbnails:
    - http:
        url: http://10.0.0.5/snapshot.jpg
        fetch_interval: 10  # capture period, s (default 10)
        timeout: 5          # request timeout, s (default 5)
      dvr: true             # store frames in the archive (default false)
    - keyframe:
        track: v1           # source video track
        width: 320          # default 320 if no size is set, minimum 32
        height: 180
        every: 3gop         # capture every 3rd GOP (default: every GOP)

Validation rules: fetch_interval, timeout, and every must be greater than 0; frame dimensions must be at least 32; timeout is only allowed on http, and width/height/every only on keyframe.

Garbage protection: a response that is not a JPEG or exceeds the size limit is discarded — the preview is not updated.

Getting screenshots

What URL
Current stream frame http://server/streaming/live-preview-jpeg/<stream>
Frame of a specific track http://server/streaming/track-preview-jpeg/<stream>/<track>
Frame from the archive http://server/streaming/dvr-preview-jpeg/<stream>/<track>/image/<ref>

Screenshots in the archive

With dvr: true frames are written into the archive as a separate JPEG track with real frame dimensions. In the archive's DASH manifest it is exposed as a standard thumbnail tile AdaptationSet (http://dashif.org/guidelines/thumbnail_tile) — players that support timeline thumbnails pick it up automatically.

Next steps