Description

Video Manager and Video objects for FFmpeg-based playback and rendering [v26.06.1].

Overview

The Video module provides playback of movie files using the bundled FFmpeg libraries. It decodes video frames, uploads them to SDL textures and renders them through the same rendering path used by the graphics modules. Audio streams are decoded separately and routed through AudioTrack so they participate in the engine audio tag and volume system.

Key features

FFmpeg backend: Uses the bundled static FFmpeg build for demuxing and decoding
File playback: Loads videos from external files using the file protocol
CDC storage: Saves and loads video resources through raw streamable CDC blocks
Audio integration: Routes decoded audio through AudioTrack with Music, SFX, Voice or Custom tags
Playback control: Play, pause, resume, stop, seek and repeat playback support
SDL rendering: Automatically renders decoded frames with retained target, viewport, alpha, color modulation and blending settings

Supported formats

The active FFmpeg project is intentionally small and enables only the formats needed by the current backend:

Containers	MOV/MP4, AVI and raw H.264 streams
Video codecs	H.264
Audio codecs	AAC, MP3 and PCM S16LE
Protocols	File protocol only

CDC storage

Video CDC resources are stored as a small CRM64Pro video metadata header followed by the original media payload. The payload is written through Archive::blockAddStream() and read through Archive::blockOpenStream(), so large videos are saved and played without buffering the full media file in memory. Videos loaded from CDC can also be saved back to CDC archives; the metadata header is rebuilt from the current Video object and the original payload is streamed.

Playback methods

Video::play()	Starts playback and optionally configures extra repeats
Video::pause()	Pauses video and linked audio playback
Video::resume()	Resumes playback from a paused state
Video::stop()	Stops playback and resets the position to the beginning
Video::seek()	Seeks to a specific playback position in milliseconds
Video::decodeFrameAt()	Decodes one frame to an ARGB8888 SDL_Surface for import tools and offline processing

Rendering methods

Videos are rendered automatically during the engine render phase once playback starts:

Video::setTarget()	Selects the screen used for automatic rendering
Video::setViewport()	Sets the target viewport, or uses the automatic native-size viewport when omitted
Video::setSourceViewport()	Sets the source crop viewport, or uses the full video frame when omitted
Video::setRenderEx()	Sets rotation, center point and flip options used by automatic rendering

Manager type

This is a standard object manager. Each loaded video has its own decode state, playback position, SDL texture and optional linked AudioTrack stream.

Limitations

Network and pipe protocols are disabled
Hardware acceleration is disabled
swscale is not enabled; supported decoded YUV formats are uploaded directly to SDL textures
Only the formats listed above are enabled in the bundled FFmpeg project
CDC video blocks must be raw streamable blocks; compressed and encrypted CDC video blocks are not supported

Best practices

Use H.264 video with AAC audio in MP4/MOV containers for best compatibility
Use hasAudio() before exposing video-specific audio controls
Use setTag() to route video audio through the correct engine audio category
Access the manager exclusively through Main::videoMgr()

Note: The Video Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::videoMgr() method.
The Video Manager is automatically released when Main::terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.
Video objects are created through VideoMgr::loadFromFile() or VideoMgr::load(); VideoMgr::create() is intentionally unavailable because an empty Video has no playable source.

Classes
struct	CRM64Pro::VideoInfo
	Video metadata and statistics. More...
class	CRM64Pro::Video
	Video Object class. More...
class	CRM64Pro::VideoMgr
	Video Manager class. More...

Functions
bool	CRM64Pro::Video::info (Sint32 iMode=0) override
	Request Video object information.
const string &	CRM64Pro::Video::getName () const override
	Get the name.
Sint32	CRM64Pro::Video::getID () const override
	Get the ID.
Sint32	CRM64Pro::Video::play (Sint32 iRepeats=0)
	Play the video.
bool	CRM64Pro::Video::pause ()
	Pause the video playback.
bool	CRM64Pro::Video::resume ()
	Resume video from a paused state.
bool	CRM64Pro::Video::stop ()
	Stop video playback and reset to the beginning.
ePlaybackStatus	CRM64Pro::Video::status () const
	Get the video status.
Sint32	CRM64Pro::Video::getDuration () const
	Get total duration.
Sint32	CRM64Pro::Video::getPlaybackPosition () const
	Get current playback position.
bool	CRM64Pro::Video::seek (Sint32 iTimeMS)
	Seek to a playback position.
