Overview

Use the Filter Stream Node to conditionally allow one or more frames to pass through to the downstream Nodes. This is typically used to selectively take snapshots, or save clips, or send webhooks when specific conditions are met.

Inputs & Outputs

Inputs : 1, Media Format : Raw Video
Outputs : Raw Video
Output Metadata: nodes.<node_id>.triggered

Pipeline usage

Place Filter Frames after nodes that produce metadata used by condition, and before expensive or output nodes that should run only for selected frames. A condition takes precedence over interval. With no duration, condition mode passes frames while the condition is true and interval mode passes one frame per interval. A non-negative duration opens a time window on each new trigger; -1 passes only the triggering frame. Because dropped frames never reach downstream nodes, do not place metadata producers needed by the condition after this node.

Properties

Property	Description	Type	Default	Required
`mode`	Mode. Options: Allow (`allow`): Allow frames to pass through conditionally; Drop (`drop`): Drop all frames.	`enum`	`allow`	No
`condition`	Allow frames when this condition evaluates to true. If `duration` is specified, allow only for `duration` every time condition goes from false to true. Otherwise, allow while condition is true. Conditional on `mode` being `allow`.	trigger-condition	`null`	No
`interval`	Allow frames at this interval. If `duration` is specified, allow for `duration` every interval, else allow once per interval. Ignored if condition is specified. Conditional on `mode` being `allow`. Unit: seconds.	`float`	`null`	No
`duration`	If specified, allow frames through for this duration depending on condition or at the specified `interval`. Set to -1 to allow only a single frame. Conditional on `mode` being `allow`. Unit: seconds.	`float`	`null`	No
`debug`	Log debugging information?	`bool`	`false`	No

Output Metadata

The fields below are declared by this node's metadata schema; the JSON values are representative examples.

Path	Type	Description
`nodes.<node_id>.triggered`	`boolean`	Boolean indicating whether the configured frame filter condition is currently true.
`nodes.<node_id>.type`	`string`	Identifies the node type that produced this metadata.

JSON example

{
  "nodes": {
    "filter_frames1": {
      "triggered": false,
      "type": "filter_frames"
    }
  }
}