> This page is for version 9.2 (default).
> For other versions, use one of these documentation indexes:
> - 9.2 (default): https://docs.nvidia.com/deepstream/9.2/llms.txt
> - Archives: https://docs.nvidia.com/deepstream/archives/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/deepstream/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/deepstream/_mcp/server.

# Gst-nvdsframeselector

The Gst-nvdsframeselector plugin is a GStreamer transform element that reduces a video stream to a smaller set of representative frames. It caches a configurable window of received frames and selects a subset from each window using one of three algorithms: BASIC equidistant selection, RANGE_BASED SAD (sum of absolute differences) selection, or optical-flow-based motion selection (default), the last of which adaptively favors frames with more motion.

## Inputs and Outputs

* Inputs

  * GStreamer buffer containing NV12/RGBA frame(s)

* Control parameters

  * gpu-id, selects the GPU ID
  * enable, cache-size, selection-count, frame-selection-algorithm, and the optical-flow/SAD tuning properties described below

* Output

  * GStreamer buffer containing only the selected representative frame(s); non-selected frames are dropped

## Features

The following table summarizes the features of the plugin.

**Gst-nvdsframeselector plugin features**

| Feature                             | Description                                                                                               | Release |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------- | ------- |
| Equidistant frame selection         | Selects evenly spaced frames from each cache window (BASIC algorithm)                                     | DS 9.2  |
| SAD-based range selection           | Selects frames using sum-of-absolute-differences scoring within each cache window (RANGE_BASED algorithm) | DS 9.2  |
| Optical-flow motion-based selection | Adaptively selects frames favoring higher motion using optical flow analysis (default algorithm)          | DS 9.2  |
| Bypass mode                         | Passes all frames through without selection when enabled                                                  | DS 9.2  |

## Gst Properties

The following table describes the Gst properties of the Gst-nvdsframeselector plugin. Use `gst-inspect-1.0 nvdsframeselector` to view the complete, current property list and defaults.

**Gst-nvdsframeselector plugin gst properties**

| Property                  | Meaning                                                                                                                                                                                           | Type and Range                        | Example Notes               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------- |
| gpu-id                    | Device ID of the GPU used for processing                                                                                                                                                          | Integer, 0 to 4,294,967,295           | gpu-id=0                    |
| enable                    | Enables or disables frame selection                                                                                                                                                               | Boolean                               | enable=1                    |
| cache-size                | Number of received frames retained before a selection decision                                                                                                                                    | Integer, 1 to 4,294,967,295           | cache-size=30               |
| selection-count           | Number of frames selected from each cache window                                                                                                                                                  | Integer, 1 to 4,294,967,295           | selection-count=5           |
| percentage-threshold      | Percentage threshold for frame filtering (0.0-100.0%, where 100% = max pixel difference of 255)                                                                                                   | Double, 0.0 to 100.0                  | percentage-threshold=10.0   |
| averaging-frames          | Number of frames to average for normalization                                                                                                                                                     | Integer, 1 to 4,294,967,295           | averaging-frames=5          |
| exclusion-range           | +/- range value for frame exclusion in the selection algorithm                                                                                                                                    | Integer, 0 to 4,294,967,295           | exclusion-range=2           |
| frame-selection-algorithm | Algorithm to use for frame selection: 0=BASIC equidistant, 1=RANGE_BASED SAD, 2=optical flow (default)                                                                                            | Enum                                  | frame-selection-algorithm=2 |
| bypass-mode               | Passes all frames through without selection when enabled                                                                                                                                          | Boolean                               | bypass-mode=0               |
| optical-flow-interval     | Analyzes every Nth received frame for optical flow; 0 automatically targets an approximately 0.5-second optical-flow interval                                                                     | Integer, 0 to 4,294,967,295           | optical-flow-interval=0     |
| enable-motion-detection   | Enables optical-flow-based motion detection for adaptive frame selection                                                                                                                          | Boolean                               | enable-motion-detection=1   |
| source-fps                | Native stream FPS; set when the input has been decimated before this element, so motion is normalized correctly                                                                                   | Double                                | source-fps=30.0             |
| of-tighten                | Tighten factor applied to the motion-scaled frame count before the minimum clamp (e.g. 0.5 halves the count, dropping the weakest frames); overridable at runtime via env NVDS_FSELECT_OF_TIGHTEN | Double, 0.0 to 1.0 (exclusive of 0.0) | of-tighten=0.5              |
| equidistant-output        | When TRUE, outputs evenly spaced frames from the chunk instead of motion-ranked frames; the count is still determined by the configured selection algorithm                                       | Boolean                               | equidistant-output=0        |