StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Multimedia::SimplePlayer Class Reference

Real-time asynchronous file preview, not a professional media player. More...

#include <StormByte/multimedia/simple_player.hxx>

Public Member Functions

 SimplePlayer (Safe::Shared< Display > display, Safe::Shared< Logger::Log > logger={})
 Construct a preview engine with an application sink.
 SimplePlayer (Safe::Shared< Display > display, Safe::Shared< Logger::Log > logger, PreviewBuffering buffering)
 Construct with an immutable, per-instance buffering policy.
 SimplePlayer (const SimplePlayer &)=delete
 SimplePlayer (SimplePlayer &&)=delete
 ~SimplePlayer () noexcept
 Stop/join workers, close input, release owners without rewinding.
SimplePlayer & operator= (const SimplePlayer &)=delete
SimplePlayer & operator= (SimplePlayer &&)=delete
bool Open (std::string_view file)
 Open a locally owned BufferedFileReader; replace any old input.
bool Open (Safe::Unique< Buffer::IO::BufferedLocationReader > reader)
 Exclusively take an input; open only if not already open.
void Acceleration (DecodeAcceleration acceleration) noexcept
 Selects hardware-assisted video decoding or forces software decoding.
bool OutputColor (PreviewColorMode mode)
 Selects SDR tone-mapped or explicit HDR preview output.
bool Play ()
 Start/resume asynchronous real-time presentation.
bool Pause ()
 Freeze workers and presentation, retaining queued decode.
bool Stop ()
 Join workers and rewind the actual reader, keeping it open.
bool Seek (double seconds)
 Seek and flush decoders, devices, cues and stale GUI deliveries.
bool SelectTrack (enum Type type, int index)
 Switch or disable a media kind at the current position.
int SelectedTrack (enum Type type) const
 Read selected stream index.
Safe::Vector< PreviewTrack > Tracks () const
 Snapshot selectable stream information.
PlaybackState State () const
 Snapshot lifecycle state.
double Position () const
 Snapshot audible/video timeline position.
double Duration () const
 Read container duration, if known.
Safe::String Error () const
 Snapshot the last explicit failure.
PreviewDiagnostics Diagnostics () const
 Snapshot actual decoder output and cumulative preview measurements.
bool Close ()
 Join workers and close/release input, without rewind.
Safe::Unique< Buffer::IO::BufferedLocationReader > ReleaseReader ()
 Join workers, rewind and transfer the still-open dynamic reader.

Detailed Description

Real-time asynchronous file preview, not a professional media player.

Control operations are serialized internally. Display callbacks must not reenter player methods. Bool failures and worker failures set Error(); inspect State() while playing. Owns exactly one buffered reader, retaining its dynamic type. Display is mandatory; no native presentation backend is bundled. All provider libraries must outlive Safe owners.

Constructor & Destructor Documentation

◆ SimplePlayer() [1/4]

StormByte::Multimedia::SimplePlayer::SimplePlayer ( Safe::Shared< Display > display,
Safe::Shared< Logger::Log > logger = {} )
explicit

Construct a preview engine with an application sink.

Parameters
displayNonempty combined presentation sink.
loggerOptional shared logger.
Exceptions
StormByte::ExceptionIf display is empty.

◆ SimplePlayer() [2/4]

StormByte::Multimedia::SimplePlayer::SimplePlayer ( Safe::Shared< Display > display,
Safe::Shared< Logger::Log > logger,
PreviewBuffering buffering )

Construct with an immutable, per-instance buffering policy.

Parameters
displayNonempty combined presentation sink.
loggerOptional shared logger.
bufferingPositive caps and read horizon; nonnegative preload/audio advance no greater than ReadAhead. Zero preload disables initial buffering.
Exceptions
StormByte::ExceptionIf the sink or policy is invalid.

◆ SimplePlayer() [3/4]

StormByte::Multimedia::SimplePlayer::SimplePlayer ( const SimplePlayer & )
delete

◆ SimplePlayer() [4/4]

StormByte::Multimedia::SimplePlayer::SimplePlayer ( SimplePlayer && )
delete

◆ ~SimplePlayer()

StormByte::Multimedia::SimplePlayer::~SimplePlayer ( )
noexcept

Stop/join workers, close input, release owners without rewinding.

Member Function Documentation

◆ Acceleration()

void StormByte::Multimedia::SimplePlayer::Acceleration ( DecodeAcceleration acceleration)
noexcept

Selects hardware-assisted video decoding or forces software decoding.

Parameters
accelerationAuto tries the platform's FFmpeg hardware devices and falls back to software if initialization or codec opening fails. Changes apply to the next Open().

