VideoFrameReference

References a single video frame.

Used to display individual video frames from a archetypes.AssetVideo. To show an entire video, a video frame reference for each frame of the video should be logged.

See https://rerun.io/docs/reference/video for details of what is and isn't supported.

Components components

Required: VideoTimestamp

Optional: EntityPath

Shown in shown-in

Spatial2DView
Spatial3DView (if logged under a projection)
DataframeView

API reference links api-reference-links

Examples examples

Video with automatically determined frames video-with-automatically-determined-frames

"""Log a video asset using automatically determined frame references."""
# TODO(#7298): ⚠️ Video is currently only supported in the Rerun web viewer.

import sys

import rerun as rr

if len(sys.argv) < 2:
    # TODO(#7354): Only mp4 is supported for now.
    print(f"Usage: {sys.argv[0]} <path_to_video.[mp4]>")
    sys.exit(1)

rr.init("rerun_example_asset_video_auto_frames", spawn=True)

# Log video asset which is referred to by frame references.
video_asset = rr.AssetVideo(path=sys.argv[1])
rr.log("video", video_asset, static=True)

# Send automatically determined video frame timestamps.
frame_timestamps_ns = video_asset.read_frame_timestamps_ns()
rr.send_columns(
    "video",
    # Note timeline values don't have to be the same as the video timestamps.
    times=[rr.TimeNanosColumn("video_time", frame_timestamps_ns)],
    components=[rr.VideoFrameReference.indicator(), rr.components.VideoTimestamp.nanoseconds(frame_timestamps_ns)],
)

View

Demonstrates manual use of video frame references demonstrates-manual-use-of-video-frame-references

"""Manual use of individual video frame references."""
# TODO(#7298): ⚠️ Video is currently only supported in the Rerun web viewer.

import sys

import rerun as rr
import rerun.blueprint as rrb

if len(sys.argv) < 2:
    # TODO(#7354): Only mp4 is supported for now.
    print(f"Usage: {sys.argv[0]} <path_to_video.[mp4]>")
    sys.exit(1)

rr.init("rerun_example_asset_video_manual_frames", spawn=True)

# Log video asset which is referred to by frame references.
rr.log("video_asset", rr.AssetVideo(path=sys.argv[1]), static=True)

# Create two entities, showing the same video frozen at different times.
rr.log(
    "frame_1s",
    rr.VideoFrameReference(seconds=1.0, video_reference="video_asset"),
)
rr.log(
    "frame_2s",
    rr.VideoFrameReference(seconds=2.0, video_reference="video_asset"),
)

# Send blueprint that shows two 2D views next to each other.
rr.send_blueprint(rrb.Horizontal(rrb.Spatial2DView(origin="frame_1s"), rrb.Spatial2DView(origin="frame_2s")))

View