VideoPlayer subclass pre-registered with every video/audio codec this library ships a portable decoder for - H264/MJPEG/MPEG-1 video, MP3/AAC/MP2 audio - so it's the "just point it at a file, any common codec just works" player. Use instead of the base VideoPlayer unless you want to keep these dependencies out of your build (the base class's own multi-decoders start out completely empty, requiring an explicit addVideoDecoder()/addAudioDecoder() call per codec). More...

#include <VideoPlayerFull.h>

Inheritance diagram for VideoPlayerFull:

Public Member Functions
	VideoPlayerFull ()

	VideoPlayerFull (Demuxer &demuxer, VideoOutput &videoOutput)

	VideoPlayerFull (Demuxer &demuxer, VideoOutput &videoOutput, AudioOutput &audioOutput)

	VideoPlayerFull (Demuxer &demuxer, VideoOutput &videoOutput, AudioStream &audioOutput)

	VideoPlayerFull (Demuxer &demuxer, VideoOutput &videoOutput, Print &audioOutput)

void	addAudioDecoder (AudioDecoder &decoder, const char *mime=nullptr)

void	addDemuxer (Demuxer &demuxer)

void	addVideoDecoder (VideoDecoder &decoder)

MultiDecoder &	audioDecoder ()

bool	begin (Stream &source)

size_t	copy ()

size_t	copyAll ()
	Copies until the source is exhausted (blocking).

MultiVideoDemuxer &	demuxer ()

void	end ()

Stream *	getStream ()
	The Stream given to begin() - nullptr before the first begin() call.

bool	isActive () const

void	logTo (Print &out)

	operator bool () const
	Same as isActive().

void	setActive (bool isActive)

void	setAudioOutput (AudioOutput &out)

void	setAudioOutput (AudioStream &out)

void	setAudioOutput (Print &out)

void	setBufferSize (int size)

void	setCatchUpThresholdFrames (float frames)

void	setIgnorePFrames (bool active)

void	setMaxQueuedIFrames (int count)

void	setQueueBytes (size_t bytes)

void	setQueueUsePSRAM (bool flag)

void	setResyncQueueFillFraction (float fraction)

void	setResyncThresholdMs (uint32_t ms)

void	setSchedulingDelayMs (uint32_t delayMs)

void	setTaskParameters (uint32_t stackSizeWords, uint8_t priority, int core=-1)

void	setUseAudioClock (bool active)

void	setVideoOutput (VideoOutput &out)

bool	useAudioClock () const
	Current setUseAudioClock() setting.

MultiVideoDecoder &	videoDecoder ()

PacedVideoOutput &	videoSyncTask ()

Protected Member Functions
void	registerAudioDecoders ()

void	registerVideoDecoders ()

Protected Attributes
AACDecoderHelix	aac_decoder

bool	active = false

AudioTimeSourceStream	audio_clock

EncodedAudioStream	audio_out

int	buffer_size = 1024

MultiDecoder	default_audio_decoder

MultiVideoDemuxer	default_demuxer

MultiVideoDecoder	default_video_decoder

H264Decoder	h264_decoder

MJPEGDecoder	mjpeg_decoder

MP2Decoder	mp2_decoder

MP3DecoderHelix	mp3_decoder

MPGDecoder	mpeg_decoder

Print *	p_audio_output = nullptr

AudioOutput *	p_audio_output_typed = nullptr

AudioStream *	p_audio_stream = nullptr

Stream *	p_source = nullptr

VideoOutput *	p_video_output = nullptr

bool	use_audio_clock = true

PacedVideoOutput	video_sync {default_video_decoder}

Detailed Description

VideoPlayer subclass pre-registered with every video/audio codec this library ships a portable decoder for - H264/MJPEG/MPEG-1 video, MP3/AAC/MP2 audio - so it's the "just point it at a file, any common codec just works" player. Use instead of the base VideoPlayer unless you want to keep these dependencies out of your build (the base class's own multi-decoders start out completely empty, requiring an explicit addVideoDecoder()/addAudioDecoder() call per codec).

Pre-registers no container demuxer though - still supply one via the constructor/addDemuxer(), as the base VideoPlayer requires. Pass a MultiVideoDemuxerFull (Video/MultiVideoDemuxerFull.h) for the same "any format just works" convenience one layer down (AVI/MP4/MPG):

MultiVideoDemuxerFull demuxer;
VideoPlayerFull player(demuxer, tftOutput, audioOut);
player.begin(file);