◆ Close()

bool StormByte::Multimedia::SimplePlayer::Close ( )

Join workers and close/release input, without rewind.

Returns
Whether presentation invalidation and reader close succeeded.

◆ Diagnostics()

PreviewDiagnostics StormByte::Multimedia::SimplePlayer::Diagnostics ( ) const

Snapshot actual decoder output and cumulative preview measurements.

◆ Duration()

double StormByte::Multimedia::SimplePlayer::Duration ( ) const

Read container duration, if known.

Returns
Seconds, or zero when unavailable.

◆ Error()

Safe::String StormByte::Multimedia::SimplePlayer::Error ( ) const

Snapshot the last explicit failure.

Returns
Safe-owned diagnostic, empty when none.

◆ Open() [1/2]

bool StormByte::Multimedia::SimplePlayer::Open ( Safe::Unique< Buffer::IO::BufferedLocationReader > reader)

Exclusively take an input; open only if not already open.

Parameters
readerDynamic reader owner. Retained even if opening fails.
Returns
Whether input and decoders are usable.

◆ Open() [2/2]

bool StormByte::Multimedia::SimplePlayer::Open ( std::string_view file)

Open a locally owned BufferedFileReader; replace any old input.

Parameters
fileBorrowed path, copied only into the reader's Safe::String.
Returns
Whether probing and initial decoder selection succeeded.

◆ operator=() [1/2]

SimplePlayer & StormByte::Multimedia::SimplePlayer::operator= ( const SimplePlayer & )
delete

◆ operator=() [2/2]

SimplePlayer & StormByte::Multimedia::SimplePlayer::operator= ( SimplePlayer && )
delete

◆ OutputColor()

bool StormByte::Multimedia::SimplePlayer::OutputColor ( PreviewColorMode mode)

Selects SDR tone-mapped or explicit HDR preview output.

Parameters
modeSDR preserves the RGBA8 Display path; HDR sends PQ/HLG frames to an optional HDRDisplay implementation.
Returns
False without changing the setting if HDR is requested without an HDRDisplay sink.

◆ Pause()

bool StormByte::Multimedia::SimplePlayer::Pause ( )

Freeze workers and presentation, retaining queued decode.

Returns
Whether pause succeeded.

◆ Play()

bool StormByte::Multimedia::SimplePlayer::Play ( )

Start/resume asynchronous real-time presentation.

Returns
Whether playback started; Ended requires Seek or Stop first.

◆ Position()

double StormByte::Multimedia::SimplePlayer::Position ( ) const

Snapshot audible/video timeline position.

Returns
Media seconds.

◆ ReleaseReader()

Safe::Unique< Buffer::IO::BufferedLocationReader > StormByte::Multimedia::SimplePlayer::ReleaseReader ( )

Join workers, rewind and transfer the still-open dynamic reader.

Returns
Owner, or empty on failure with ownership retained by the player.

Never closes or reopens a faulted reader as a fallback. Stop/transfer reject faulted sessions before Rewind to preserve remote mount tokens.

◆ Seek()

bool StormByte::Multimedia::SimplePlayer::Seek ( double seconds)

Seek and flush decoders, devices, cues and stale GUI deliveries.

Parameters
secondsNonnegative media seconds. Paused seek displays a new image.
Returns
Whether seek started successfully; asynchronous errors remain observable.

◆ SelectedTrack()

int StormByte::Multimedia::SimplePlayer::SelectedTrack ( enum Type type) const

Read selected stream index.

Parameters
typeMedia kind.
Returns
Stream index, or -1 when disabled.

◆ SelectTrack()

bool StormByte::Multimedia::SimplePlayer::SelectTrack ( enum Type type,
int index )

Switch or disable a media kind at the current position.

Parameters
typeVideo, audio or subtitle.
indexStream index, or -1 to disable.
Returns
Whether selection succeeded; asynchronous errors remain observable.

Selecting the active index is a no-op. During playback, an audio-only invalidation-capable Display preserves video decoding and presentation; other changes and end-of-input reconstruct at the current position.

◆ State()

PlaybackState StormByte::Multimedia::SimplePlayer::State ( ) const

Snapshot lifecycle state.

Returns
Current state.

◆ Stop()

bool StormByte::Multimedia::SimplePlayer::Stop ( )

Join workers and rewind the actual reader, keeping it open.

Returns
Whether rewind succeeded; failure retains ownership.

◆ Tracks()

Safe::Vector< PreviewTrack > StormByte::Multimedia::SimplePlayer::Tracks ( ) const

Snapshot selectable stream information.

Returns
Safe-owned track list.

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