Frame Access

app.infrastructure.session.frame_access

View source code

Frame retrieval orchestration for session decode workers.

This module isolates cache lookup + seek + timeout polling from Session so the QObject container remains focused on view_state ownership.

See Also

• VideoRingBuffer — provides cached frame lookup
• Session — delegates frame retrieval to this accessor

Layer: Infrastructure. Context: Implements concrete processing and I/O behind application-facing contracts.

SessionFrameAccessor

Resolve requested frames through the decode worker cache.

The accessor preserves the existing playback semantics

1. Clamp frame index to valid metadata range.
2. Return cache hits immediately.
3. Trigger request_seek for non-sequential jumps.
4. Poll for worker output until timeout.
5. Synchronize session view_state on successful retrieval.

PARAMETER	DESCRIPTION
timeout_seconds	Maximum time to wait for a decoded frame. TYPE: float DEFAULT: 2.0
poll_interval_seconds	Delay between checks for a decoded frame. TYPE: float DEFAULT: 0.01

__init__(timeout_seconds: float = 2.0, poll_interval_seconds: float = 0.01) -> None

get_buffered_frame(*, session_state: SessionState, decode_worker: VideoDecodeWorker) -> RGBFrame | None

Return lookahead frame (current index + 1) from decode cache flow.

PARAMETER	DESCRIPTION
session_state	Playback state whose index and frame cache are updated. TYPE: SessionState
decode_worker	Worker providing decoded frames and seek requests. TYPE: VideoDecodeWorker

RETURNS	DESCRIPTION
RGBFrame | None	Next RGB frame, or None if it is not decoded before the timeout.

Side Effects

Because this delegates to get_next_frame, successful retrieval also advances the playback index and updates the current-frame cache.

get_current_frame(*, session_state: SessionState, decode_worker: VideoDecodeWorker) -> RGBFrame | None

Return the cached frame at the current playback position, loading it if absent.

PARAMETER	DESCRIPTION
session_state	Session playback state and current-frame cache. TYPE: SessionState
decode_worker	Worker providing decoded frames. TYPE: VideoDecodeWorker

RETURNS	DESCRIPTION
RGBFrame | None	Current RGB frame, or None if retrieval times out.

Side Effects

On a cache miss, delegates to get_frame_by_index, which may seek, wait for decoding, and update session playback/cache state.

get_frame_by_index(*, session_state: SessionState, decode_worker: VideoDecodeWorker, frame_index: int) -> RGBFrame | None

Return a clamped frame index from cache, seeking and polling on a cache miss.

PARAMETER	DESCRIPTION
session_state	Session state providing frame-count bounds and playback cache. TYPE: SessionState
decode_worker	Decode worker that owns the ring buffer cache. TYPE: VideoDecodeWorker
frame_index	Requested index; it is clamped to the available metadata range. TYPE: int

RETURNS	DESCRIPTION
RGBFrame | None	Decoded RGB frame, or None if it is not available before the timeout.

Side Effects

On a cache hit or successful poll, updates the current frame index and frame-data cache. A seek is requested for non-sequential misses and misses of the current frame.

get_next_frame(*, session_state: SessionState, decode_worker: VideoDecodeWorker) -> RGBFrame | None

Request the frame one index after the current playback position.

PARAMETER	DESCRIPTION
session_state	Playback state whose index and frame cache are updated. TYPE: SessionState
decode_worker	Worker providing decoded frames and seek requests. TYPE: VideoDecodeWorker

RETURNS	DESCRIPTION
RGBFrame | None	Next RGB frame, or None if it is not decoded before the timeout.

Side Effects

The requested index is clamped to the metadata range, so the final frame is returned again when playback is already at the end. On success, updates the playback index and current-frame cache.

get_previous_frame(*, session_state: SessionState, decode_worker: VideoDecodeWorker) -> RGBFrame | None

Request the frame one index before the current playback position.

PARAMETER	DESCRIPTION
session_state	Playback state whose index and frame cache are updated. TYPE: SessionState
decode_worker	Worker providing decoded frames and seek requests. TYPE: VideoDecodeWorker

RETURNS	DESCRIPTION
RGBFrame | None	Previous RGB frame, or None if it is not decoded before the timeout.

Side Effects

The requested index is clamped to the metadata range, so frame zero is returned again when playback is already at the beginning. On success, updates the playback index and current-frame cache.