StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
plan.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/bitmask.hxx>
54#include <StormByte/buffer/io/buffered_location_reader.hxx>
55#include <StormByte/buffer/io/buffered_location_writer.hxx>
56#include <StormByte/buffer/telemetry.hxx>
64#include <StormByte/safe/atomic.hxx>
65#include <StormByte/safe/function.hxx>
66#include <StormByte/safe/mutex.hxx>
67#include <StormByte/safe/optional.hxx>
68#include <StormByte/safe/pointers.hxx>
69#include <StormByte/safe/string.hxx>
70
71#include <chrono>
72#include <cstdint>
73#include <utility>
74
76 class FFmpeg;
77}
78
83namespace StormByte {
88 namespace Multimedia {
93 namespace Backend::Pipeline {
97 class Demuxer;
98
102 class Ceiling;
103
108 namespace Detail::Muxer::FFmpeg {
112 class Container;
113 }
114
118 class Transcoder;
119 }
120
127 namespace Pipeline {
131 class Demuxer;
132
136 class Decoder;
137
141 class Encoder;
142
146 class Remuxer;
147
151 class Muxer;
152
156 class Filters;
157
161 class Step;
162
166 class Route;
167
171 class Transcoder;
172
207 public:
212 enum class State: std::uint8_t {
218 };
219
227 enum class Policy: std::uint32_t {
228 None = 0,
229 EnforceFeatures = 1u << 0
230 };
231
240 friend constexpr enum Policy operator~(enum Policy policy) noexcept {
241 return static_cast<enum Policy>(~static_cast<std::uint32_t>(policy));
242 }
243
249 static constexpr const char* ToString(enum Policy policy) noexcept {
250 switch (policy) {
251 case Policy::None: return "None";
252 case Policy::EnforceFeatures: return "EnforceFeatures";
253 }
254 return "UnknownPolicy";
255 }
256
265 public:
269 constexpr Policies() noexcept: Bitmask() {}
270
275 constexpr Policies(enum Policy policy) noexcept: Bitmask(policy) {}
276
281 constexpr Policies(const Policies& other) noexcept = default;
282
287 constexpr Policies(Policies&& other) noexcept = default;
288
292 constexpr ~Policies() noexcept override = default;
293
299 constexpr Policies& operator=(const Policies& other) noexcept = default;
300
306 constexpr Policies& operator=(Policies&& other) noexcept = default;
307 };
308
313 enum State State() const noexcept;
314
319 StormByte::Safe::Optional<StormByte::Safe::String> Error() const;
320
325
332 Plan(const StormByte::Safe::String& source,
333 const StormByte::Safe::String& destination,
334 StormByte::Safe::Optional<std::int64_t> duration = {});
335
345
353 const StormByte::Safe::String& destination,
355
365
376 const StormByte::Safe::Function<void(double)>* progress);
377
386 const StormByte::Safe::String& destination,
387 const class Container& container,
389
399 const class Container& container,
401
410 const StormByte::Safe::String& destination,
411 const class Container& container,
413
423 const class Container& container,
425
436 const class Container& container,
438 const StormByte::Safe::Function<void(double)>* progress);
439
444 Plan(const Plan& other) = delete;
445
450 Plan(Plan&& other) noexcept = delete;
451
455 virtual ~Plan() noexcept;
456
462 Plan& operator=(const Plan& other) = delete;
463
469 Plan& operator=(Plan&& other) noexcept = delete;
470
474
479 explicit operator bool() const;
480
485
490 StormByte::Safe::Shared<StormByte::Buffer::ReadTelemetry> InputTelemetry() const noexcept;
491
496 StormByte::Safe::Shared<StormByte::Buffer::WriteTelemetry> OutputTelemetry() const noexcept;
497
502 inline void add(const Track& track) {
503 m_tracks.add(track);
504 }
505
510 inline void add(Track&& track) {
511 m_tracks.add(std::move(track));
512 }
513
518 inline const class Tracks& Tracks() const noexcept {
519 return m_tracks;
520 }
521
526 inline const class Policies& Policies() const noexcept {
527 return m_policies;
528 }
529
539 inline void Policies(enum Policy policy) noexcept {
540 constexpr auto defined = static_cast<std::uint32_t>(Policy::EnforceFeatures);
541 const auto bits = static_cast<std::uint32_t>(policy);
542 if ((bits & ~defined) == 0) {
543 if (bits != 0)
544 m_policies.Add(policy);
545 return;
546 }
547
548 const auto clear = defined & ~bits;
549 if (clear != 0)
550 m_policies.Remove(static_cast<enum Policy>(clear));
551 }
552
557 constexpr ResourceUsage Resources() const noexcept {
558 // Keep the installed Plan layout stable by encoding this internal
559 // policy in reserved bits of its existing Policy mask.
560 if (m_policies.Has(static_cast<Policy>(1u << 30)))
561 return ResourceUsage::Low;
562 if (m_policies.Has(static_cast<Policy>(1u << 29)))
564 return ResourceUsage::Full;
565 }
566
571 inline void Resources(ResourceUsage usage) noexcept {
572 const auto resourceBits = static_cast<Policy>((1u << 30) | (1u << 29));
573 m_policies.Remove(resourceBits);
574 switch (usage) {
576 m_policies.Add(static_cast<Policy>(1u << 29));
577 break;
579 m_policies.Add(static_cast<Policy>(1u << 30));
580 break;
582 break;
583 }
584 }
585
590 const BufferingPolicy& Buffering() const noexcept;
591
598 bool Buffering(const BufferingPolicy& policy) noexcept;
599
603
624 virtual CheckResult Check() const;
625
626 private:
631 StormByte::Buffer::IO::BufferedLocationReader& Reader() noexcept;
632
637 const StormByte::Buffer::IO::BufferedLocationReader& Reader() const noexcept;
638
646 const StormByte::Multimedia::File& Snapshot() const noexcept;
647
652 inline const class Container& Container() const noexcept {
653 return *m_container;
654 }
655
661
666 const StormByte::Buffer::IO::BufferedLocationWriter& Writer() const noexcept;
667
672 inline const StormByte::Safe::String& Path() const noexcept {
673 return m_writer->Path();
674 }
675
679 friend class Demuxer;
680
684 friend class Decoder;
685
689 friend class Encoder;
690
694 friend class Remuxer;
695
699 friend class Muxer;
700
704 friend class Filters;
705
709 friend class Backend::Pipeline::Demuxer;
710
714 friend class Backend::Pipeline::Ceiling;
715
719 friend class Backend::Pipeline::Detail::Muxer::FFmpeg::Container;
720
724 friend class Step;
725
726 friend class Filter::FFmpeg;
727
731 friend class Route;
732
736 friend class Transcoder;
737
741 friend class Backend::Pipeline::Transcoder;
742
749 enum State State(enum State desired,
751
756 void Observe(Step& step);
757
762 void Unobserve(Step& step) noexcept;
763
768 void Hold(bool held);
769
774 void WaitWhileHeld(const Step& step) const noexcept;
775
781 void Complete(Step& step, bool success);
782
787 void Halt() noexcept;
788
792 class Observers;
793
804 const class Container* container,
805 StormByte::Safe::Optional<std::int64_t> duration,
806 const StormByte::Safe::Function<void(double)>* progress);
807
813 CheckResult Validate(bool tracks) const;
814
815 StormByte::Safe::Shared<StormByte::Buffer::ReadTelemetry> m_input_telemetry;
816 StormByte::Safe::Shared<StormByte::Buffer::WriteTelemetry> m_output_telemetry;
817 StormByte::Safe::Unique<StormByte::Buffer::IO::BufferedLocationReader> m_reader;
818 StormByte::Safe::Unique<StormByte::Buffer::IO::BufferedLocationWriter> m_writer;
819 StormByte::Safe::Unique<StormByte::Multimedia::File> m_snapshot;
820 const class Container* m_container = nullptr;
821 const char* m_format = nullptr;
822 class Tracks m_tracks;
823 mutable StormByte::Safe::Mutex m_state_mutex;
824 mutable StormByte::Safe::Atomic<enum State> m_state{State::Created};
827
828 protected:
836 };
837
845 }
846 }
847}
848
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Immutable container identity owned by StormByte::Multimedia::Registry.
Definition container.hxx:84
Read-only consultation snapshot of a media source.
Definition file.hxx:135
Queue element-cap overrides shared by Plans and Transcoders.
Definition buffering.hxx:99
Reads interleaved compressed packets from the Plan reader.
Definition demuxer.hxx:148
Abstract base for every StormByte Multimedia filter.
Definition ffmpeg.hxx:261
Bitmask of Policy flags.
Definition plan.hxx:264
constexpr Policies(Policies &&other) noexcept=default
Move constructor.
constexpr Policies() noexcept
Empty mask.
Definition plan.hxx:269
constexpr Policies(const Policies &other) noexcept=default
Copy constructor.
constexpr Policies(enum Policy policy) noexcept
Mask from one flag.
Definition plan.hxx:275
constexpr ~Policies() noexcept override=default
Destructor.
Intention flags.
Definition plan.hxx:835
Closed job intention: owned location reader, writer and tracks.
Definition plan.hxx:206
Policy
Job-intention flags.
Definition plan.hxx:227
@ EnforceFeatures
Check rejects an encode that drops source features.
Definition plan.hxx:229
@ None
No flags.
Definition plan.hxx:228
Plan(Plan &&other) noexcept=delete
Move construction is not supported; stages retain shared ownership.
Plan(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Optional< std::int64_t > duration, const StormByte::Safe::Function< void(double)> *progress)
Takes both owners and observes automatic duration resolution.
Plan(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, const StormByte::Safe::String &destination, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
Owns the reader and a container copy and builds a local writer.
Plan(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
Owns both locations and a copy of the explicit destination identity.
State
Shared execution state of the pipeline plan.
Definition plan.hxx:212
Plan(const Plan &other)=delete
Copy construction is not supported.
void add(Track &&track)
Appends track.
Definition plan.hxx:510
friend class Backend::Pipeline::Detail::Muxer::FFmpeg::Container
Allows muxing with the resolved FFmpeg identity.
Definition plan.hxx:719
friend class Remuxer
Allows remux snapshot consultation.
Definition plan.hxx:694
const BufferingPolicy & Buffering() const noexcept
Queue capacity policy shared with manually mounted pipelines.
void add(const Track &track)
Appends a clone of track.
Definition plan.hxx:502
constexpr ResourceUsage Resources() const noexcept
Resource policy carried by this plan.
Definition plan.hxx:557
const class Policies & Policies() const noexcept
Active intention flags.
Definition plan.hxx:526
friend class Decoder
Allows decoder snapshot consultation.
Definition plan.hxx:684
Plan(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, const StormByte::Safe::String &destination, StormByte::Safe::Optional< std::int64_t > duration={})
Takes reader and builds a local writer.
friend constexpr enum Policy operator~(enum Policy policy) noexcept
Bitwise complement of one flag, for Policies(Policy).
Definition plan.hxx:240
StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry > OutputTelemetry() const noexcept
Shared telemetry for the owned output writer.
StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > InputTelemetry() const noexcept
Shared telemetry for the owned input reader.
friend class Route
Allows private route snapshot consultation.
Definition plan.hxx:731
StormByte::Safe::Optional< StormByte::Safe::String > Error() const
Copies the synchronized first failure reason.
Plan(const StormByte::Safe::String &source, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Optional< std::int64_t > duration={})
Builds a local reader and takes writer.
Plan(const StormByte::Safe::String &source, const StormByte::Safe::String &destination, StormByte::Safe::Optional< std::int64_t > duration={})
Builds reader and writer from paths.
Plan(const StormByte::Safe::String &source, const StormByte::Safe::String &destination, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
Builds local locations with an owned explicit container copy.
friend class Encoder
Allows encoder track consultation.
Definition plan.hxx:689
const class Tracks & Tracks() const noexcept
Tube tracks.
Definition plan.hxx:518
friend class Filters
Allows filter matching against the source snapshot.
Definition plan.hxx:704
Plan(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration, const StormByte::Safe::Function< void(double)> *progress)
Owns locations and a container copy while observing duration resolution.
virtual ~Plan() noexcept
Destructor.
friend class Demuxer
Allows the input stage to consume source data.
Definition plan.hxx:679
Plan(const StormByte::Safe::String &source, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
Builds a local reader and owns the writer and a container copy.
void Policies(enum Policy policy) noexcept
Adds policy, or clears it when passed as ~policy.
Definition plan.hxx:539
void Resources(ResourceUsage usage) noexcept
Sets the resource policy before pipeline stages bind.
Definition plan.hxx:571
Plan(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Optional< std::int64_t > duration={})
Takes both location owners without slicing.
virtual CheckResult Check() const
Whether this intention is well formed.
friend class Muxer
Allows the output stage to consume destination data.
Definition plan.hxx:699
friend class Step
Allows stages to register state notifications.
Definition plan.hxx:724
friend class Transcoder
Allows the public facade to publish failure and cancellation.
Definition plan.hxx:736
static constexpr const char * ToString(enum Policy policy) noexcept
Converts a Policy to a stable token.
Definition plan.hxx:249
A pipeline stage that receives and emits media items.
Definition step.hxx:196
One source stream that enters the tube.
Definition track.hxx:96
Ordered tube tracks.
Definition track.hxx:254
Coordinator behind StormByte::Multimedia::Pipeline::Transcoder.
State
Lifecycle of the stage thread.
Definition typedefs.hxx:211
ResourceUsage
Relative CPU policy and automatic queue-capacity profile.
Definition resource_usage.hxx:75
@ Created
Constructed and available for configuration.
Definition typedefs.hxx:212
@ Route
A configured connection between pipeline stages.
Definition typedefs.hxx:141
@ Filters
Filters stage.
Definition typedefs.hxx:142
@ Running
Coordinator is alive and not paused.
Definition transcoder.hxx:153
@ Aborted
Cancel() while Running/Paused, or OnStart returned Aborted.
Definition transcoder.hxx:157
@ Low
Target at most two available process CPUs.
Definition resource_usage.hxx:78
@ Medium
Target approximately half of available process CPUs.
Definition resource_usage.hxx:77
@ Full
Keep native codec threading and all requested VMAF workers, with bounded queues.
Definition resource_usage.hxx:76
Internal pipeline consumers of the plan intention.
Output format implementation.
Multimedia module of the StormByte suite.
Pipeline Demux / decode / filter / encode / mux types.
Typed item queues provided by StormByte-Buffer.
Frame and packet steps attached to a job or a raw pipeline.
@ Finished
Execution ended, including cancellation.
Definition activity.hxx:87
@ Failed
Execution ended with a stage failure.
Definition activity.hxx:88
Decoder & operator>>(Demuxer &demuxer, Decoder &decoder) noexcept
Binds one origin track of demuxer to decoder.
StormByte::Expected< void, PlanException > CheckResult
Outcome of Plan::Check.
Definition typedefs.hxx:97
@ Demuxer
Container reader; owns the demux pending queues.
Definition telemetry.hxx:393
@ Encoder
Track encoder feeding the muxer.
Definition telemetry.hxx:396
@ Remuxer
Stream-copy stage feeding the muxer.
Definition telemetry.hxx:397
@ Decoder
Track decoder feeding a decode/encode lane.
Definition telemetry.hxx:394
Multimedia module of the StormByte suite.
@ None
No flags.
Definition feature.hxx:83
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61