StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
transcoder.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/size.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>
57#include <StormByte/logger/log.hxx>
72#include <StormByte/safe/clonable.hxx>
73#include <StormByte/safe/function.hxx>
74#include <StormByte/safe/map.hxx>
75#include <StormByte/safe/optional.hxx>
76#include <StormByte/safe/pair.hxx>
77#include <StormByte/safe/string.hxx>
78#include <StormByte/safe/vector.hxx>
79#include <StormByte/type_traits.hxx>
80
81#include <chrono>
82#include <cstdint>
83#include <string_view>
84#include <utility>
85
97 class Transcoder;
98}
99
105namespace StormByte {
111 namespace Multimedia {
117 namespace Pipeline {
122 class Encoder;
123
128 class Transcoder;
129
139
159
171 public StormByte::Safe::Clonable<TrackSettled, StormByte::Safe::Unique<TrackSettled>> {
172 public:
177
182
188
194
198 virtual ~TrackSettled() noexcept override;
199
205 TrackSettled& operator=(const TrackSettled& other);
206
212 TrackSettled& operator=(TrackSettled&& other) noexcept;
213
217
224 PointerType Clone() const override;
225
231 PointerType Move() override;
232
237 virtual StormByte::Safe::String ToString() const;
238
239 int In = -1;
240 int Out = -1;
241 Type Kind = Type::Unknown;
242 const Codec* Source = nullptr;
243 const Codec* Destination = nullptr;
245 StormByte::Safe::Optional<double> Crf;
246 StormByte::Safe::Optional<std::int64_t> BitRate;
247 StormByte::Safe::Optional<std::int64_t> MaxBitRate;
248 StormByte::Safe::Optional<StormByte::Safe::String> Preset;
249 StormByte::Safe::Optional<StormByte::Safe::String> Tune;
250 StormByte::Safe::Map<StormByte::Safe::String, StormByte::Safe::String> FineTune;
251 StormByte::Safe::Optional<int> SampleFormat;
252 StormByte::Safe::Optional<int> SourceChannels;
254 StormByte::Safe::Optional<int> FrameSize;
255 StormByte::Safe::Optional<int> SampleRate;
256 };
257
316 public:
327 public:
332
337 Track(const Track& other) noexcept = default;
338
343 Track(Track&& other) noexcept = default;
344
348 ~Track() noexcept = default;
349
355 Track& operator=(const Track& other) noexcept = default;
356
362 Track& operator=(Track&& other) noexcept = default;
363
367
372 Track& Remux() noexcept;
373
379 Track& Codec(const Codec& codec) noexcept;
380
387
395
402
408 Track& CRF(double value);
409
415 Track& BitRate(std::int64_t bits_per_second);
416
422 Track& MaxBitRate(std::int64_t bits_per_second);
423
429 Track& Preset(StormByte::Safe::String name);
430
436 Track& Tune(StormByte::Safe::String name);
437
448 Track& FineTune(StormByte::Safe::Map<StormByte::Safe::String, StormByte::Safe::String> options);
449
455 Track& Language(StormByte::Safe::String language);
456
463
469 Track& Title(StormByte::Safe::String title);
470
476
489 template<typename FilterType, typename... Args>
490 Track& Filter(Args&&... args) {
491 m_owner->AttachFilter(m_slot,
493 return *this;
494 }
495
496 private:
500 friend class Transcoder;
501
507 Track(Transcoder& owner, StormByte::Size slot) noexcept;
508
509 Transcoder* m_owner;
510 StormByte::Size m_slot;
511 };
512
517
529 const StormByte::Safe::String& destination,
532
544
553 const StormByte::Safe::String& destination,
556
568
578 const StormByte::Safe::String& destination,
579 const class Container& container,
582
593 const class Container& container,
596
606 const StormByte::Safe::String& destination,
607 const class Container& container,
610
621 const class Container& container,
624
629 Transcoder(const Transcoder& other) = delete;
630
635 Transcoder(Transcoder&& other) = delete;
636
640 virtual ~Transcoder() noexcept;
641
647 Transcoder& operator=(const Transcoder& other) = delete;
648
654 Transcoder& operator=(Transcoder&& other) noexcept = delete;
655
659
668 const StormByte::Safe::Shared<StormByte::Logger::Log>& Logger() const noexcept;
669
674 inline const StormByte::Safe::Shared<class Plan>& Plan() const noexcept {
675 return m_plan;
676 }
677
682
689 Track Video(int in) noexcept;
690
697 Track Audio(int in) noexcept;
698
705 Track Subtitle(int in) noexcept;
706
715
722 Transcoder& Attachments(std::string_view pattern) noexcept;
723
733 Transcoder& Tag(StormByte::Multimedia::Metadata::FileTag tag, StormByte::Safe::String value) noexcept;
734
741
746 ResourceUsage Resources() const noexcept;
747
771 void Resources(ResourceUsage usage) noexcept;
772
777 BufferingPolicy Buffering() const noexcept;
778
786 void Buffering(const BufferingPolicy& policy) noexcept;
787
793 Transcoder& Ignore(int in) noexcept;
794
805 template<typename FilterType, typename... Args>
806 Transcoder& Filter(Args&&... args) {
808 "Track filters attach on Track::Filter");
809 AttachAnalytics(StormByte::Safe::Shared<Filter::FFmpeg>::MakePointer<FilterType>(std::forward<Args>(args)...));
810 return *this;
811 }
812
816
821
830 void Run() noexcept;
831
836 void Cancel() noexcept;
837
845 void Pause() noexcept;
846
850 void Resume() noexcept;
851
856 enum Status Status() const noexcept;
857
862 bool Failed() const noexcept;
863
868 StormByte::Safe::Optional<StormByte::Safe::String> Error() const;
869
874 StormByte::Safe::Shared<StormByte::Buffer::ReadTelemetry> InputTelemetry() const noexcept;
875
880 StormByte::Safe::Shared<StormByte::Buffer::WriteTelemetry> OutputTelemetry() const noexcept;
881
890 StormByte::Safe::Shared<const class Progress> Progress() const noexcept;
891
905 StormByte::Safe::Vector<StormByte::Safe::Pair<StormByte::Safe::String, Filter::Report>> Reports() const;
906
916 StormByte::Safe::Shared<const JobTelemetry> Telemetry() const noexcept;
917
922 explicit operator bool() const noexcept;
923
927
928 protected:
940 virtual void InstallLog();
941
949 inline const StormByte::Safe::Shared<StormByte::Logger::Log>& ApplicationLog() const noexcept {
950 return m_app_log;
951 }
952
973 const class Container* container = nullptr) const;
974
983
993
997 virtual void OnConfigure() noexcept;
998
1003 virtual enum Status OnStart() noexcept;
1004
1009 virtual void OnPlan(const class Plan& plan) noexcept;
1010
1015 virtual void OnSettled(const TrackSettled& track) noexcept;
1016
1022 virtual void OnMeasureDone() noexcept;
1023
1029 virtual void OnAnalyticsDone() noexcept;
1030
1034 virtual void OnProgress() noexcept;
1035
1039 virtual void OnDone() noexcept;
1040
1045 virtual void OnError(const StormByte::Safe::String& message) noexcept;
1046
1050 virtual void OnAborted() noexcept;
1051
1052 private:
1057
1061 friend class Track;
1062
1072 StormByte::Safe::Unique<StormByte::Buffer::IO::BufferedLocationWriter> writer,
1073 StormByte::Safe::Shared<StormByte::Logger::Log> logger,
1074 StormByte::Safe::Optional<std::int64_t> duration,
1075 const class Container* container);
1076
1081 void Fail(std::string_view reason) noexcept;
1082
1086 void Fail() noexcept;
1087
1092 bool ProbeSource() noexcept;
1093
1100 Track AddTrack(int in, Type kind) noexcept;
1101
1107 void MarkSettled(int out, Encoder& encoder);
1108
1114 bool ValidSlot(StormByte::Size slot) const noexcept;
1115
1121 void AttachFilter(StormByte::Size slot, StormByte::Safe::Shared<Filter::FFmpeg> filter);
1122
1127 void AttachAnalytics(StormByte::Safe::Shared<Filter::FFmpeg> filter);
1128
1129 StormByte::Safe::Shared<StormByte::Logger::Log> m_app_log;
1130 StormByte::Safe::Shared<StormByte::Logger::Log> m_logger;
1131 StormByte::Safe::Shared<StormByte::Buffer::ReadTelemetry> m_input_telemetry;
1132 StormByte::Safe::Shared<StormByte::Buffer::WriteTelemetry> m_output_telemetry;
1133 StormByte::Safe::Unique<StormByte::Buffer::IO::BufferedLocationReader> m_reader;
1134 StormByte::Safe::Unique<StormByte::Buffer::IO::BufferedLocationWriter> m_writer;
1135 StormByte::Safe::Optional<std::int64_t> m_duration;
1136 const class Container* m_container = nullptr;
1137 StormByte::Safe::Unique<File> m_consult;
1138 StormByte::Safe::Shared<class Plan> m_plan;
1139 StormByte::Safe::Unique<Backend::Pipeline::Transcoder> m_backend;
1140 bool m_armed;
1141 };
1142 }
1143 }
1144}
1145
1151
1157
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Immutable codec identity owned by Registry.
Definition codec.hxx:94
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
Decodes packets of one origin track into frames.
Definition decoder.hxx:148
Encodes frames of one output track into packets.
Definition encoder.hxx:145
Retained job telemetry with per-stage snapshots and RSS samples.
Definition telemetry.hxx:602
What an encoder actually opened.
Definition transcoder.hxx:171
StormByte::Safe::Optional< int > SampleFormat
Encoder AVSampleFormat.
Definition transcoder.hxx:251
virtual StormByte::Safe::String ToString() const
Human-readable line for logs.
StormByte::Safe::Optional< int > SampleRate
Samples per second.
Definition transcoder.hxx:255
TrackSettled(TrackSettled &&other)
Move constructor.
StormByte::Safe::Optional< double > Crf
CRF/CQ actually used.
Definition transcoder.hxx:245
StormByte::Safe::Optional< StormByte::Safe::String > Implementation
Opened encoder implementation pin.
Definition transcoder.hxx:244
const Codec * Destination
Borrowed opened encoder codec, or null for remux.
Definition transcoder.hxx:243
StormByte::Safe::Optional< std::int64_t > BitRate
Bitrate actually used.
Definition transcoder.hxx:246
PointerType Move() override
Move into a new pointer.
int In
Origin stream or attachment slot.
Definition transcoder.hxx:239
StormByte::Safe::Optional< std::int64_t > MaxBitRate
VBV bitrate actually used.
Definition transcoder.hxx:247
StormByte::Safe::Optional< int > FrameSize
Encoder frame size.
Definition transcoder.hxx:254
StormByte::Safe::Optional< StormByte::Safe::String > Preset
Preset actually used.
Definition transcoder.hxx:248
TrackSettled(const TrackSettled &other)
Copy constructor.
StormByte::Safe::Optional< int > EncoderChannels
Encoder channel count.
Definition transcoder.hxx:253
Type Kind
Media kind.
Definition transcoder.hxx:241
const Codec * Source
Borrowed registry origin codec.
Definition transcoder.hxx:242
StormByte::Safe::Optional< int > SourceChannels
Decoded channel count.
Definition transcoder.hxx:252
StormByte::Safe::Optional< StormByte::Safe::String > Tune
Tune actually used.
Definition transcoder.hxx:249
StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > FineTune
Vendor options actually used.
Definition transcoder.hxx:250
PointerType Clone() const override
Deep copy.
virtual ~TrackSettled() noexcept override
Destructor.
int Out
Index in Plan::Tracks after Add.
Definition transcoder.hxx:240
Fluent handle for one origin stream in this job.
Definition transcoder.hxx:326
Track & CRF(double value)
Sets CRF/CQ.
Track(Track &&other) noexcept=default
Move constructor.
Track & RemoveLanguage()
Writes this track without a language tag.
Track & Title(StormByte::Safe::String title)
Overrides stream title.
Track & Implementation(StormByte::Safe::String name)
Pins an FFmpeg encoder name.
Track & Remux() noexcept
Remux this track (no destination codec).
Track & MaxBitRate(std::int64_t bits_per_second)
Sets VBV / max bitrate.
Track & RemoveTitle()
Writes this track without a title.
Track & Acceleration(DecodeAcceleration acceleration)
Selects hardware or software decoding for this video track.
Track & Filter(Args &&... args)
Appends a Process, Packet or Analytics filter to this track.
Definition transcoder.hxx:490
Track & FineTune(StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > options)
Replaces vendor leftovers.
Track & Preset(StormByte::Safe::String name)
Sets encoder preset.
Track(const Track &other) noexcept=default
Copy constructor.
Track & BitRate(std::int64_t bits_per_second)
Sets target bitrate.
Track & Tune(StormByte::Safe::String name)
Sets encoder tune.
Track & Codec(const Codec &codec) noexcept
Encodes this track to codec.
Track & Language(StormByte::Safe::String language)
Overrides stream language.
friend class Transcoder
Parent job that constructs mapped track handles.
Definition transcoder.hxx:500
Transcoder(const StormByte::Safe::String &source, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Builds a local reader and takes the writer with an explicit container.
StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > InputTelemetry() const noexcept
Shared telemetry for the original input reader.
virtual void InstallLog()
Scopes this job's own logger.
Transcoder(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Takes both location owners without slicing.
void Cancel() noexcept
Requests abort.
Transcoder & Tag(StormByte::Multimedia::Metadata::FileTag tag, StormByte::Safe::String value) noexcept
Replaces a file-level tag in the output.
virtual StormByte::Safe::Shared< class Plan > EmptyPlan(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Optional< std::int64_t > duration={}, const class Container *container=nullptr) const
Allocates the Plan type for this job.
BufferingPolicy Buffering() const noexcept
Queue capacity overrides used by the Plan built on Run.
enum Status Status() const noexcept
Current lifecycle value.
void Pause() noexcept
Pauses the job.
Track Subtitle(int in) noexcept
Maps a subtitle origin stream.
Transcoder & Filter(Args &&... args)
Appends a global analytics filter.
Definition transcoder.hxx:806
StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry > OutputTelemetry() const noexcept
Shared telemetry for the destination writer.
StormByte::Safe::Shared< const JobTelemetry > Telemetry() const noexcept
Shared job and stage telemetry, available before Run.
virtual void OnSettled(const TrackSettled &track) noexcept
One encode lane finished Encoder open.
const StormByte::Safe::Shared< StormByte::Logger::Log > & Logger() const noexcept
Logger used by this job after InstallLog.
virtual StormByte::Safe::Unique< TrackSettled > EmptySettled() const
Allocates the settled-row type.
friend class Backend::Pipeline::Transcoder
Backend coordinator that runs this job's pipeline.
Definition transcoder.hxx:1056
virtual void OnAnalyticsDone() noexcept
Analytics taps idle.
virtual void OnAborted() noexcept
Cancel completed.
StormByte::Safe::Function< void(double)> DurationProgress() const
Observer for duration resolution in custom EmptyPlan implementations.
Transcoder(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Takes both locations with an authoritative borrowed container.
Transcoder & Attachments() noexcept
Keeps every source attachment.
void Run() noexcept
Builds the Plan, starts the coordinator and returns.
Transcoder(const StormByte::Safe::String &source, const StormByte::Safe::String &destination, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Builds reader and writer from paths.
virtual void OnMeasureDone() noexcept
Measure pass closed.
Transcoder(Transcoder &&other)=delete
Move constructor.
StormByte::Safe::Vector< StormByte::Safe::Pair< StormByte::Safe::String, Filter::Report > > Reports() const
Analytics snapshots after the job is Idle.
Track Video(int in) noexcept
Maps a video origin stream.
StormByte::Safe::Shared< const class Progress > Progress() const noexcept
Shared tube clock.
virtual void OnError(const StormByte::Safe::String &message) noexcept
Hard error.
Transcoder & Ignore(int in) noexcept
Drops an origin stream (omit from the Plan).
Transcoder & RemoveTag(StormByte::Multimedia::Metadata::FileTag tag) noexcept
Writes the output without file tag tag.
Track Audio(int in) noexcept
Maps an audio origin stream.
virtual enum Status OnStart() noexcept
Gate after the Plan is filled.
virtual void OnProgress() noexcept
Progress tick.
virtual ~Transcoder() noexcept
Destructor.
ResourceUsage Resources() const noexcept
Resource policy selected for this job.
Transcoder(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, const StormByte::Safe::String &destination, const class Container &container, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Takes the reader and builds a writer with an explicit container.
StormByte::Safe::Optional< StormByte::Safe::String > Error() const
Failure text.
bool Failed() const noexcept
Whether the job failed.
Transcoder(const StormByte::Safe::String &source, const StormByte::Safe::String &destination, const class Container &container, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Builds local locations with an authoritative borrowed container.
const StormByte::Safe::Shared< class Plan > & Plan() const noexcept
Intention built for this job, if any.
Definition transcoder.hxx:674
virtual void OnConfigure() noexcept
Last chance to raise ceilings before the job starts.
Transcoder(StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, const StormByte::Safe::String &destination, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Takes reader and builds a local writer.
Transcoder(const StormByte::Safe::String &source, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Shared< StormByte::Logger::Log > logger, StormByte::Safe::Optional< std::int64_t > duration={})
Builds a local reader and takes writer.
void Resume() noexcept
Resumes after Pause.
virtual void OnPlan(const class Plan &plan) noexcept
Intention, just before plan >> demuxer.
Transcoder(const Transcoder &other)=delete
Copy constructor.
virtual void OnDone() noexcept
Successful flush.
const StormByte::Safe::Shared< StormByte::Logger::Log > & ApplicationLog() const noexcept
Application logger passed to the constructor.
Definition transcoder.hxx:949
static Shared< T > MakePointer(Args &&... args)
Coordinator behind StormByte::Multimedia::Pipeline::Transcoder.
ImplementationSide
Codec stage selected by a track implementation pin.
Definition transcoder.hxx:135
Status
Lifecycle of a Transcoder instance.
Definition transcoder.hxx:151
ResourceUsage
Relative CPU policy and automatic queue-capacity profile.
Definition resource_usage.hxx:75
@ Running
Coordinator is alive and not paused.
Definition transcoder.hxx:153
@ Aborted
Cancel() while Running/Paused, or OnStart returned Aborted.
Definition transcoder.hxx:157
@ Stopped
Constructed; Run has not started, or OnStart declined.
Definition transcoder.hxx:152
@ Done
Finished and flushed.
Definition transcoder.hxx:155
Multimedia module of the StormByte suite.
Pipeline Demux / decode / filter / encode / mux types.
Typed item queues provided by StormByte-Buffer.
Multimedia-owned pipeline stages and unit holders.
Private RAII wrappers over libav*.
Snapshot metadata for files and streams.
@ Paused
Actually blocked by a cooperative pause.
Definition activity.hxx:86
@ Encoder
Track encoder feeding the muxer.
Definition telemetry.hxx:396
DecodeAcceleration
Selects whether video decoders may use an available FFmpeg hardware backend.
Definition decode_policy.hxx:43
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61