Handles prefetching and caching of video/audio frames for smooth playback. More...

#include <Qt/VideoCacheThread.h>

Inheritance diagram for openshot::VideoCacheThread:

Collaboration diagram for openshot::VideoCacheThread:

Public Member Functions
int	getSpeed () const

bool	isReady ()

void	NotifyPlaybackPosition (int64_t new_position)
	Update playback position without triggering seek behavior or cache invalidation. More...

void	Play ()
	Play method is unimplemented. More...

void	Reader (ReaderBase *new_reader)
	Attach a ReaderBase (e.g. Timeline, FFmpegReader) and begin caching. More...

void	Seek (int64_t new_position)
	Backward-compatible alias for playback position updates (no seek side effects). More...

void	Seek (int64_t new_position, bool start_preroll)
	Seek to a specific frame and optionally start a preroll (cache reset). More...

void	setSpeed (int new_speed)
	Set playback speed/direction. Positive = forward, negative = rewind, zero = pause. More...

bool	StartThread ()
	Start the cache thread at high priority. Returns true if it’s actually running. More...

void	Stop ()
	Stop method is unimplemented. More...

bool	StopThread (int timeoutMs=0)
	Stop the cache thread (wait up to timeoutMs ms). Returns true if it stopped. More...

	VideoCacheThread ()
	Constructor: initializes member variables and assumes forward direction on first launch. More...

	~VideoCacheThread () override

Protected Member Functions
int64_t	clampToTimelineRange (int64_t frame, int64_t timeline_end) const
	Clamp frame index to [1, timeline_end] when timeline_end is valid. More...

bool	clearCacheIfPaused (int64_t playhead, bool paused, CacheBase *cache)
	When paused and playhead is outside current cache, clear all frames. More...

int	computeDirection () const

int64_t	computePrerollFrames (const Settings *settings) const
	Compute preroll frame count from settings. More...

void	computeWindowBounds (int64_t playhead, int dir, int64_t ahead_count, int64_t timeline_end, int64_t &window_begin, int64_t &window_end) const
	Compute the “window” of frames to cache around playhead. More...

int64_t	getBytes (int width, int height, int sample_rate, int channels, float fps)
	Estimate memory usage for a single frame (video + audio). More...

void	handleUserSeek (int64_t playhead, int dir)
	If userSeeked is true, reset last_cached_index just behind the playhead. More...

void	handleUserSeekWithPreroll (int64_t playhead, int dir, int64_t timeline_end, int64_t preroll_frames)
	Reset last_cached_index to start caching with a directional preroll offset. More...

bool	prefetchWindow (CacheBase cache, int64_t window_begin, int64_t window_end, int dir, ReaderBase reader, int64_t max_frames_to_fetch=-1)
	Prefetch all missing frames in [window_begin ... window_end] or [window_end ... window_begin]. More...

int64_t	resolveTimelineEnd () const
	Resolve timeline end frame from reader/timeline metadata. More...

void	run () override
	Thread entry point: loops until threadShouldExit() is true. More...

Protected Attributes
std::atomic< int64_t >	cached_frame_count
	Estimated count of frames currently stored in cache. More...

std::atomic< bool >	clear_cache_on_next_fill
	True if next cache loop should clear existing cache ranges. More...

int64_t	current_display_frame
	Currently displayed frame (unused here, reserved). More...

bool	force_directional_cache
	(Reserved for future use). More...

std::shared_ptr< Frame >	last_cached_frame
	Last frame pointer added to cache. More...

std::atomic< int64_t >	last_cached_index
	Index of the most recently cached frame. More...

std::atomic< int >	last_dir
	Last direction sign (+1 forward, –1 backward). More...

std::atomic< int >	last_speed
	Last non-zero speed (for tracking). More...

std::atomic< int64_t >	min_frames_ahead
	Minimum number of frames considered “ready” (pre-roll). More...

std::atomic< bool >	preroll_on_next_fill
	True if next cache rebuild should include preroll offset. More...

ReaderBase *	reader
	The source reader (e.g., Timeline, FFmpegReader). More...

