Video in Rerun

A stream of images (like those produced by a camera) can be logged to Rerun in several different ways:

• Uncompressed, as many Images
• Compressed as many EncodedImages, using e.g. JPEG.
• Compressed as a single AssetVideo, using e.g. MP4.

These alternatives range on a scale of "simple, lossless, and big" to "complex, lossy, and small".

If you want lossless encoded images (with no compression artifacts), then you should log each video frame as Image. This will use up a lot of space and bandwidth. You can also encode them as PNG and log them as EncodedImage, though it should be noted that PNG encoding usually does very little for the file size of photographic images.

If you want to reduce bandwidth and storage cost, you can encode each frame as a JPEG and log it using EncodedImage. This can easily reduce the file sizes by almost two orders of magnitude with minimal perceptual loss. This is also very simple to do, and the Python logging SDK has built-in support for it using Image.compress.

Finally, you can encode the images as a video file, and log it using AssetVideo. This gives the best compression ratio, reducing file sizes and bandwidth requirements.

"""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)],
)

AssetVideo limitations assetvideo-limitations

Video support is new in Rerun, and has several limitations:

• #7298: Video playback only works in the web viewer
• #7354: Only the MP4 container format is supported
• #5181: There is no audio support
• There is no video encoder in the Rerun SDK, so you need to create the video file yourself
• Only a limited sets of codecs are supported (see below)

Web viewer support web-viewer-support

As of writing, playback of AssetVideo is only supported on the web viewer. Native video playback is coming, and can be tracked in this GitHub issue.

Video playback is done using the browser's own video decoder, so the supported codecs depend on your browser.

Overall, we recommend using Chrome or another Chromium-based browser, as it seems to have the best video support as of writing.

When choosing a codec, we recommend AV1, as it seems to have the best overall playback support while also having very high compression quality. Since AV1 is patent-free, it is also likely the first codec we will support in the native viewer.

For decoding video in the Web Viewer, we use the WebCodecs API. This API enables us to take advantage of the browser's hardware accelerated video decoding capabilities. It is implemented by all modern browsers, but with varying levels of support for different codecs, and varying levels of quality.

With that in mind, here are the browsers which we have tested and verified to generally work:

When it comes to codecs, we aim to support any codec which the browser supports, but we currently cannot guarantee that all of them will work. For more information about which codecs are supported by which browser, see Video codecs on MDN.

At the moment, we test the following codecs:

Links links

• Web video codec guide, by Mozilla