StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
simple_player.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Multimedia.
5 *
6 * StormByte-Multimedia original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Multimedia source in this
20 * file. Third-party components — including FFmpeg and embedded trained data —
21 * remain under their own licenses and are not covered by the commercial grant.
22 *
23 * A written StormByte commercial agreement may license this original source
24 * on terms other than the LGPL, including specific use, distribution or
25 * linking arrangements such as static linking, as stated in that agreement.
26 * It does not grant rights to dependencies or waive their license conditions.
27 * Enabling WITH_GPL or WITH_NONFREE may include components with separate
28 * obligations for modification, linking (static or dynamic), redistribution
29 * or works that incorporate them. The person modifying, linking, packaging or
30 * distributing the resulting work is responsible for determining and meeting
31 * all applicable requirements, including any needed patent permissions.
32 * A StormByte commercial agreement does not provide those rights for GPL or
33 * nonfree components.
34 *
35 * Neither license grants any patent rights. Any patent licenses required
36 * to use this software or third-party components must be obtained separately
37 * from the patent holders.
38 *
39 * StormByte-Multimedia is distributed in the hope that it will be useful,
40 * but WITHOUT ANY WARRANTY; without even the implied warranty of
41 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
42 * GNU Lesser General Public License for more details.
43 *
44 * You should have received a copy of the GNU Lesser General Public License
45 * version 3 along with StormByte-Multimedia. If not, see
46 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
47 *
48 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
49 */
50
51#pragma once
52
53#include <StormByte/buffer/io/buffered_location_reader.hxx>
54#include <StormByte/logger/log.hxx>
58
59#include <chrono>
60#include <cstddef>
61#include <string_view>
62
67namespace StormByte {
72 namespace Multimedia {
77 namespace Backend {
81 class SimplePlayer;
82 }
83 }
84}
85
90namespace StormByte {
95 namespace Multimedia {
105 std::chrono::milliseconds Preload{750};
106 std::chrono::milliseconds ReadAhead{2000};
107 std::chrono::milliseconds AudioAhead{500};
108 std::size_t MaxBytes = 128 * 1024 * 1024;
109 std::size_t MaxEvents = 256;
110 };
111
114
141
154
163 PreviewTrack() = default;
164
169 PreviewTrack(const PreviewTrack& other) = default;
170
175 PreviewTrack(PreviewTrack&& other) noexcept = default;
176
180 ~PreviewTrack() noexcept = default;
181
187 PreviewTrack& operator=(const PreviewTrack& other) = default;
188
194 PreviewTrack& operator=(PreviewTrack&& other) noexcept = default;
195
196 int m_index = -1;
197 enum Type m_type = Type::Unknown;
198 Safe::String m_language;
199 Safe::String m_title;
200 Safe::String m_codec;
201 };
202 }
203}
204
209
214namespace StormByte {
219 namespace Multimedia {
231 public:
239
249 PreviewBuffering buffering);
250
251 SimplePlayer(const SimplePlayer&) = delete;
252
254
258 ~SimplePlayer() noexcept;
259
260 SimplePlayer& operator=(const SimplePlayer&) = delete;
261
262 SimplePlayer& operator=(SimplePlayer&&) = delete;
263
269 bool Open(std::string_view file);
270
276 bool Open(Safe::Unique<Buffer::IO::BufferedLocationReader> reader);
277
284 void Acceleration(DecodeAcceleration acceleration) noexcept;
285
294
299 bool Play();
300
305 bool Pause();
306
311 bool Stop();
312
318 bool Seek(double seconds);
319
330 bool SelectTrack(enum Type type, int index);
331
337 int SelectedTrack(enum Type type) const;
338
343 Safe::Vector<PreviewTrack> Tracks() const;
344
350
355 double Position() const;
356
361 double Duration() const;
362
367 Safe::String Error() const;
368
371
376 bool Close();
377
386
387 private:
388 Safe::Unique<Backend::SimplePlayer> m_backend;
389 };
390 }
391}
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
PlaybackState State() const
Snapshot lifecycle state.
bool Play()
Start/resume asynchronous real-time presentation.
bool Open(std::string_view file)
Open a locally owned BufferedFileReader; replace any old input.
SimplePlayer(const SimplePlayer &)=delete
double Position() const
Snapshot audible/video timeline position.
Safe::Vector< PreviewTrack > Tracks() const
Snapshot selectable stream information.
Safe::String Error() const
Snapshot the last explicit failure.
bool SelectTrack(enum Type type, int index)
Switch or disable a media kind at the current position.
bool Pause()
Freeze workers and presentation, retaining queued decode.
bool Stop()
Join workers and rewind the actual reader, keeping it open.
SimplePlayer(SimplePlayer &&)=delete
int SelectedTrack(enum Type type) const
Read selected stream index.
PreviewDiagnostics Diagnostics() const
Snapshot actual decoder output and cumulative preview measurements.
SimplePlayer(Safe::Shared< Display > display, Safe::Shared< Logger::Log > logger, PreviewBuffering buffering)
Construct with an immutable, per-instance buffering policy.
SimplePlayer(Safe::Shared< Display > display, Safe::Shared< Logger::Log > logger={})
Construct a preview engine with an application sink.
double Duration() const
Read container duration, if known.
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.
Safe::Unique< Buffer::IO::BufferedLocationReader > ReleaseReader()
Join workers, rewind and transfer the still-open dynamic reader.
bool Close()
Join workers and close/release input, without rewind.
bool Seek(double seconds)
Seek and flush decoders, devices, cues and stale GUI deliveries.
~SimplePlayer() noexcept
Stop/join workers, close input, release owners without rewinding.
Multimedia module of the StormByte suite.
Typed item queues provided by StormByte-Buffer.
Multimedia module of the StormByte suite.
DecodeAcceleration
Selects whether video decoders may use an available FFmpeg hardware backend.
Definition decode_policy.hxx:43
@ Software
Do not initialize a hardware device.
Definition decode_policy.hxx:45
PlaybackState
Observable preview lifecycle.
Definition simple_player.hxx:146
@ Ended
Decode and presentation drained.
Definition simple_player.hxx:151
@ Closed
No input.
Definition simple_player.hxx:147
@ Stopped
Open input, rewound.
Definition simple_player.hxx:148
@ Playing
Asynchronous playback.
Definition simple_player.hxx:149
@ Paused
Frozen presentation, including paused seek previews.
Definition simple_player.hxx:150
PreviewDecodeBackend
Actual output of the video decoder, not the requested policy.
Definition simple_player.hxx:113
@ Hardware
Definition simple_player.hxx:113
@ Unknown
Definition simple_player.hxx:113
PreviewColorMode
Selects SDR presentation or HDR signal preservation for preview.
Definition display.hxx:78
@ Unknown
Subtitle without a reliable representation classification.
Definition codec.hxx:83
Root namespace of the StormByte C++ suite.
STL namespace.
Per-player buffering policy, fixed for the engine's lifetime.
Definition simple_player.hxx:104
std::chrono::milliseconds ReadAhead
Decoded timeline horizon, except interleave skew.
Definition simple_player.hxx:106
std::size_t MaxBytes
Pending decoded payload bytes, allocated on demand.
Definition simple_player.hxx:108
std::chrono::milliseconds AudioAhead
Maximum advance of PCM delivery to Display.
Definition simple_player.hxx:107
std::size_t MaxEvents
Maximum pending decoded units.
Definition simple_player.hxx:109
std::chrono::milliseconds Preload
Initial and reconstructed-seek coverage goal.
Definition simple_player.hxx:105
Thread-safe diagnostics, cumulative since Open (including seeks).
Definition simple_player.hxx:124
PreviewDecodeBackend m_backend
Unknown until a frame is decoded.
Definition simple_player.hxx:127
std::uint64_t m_shown_video
Successful video sink callbacks, not compositor presentations.
Definition simple_player.hxx:129
double m_tone_mapping_seconds
Definition simple_player.hxx:136
std::uint64_t m_audio_clock_samples
Valid active-clock observations.
Definition simple_player.hxx:131
double m_download_seconds
Definition simple_player.hxx:134
double m_color_conversion_seconds
HDR output transfer/color conversion.
Definition simple_player.hxx:137
double m_linearization_seconds
HDR input matrix/primaries conversion plus linearization.
Definition simple_player.hxx:135
std::size_t m_peak_queue_bytes
Decoded presentation payload only, not process RSS.
Definition simple_player.hxx:133
Safe::String m_device
Actual hardware-frame device type, otherwise empty.
Definition simple_player.hxx:126
double m_rgba_packing_seconds
Allocation and packing; fused color conversion for SDR.
Definition simple_player.hxx:138
std::uint64_t m_skipped_video
Processing-pressure drops, not seek trimming.
Definition simple_player.hxx:128
std::uint64_t m_audio_underruns
Definition simple_player.hxx:130
double m_conversion_fps
Pictures / sum of measured conversion-stage seconds; excludes queue waits.
Definition simple_player.hxx:139
Safe::String m_decoder
Opened video codec name; empty without video.
Definition simple_player.hxx:125
std::uint64_t m_converted_video
Successfully converted pictures.
Definition simple_player.hxx:132
Selectable input stream, excluding attached pictures and attachments.
Definition simple_player.hxx:159
PreviewTrack(PreviewTrack &&other) noexcept=default
Move track information.
PreviewTrack()=default
Construct an invalid track.
int m_index
Demux stream index.
Definition simple_player.hxx:196
Safe::String m_language
Container language tag.
Definition simple_player.hxx:198
Safe::String m_title
Container title tag.
Definition simple_player.hxx:199
PreviewTrack(const PreviewTrack &other)=default
Copy track information.
~PreviewTrack() noexcept=default
Release track text.
Safe::String m_codec
Decoder codec name.
Definition simple_player.hxx:200
enum Type m_type
Video, audio or subtitle.
Definition simple_player.hxx:197
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61