Uint64	CRM64Pro::Video::getFrameCount () const
	Get total frame count.
Uint64	CRM64Pro::Video::getFrameCurrent () const
	Get current frame index.
Sint32	CRM64Pro::Video::getWidth () const
	Get the native video width.
Sint32	CRM64Pro::Video::getHeight () const
	Get the native video height.
bool	CRM64Pro::Video::setBlendMode (SDL_BlendMode bmValue)
	Set the alpha blending mode.
SDL_BlendMode	CRM64Pro::Video::getBlendMode () const
	Get the alpha blending mode.
bool	CRM64Pro::Video::setAlphaMod (Sint32 iAlpha)
	Set the alpha modulation value.
Sint32	CRM64Pro::Video::getAlphaMod () const
	Get the alpha modulation value.
bool	CRM64Pro::Video::setColorMod (Uint8 iR, Uint8 iG, Uint8 iB)
	Set the color modulation value.
Sint32	CRM64Pro::Video::getColorMod (Uint8 &iR, Uint8 &iG, Uint8 &iB) const
	Get the color modulation value.
bool	CRM64Pro::Video::setTag (eAudioTrackTag eTag)
	Set video audio tag category.
eAudioTrackTag	CRM64Pro::Video::getTag () const
	Get video audio tag category.
bool	CRM64Pro::Video::hasAudio () const
	Check if the video media contains an audio stream.
bool	CRM64Pro::Video::hasAudioError () const
	Check if video audio playback was dropped after a runtime audio failure.
bool	CRM64Pro::Video::getInfo (VideoInfo *pVI) const
	Get video detailed information.
Sint32	CRM64Pro::Video::decodeFrameAt (Sint32 iTimeMS, SDL_Surface **ppSurface)
	Decode and copy one video frame at or near a timestamp.
Sint32	CRM64Pro::Video::save (const string &sCDCFile, const string &sResourceName="")
	Save the Video into a CDC file.
Sint32	CRM64Pro::Video::save (Sint32 idCDC, const string &sResourceName="")
	Save the Video into a CDC file.
Sint32	CRM64Pro::Video::saveToFile (const string &sFile) const
	Export the Video to an external file.
bool	CRM64Pro::Video::setTarget (Sint32 idRes=0)
	Set the video render target.
bool	CRM64Pro::Video::setViewport (const SDL_FRect *pRect=nullptr)
	Set the target viewport used for automatic video rendering.
bool	CRM64Pro::Video::setSourceViewport (const SDL_FRect *pRect=nullptr)
	Set the source viewport used for automatic video rendering.
bool	CRM64Pro::Video::setRenderEx (double dAngle=0.0, const SDL_FPoint *pCenter=nullptr, SDL_FlipMode rf=SDL_FLIP_NONE)
	Set extended render attributes used for automatic video rendering.
bool	CRM64Pro::VideoMgr::info (Sint32 iMode=0) override
	Request Video Manager information.
Sint32	CRM64Pro::VideoMgr::close (Sint32 idVideo=0) override
	Close and destroy a video object.
Sint32	CRM64Pro::VideoMgr::getCount () const override
	Get number of loaded objects.
Sint32	CRM64Pro::VideoMgr::setName (Sint32 idVideo, const string &sName) override
	Change the object name.
Video *	CRM64Pro::VideoMgr::get (Sint32 idVideo)
	Get a pointer to the video using its handle.
Sint32	CRM64Pro::VideoMgr::loadFromFile (const string &sFile, const string &sName="", eAudioTrackTag eTag=ATT_MUSIC)
	Load a video from an external file.
Sint32	CRM64Pro::VideoMgr::load (const string &sCDCFile, const string &sName)
	Load a video stored in a CDC file.
Sint32	CRM64Pro::VideoMgr::load (Sint32 idCDC, const string &sName)
	Load a video stored in a CDC file.
Sint32	CRM64Pro::VideoMgr::remove (Sint32 idCDC, const string &sName)
	Remove a video stored in a CDC file.
bool	CRM64Pro::VideoMgr::exists (Sint32 idCDC, const string &sName) const
	Check if a video is stored in a CDC file.

Function Documentation

◆ info() [1/2]

bool CRM64Pro::Video::info ( Sint32 iMode = 0 )

override

Request Video object information.

Writes information to the default log.

Parameters

iMode 0 for standard output and 1 for extended output.

Returns: true on success, or false on failure.