std::atomic< int64_t >	requested_display_frame
	Frame index the user requested. More...

std::atomic< bool >	scrub_active
	True while user is dragging/scrubbing the playhead. More...

std::mutex	seek_state_mutex
	Protects coherent seek state updates/consumption. More...

uint64_t	seen_timeline_cache_epoch
	Last observed Timeline cache invalidation epoch. More...

std::atomic< int >	speed
	Current playback speed (0=paused, >0 forward, <0 backward). More...

bool	timeline_cache_epoch_initialized
	True once an initial epoch snapshot has been taken. More...

int64_t	timeline_max_frame
	Highest valid frame index in the timeline. More...

std::atomic< bool >	userSeeked
	True if Seek(..., true) was called (forces a cache reset). More...

Detailed Description

Handles prefetching and caching of video/audio frames for smooth playback.

This thread continuously maintains a “window” of cached frames in the current playback direction (forward or backward). When paused, it continues to fill that same window; when seeking, it resets to cache around the new position.

Definition at line 37 of file VideoCacheThread.h.

Constructor & Destructor Documentation

◆ VideoCacheThread()

openshot::VideoCacheThread::VideoCacheThread ( )

Constructor: initializes member variables and assumes forward direction on first launch.

Definition at line 26 of file VideoCacheThread.cpp.

◆ ~VideoCacheThread()

openshot::VideoCacheThread::~VideoCacheThread ( )

override

Definition at line 49 of file VideoCacheThread.cpp.

Member Function Documentation

◆ clampToTimelineRange()

int64_t openshot::VideoCacheThread::clampToTimelineRange	(	int64_t	frame,
		int64_t	timeline_end
	)		const

protected

Clamp frame index to [1, timeline_end] when timeline_end is valid.

Definition at line 372 of file VideoCacheThread.cpp.

Referenced by clearCacheIfPaused(), isReady(), run(), and Seek().

◆ clearCacheIfPaused()

bool openshot::VideoCacheThread::clearCacheIfPaused	(	int64_t	playhead,
		bool	paused,
		CacheBase *	cache
	)

protected

When paused and playhead is outside current cache, clear all frames.

Parameters

playhead	Current requested_display_frame
paused	True if speed == 0
cache	Pointer to CacheBase

Returns: True if ClearAllCache() was invoked.

Definition at line 380 of file VideoCacheThread.cpp.

Referenced by run().

◆ computeDirection()

int openshot::VideoCacheThread::computeDirection ( ) const

protected

Returns: Effective playback direction (+1 forward, –1 backward), preserving last_dir if speed == 0.

Definition at line 308 of file VideoCacheThread.cpp.

Referenced by isReady(), run(), and Seek().

◆ computePrerollFrames()

int64_t openshot::VideoCacheThread::computePrerollFrames ( const Settings * settings ) const

protected

Compute preroll frame count from settings.

Definition at line 341 of file VideoCacheThread.cpp.

Referenced by run().

◆ computeWindowBounds()

void openshot::VideoCacheThread::computeWindowBounds	(	int64_t	playhead,
		int	dir,
		int64_t	ahead_count,
		int64_t	timeline_end,
		int64_t &	window_begin,
		int64_t &	window_end
	)		const

protected

Compute the “window” of frames to cache around playhead.

Parameters

	playhead	Current requested_display_frame
	dir	Effective direction (±1)
	ahead_count	Number of frames ahead/back to cache
	timeline_end	Last valid frame index
[out]	window_begin	Lower bound (inclusive) of caching window
[out]	window_end	Upper bound (inclusive) of caching window

If dir > 0: window = [playhead ... playhead + ahead_count] If dir < 0: window = [playhead – ahead_count ... playhead] Always clamps to [1 ... timeline_end].

Definition at line 400 of file VideoCacheThread.cpp.

Referenced by run().

◆ getBytes()

int64_t openshot::VideoCacheThread::getBytes	(	int	width,
		int	height,
		int	sample_rate,
		int	channels,
		float	fps
	)

protected

Estimate memory usage for a single frame (video + audio).

Parameters

