Frame Delay

Reference a value from an earlier frame of the same video stream (N-k, into the past).

Reference a value produced on an earlier frame of the same video stream. Wire any workflow output (detections, numbers, strings, images, ...) into this block, set a negative offset, and the block returns that value as it was |offset| frames ago.

Only past (non-positive) offsets are supported. Genuine future look-ahead would require delaying the entire workflow output, which is not possible on synchronous runtimes (WebRTC/webexec, single-image HTTP), so it is intentionally not offered here.

How This Block Works

1. Reads video_metadata from the connected image to obtain the video_identifier (used to keep per-stream state isolated) and the monotonic frame_number (N).

2. Stores the incoming data in a per-video ring buffer keyed by frame number.

3. Resolves target_frame = N + offset (with offset <= 0) and returns data[target_frame] when buffered, otherwise default_value.

4. Reports is_available (whether the target frame was buffered) and reference_frame_number (always the current frame N).

Common Use Cases

• Compare the current frame to a past frame (-1, -5) for change/trend detection.

• Align a slow, delayed signal with the frame it belongs to.

• Remember what a value was N frames ago (e.g. the dominant color 10 frames earlier).

Requirements and Limitations

• offset must be <= 0. Positive offsets are rejected.

• |offset| may not exceed 256. Each buffered frame is held in memory, so delaying an image stream by a large offset is costly (~6 MB per frame at 1080p, ~25 MB at 4K). Prefer delaying a small derived value over a full image where possible.

• Past offsets work in every execution context; no output delay is introduced.

• State is kept in process memory keyed by video_identifier; it degrades on stateless/multi-replica remote HTTP runtimes.

• At most 16 streams are tracked concurrently; the least recently seen stream's buffer is discarded beyond that.

• A stream whose frame_number restarts (e.g. on reconnect) has its buffer cleared.

• State persists for the lifetime of the workflow and resets on restart.

• Values are unavailable (returning default_value) until enough frames have been processed to reach the requested |offset| depth.

• When offset is wired to a runtime selector, the buffer is sized to the largest |offset| seen so far on the stream, so alternating between shallow and deep offsets keeps the deep history available. Increasing the offset mid-stream makes deeper frames available only once enough new frames have been buffered.

Type identifier

Use the following identifier in step "type" field: roboflow_core/frame_delay@v1 to add the block as a step in your workflow.

Properties

Name	Type	Description	Refs
name	str	Enter a unique identifier for this step..	❌
offset	int	Relative frame offset into the past. Must be <= 0: e.g. -1 is the previous frame, -10 is ten frames ago, 0 is the current frame. Limited to -256, since every buffered frame is held in memory..	✅
default_value	Optional[bool, float, int, str]	Value returned when the requested frame is not (yet) available in the buffer..	❌

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Runtime compatibility

soft - runtime hosted_serverless, dedicated_deployment; execution remote; input video : Block keeps per-video state in process memory (keyed by video_metadata.video_identifier). With remote step execution on stateless or multi-replica HTTP runtimes, successive requests may be served by different worker processes, so the state resets between calls and the output is meaningless for tracking / counting / aggregation. Use local step execution in a persistent WebRTC session for stable cross-frame results.

soft - input image : Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Frame Delay in version v1 has.

Input and output bindings

• input

  • image (image): The image / video frame providing the video metadata (frame number and stream identifier) used to index the buffer..

  • data (Union[list_of_values, image, instance_segmentation_prediction, *, keypoint_detection_prediction, object_detection_prediction]): The value to delay. Can be detections, numbers, strings, images, or any other workflow output..

  • offset (integer): Relative frame offset into the past. Must be <= 0: e.g. -1 is the previous frame, -10 is ten frames ago, 0 is the current frame. Limited to -256, since every buffered frame is held in memory..

• output

  • output (*): Equivalent of any element.

  • is_available (boolean): Boolean flag.

  • reference_frame_number (integer): Integer value.

Example JSON definition

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/frame_delay@v1",
	    "image": "$inputs.image",
	    "data": "$steps.object_detection_model.predictions",
	    "offset": -1,
	    "default_value": null
	}