◆ getName()

const string & CRM64Pro::Video::getName ( ) const

override

Get the name.

Returns: The object name.

◆ getID()

Sint32 CRM64Pro::Video::getID ( ) const

override

Get the ID.

Returns: Object ID.

◆ play()

Sint32 CRM64Pro::Video::play ( Sint32 iRepeats = 0 )

Play the video.

Parameters

iRepeats Number of extra repeats after the first play. 0 plays once, -1 repeats forever.

Returns: 0 on success, or a negative error code on failure.

◆ pause()

bool CRM64Pro::Video::pause ( )

Pause the video playback.

Returns: true on success or if already paused, or false on failure.

◆ resume()

bool CRM64Pro::Video::resume ( )

Resume video from a paused state.

Returns: true on success or if already playing, or false on failure.

◆ stop()

bool CRM64Pro::Video::stop ( )

Stop video playback and reset to the beginning.

Returns: true once playback is stopped. Resetting the preview frame to the beginning is best-effort.

◆ status()

ePlaybackStatus CRM64Pro::Video::status ( ) const

Get the video status.

Returns: ::PS_PLAYING, ::PS_PAUSED, ::PS_FINISHED, or ::PS_STOPPED.

◆ getDuration()

Sint32 CRM64Pro::Video::getDuration ( ) const

Get total duration.

Returns: Total duration in milliseconds.

◆ getPlaybackPosition()

Sint32 CRM64Pro::Video::getPlaybackPosition ( ) const

Get current playback position.

Returns: The position in milliseconds, or -1 if invalid.

◆ seek()

bool CRM64Pro::Video::seek ( Sint32 iTimeMS )

Seek to a playback position.

Parameters

iTimeMS The position in milliseconds to seek to.

Returns: true on success, or false on failure.

◆ getFrameCount()

Uint64 CRM64Pro::Video::getFrameCount ( ) const

Get total frame count.

Returns: Total number of frames.

◆ getFrameCurrent()

Uint64 CRM64Pro::Video::getFrameCurrent ( ) const

Get current frame index.

Returns: Current frame index [0 to frame count - 1].

◆ getWidth()

Sint32 CRM64Pro::Video::getWidth ( ) const

Get the native video width.

Returns: The width in pixels.

◆ getHeight()

Sint32 CRM64Pro::Video::getHeight ( ) const

Get the native video height.

Returns: The height in pixels.

◆ setBlendMode()

bool CRM64Pro::Video::setBlendMode ( SDL_BlendMode bmValue )

Set the alpha blending mode.

Parameters

bmValue the SDL_BlendMode to use for rendering.

Returns: true on success, or false on failure.

◆ getBlendMode()

SDL_BlendMode CRM64Pro::Video::getBlendMode ( ) const

Get the alpha blending mode.

Returns: The SDL_BlendMode used for rendering.

◆ setAlphaMod()

bool CRM64Pro::Video::setAlphaMod ( Sint32 iAlpha )

Set the alpha modulation value.

Parameters

iAlpha Ranges from 255 (opaque) to 0 (fully transparent).

Returns: true on success, or false on failure.

◆ getAlphaMod()

Sint32 CRM64Pro::Video::getAlphaMod ( ) const

Get the alpha modulation value.

Returns: The alpha modulation value [0,255].

◆ setColorMod()

bool CRM64Pro::Video::setColorMod	(	Uint8	iR,
		Uint8	iG,
		Uint8	iB )

Set the color modulation value.

Parameters

iR	Red (0-255).
iG	Green (0-255).
iB	Blue (0-255).

Returns: true on success, or false on failure.

◆ getColorMod()

Sint32 CRM64Pro::Video::getColorMod	(	Uint8 &	iR,
		Uint8 &	iG,
		Uint8 &	iB ) const

Get the color modulation value.

Parameters

iR	reference to receive red [0,255].
iG	reference to receive green [0,255].
iB	reference to receive blue [0,255].

Returns: 0 on success, or a negative error code on failure.

◆ setTag()

bool CRM64Pro::Video::setTag ( eAudioTrackTag eTag )

Set video audio tag category.

Links the video's audio to the ConfigMgr's volume system.

Parameters

eTag	The tag category (e.g., ATT_MUSIC or ATT_VOICE).

Returns: true on success, or false on failure.

◆ getTag()

eAudioTrackTag CRM64Pro::Video::getTag ( ) const

