Skip to content

Framegrab

Flex Video can capture periodic frame grabs from video streams in AVIF format, supporting both still images and motion sequences.

Overview

Frame grabs are captured directly from the video pipeline, providing:

  • Still images: Periodic AVIF snapshots at configurable intervals
  • Motion AVIF: Animated sequences for extended capture periods
  • File rotation: Automatic cleanup when file limit is reached
  • Lossless option: Perfect quality preservation when needed

Configuration

Basic Framegrab Capture

Add framegrab configuration to your pipeline:

{
  "id": "camera-1",
  "mode": "simple",
  "source": { "uri": "rtsp://192.168.1.100:8554/live" },
  "encoding": { ... },
  "output": { ... },
  "framegrab": {
    "interval_seconds": 5,
    "max_files": 20,
    "quality": 80
  }
}

Configuration Options

Option Type Default Description
interval_seconds int 1 Capture interval (still mode only)
max_files int 10 Maximum files before rotation
quality int 80 AVIF quality (1-100)
speed int 4 Encoding speed (1-10, lower=better)
lossless bool false Enable lossless encoding
motion bool false Enable motion AVIF mode
motion_duration_seconds int null Max clip duration (motion mode)
motion_keyframe_interval int 30 Keyframes per clip (motion mode)

Still Image Mode

Captures individual AVIF images at regular intervals.

"framegrab": {
  "interval_seconds": 10,
  "max_files": 100,
  "quality": 90
}

Output files: camera-1-00001.avif, camera-1-00002.avif, etc.

Quality vs. File Size

Quality Use Case Typical Size (1080p)
60-70 Surveillance, archival 50-100 KB
80-85 General purpose 100-200 KB
90-95 High quality review 200-400 KB
100 Maximum quality 400-800 KB

Lossless Mode

For forensic or archival purposes:

"framegrab": {
  "interval_seconds": 30,
  "max_files": 50,
  "lossless": true
}

Lossless Files

Lossless AVIF files are significantly larger but preserve every detail of the original frame.

Motion AVIF Mode

Captures animated AVIF sequences instead of individual stills.

"framegrab": {
  "motion": true,
  "motion_duration_seconds": 30,
  "max_files": 10,
  "quality": 80
}

Output files: camera-1-00001.avifs, camera-1-00002.avifs, etc.

Clip Duration

Setting Behavior
motion_duration_seconds: 30 Creates 30-second clips
motion_duration_seconds: null Continuous recording until max_files

Motion vs. Still Comparison

Feature Still Mode Motion Mode
File extension .avif .avifs
Contains Single frame Animated sequence
File size Smaller Larger
Use case Periodic snapshots Event recording

Starting and Stopping

Automatic Start

Frame grabs start automatically when the pipeline plays if configured.

Manual Control

Start framegrab on a running pipeline:

curl -X PUT http://localhost:3539/flex/pipeline/camera-1/framegrab/start

Stop framegrab:

curl -X PUT http://localhost:3539/flex/pipeline/camera-1/framegrab/stop

Runtime Configuration

Override settings when starting:

curl -X PUT http://localhost:3539/flex/pipeline/camera-1/framegrab/start \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 2, "quality": 95}'

File Management

List Framegrabs

curl http://localhost:3539/flex/files/framegrabs

Filter by pipeline:

curl "http://localhost:3539/flex/files/framegrabs?pipeline_id=camera-1"

Response:

{
  "files": [
    {
      "filename": "camera-1-00001.avif",
      "pipeline_id": "camera-1",
      "size": 125432,
      "modified_at": "2026-01-27T10:30:00.000Z",
      "is_motion": false
    }
  ],
  "total_count": 5,
  "total_size": 627160
}

Download Framegrabs

curl -O http://localhost:3539/flex/files/framegrabs/camera-1-00001.avif

Delete Framegrabs

Single file:

curl -X DELETE http://localhost:3539/flex/files/framegrabs/camera-1-00001.avif

All files for a pipeline:

curl -X DELETE "http://localhost:3539/flex/files/framegrabs?pipeline_id=camera-1"

Rate Limits

Delete operations are rate-limited: 60/min for single files, 10/min for bulk delete.

Storage Location

Framegrabs are stored in the /framegrabs Docker volume:

volumes:
  - framegrabs:/framegrabs

To use a host directory instead:

volumes:
  - /path/to/framegrabs:/framegrabs

Best Practices

  1. Set appropriate intervals: Too frequent captures waste storage
  2. Use motion mode for events: Better for reviewing incidents
  3. Monitor disk usage: Framegrabs can consume significant storage
  4. Use quality 80-85: Good balance of quality and size
  5. Set reasonable max_files: Prevent disk exhaustion

Viewing AVIF Files

AVIF is supported by modern browsers and image viewers:

  • Chrome/Firefox/Safari: Native support
  • macOS Preview: Supports AVIF
  • Windows: Requires AV1 Video Extension from Microsoft Store
  • ImageMagick: display image.avif
  • ffmpeg: ffplay image.avif

For motion AVIF (.avifs):

  • Modern browsers support animated AVIF
  • VLC: vlc animation.avifs