width	Frame width (pixels)
height	Frame height (pixels)
sample_rate	Audio sample rate (e.g. 48000)
channels	Number of audio channels
fps	Frames per second

Returns: Approximate size in bytes for one frame

Definition at line 107 of file VideoCacheThread.cpp.

Referenced by run().

◆ getSpeed()

int openshot::VideoCacheThread::getSpeed ( ) const

inline

Returns: The current speed (1=normal, 2=fast, –1=rewind, etc.)

Definition at line 63 of file VideoCacheThread.h.

◆ handleUserSeek()

void openshot::VideoCacheThread::handleUserSeek	(	int64_t	playhead,
		int	dir
	)

protected

If userSeeked is true, reset last_cached_index just behind the playhead.

Parameters

playhead	Current requested_display_frame
dir	Effective direction (±1)

Definition at line 318 of file VideoCacheThread.cpp.

Referenced by run().

◆ handleUserSeekWithPreroll()

void openshot::VideoCacheThread::handleUserSeekWithPreroll	(	int64_t	playhead,
		int	dir,
		int64_t	timeline_end,
		int64_t	preroll_frames
	)

protected

Reset last_cached_index to start caching with a directional preroll offset.

Parameters

playhead	Current requested_display_frame
dir	Effective direction (±1)
timeline_end	Last valid frame index
preroll_frames	Number of frames to offset the cache start

Definition at line 324 of file VideoCacheThread.cpp.

Referenced by run().

◆ isReady()

bool openshot::VideoCacheThread::isReady ( )

Returns: True if at least min_frames_ahead frames have been cached.

Definition at line 54 of file VideoCacheThread.cpp.

Referenced by openshot::AudioReaderSource::getNextAudioBlock().

◆ NotifyPlaybackPosition()

void openshot::VideoCacheThread::NotifyPlaybackPosition ( int64_t new_position )

Update playback position without triggering seek behavior or cache invalidation.

Definition at line 288 of file VideoCacheThread.cpp.

Referenced by Seek().

◆ Play()

void openshot::VideoCacheThread::Play ( )

inline

Play method is unimplemented.

Definition at line 48 of file VideoCacheThread.h.

Referenced by Reader().

◆ prefetchWindow()

bool openshot::VideoCacheThread::prefetchWindow	(	CacheBase *	cache,
		int64_t	window_begin,
		int64_t	window_end,
		int	dir,
		ReaderBase *	reader,
		int64_t	max_frames_to_fetch = `-1`
	)

protected

Prefetch all missing frames in [window_begin ... window_end] or [window_end ... window_begin].

Parameters

cache	Pointer to CacheBase
window_begin	Inclusive lower bound of the window
window_end	Inclusive upper bound of the window
dir	Effective direction (±1)
reader	Pointer to ReaderBase to call GetFrame()

Returns: True if the window was already full (no new frames added)

Internally, this method iterates from last_cached_index + dir toward window_end (or window_begin) and calls GetFrame()/Add() for each missing frame until hitting the window boundary or an OOB. It also breaks early if threadShouldExit() or userSeeked becomes true.

Definition at line 422 of file VideoCacheThread.cpp.

Referenced by run().

◆ Reader()

void openshot::VideoCacheThread::Reader ( ReaderBase * new_reader )

Attach a ReaderBase (e.g. Timeline, FFmpegReader) and begin caching.

Parameters

new_reader

Definition at line 136 of file VideoCacheThread.cpp.

Referenced by openshot::QtPlayer::Reader().

◆ resolveTimelineEnd()

int64_t openshot::VideoCacheThread::resolveTimelineEnd ( ) const

protected

Resolve timeline end frame from reader/timeline metadata.

Definition at line 357 of file VideoCacheThread.cpp.

Referenced by clearCacheIfPaused(), run(), and Seek().

◆ run()

void openshot::VideoCacheThread::run ( )

overrideprotected

Thread entry point: loops until threadShouldExit() is true.

Definition at line 475 of file VideoCacheThread.cpp.

◆ Seek() [1/2]

void openshot::VideoCacheThread::Seek ( int64_t new_position )

Backward-compatible alias for playback position updates (no seek side effects).