Get video audio tag category.

Returns: The current eAudioTrackTag.

◆ hasAudio()

bool CRM64Pro::Video::hasAudio ( ) const

Check if the video media contains an audio stream.

Returns: true if the media file contains an audio stream, otherwise false.

Note: Audio may still be unavailable at runtime if playback setup or decoding fails. Use hasAudioError() to check whether audio was dropped during playback.

◆ hasAudioError()

bool CRM64Pro::Video::hasAudioError ( ) const

Check if video audio playback was dropped after a runtime audio failure.

Returns: true if an audio stream was detected but disabled during playback after setup or decoding failed, otherwise false.

◆ getInfo()

bool CRM64Pro::Video::getInfo ( VideoInfo * pVI ) const

Get video detailed information.

Parameters

pVI	Pointer to a VideoInfo struct to be filled.

Returns: true on success, or false on failure.

◆ decodeFrameAt()

Sint32 CRM64Pro::Video::decodeFrameAt	(	Sint32	iTimeMS,
		SDL_Surface **	ppSurface )

Decode and copy one video frame at or near a timestamp.

Parameters

iTimeMS	Target position in milliseconds.
ppSurface	Output SDL surface in SDL_PIXELFORMAT_ARGB8888 format.

Returns: 0 on success, or a negative error code on failure.

Note: The caller owns the returned surface and must release it with SDL_DestroySurface().; This method advances the video decoder state. Sequential increasing calls decode forward efficiently; backward calls seek.; This method cannot be used while the video is playing. Pause or stop playback first, or use a separate Video instance for offline extraction.

◆ save() [1/2]

Sint32 CRM64Pro::Video::save	(	const string &	sCDCFile,
		const string &	sResourceName = "" )

Save the Video into a CDC file.

Parameters

sCDCFile	Path to the CDC archive.
sResourceName	Optional resource name to use in the CDC. If empty (default), uses the Video object's internal name.

Returns: 0 on success, or a negative error code on failure.

◆ save() [2/2]

Sint32 CRM64Pro::Video::save	(	Sint32	idCDC,
		const string &	sResourceName = "" )

Save the Video into a CDC file.

Parameters

idCDC	CDC id.
sResourceName	Optional resource name to use in the CDC. If empty (default), uses the Video object's internal name.

Returns: 0 on success, or a negative error code on failure.

◆ saveToFile()

Sint32 CRM64Pro::Video::saveToFile ( const string & sFile ) const

Export the Video to an external file.

Parameters

sFile Output file path.

Returns: 0 on success, or a negative error code on failure.

Note: If the output path has no matching video extension, one is appended based on the detected container.

◆ setTarget()

bool CRM64Pro::Video::setTarget ( Sint32 idRes = 0 )

Set the video render target.

Parameters

idRes A valid screen handle. Default uses the default screen.

Returns: true on success, or false on failure.

◆ setViewport()

bool CRM64Pro::Video::setViewport ( const SDL_FRect * pRect = nullptr )

Set the target viewport used for automatic video rendering.

Parameters

pRect Destination viewport on the render target, or nullptr to use the automatic viewport.

Returns: true on success, or false on failure.

Note: The automatic viewport starts at (0,0), uses the native video size and shrinks to fit the target while preserving aspect ratio.

◆ setSourceViewport()

bool CRM64Pro::Video::setSourceViewport ( const SDL_FRect * pRect = nullptr )

Set the source viewport used for automatic video rendering.

Parameters

pRect Source viewport in video pixels, or nullptr to use the full video frame.

Returns: true on success, or false on failure.

◆ setRenderEx()

bool CRM64Pro::Video::setRenderEx	(	double	dAngle = 0.0,
		const SDL_FPoint *	pCenter = nullptr,
		SDL_FlipMode	rf = SDL_FLIP_NONE )

Set extended render attributes used for automatic video rendering.

Parameters

dAngle	Angle in degrees for rotation.
pCenter	SDL_FPoint pointer indicating rotation center. Default nullptr rotates around the target viewport center.
rf	SDL_FlipMode value for flipping actions.

Returns: true on success, or false on failure.

◆ info() [2/2]

bool CRM64Pro::VideoMgr::info ( Sint32 iMode = 0 )

override

Request Video Manager information.

Writes manager information to the default log.

Parameters

iMode -1 to display only manager information. 0 (default) to display manager and all objects. A specific object ID displays manager information and only that object.

