pynaviz.audiovideo.video_handling#

Classes

`FrameBuffer`([maxsize])	Fixed-size FIFO cache mapping frame index → raw av.VideoFrame.
`VideoHandler`(video_path[, stream_index, ...])	Random-access video reader with timestamp-aware seeking.

class pynaviz.audiovideo.video_handling.FrameBuffer(maxsize=30)[source]#

Bases: object

Fixed-size FIFO cache mapping frame index → raw av.VideoFrame.

Frames are stored in their native pixel format; conversion happens on retrieval, matching the existing behaviour of VideoHandler.

Parameters:: maxsize (int) – Maximum number of frames to keep. When full the oldest-inserted entry is evicted before adding a new one.

get(idx)[source]#

Return the cached frame for idx, or None on a miss.

Parameters:: idx (int)
Return type:: VideoFrame | None

put(idx, frame)[source]#

Insert frame under idx, evicting the oldest entry if full.

Parameters:

idx (int)
frame (VideoFrame)

Return type:

None

class pynaviz.audiovideo.video_handling.VideoHandler(video_path, stream_index=0, time=None, return_frame_array=True, buffer_size=30)[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.
buffer_size (int)

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)

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:: VideoFrame | TypeAliasForwardRef(‘numpy.typing.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:

start (float)
end (float)

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.

reopen()[source]#: Reopen the video stream if it was previously closed. No-op if already open.

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.