WAV is deliberately not included (no external dependency to justify bundling it) - register it yourself if needed: addAudioDecoder(wavDecoder, "audio/vnd.wave").

Dependencies (install via Library Manager):

Author: Phil Schatzmann

Copyright: GPLv3

Constructor & Destructor Documentation

◆ VideoPlayerFull() [1/5]

VideoPlayerFull ( )

inline

Registers all bundled video/audio decoders (H264/MJPEG/MPEG-1 video, MP3/AAC/MP2 audio); wire a Demuxer and VideoOutput/AudioOutput separately via addDemuxer()/setVideoOutput()/setAudioOutput() before begin().

◆ VideoPlayerFull() [2/5]

VideoPlayerFull	(	Demuxer &	demuxer,
		VideoOutput &	videoOutput
	)

inline

Video-only playback (no audio track), pre-registered with all bundled video decoders. demuxer is registered the same way VideoPlayer's own matching constructor does (a plain addDemuxer() call) - pass a MultiVideoDemuxerFull here instead of a single concrete demuxer if you also want every container format supported (see this class's own comment).

◆ VideoPlayerFull() [3/5]

VideoPlayerFull	(	Demuxer &	demuxer,
		VideoOutput &	videoOutput,
		AudioOutput &	audioOutput
	)

inline

Video + audio playback with an AudioOutput target, pre-registered with all bundled video/audio decoders - audio-clock-driven video scheduling applies by default, same as VideoPlayer's matching constructor; demuxer is registered as described in the video-only constructor above.

◆ VideoPlayerFull() [4/5]

VideoPlayerFull	(	Demuxer &	demuxer,
		VideoOutput &	videoOutput,
		Print &	audioOutput
	)

inline

Video + audio playback with a generic Print target, pre-registered with all bundled video/audio decoders - audio-clock-driven video scheduling applies by default, same as VideoPlayer's matching constructor; demuxer is registered as described in the video-only constructor above.

◆ VideoPlayerFull() [5/5]

VideoPlayerFull	(	Demuxer &	demuxer,
		VideoOutput &	videoOutput,
		AudioStream &	audioOutput
	)

inline

Video + audio playback with an AudioStream target, pre-registered with all bundled video/audio decoders - audio-clock-driven video scheduling applies by default, same as VideoPlayer's matching constructor; demuxer is registered as described in the video-only constructor above.

Member Function Documentation

◆ addAudioDecoder()

void addAudioDecoder	(	AudioDecoder &	decoder,
		const char *	mime = `nullptr`
	)

inlineinherited