Definition at line 283 of file VideoCacheThread.cpp.

Referenced by openshot::QtPlayer::Seek().

◆ Seek() [2/2]

void openshot::VideoCacheThread::Seek	(	int64_t	new_position,
		bool	start_preroll
	)

Seek to a specific frame and optionally start a preroll (cache reset).

Parameters

new_position	Frame index to jump to.
start_preroll	If true, forces cache to rebuild around new_position.

Definition at line 145 of file VideoCacheThread.cpp.

◆ setSpeed()

void openshot::VideoCacheThread::setSpeed ( int new_speed )

Set playback speed/direction. Positive = forward, negative = rewind, zero = pause.

Parameters

new_speed If new_speed != 0, last_speed and last_dir are updated. If new_speed == 0, last_dir is left unchanged so that pausing does not flip direction.

Definition at line 94 of file VideoCacheThread.cpp.

Referenced by openshot::QtPlayer::Speed().

◆ StartThread()

bool openshot::VideoCacheThread::StartThread ( )

Start the cache thread at high priority. Returns true if it’s actually running.

Start the cache thread at high priority, and return true if it’s actually running.

Definition at line 121 of file VideoCacheThread.cpp.

◆ Stop()

void openshot::VideoCacheThread::Stop ( )

inline

Stop method is unimplemented.

Definition at line 51 of file VideoCacheThread.h.

Referenced by openshot::QtPlayer::Stop().

◆ StopThread()

bool openshot::VideoCacheThread::StopThread ( int timeoutMs = 0 )

Stop the cache thread (wait up to timeoutMs ms). Returns true if it stopped.

Stop the cache thread, waiting up to timeoutMs ms. Returns true if it actually stopped.

Definition at line 130 of file VideoCacheThread.cpp.

Member Data Documentation

◆ cached_frame_count

std::atomic<int64_t> openshot::VideoCacheThread::cached_frame_count

protected

Estimated count of frames currently stored in cache.

Definition at line 201 of file VideoCacheThread.h.

Referenced by clearCacheIfPaused(), NotifyPlaybackPosition(), prefetchWindow(), run(), and Seek().

◆ clear_cache_on_next_fill

std::atomic<bool> openshot::VideoCacheThread::clear_cache_on_next_fill

protected

True if next cache loop should clear existing cache ranges.

Definition at line 196 of file VideoCacheThread.h.

Referenced by run(), and Seek().

◆ current_display_frame

int64_t openshot::VideoCacheThread::current_display_frame

protected

Currently displayed frame (unused here, reserved).

Definition at line 200 of file VideoCacheThread.h.

◆ force_directional_cache

bool openshot::VideoCacheThread::force_directional_cache

protected

(Reserved for future use).

Definition at line 207 of file VideoCacheThread.h.

◆ last_cached_frame

std::shared_ptr<Frame> openshot::VideoCacheThread::last_cached_frame

protected

Last frame pointer added to cache.

Definition at line 189 of file VideoCacheThread.h.

◆ last_cached_index

std::atomic<int64_t> openshot::VideoCacheThread::last_cached_index

protected

Index of the most recently cached frame.

Definition at line 211 of file VideoCacheThread.h.

Referenced by handleUserSeek(), handleUserSeekWithPreroll(), isReady(), prefetchWindow(), run(), and Seek().

◆ last_dir

std::atomic<int> openshot::VideoCacheThread::last_dir

protected

Last direction sign (+1 forward, –1 backward).

Definition at line 193 of file VideoCacheThread.h.

Referenced by computeDirection(), run(), and setSpeed().

◆ last_speed

std::atomic<int> openshot::VideoCacheThread::last_speed

protected

Last non-zero speed (for tracking).

Definition at line 192 of file VideoCacheThread.h.

Referenced by setSpeed().

◆ min_frames_ahead

std::atomic<int64_t> openshot::VideoCacheThread::min_frames_ahead

protected

Minimum number of frames considered “ready” (pre-roll).

Definition at line 203 of file VideoCacheThread.h.

Referenced by isReady(), and run().

◆ preroll_on_next_fill

