roboto.experimental.video.frames#

On-demand extraction of decoded frames from a time range of compressed video.

A time range of video usually starts mid-GOP: its leading delta frames are only decodable after the keyframe that precedes the range. This module hides that — callers provide a way to load (log_time, data) messages for a time range, ask for a range, and receive one decoded frame per decodable frame in it. When the range starts mid-GOP, the preceding keyframe is found by walking backward (bounded by keyframe_lookback_ns) and the prefix is decoded but not emitted.

Module Contents#

roboto.experimental.video.frames.DEFAULT_KEYFRAME_LOOKBACK_NS: int = 10000000000#

How far before a requested range to search for the keyframe that makes the range’s leading delta frames decodable. Bounds the cost of the backward walk on streams with pathological keyframe intervals.

roboto.experimental.video.frames.MessageRangeLoader#

Loads a topic’s (log_time, data) messages for a (start_time, end_time) range.

Both times are nanoseconds since Unix epoch; messages must come back in ascending log-time order. Whether end_time is inclusive follows the underlying reader — frame emission is bounded by log-time filtering, not by the loader’s boundary semantics.

roboto.experimental.video.frames.decode_frames_in_range(load_messages, start_time, end_time, keyframe_lookback_ns=DEFAULT_KEYFRAME_LOOKBACK_NS)#

Decode the H.264 video frames of a time range.

Frames in the range that are undecodable — e.g. delta frames whose keyframe lies further back than keyframe_lookback_ns — are silently omitted; no player could render them either.

Parameters:

  • load_messages (MessageRangeLoader) – Loads the topic’s (log_time, data) messages for a time range; called once for the requested range and, when the range starts mid-GOP, once more for the keyframe lookback before it.

  • start_time (int) – Start of the range in nanoseconds since Unix epoch (inclusive).

  • end_time (int) – End of the range in nanoseconds since Unix epoch; passed through to load_messages.

  • keyframe_lookback_ns (int) – Upper bound on how far before start_time to search for the keyframe that anchors the range’s leading delta frames.

Yields:

One DecodedVideoFrame per decodable frame with log_time >= start_time, in ascending log-time order.

Raises:

ImportError – If PyAV is not installed (roboto[video]).

Return type:

collections.abc.Generator[roboto.experimental.video.decoder.DecodedVideoFrame, None, None]

Examples

>>> from roboto.experimental.video import decode_frames_in_range
>>> frames = decode_frames_in_range(  
...     load_messages=my_loader, start_time=start_ns, end_time=end_ns
... )
>>> next(frames).to_image()
On this page