Registers an audio codec decoder (MP3DecoderHelix/AACDecoderHelix/...) with the built-in MultiDecoder, keyed by the mime string given here (or the decoder's own default mime type if mime is null). The built-in decoder selector starts out completely empty, so this needs at least one call per audio codec your content actually uses before begin() is called - call it multiple times to support more than one codec.

◆ addDemuxer()

void addDemuxer ( Demuxer & demuxer )

inlineinherited

Registers a container demuxer implementation (DemuxerAVI/DemuxerMP4/ DemuxerMPG/...) with the built-in MultiVideoDemuxer, keyed under the demuxer's own Demuxer::mimeVideo(). The built-in demuxer selector starts out completely empty, so this needs at least one call per container format your content actually uses before begin() is called

call it multiple times to support more than one format.

◆ addVideoDecoder()

void addVideoDecoder ( VideoDecoder & decoder )

inlineinherited

Registers a video codec decoder (H264Decoder/MJPEGDecoder/MPGDecoder/ ...) with the built-in MultiVideoDecoder, keyed under the decoder's own VideoDecoder::codecFormat(). The built-in decoder selector starts out completely empty, so this needs at least one call per video codec your content actually uses before begin() is called - call it multiple times to support more than one codec.

◆ audioDecoder()

MultiDecoder & audioDecoder ( )

inlineinherited

The built-in audio multi-decoder, empty until addAudioDecoder() has registered at least one audio codec decoder - also useful for diagnostics (e.g. selectedMime()).

◆ begin()

bool begin ( Stream & source )

inlineinherited

Wires the full pipeline (video decoder -> output via PacedVideoOutput; audio decoder -> [audio clock ->] output, if an audio output was given) and starts the demuxer. source (e.g. an open File) is read from on every subsequent copy() call - the caller owns it and is responsible for closing it once copy()/copyAll() signal end of stream (return 0).

◆ copy()

size_t copy ( )

inlineinherited

Reads and demuxes one chunk (setBufferSize(), default 1024 bytes) from the source given to begin() - call this every loop() iteration. Also keeps the video schedule's fps in sync with the demuxer's own parsed rate, since VideoInfo::fps only becomes known partway through (once the container's header has been parsed) - no separate polling needed in the caller's loop(), unlike the *.ino examples this class replaces.

Returns: bytes actually copied - 0 once the source is exhausted (or playback is inactive/not begin()'d), matching CodecCopy::copy()'s own "0 means stop" convention every current *.ino example already checks for.

◆ copyAll()

size_t copyAll ( )

inlineinherited

Copies until the source is exhausted (blocking).

◆ demuxer()

MultiVideoDemuxer & demuxer ( )

inlineinherited

The built-in demuxer multi-selector, empty until addDemuxer() has registered at least one container demuxer - also useful for diagnostics (e.g. selectedDemuxer()/mimeVideo()).

◆ end()

void end ( )

inlineinherited

Stops playback and releases the video/audio decoders + the sync task's background render thread. The Stream given to begin() is left for the caller to close.

◆ getStream()

Stream * getStream ( )

inlineinherited

The Stream given to begin() - nullptr before the first begin() call.

◆ isActive()

bool isActive ( ) const

inlineinherited

True between a successful begin() and end()/setActive(false)/source exhaustion.

◆ logTo()

void logTo ( Print & out )

inlineinherited

Logs periodic playback diagnostics (frame count, average frame time, output fps, ...) to out - convenience shortcut for videoSyncTask().logTo(out).

◆ operator bool()

operator bool ( ) const

inlineinherited

Same as isActive().

◆ registerAudioDecoders()

void registerAudioDecoders ( )

inlineprotected

Registers all bundled audio decoders (MP3/AAC/MP2) with the base VideoPlayer's MultiDecoder - called from every constructor.

◆ registerVideoDecoders()

void registerVideoDecoders ( )

inlineprotected

Registers all bundled video decoders (H264/MJPEG/MPEG-1) with the base VideoPlayer's MultiVideoDecoder - called from every constructor.

◆ setActive()

void setActive ( bool isActive )

inlineinherited

Halts copy()/copyAll() without tearing down the pipeline (unlike end()) - resume with setActive(true).

◆ setAudioOutput() [1/3]

void setAudioOutput ( AudioOutput & out )

inlineinherited

◆ setAudioOutput() [2/3]

void setAudioOutput ( AudioStream & out )

inlineinherited

◆ setAudioOutput() [3/3]

void setAudioOutput ( Print & out )

inlineinherited

Defines the final audio output target and enables the audio playback path - leave unset entirely for video-only content. The caller must already have configured/begin()'d it. Call before begin(). Also enables audio-clock-driven video scheduling by default (see setUseAudioClock()) - call setUseAudioClock(false) afterwards to turn that off.

Three overloads, mirroring AudioPlayer::setOutput(): AudioOutput and AudioStream are unrelated types (both derive from Print, but neither derives from the other), so the most specific one actually available should be used. Using the specific overload lets begin() wire the audio clock/EncodedAudioStream through the matching setOutput(AudioOutput&)/setStream(AudioStream&) overload instead of falling back to the generic Print& one - that's what makes things like audio-info change notifications reach the real output correctly.

◆ setBufferSize()

void setBufferSize ( int size )

inlineinherited

Sets the read-buffer size (bytes) copy() uses per call (default 1024, same as CodecCopy's own default). Call before begin().

◆ setCatchUpThresholdFrames()

void setCatchUpThresholdFrames ( float frames )

inlineinherited

How many frame periods behind schedule playback must fall before non-keyframes start being proactively dropped to catch up, instead of only dropping once the frame queue is completely full. 1.0 (the default) starts dropping once the most recently rendered frame was at least one frame period late; a lower value catches up faster at the cost of more dropped frames, a higher value tolerates more backlog before reacting. Forwards to the built-in PacedVideoOutput; call before begin().

◆ setIgnorePFrames()

void setIgnorePFrames ( bool active )

inlineinherited

Unconditionally discards every non-keyframe (P/B-frame) as it arrives, before it is even queued for decode - a codec-agnostic way to render only keyframes, cheaper than letting the decoder decode and then discard each one. Off by default. Independent of the catch-up/backlog-driven dropping described above, which still applies when this is off. Forwards to the built-in PacedVideoOutput; call before begin().

◆ setMaxQueuedIFrames()

void setMaxQueuedIFrames ( int count )

inlineinherited

Number of not-yet-consumed keyframes sitting in the queue that triggers the same resync as the other two thresholds - catches a growing backlog earlier than either: once several groups-of-pictures worth of unconsumed keyframes have piled up, none of them are worth rendering in order anymore, so the freshest one is kept and the rest discarded. 3 by default (deliberately small); 0 disables this trigger. Forwards to the built-in PacedVideoOutput; call before begin().

◆ setQueueBytes()

void setQueueBytes ( size_t bytes )

inlineinherited

Byte capacity of the frame queue sitting between the demuxer/decoder and the paced render task - default 32KB. Too small behaves like a 1-frame queue, where any single slow frame blocks the writer immediately; a larger queue absorbs transient jitter at the cost of more RAM and more frames buffered ahead of what's actually on screen. It does not change what happens under a sustained rate mismatch - the queue still eventually fills, just later. Forwards to the built-in PacedVideoOutput; call before begin()/the first frame - not supported afterwards.

◆ setQueueUsePSRAM()

void setQueueUsePSRAM ( bool flag )

inlineinherited

Whether the frame queue above is allocated from PSRAM instead of the internal heap - silently falls back to internal heap on boards without PSRAM. On by default, since internal heap is a scarcer shared resource on most ESP32 boards and video decoding already needs PSRAM for other buffers (decoded picture buffers, scaling scratch space, ...). Turn it off for a queue small enough that internal heap is preferable, or on a board with no PSRAM where the fallback path is undesired. Forwards to the built-in PacedVideoOutput; call before begin()/the first frame - has no effect on an already-allocated queue.

◆ setResyncQueueFillFraction()

void setResyncQueueFillFraction ( float fraction )

inlineinherited

Byte-occupancy fraction (0..1) of the internal frame queue that triggers the same forward-jump resync as setResyncThresholdMs(), but from a different signal: dropped frames can keep the most recently rendered frame's own lateness low even while newer, not-yet-rendered bytes keep piling up faster than they're consumed. 0.8 (80% full) by default; 0 disables this trigger. Forwards to the built-in PacedVideoOutput; call before begin().

◆ setResyncThresholdMs()

void setResyncThresholdMs ( uint32_t ms )

inlineinherited

How far behind schedule (milliseconds) playback must fall before it gives up trying to catch up frame-by-frame and instead jumps its internal schedule forward to the current time - dropping frames alone can only slow a backlog's growth, never actually shrink it, since decoding can't outrun real time. Content in the skipped gap is never shown - this trades a visible jump for recovering instead of lagging further and further behind. 2000ms by default; 0 disables this resync behavior entirely. Forwards to the built-in PacedVideoOutput; call before begin().

◆ setSchedulingDelayMs()

void setSchedulingDelayMs ( uint32_t delayMs )

inlineinherited

Corrects for the real audio output's own buffering latency: the audio clock advances as soon as bytes are accepted by write(), not when they actually become audible - e.g. ~100ms ahead on a device with ~100ms of internal buffering, which would otherwise make every video frame appear that much too early. Delaying each frame's schedule by this amount cancels that out. There's no way to derive it automatically - set it to roughly match the audio output's own buffering latency. 0 (the default) applies no correction. Forwards to the built-in PacedVideoOutput; call before begin().

◆ setTaskParameters()

void setTaskParameters	(	uint32_t	stackSizeWords,
		uint8_t	priority,
		int	core = `-1`
	)

inlineinherited

Stack size (in words), priority, and (optionally) CPU core for the background task that renders queued video frames on schedule. core pins that task to a specific core - e.g. core 0, to keep it off whichever core runs copy()/loop() (audio decode/demuxing), giving audio and video decoding their own separate cores with no further setup. -1 (the default) leaves core assignment up to the RTOS. Forwards to the built-in PacedVideoOutput; call before begin() - has no effect on an already-running render task.

◆ setUseAudioClock()

void setUseAudioClock ( bool active )

inlineinherited

Whether video frames are scheduled against the real audio output's playback progress (an "audio clock", via AudioTimeSourceStream) instead of a free-running timer - keeps video in sync with audio even as the two decode at slightly different rates, since the audio clock only advances as audio is actually consumed. True (on) by default once an audio output is set via setAudioOutput() - calling setAudioOutput() again does not reset this. Turn it off if the content's audio track never actually delivers bytes (e.g. a silent/empty track), since the clock would then never advance and video would never play. Call before begin().

◆ setVideoOutput()

void setVideoOutput ( VideoOutput & out )

inlineinherited

Defines the final video display target (e.g. OutputTinyGPU, OutputOpenCV) - the caller must already have configured/begin()'d it (board/panel init, such as pin setup or a TFT library's own begin(), is outside this class's scope). Call before begin().

◆ useAudioClock()

bool useAudioClock ( ) const

inlineinherited

Current setUseAudioClock() setting.

◆ videoDecoder()

MultiVideoDecoder & videoDecoder ( )

inlineinherited

The built-in video multi-decoder, empty until addVideoDecoder() has registered at least one video codec decoder - also useful for diagnostics (e.g. selectedFormat()).

◆ videoSyncTask()

PacedVideoOutput & videoSyncTask ( )

inlineinherited

Escape hatch for tuning beyond this class's own surface - e.g. setTaskParameters()/setQueueBytes()/setMaxQueuedIFrames()/ setIgnorePFrames()/setSchedulingDelayMs(), or the frameCount()/ avgFrameMs()/outputFPS() family of diagnostics - returns the PacedVideoOutput instance that VideoPlayer's own tuning forwarders above delegate to.

Member Data Documentation

◆ aac_decoder

AACDecoderHelix aac_decoder

protected

◆ active

bool active = false

protectedinherited

◆ audio_clock

AudioTimeSourceStream audio_clock

protectedinherited

◆ audio_out

EncodedAudioStream audio_out

protectedinherited

◆ buffer_size

int buffer_size = 1024

protectedinherited

◆ default_audio_decoder

MultiDecoder default_audio_decoder

protectedinherited

◆ default_demuxer

MultiVideoDemuxer default_demuxer

protectedinherited

◆ default_video_decoder

MultiVideoDecoder default_video_decoder

protectedinherited

◆ h264_decoder

H264Decoder h264_decoder

protected

◆ mjpeg_decoder

MJPEGDecoder mjpeg_decoder

protected

◆ mp2_decoder

MP2Decoder mp2_decoder

protected

◆ mp3_decoder

MP3DecoderHelix mp3_decoder

protected

◆ mpeg_decoder

MPGDecoder mpeg_decoder

protected

◆ p_audio_output

Print* p_audio_output = nullptr

protectedinherited

◆ p_audio_output_typed

AudioOutput* p_audio_output_typed = nullptr

protectedinherited

◆ p_audio_stream

AudioStream* p_audio_stream = nullptr

protectedinherited

◆ p_source

Stream* p_source = nullptr

protectedinherited

◆ p_video_output

VideoOutput* p_video_output = nullptr

protectedinherited

◆ use_audio_clock

bool use_audio_clock = true

protectedinherited

◆ video_sync

PacedVideoOutput video_sync {default_video_decoder}

protectedinherited

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

src/AudioTools/Video/VideoPlayerFull.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ VideoPlayerFull() [1/5]

◆ VideoPlayerFull() [2/5]

◆ VideoPlayerFull() [3/5]

◆ VideoPlayerFull() [4/5]

◆ VideoPlayerFull() [5/5]

Member Function Documentation

◆ addAudioDecoder()

◆ addDemuxer()

◆ addVideoDecoder()

◆ audioDecoder()

◆ begin()

◆ copy()

◆ copyAll()

◆ demuxer()

◆ end()

◆ getStream()

◆ isActive()

◆ logTo()

◆ operator bool()

◆ registerAudioDecoders()

◆ registerVideoDecoders()

◆ setActive()

◆ setAudioOutput() [1/3]

◆ setAudioOutput() [2/3]

◆ setAudioOutput() [3/3]

◆ setBufferSize()

◆ setCatchUpThresholdFrames()

◆ setIgnorePFrames()

◆ setMaxQueuedIFrames()

◆ setQueueBytes()

◆ setQueueUsePSRAM()

◆ setResyncQueueFillFraction()

◆ setResyncThresholdMs()

◆ setSchedulingDelayMs()

◆ setTaskParameters()

◆ setUseAudioClock()

◆ setVideoOutput()

◆ useAudioClock()

◆ videoDecoder()

◆ videoSyncTask()

Member Data Documentation

◆ aac_decoder

◆ active

◆ audio_clock

◆ audio_out

◆ buffer_size

◆ default_audio_decoder

◆ default_demuxer

◆ default_video_decoder

◆ h264_decoder

◆ mjpeg_decoder

◆ mp2_decoder

◆ mp3_decoder

◆ mpeg_decoder

◆ p_audio_output

◆ p_audio_output_typed

◆ p_audio_stream

◆ p_source

◆ p_video_output

◆ use_audio_clock

◆ video_sync