pynaviz.audiovideo.VideoHandler#

class pynaviz.audiovideo.VideoHandler(video_path, stream_index=0, time=None, return_frame_array=True)[source]#

Bases: BaseAudioVideo

Random-access video reader with timestamp-aware seeking.

This class wraps a PyAV container to provide precise, timestamp-based random access to frames. It can return either av.VideoFrame objects or RGB float arrays in the shape (H, W, 3) normalized to [0, 1]. Internally, a background thread builds an index of presentation timestamps (PTS) for fast seeks, with a fallback to on-the-fly indexing when the total frame count is unknown.

Parameters:

  • video_path (str | pathlib.Path) – Path to the video file.

  • stream_index (int) – Index of the video stream to use, default is 0.

  • time (Optional[NDArray]) – Experimental timestamps for each frame (seconds). If None, a uniform grid is generated from the stream’s average rate.

  • return_frame_array (bool) – If True (default), return frames as np.ndarray (RGB, float32 in [0, 1]); otherwise return av.VideoFrame instances.

Examples

>>> from pynaviz.audiovideo import VideoHandler
>>> vh = VideoHandler("example.mp4")
>>> # Get the frame at 1.5 seconds.
>>> frame = vh.get(1.5)
>>> # Shape: (height, width, channels)
>>> frame.shape
(480, 640, 3)
>>> # Get frames from the second to the 10th, every other frame.
>>> frame_sequence = vh[1:10:2]
>>> # Shape: (n_samples, height, width, channels)
>>> frame_sequence.shape
(5, 480, 640, 3)
__init__(video_path, stream_index=0, time=None, return_frame_array=True)[source]#
Parameters:

  • video_path (str | Path)

  • stream_index (int)

  • time (TypeAliasForwardRef('numpy.typing.NDArray') | None)

  • return_frame_array (bool)

Return type:

None

Methods

__init__(video_path[, stream_index, time, ...])

close()

Close the audiovideo stream.

get(ts)

Return the frame at (or immediately preceding) a timestamp.

get_slice(start[, end])

Attributes

index

Time index in seconds corresponding to frames.

shape

t

Time index in seconds corresponding to frames.
close()#

Close the audiovideo stream.

get(ts)[source]#

Return the frame at (or immediately preceding) a timestamp.

Parameters:

ts (float) – Target time in seconds.

Returns:

If return_frame_array is True, returns an array with shape (H, W, 3) (RGB, float32 in [0, 1]). Otherwise returns an av.VideoFrame.

Return type:

av.VideoFrame | NDArray

Notes

  • Seeks to the closest keyframe behind ts and decodes forward until the target is reached.

  • Uses an internal cache: if the requested frame index matches the previously decoded one, the cached frame is returned.

get_slice(start, end=None)[source]#
Parameters:
property index: numpy.typing.NDArray#

Time index in seconds corresponding to frames.

If time was provided at initialization, that array is returned. Otherwise, a uniformly spaced array derived from the stream rate is used and may be updated as indexing progresses.

property shape: Tuple[int, int, int]#
:

Shape of the video, (n_frames, width, height).

Notes

  • When the total frame count is unknown at initialization, the length may grow while the background indexer discovers frames. A warning is emitted until indexing is complete.

property t: numpy.typing.NDArray#

Time index in seconds corresponding to frames.

If time was provided at initialization, that array is returned. Otherwise, a uniformly spaced array derived from the stream rate is used and may be updated as indexing progresses.