std::atomic<bool> openshot::VideoCacheThread::preroll_on_next_fill

protected

True if next cache rebuild should include preroll offset.

Definition at line 195 of file VideoCacheThread.h.

Referenced by run(), and Seek().

◆ reader

ReaderBase* openshot::VideoCacheThread::reader

protected

The source reader (e.g., Timeline, FFmpegReader).

Definition at line 206 of file VideoCacheThread.h.

Referenced by clearCacheIfPaused(), isReady(), NotifyPlaybackPosition(), prefetchWindow(), Reader(), resolveTimelineEnd(), run(), and Seek().

◆ requested_display_frame

std::atomic<int64_t> openshot::VideoCacheThread::requested_display_frame

protected

Frame index the user requested.

Definition at line 199 of file VideoCacheThread.h.

Referenced by isReady(), NotifyPlaybackPosition(), run(), and Seek().

◆ scrub_active

std::atomic<bool> openshot::VideoCacheThread::scrub_active

protected

True while user is dragging/scrubbing the playhead.

Definition at line 197 of file VideoCacheThread.h.

Referenced by NotifyPlaybackPosition(), run(), Seek(), and setSpeed().

◆ seek_state_mutex

std::mutex openshot::VideoCacheThread::seek_state_mutex

mutableprotected

Protects coherent seek state updates/consumption.

Definition at line 212 of file VideoCacheThread.h.

Referenced by NotifyPlaybackPosition(), Reader(), run(), and Seek().

◆ seen_timeline_cache_epoch

uint64_t openshot::VideoCacheThread::seen_timeline_cache_epoch

protected

Last observed Timeline cache invalidation epoch.

Definition at line 208 of file VideoCacheThread.h.

Referenced by Reader(), and run().

◆ speed

std::atomic<int> openshot::VideoCacheThread::speed

protected

Current playback speed (0=paused, >0 forward, <0 backward).

Definition at line 191 of file VideoCacheThread.h.

Referenced by computeDirection(), getSpeed(), run(), Seek(), and setSpeed().

◆ timeline_cache_epoch_initialized

bool openshot::VideoCacheThread::timeline_cache_epoch_initialized

protected

True once an initial epoch snapshot has been taken.

Definition at line 209 of file VideoCacheThread.h.

Referenced by Reader(), and run().

◆ timeline_max_frame

int64_t openshot::VideoCacheThread::timeline_max_frame

protected

Highest valid frame index in the timeline.

Definition at line 204 of file VideoCacheThread.h.

◆ userSeeked

std::atomic<bool> openshot::VideoCacheThread::userSeeked

protected

True if Seek(..., true) was called (forces a cache reset).

Definition at line 194 of file VideoCacheThread.h.

Referenced by prefetchWindow(), run(), and Seek().

The documentation for this class was generated from the following files:

Qt/VideoCacheThread.h
Qt/VideoCacheThread.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ VideoCacheThread()

◆ ~VideoCacheThread()

Member Function Documentation

◆ clampToTimelineRange()

◆ clearCacheIfPaused()

◆ computeDirection()

◆ computePrerollFrames()

◆ computeWindowBounds()

◆ getBytes()

◆ getSpeed()

◆ handleUserSeek()

◆ handleUserSeekWithPreroll()

◆ isReady()

◆ NotifyPlaybackPosition()

◆ Play()

◆ prefetchWindow()

◆ Reader()

◆ resolveTimelineEnd()

◆ run()

◆ Seek() [1/2]

◆ Seek() [2/2]

◆ setSpeed()

◆ StartThread()

◆ Stop()

◆ StopThread()

Member Data Documentation

◆ cached_frame_count

◆ clear_cache_on_next_fill

◆ current_display_frame

◆ force_directional_cache

◆ last_cached_frame

◆ last_cached_index

◆ last_dir

◆ last_speed

◆ min_frames_ahead

◆ preroll_on_next_fill

◆ reader

◆ requested_display_frame

◆ scrub_active

◆ seek_state_mutex

◆ seen_timeline_cache_epoch

◆ speed

◆ timeline_cache_epoch_initialized

◆ timeline_max_frame

◆ userSeeked