Streaming FFmpeg-based video file reader with background decode. More...

#include <VideoFileReader.hpp>

Inheritance diagram for MayaFlux::IO::VideoFileReader:

Collaboration diagram for MayaFlux::IO::VideoFileReader:

Public Member Functions
	VideoFileReader ()

	~VideoFileReader () override

bool	can_read (const std::string &filepath) const override
	Check if a file can be read by this reader.

bool	open (const std::string &filepath, FileReadOptions options=FileReadOptions::ALL) override
	Open a file for reading.

void	close () override
	Close the currently open file.

bool	is_open () const override
	Check if a file is currently open.

std::optional< FileMetadata >	get_metadata () const override
	Get metadata from the open file.

std::vector< FileRegion >	get_regions () const override
	Get semantic regions from the file.

std::vector< Kakshya::DataVariant >	read_all () override
	Read all data from the file into memory.

std::vector< Kakshya::DataVariant >	read_region (const FileRegion &region) override
	Read a specific region of data.

std::shared_ptr< Kakshya::SignalSourceContainer >	create_container () override
	Create and initialize a container from the file.

bool	load_into_container (std::shared_ptr< Kakshya::SignalSourceContainer > container) override
	Load file data into an existing container.

std::vector< uint64_t >	get_read_position () const override
	Get current read position in primary dimension.

bool	seek (const std::vector< uint64_t > &position) override
	Seek to a specific position in the file.

std::vector< std::string >	get_supported_extensions () const override
	Get supported file extensions for this reader.

std::type_index	get_data_type () const override
	Get the data type this reader produces.

std::type_index	get_container_type () const override
	Get the container type this reader creates.

std::string	get_last_error () const override
	Get the last error message.

bool	supports_streaming () const override
	Check if streaming is supported for the current file.

uint64_t	get_preferred_chunk_size () const override
	Get the preferred chunk size for streaming.

size_t	get_num_dimensions () const override
	Get the dimensionality of the file data.

std::vector< uint64_t >	get_dimension_sizes () const override
	Get size of each dimension in the file data.

void	set_ring_capacity (uint32_t n)
	Set the number of decoded frame slots in the ring buffer.

void	set_decode_batch_size (uint32_t n)
	Set the number of frames decoded per batch by the background thread.

void	set_refill_threshold (uint32_t n)
	Start refilling when fewer than this many frames remain ahead of the consumer read head.

void	set_video_options (VideoReadOptions options)

void	set_target_dimensions (uint32_t width, uint32_t height)

void	set_target_sample_rate (uint32_t sample_rate)

void	set_audio_options (AudioReadOptions options)

std::shared_ptr< Kakshya::SoundFileContainer >	get_audio_container () const
	After load_into_container(), retrieve the audio container if EXTRACT_AUDIO was set.

void	set_reader_id (uint64_t id)
	Assign an externally-managed reader_id before load_into_container().

uint64_t	get_reader_id () const
	Returns the reader_id active for this instance.

void	signal_decode ()
	Non-blocking signal to the background decode thread.

void	setup_io_service (uint64_t reader_id=0)
	Internal setup for IOService integration.

void	setup_io_service (const std::shared_ptr< Registry::Service::IOService > &io_service, uint64_t reader_id)
	Overload for IOManager-managed IOService.

Public Member Functions inherited from MayaFlux::IO::FileReader
virtual	~FileReader ()=default

Private Member Functions
void	start_decode_thread ()

void	stop_decode_thread ()

void	decode_thread_func ()

uint64_t	decode_batch (Kakshya::VideoFileContainer &vc, uint64_t batch_size)
	Decode up to batch_size frames starting at m_decode_head.

bool	seek_internal (const std::shared_ptr< FFmpegDemuxContext > &demux, const std::shared_ptr< VideoStreamContext > &video, uint64_t frame_position)

void	build_metadata (const std::shared_ptr< FFmpegDemuxContext > &demux, const std::shared_ptr< VideoStreamContext > &video) const

void	build_regions (const std::shared_ptr< FFmpegDemuxContext > &demux, const std::shared_ptr< VideoStreamContext > &video) const

void	set_error (const std::string &msg) const

void	clear_error () const

Private Attributes
std::shared_ptr< FFmpegDemuxContext >	m_demux

std::shared_ptr< VideoStreamContext >	m_video

std::shared_ptr< AudioStreamContext >	m_audio

std::shared_mutex	m_context_mutex

std::string	m_filepath

FileReadOptions	m_options = FileReadOptions::ALL

VideoReadOptions	m_video_options = VideoReadOptions::NONE

AudioReadOptions	m_audio_options = AudioReadOptions::NONE

uint32_t	m_target_width { 0 }

uint32_t	m_target_height { 0 }

uint32_t	m_target_sample_rate { 0 }

std::string	m_last_error

std::mutex	m_error_mutex

std::optional< FileMetadata >	m_cached_metadata

std::vector< FileRegion >	m_cached_regions

std::mutex	m_metadata_mutex

std::shared_ptr< Kakshya::SoundFileContainer >	m_audio_container

uint32_t	m_ring_capacity { 32 }

uint32_t	m_decode_batch_size { 8 }

uint32_t	m_refill_threshold { 0 }

uint64_t	m_reader_id { 0 }

bool	m_owns_io_service {}

std::weak_ptr< Kakshya::VideoFileContainer >	m_container_ref

std::thread	m_decode_thread

std::mutex	m_decode_mutex

std::condition_variable	m_decode_cv

std::atomic< bool >	m_decode_stop { false }

std::atomic< bool >	m_decode_active { false }

std::atomic< uint64_t >	m_decode_head { 0 }

std::shared_ptr< Registry::Service::IOService >	m_io_service

std::vector< uint8_t >	m_sws_buf
	One-frame sws scratch buffer (padded linesize, reused by decode thread).

Additional Inherited Members
Static Protected Member Functions inherited from MayaFlux::IO::FileReader
static std::unordered_map< std::string, Kakshya::RegionGroup >	regions_to_groups (const std::vector< FileRegion > &regions)
	Convert file regions to region groups.

Detailed Description

Streaming FFmpeg-based video file reader with background decode.

The reader is NOT transient — it stays alive alongside its container and owns the FFmpeg decode contexts plus a background decode thread. The lifecycle is:

open() → create_container() → load_into_container() → [playback] → close()

load_into_container() sets up the container's ring buffer, synchronously decodes the first batch (so frame 0 is available immediately), then starts a background thread that batch-decodes ahead of the consumer read head.

When the consumer (FrameAccessProcessor → VideoStreamReader) advances past ring_capacity - refill_threshold decoded frames, the decode thread automatically refills with the next decode_batch_size frames.

Seek invalidates the ring, repositions the demuxer, synchronously decodes the first batch at the new position, then restarts background decoding.

Audio extraction (EXTRACT_AUDIO) is delegated to SoundFileReader as before.

Definition at line 62 of file VideoFileReader.hpp.

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

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description