Returns: true on success, or false on failure.

◆ close()

Sint32 CRM64Pro::VideoMgr::close ( Sint32 idVideo = 0 )

override

Close and destroy a video object.

Parameters

idVideo 0 for closing all videos or the specific Video id.

Returns: 0 on success, or a negative error code on failure.

◆ getCount()

Sint32 CRM64Pro::VideoMgr::getCount ( ) const

override

Get number of loaded objects.

Returns: The number of videos.

◆ setName()

Sint32 CRM64Pro::VideoMgr::setName	(	Sint32	idVideo,
		const string &	sName )

override

Change the object name.

Parameters

idVideo	Video id.
sName	The video name. Must be unique.

Returns: 0 on success, or a negative error code on failure.

◆ get()

Video * CRM64Pro::VideoMgr::get ( Sint32 idVideo )

Get a pointer to the video using its handle.

Parameters

idVideo Video id.

Returns: Borrowed pointer to the Video object, or nullptr if not found.

Note: The returned pointer must not be deleted. It remains valid until the Video is closed or VideoMgr is reset or terminated.

◆ loadFromFile()

Sint32 CRM64Pro::VideoMgr::loadFromFile	(	const string &	sFile,
		const string &	sName = "",
		eAudioTrackTag	eTag = ATT_MUSIC )

Load a video from an external file.

Parameters

sFile	string containing [directory]+filename+[extension].
sName	Object name. If empty, filename without extension is used. Must be unique and shorter than 64 characters.
eTag	Audio category tag (default ATT_MUSIC).

Returns: Greater than 0 on success (the Video id), or a negative error code on failure.

◆ load() [1/2]

Sint32 CRM64Pro::VideoMgr::load	(	const string &	sCDCFile,
		const string &	sName )

Load a video stored in a CDC file.

Parameters

sCDCFile	string containing [directory]+filename+[extension] of the CDC archive.
sName	string with the video name.

Note: The audio category tag is restored from the CDC metadata. Use Video::setTag() after loading to change it.; The returned video owns the CDC archive handle opened by this call and keeps it alive until the video is closed.

Returns: Greater than 0 on success (the Video id), or a negative error code on failure.

◆ load() [2/2]

Sint32 CRM64Pro::VideoMgr::load	(	Sint32	idCDC,
		const string &	sName )

Load a video stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the video name.

Note: The audio category tag is restored from the CDC metadata. Use Video::setTag() after loading to change it.; The returned video streams from the caller-owned CDC archive. ArchiveMgr::close(idCDC) releases only the caller's archive owner reference and the video keeps its active block streams alive, but ArchiveMgr::close(0) closes CDC-backed videos and invalidates their ids and pointers.

Returns: Greater than 0 on success (the Video id), or a negative error code on failure.

◆ remove()

Sint32 CRM64Pro::VideoMgr::remove	(	Sint32	idCDC,
		const string &	sName )

Remove a video stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the video name.

Returns: 0 on success, or a negative error code on failure.

◆ exists()

bool CRM64Pro::VideoMgr::exists	(	Sint32	idCDC,
		const string &	sName ) const

Check if a video is stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the video name.

Returns: true if the resource is stored in the CDC file, or false otherwise. No error is reported.

Description

Overview

Key features

Supported formats

CDC storage

Playback methods

Rendering methods

Manager type

Limitations

Best practices

Classes

Functions

Function Documentation

◆ info() [1/2]

◆ getName()

◆ getID()

◆ play()

◆ pause()

◆ resume()

◆ stop()

◆ status()

◆ getDuration()

◆ getPlaybackPosition()

◆ seek()

◆ getFrameCount()

◆ getFrameCurrent()

◆ getWidth()

◆ getHeight()

◆ setBlendMode()

◆ getBlendMode()

◆ setAlphaMod()

◆ getAlphaMod()

◆ setColorMod()

◆ getColorMod()

◆ setTag()

◆ getTag()

◆ hasAudio()

◆ hasAudioError()

◆ getInfo()

◆ decodeFrameAt()

◆ save() [1/2]

◆ save() [2/2]

◆ saveToFile()

◆ setTarget()

◆ setViewport()

◆ setSourceViewport()

◆ setRenderEx()

◆ info() [2/2]

◆ close()

◆ getCount()

◆ setName()

◆ get()

◆ loadFromFile()

◆ load() [1/2]

◆ load() [2/2]

◆ remove()

◆ exists()