StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
ffmpeg.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 * Neither license grants any patent rights. Any patent licenses required
24 * to use this software or third-party components must be obtained separately
25 * from the patent holders.
26 *
27 * StormByte-Multimedia is distributed in the hope that it will be useful,
28 * but WITHOUT ANY WARRANTY; without even the implied warranty of
29 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30 * GNU Lesser General Public License for more details.
31 *
32 * You should have received a copy of the GNU Lesser General Public License
33 * version 3 along with StormByte-Multimedia. If not, see
34 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
35 *
36 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
37 */
38
39#pragma once
40
41#include <StormByte/size.hxx>
42#include <StormByte/logger/log.hxx>
54#include <StormByte/safe/atomic.hxx>
55#include <StormByte/safe/optional.hxx>
56#include <StormByte/safe/pointers.hxx>
57#include <StormByte/safe/string.hxx>
58
59#include <cstddef>
60#include <cstdint>
61#include <string_view>
62
64 class Host;
65 class Pipe;
66 class Pumper;
67 class Worker;
68 class TopologyAccess;
69}
70
72 class Filter;
73}
74
76 class Filters;
77 class Route;
78}
79
85 class ProcessTwoPasses;
86
264 friend class StormByte::Multimedia::Backend::Pipeline::Detail::Worker::Filter;
265 friend class ProcessTwoPasses;
266 friend class StormByte::Multimedia::Backend::Pipeline::TopologyAccess;
267
268 public:
273
277 FFmpeg(const FFmpeg& other) = delete;
278
282 FFmpeg(FFmpeg&& other) noexcept = delete;
283
288 virtual ~FFmpeg() noexcept;
289
293 FFmpeg& operator=(const FFmpeg& other) = delete;
294
298 FFmpeg& operator=(FFmpeg&& other) noexcept = delete;
299
303
308
313 virtual enum StormByte::Multimedia::Type Media() const noexcept = 0;
314
319 StormByte::Safe::String Name() const;
320
326
332 StormByte::Buffer::QueueSnapshot QueueSnapshot(int track) const noexcept;
333
338 inline const StormByte::Safe::String& Leaf() const noexcept {
339 return m_name;
340 }
341
346 inline const Pipeline::Kinds& Receives() const noexcept {
347 return m_receives;
348 }
349
354 inline const Pipeline::Kinds& Produces() const noexcept {
355 return m_produces;
356 }
357
361
366
373 virtual void Clean() noexcept = 0;
374
381 virtual void Setup() noexcept = 0;
382
397 virtual void Process(const Pipeline::Frame& frame) noexcept;
398
406 virtual void Process(const Pipeline::Packet& packet) noexcept;
407
415 virtual class Report Report() const;
416
421 Pipeline::State Status() const noexcept;
422
427 bool Failed() const noexcept;
428
433 const StormByte::Safe::Optional<StormByte::Safe::String>& Error() const noexcept;
434
442 virtual StormByte::Size InputCeiling() const noexcept;
443
447
448 protected:
453
470 std::string_view name, Pipeline::Kinds receives, Pipeline::Kinds produces);
471
475
485 void Log(StormByte::Logger::Level level, std::string_view message) noexcept;
486
492 void Fail(StormByte::Safe::String reason) noexcept;
493
497 void Fail() noexcept;
498
503 void Fail(const char* reason) noexcept {
504 Fail(std::string_view{reason ? reason : ""});
505 }
506
511 void Fail(std::string_view reason) noexcept;
512
524 void Hold(std::uint8_t n) noexcept;
525
533 void Release() noexcept;
534
539 bool Held() const noexcept;
540
545 std::uint8_t HeldFor() const noexcept;
546
554 virtual void Eof() noexcept;
555
567 virtual void LastChance(const Pipeline::Frame& frame) noexcept;
568
573 virtual void LastChance(const Pipeline::Packet& packet) noexcept;
574
589 const StormByte::Multimedia::FFmpeg::AVFrame& AVFrame() const noexcept;
590
595 StormByte::Multimedia::FFmpeg::AVFrame::ScaleContext& ScalingContext() const noexcept;
596
611 const StormByte::Multimedia::FFmpeg::AVPacket& AVPacket() const noexcept;
612
631 void Save(StormByte::Multimedia::FFmpeg::AVFrame&& incoming) noexcept;
632
643 StormByte::Safe::Optional<Property::AVRational> frameRate = {}) noexcept;
644
651 void Drop() noexcept;
652
659 void EmitGraph(StormByte::Multimedia::FFmpeg::AVFilterGraph& graph,
660 StormByte::Multimedia::FFmpeg::AVFrame&& incoming,
661 StormByte::Safe::Optional<Property::AVRational> frameRate = {}) noexcept;
662
675
677 private:
681 class Surface;
682
686 void Open() noexcept;
687
692 void Work(Pipeline::Item::PointerType item) noexcept;
693
698 void Finish() noexcept;
699
703 void Park() noexcept;
704
708 void CallLastChance() noexcept;
709
713 void Emit(Pipeline::Item::PointerType item) noexcept;
714
719 void Wait() noexcept;
720
724 void Launch() noexcept;
725
729 void Halt() noexcept;
730
734 void Stop() noexcept;
735
739 bool Stopping() const noexcept;
740
744 Backend::Pipeline::Host& Face() noexcept;
745
749 void Wake() noexcept;
750
754 void CloseHoppers() noexcept;
755
759 void BindPlan(StormByte::Safe::Shared<const Pipeline::Plan> plan) noexcept;
760
765 void RecordWork(std::int64_t microseconds) noexcept;
766
770 void DumpWork() noexcept;
771
778 bool MeasuringTwoPass() const noexcept;
779
780 StormByte::Safe::Shared<StormByte::Logger::Log> m_log;
781 StormByte::Safe::String m_name;
782 Pipeline::Kinds m_receives;
783 Pipeline::Kinds m_produces;
784
785 private:
789 class PrivateState;
790
791 PrivateState* m_state;
792
793 protected:
798 Backend::Pipeline::Pipe& pipe() noexcept;
799
804 const Backend::Pipeline::Pipe& pipe() const noexcept;
805
806 StormByte::Safe::Shared<Pipeline::StageTelemetry> m_telemetry;
807 StormByte::Safe::Optional<StormByte::Safe::String> m_error;
808 bool m_exhausted;
809 std::uint64_t m_workN;
810 std::int64_t m_workMin;
811 std::int64_t m_workMax;
812 std::int64_t m_lastWork;
813 Pipeline::Item::PointerType m_current;
814 std::uint8_t m_hold;
815 std::uint8_t m_heldFor;
816 StormByte::Safe::Shared<const Pipeline::Plan> m_plan;
817 int m_origin;
819 };
820
845 public:
849 Process(const Process& other) = delete;
850
854 Process(Process&& other) noexcept = delete;
855
859 ~Process() noexcept override = default;
860
864 Process& operator=(const Process& other) = delete;
865
869 Process& operator=(Process&& other) noexcept = delete;
870
871 protected:
877 Process(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name);
878
886 Process(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name,
887 Pipeline::Kinds receives, Pipeline::Kinds produces);
888 };
889
904 friend class FFmpeg;
905
906 public:
910 ProcessTwoPasses(const ProcessTwoPasses& other) = delete;
911
915 ProcessTwoPasses(ProcessTwoPasses&& other) noexcept = delete;
916
920 ~ProcessTwoPasses() noexcept override = default;
921
925 ProcessTwoPasses& operator=(const ProcessTwoPasses& other) = delete;
926
930 ProcessTwoPasses& operator=(ProcessTwoPasses&& other) noexcept = delete;
931
932 protected:
938 ProcessTwoPasses(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name);
939
947 ProcessTwoPasses(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name,
948 Pipeline::Kinds receives, Pipeline::Kinds produces);
949
956 bool Measuring() const noexcept;
957
962 virtual void Measure(const Pipeline::Frame& frame) noexcept = 0;
963
971 virtual void Measured() noexcept;
972
973 private:
977 void EnterMeasure() noexcept;
978
986 void LeaveMeasure() noexcept;
987
992 void BindMeasure(StormByte::Multimedia::Pipeline::Filters* owner) noexcept;
993
994 bool m_measuring = false;
995 StormByte::Multimedia::Pipeline::Filters* m_measureOwner = nullptr;
996 };
997
1007 public:
1011 Packet(const Packet& other) = delete;
1012
1016 Packet(Packet&& other) noexcept = delete;
1017
1021 ~Packet() noexcept override = default;
1022
1026 Packet& operator=(const Packet& other) = delete;
1027
1031 Packet& operator=(Packet&& other) noexcept = delete;
1032
1033 protected:
1039 Packet(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name);
1040
1048 Packet(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name,
1049 Pipeline::Kinds receives, Pipeline::Kinds produces);
1050 };
1051
1080 public:
1084 Analytics(const Analytics& other) = delete;
1085
1089 Analytics(Analytics&& other) noexcept = delete;
1090
1094 ~Analytics() noexcept override = default;
1095
1099 Analytics& operator=(const Analytics& other) = delete;
1100
1104 Analytics& operator=(Analytics&& other) noexcept = delete;
1105
1106 protected:
1114 Analytics(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name);
1115
1123 Analytics(StormByte::Safe::Shared<StormByte::Logger::Log> log, std::string_view name,
1124 Pipeline::Kinds receives, Pipeline::Kinds produces);
1125
1134
1139 void Save(StormByte::Multimedia::FFmpeg::AVFrame&& incoming) noexcept = delete;
1140
1145 void Save(StormByte::Multimedia::FFmpeg::AVPacket&& incoming) noexcept = delete;
1146
1153 StormByte::Safe::Optional<Property::AVRational> frameRate = {}) noexcept = delete;
1154
1163 StormByte::Safe::Optional<Property::AVRational> frameRate = {}) noexcept = delete;
1164
1168 void Drop() noexcept = delete;
1169
1174 void Hold(std::uint8_t n) noexcept = delete;
1175
1179 void Release() noexcept = delete;
1180
1184 bool Held() const noexcept = delete;
1185
1189 std::uint8_t HeldFor() const noexcept = delete;
1190
1195 void LastChance(const Pipeline::Frame& frame) noexcept override {
1196 (void)frame;
1197 }
1198
1203 void LastChance(const Pipeline::Packet& packet) noexcept override {
1204 (void)packet;
1205 }
1206 };
1207}
1208
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
RAII AVFilterGraph with a single video or audio in/out.
Definition AVFilterGraph.hxx:111
RAII owner of a libav AVFrame.
Definition AVFrame.hxx:161
RAII owner of a libav AVPacket.
Definition AVPacket.hxx:126
Measures units.
Definition ffmpeg.hxx:1079
void Save(StormByte::Multimedia::FFmpeg::AVFrame &&incoming) noexcept=delete
Deleted.
void EmitGraph(StormByte::Multimedia::FFmpeg::AVFilterGraph &graph, StormByte::Multimedia::FFmpeg::AVFrame &&incoming, StormByte::Safe::Optional< Property::AVRational > frameRate={}) noexcept=delete
Deleted.
void EmitFrame(StormByte::Multimedia::FFmpeg::AVFrame &&incoming, StormByte::Safe::Optional< Property::AVRational > frameRate={}) noexcept=delete
Deleted.
Analytics(const Analytics &other)=delete
Copy is not allowed.
void LastChance(const Pipeline::Packet &packet) noexcept override
Unused on Analytics.
Definition ffmpeg.hxx:1203
void LastChance(const Pipeline::Frame &frame) noexcept override
Unused on Analytics.
Definition ffmpeg.hxx:1195
StormByte::Size PendingCeiling(StormByte::Size full) const noexcept
Constrains pending analytics looks for the selected resource policy.
void Hold(std::uint8_t n) noexcept=delete
Deleted.
bool Held() const noexcept=delete
Deleted.
Analytics(Analytics &&other) noexcept=delete
Move is not allowed.
std::uint8_t HeldFor() const noexcept=delete
Deleted.
~Analytics() noexcept override=default
Releases only filter resources.
Abstract base for every StormByte Multimedia filter.
Definition ffmpeg.hxx:261
const Pipeline::Kinds & Produces() const noexcept
Kinds this filter emits.
Definition ffmpeg.hxx:354
virtual void Clean() noexcept=0
Drops per-run state.
virtual void Eof() noexcept
Filter-visible end-of-input hook.
virtual void Setup() noexcept=0
Acquires per-run state.
void Fail(StormByte::Safe::String reason) noexcept
Marks a hard error and wakes the filter.
std::uint8_t HeldFor() const noexcept
Units currently parked in the Hold queue.
void Save(StormByte::Multimedia::FFmpeg::AVFrame &&incoming) noexcept
Replaces the media of the current frame.
StormByte::Buffer::QueueSnapshot QueueSnapshot(int track) const noexcept
Reads effective queue limits and logical-byte accounting.
const StormByte::Safe::String & Leaf() const noexcept
Leaf token used in reports (vmaf).
Definition ffmpeg.hxx:338
void Save(StormByte::Multimedia::FFmpeg::AVPacket &&incoming) noexcept
Replaces the media of the current packet.
Pipeline::State Status() const noexcept
Current lifecycle value.
bool Failed() const noexcept
Whether this filter has failed.
void Log(StormByte::Logger::Level level, std::string_view message) noexcept
Writes one log line on the scoped module logger.
void EmitGraph(StormByte::Multimedia::FFmpeg::AVFilterGraph &graph, StormByte::Multimedia::FFmpeg::AVFrame &&incoming, StormByte::Safe::Optional< Property::AVRational > frameRate={}) noexcept
Emits a graph's first output and drains all currently available frames.
virtual void Process(const Pipeline::Frame &frame) noexcept
Frame body.
bool Held() const noexcept
Whether this filter is inside a Hold.
friend class ProcessTwoPasses
Definition ffmpeg.hxx:265
const StormByte::Multimedia::FFmpeg::AVPacket & AVPacket() const noexcept
Borrowed RAII handle of the current packet.
const StormByte::Safe::Optional< StormByte::Safe::String > & Error() const noexcept
Failure text.
void Release() noexcept
Ends the Hold and replays parked units through Process, then Emits them.
StormByte::Multimedia::FFmpeg::AVFrame::ScaleContext & ScalingContext() const noexcept
Reusable scaling cache owned by this filter, not by TLS.
void Hold(std::uint8_t n) noexcept
Starts a Hold of at most n units.
void EmitFrame(StormByte::Multimedia::FFmpeg::AVFrame &&incoming, StormByte::Safe::Optional< Property::AVRational > frameRate={}) noexcept
Emits a distinct filtered frame without forwarding the input.
FFmpeg(const FFmpeg &other)=delete
Copy is not allowed.
virtual void LastChance(const Pipeline::Frame &frame) noexcept
Last look before the Hold must end.
const Pipeline::Kinds & Receives() const noexcept
Kinds this filter consumes.
Definition ffmpeg.hxx:346
StormByte::Safe::String Name() const
Media()/name computed on each call; may allocate.
virtual enum StormByte::Multimedia::Type Media() const noexcept=0
Media this filter handles.
virtual class Report Report() const
Measurement, if any.
void Drop() noexcept
Consumes the current input without passthrough.
StormByte::Safe::Shared< const Pipeline::StageTelemetry > Telemetry() const
Shared counters retained independently of this filter.
FFmpeg(FFmpeg &&other) noexcept=delete
Move is not allowed.
void Fail(std::string_view reason) noexcept
Copies borrowed text into Safe storage and marks a hard error.
const StormByte::Multimedia::FFmpeg::AVFrame & AVFrame() const noexcept
Borrowed RAII handle of the current frame.
virtual StormByte::Size InputCeiling() const noexcept
Ceiling of this filter's input hopper.
Mutates compressed packets.
Definition ffmpeg.hxx:1006
Packet(const Packet &other)=delete
Copy is not allowed.
~Packet() noexcept override=default
Releases filter resources; the job manages worker shutdown.
Packet(Packet &&other) noexcept=delete
Move is not allowed.
Process that measures the origin before it rewrites.
Definition ffmpeg.hxx:902
virtual void Measure(const Pipeline::Frame &frame) noexcept=0
First pass.
ProcessTwoPasses(const ProcessTwoPasses &other)=delete
Copy is not allowed.
ProcessTwoPasses(ProcessTwoPasses &&other) noexcept=delete
Move is not allowed.
virtual void Measured() noexcept
After measure EoF, before the second read.
~ProcessTwoPasses() noexcept override=default
Releases only filter resources.
bool Measuring() const noexcept
Whether the tube is in the measure pass.
friend class FFmpeg
Definition ffmpeg.hxx:904
friend class StormByte::Multimedia::Pipeline::Filters
Definition ffmpeg.hxx:903
One-pass filter that mutates decoded frames.
Definition ffmpeg.hxx:844
Process(Process &&other) noexcept=delete
Move is not allowed.
Process(const Process &other)=delete
Copy is not allowed.
~Process() noexcept override=default
Releases only filter resources.
Optional facade: Between stretches, Add filters, Close.
Definition filters.hxx:194
One decoded access unit.
Definition frame.hxx:103
Facade shared by Frame and Packet.
Definition item.hxx:159
Bitmask of Kind.
Definition typedefs.hxx:179
One compressed access unit.
Definition packet.hxx:102
Closed job intention: owned location reader, writer and tracks.
Definition plan.hxx:206
Thread-safe counters and timings for one pipeline worker.
Definition telemetry.hxx:132
State
Lifecycle of the stage thread.
Definition typedefs.hxx:211
@ Route
A configured connection between pipeline stages.
Definition typedefs.hxx:141
Multimedia module of the StormByte suite.
Pipeline Demux / decode / filter / encode / mux types.
Media property value types.
Typed item queues provided by StormByte-Buffer.
Internal pipeline workers.
Definition decoder.hxx:82
Multimedia-owned pipeline stages and unit holders.
Frame and packet steps attached to a job or a raw pipeline.
Demux / decode / filter / encode / mux types.
@ Pipe
Buffer::Sink hopper owned by its consumer stage.
Definition telemetry.hxx:429
@ Filter
User or built-in filter leaf (see TopologyFilterKind).
Definition telemetry.hxx:395
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61