StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
encoder.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/fifo.hxx>
55#include <StormByte/logger/log.hxx>
63#include <StormByte/safe/map.hxx>
64#include <StormByte/safe/optional.hxx>
65#include <StormByte/safe/pointers.hxx>
66#include <StormByte/safe/string.hxx>
67
68#include <cstddef>
69#include <cstdint>
70#include <StormByte/safe/optional.hxx>
71
82 class Encoder;
83
87 class Packet;
88}
89
98 class Encode;
99}
100
105namespace StormByte {
110 namespace Multimedia {
117 namespace Pipeline {
121 class Encoder;
122
126 class Frame;
127
131 class Muxer;
132
146 public:
151
159 int output_index, const Codec& codec);
160
165 Encoder(const Encoder& other) = delete;
166
171 Encoder(Encoder&& other) noexcept = delete;
172
176 ~Encoder() noexcept override;
177
183 Encoder& operator=(const Encoder& other) = delete;
184
190 Encoder& operator=(Encoder&& other) noexcept = delete;
191
195
200
205 explicit operator bool() const noexcept;
206
211 inline int Index() const noexcept {
212 return m_index;
213 }
214
219 StormByte::Size InputCeiling() const noexcept override;
220
225 inline const Codec& Destination() const noexcept {
226 return *m_codec;
227 }
228
233 bool Opened() const noexcept;
234
239 StormByte::Safe::Optional<int> AudioChannels() const;
240
245 StormByte::Safe::Optional<int> AudioSampleRate() const;
246
251 StormByte::Safe::Optional<int> AudioFrameSize() const;
252
257 StormByte::Safe::Optional<int> AudioSampleFormat() const;
258
262
267
272 inline const StormByte::Safe::String& EncoderTag() const noexcept {
273 return m_encoderTag;
274 }
275
279
284
290 return m_implementation;
291 }
292
298
303 inline const Features& Require() const noexcept {
304 return m_require;
305 }
306
311 inline void Require(Features features) noexcept {
312 m_require = features;
313 }
314
319 inline const Features& Capabilities() const noexcept {
320 return m_capabilities;
321 }
322
326
331
336 inline void CRF(double value) noexcept {
337 m_crf = value;
338 }
339
344 inline const StormByte::Safe::Optional<double>& CRF() const noexcept {
345 return m_crf;
346 }
347
352 inline void BitRate(std::int64_t bits_per_second) noexcept {
353 m_bitRate = bits_per_second;
354 }
355
360 inline const StormByte::Safe::Optional<std::int64_t>& BitRate() const noexcept {
361 return m_bitRate;
362 }
363
368 inline void MaxBitRate(std::int64_t bits_per_second) noexcept {
369 m_maxBitRate = bits_per_second;
370 }
371
377 return m_maxBitRate;
378 }
379
384 void Preset(StormByte::Safe::String name) noexcept;
385
391 return m_preset;
392 }
393
398 void Tune(StormByte::Safe::String name) noexcept;
399
405 return m_tune;
406 }
407
411
416
422 return m_fineTune;
423 }
424
430 m_fineTune = std::move(options);
431 }
432
436
437 private:
441 friend class Backend::Pipeline::Encoder;
442
446 friend class Backend::Pipeline::Detail::Worker::Encode;
447
451 friend class Muxer;
452
457
461 using Step::Log;
462
468 StormByte::Safe::String Label() const override;
469
473
494 enum StormByte::Multimedia::Type type, int index,
499 bool keyFrame,
502
508 bool MuxBindStream(void* avStream) noexcept;
509
515 void* FrameHandle(Frame& frame) noexcept;
516
522 const void* FrameHandle(const Frame& frame) noexcept;
523
528 void Emit(Packet::PointerType packet) noexcept;
529
534 bool WaitForPlan() noexcept;
535
540 bool SetupPlan() noexcept;
541
542 int m_index;
543 const Codec* m_codec;
544 StormByte::Safe::String m_encoderTag;
545 StormByte::Safe::Optional<StormByte::Safe::String> m_implementation;
546 Features m_require;
547 Features m_capabilities;
548 StormByte::Safe::Optional<double> m_crf;
549 StormByte::Safe::Optional<std::int64_t> m_bitRate;
550 StormByte::Safe::Optional<std::int64_t> m_maxBitRate;
551 StormByte::Safe::Optional<StormByte::Safe::String> m_preset;
552 StormByte::Safe::Optional<StormByte::Safe::String> m_tune;
553 StormByte::Safe::Map<StormByte::Safe::String, StormByte::Safe::String> m_fineTune;
554 StormByte::Safe::Unique<Backend::Pipeline::Encoder> m_backend;
555 StormByte::Safe::Optional<std::uint64_t> m_serial;
556 std::uint64_t m_part;
557 Join m_join{*this};
558 };
559 }
560 }
561}
562
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Buffer::Bridge)
Immutable codec identity owned by Registry.
Definition codec.hxx:94
Bitmask of Feature flags.
Definition features.hxx:77
Encodes frames of one output track into packets.
Definition encoder.hxx:145
void Implementation(StormByte::Safe::String name) noexcept
Pins an FFmpeg encoder name.
const StormByte::Safe::Optional< StormByte::Safe::String > & Tune() const noexcept
Tune, if set.
Definition encoder.hxx:404
Encoder(Encoder &&other) noexcept=delete
Move constructor.
StormByte::Safe::Optional< int > AudioChannels() const
Encoder channel count after Open(), audio only.
void CRF(double value) noexcept
Constant quality (CRF/CQ).
Definition encoder.hxx:336
Encoder(const Encoder &other)=delete
Copy constructor.
friend class Backend::Pipeline::Encoder
Allows the encode backend to wrap and emit encoded packets.
Definition encoder.hxx:441
Encoder(StormByte::Safe::Shared< StormByte::Logger::Log > log, int output_index, const Codec &codec)
Encoder for output track output_index and destination codec.
const StormByte::Safe::Optional< double > & CRF() const noexcept
CRF/CQ, if set.
Definition encoder.hxx:344
const StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > & FineTune() const noexcept
Vendor leftovers.
Definition encoder.hxx:421
const Features & Capabilities() const noexcept
Features of the row selected at open.
Definition encoder.hxx:319
void FineTune(StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > options) noexcept
Replaces the vendor dict (before open).
Definition encoder.hxx:429
StormByte::Size InputCeiling() const noexcept override
Maximum number of queued input frames.
const StormByte::Safe::Optional< StormByte::Safe::String > & Implementation() const noexcept
Pinned FFmpeg encoder name, if any.
Definition encoder.hxx:289
const StormByte::Safe::Optional< StormByte::Safe::String > & Preset() const noexcept
Preset, if set.
Definition encoder.hxx:390
void Preset(StormByte::Safe::String name) noexcept
Encoder preset.
const StormByte::Safe::Optional< std::int64_t > & BitRate() const noexcept
Target bitrate, if set.
Definition encoder.hxx:360
~Encoder() noexcept override
Destructor.
StormByte::Safe::Optional< int > AudioSampleFormat() const
Encoder sample format after Open(), audio only.
bool Opened() const noexcept
Whether encoder initialization has completed.
StormByte::Safe::Optional< int > AudioFrameSize() const
Encoder frame_size after Open(), audio only.
const StormByte::Safe::Optional< std::int64_t > & MaxBitRate() const noexcept
VBV ceiling, if set.
Definition encoder.hxx:376
StormByte::Safe::Optional< int > AudioSampleRate() const
Encoder sample rate after Open(), audio only.
const StormByte::Safe::String & EncoderTag() const noexcept
Writing-application tag stamped on every encoded stream.
Definition encoder.hxx:272
const Features & Require() const noexcept
Extra features the caller demands besides Frame HDR.
Definition encoder.hxx:303
void Require(Features features) noexcept
Replaces the extra feature mask (before open).
Definition encoder.hxx:311
void BitRate(std::int64_t bits_per_second) noexcept
Target bitrate in bits per second.
Definition encoder.hxx:352
void MaxBitRate(std::int64_t bits_per_second) noexcept
VBV ceiling in bits per second.
Definition encoder.hxx:368
int Index() const noexcept
Mux destination order key.
Definition encoder.hxx:211
void Tune(StormByte::Safe::String name) noexcept
Content tune.
friend class Muxer
Allows the muxer to bind the encoded stream.
Definition encoder.hxx:451
const Codec & Destination() const noexcept
Destination codec.
Definition encoder.hxx:225
One decoded access unit.
Definition frame.hxx:103
StormByte::Safe::Shared< Packet > PointerType
Base-heap shared owner of a packet; keep its providers loaded.
Definition packet.hxx:107
Ensures a derived stage stops before its resources expire.
Definition step.hxx:501
Step(const Step &other)=delete
Copy construction is disabled.
virtual void Log(StormByte::Logger::Level level, std::string_view message) noexcept
Writes one log line on the scoped module logger.
@ Frame
Decoded StormByte::Multimedia::Pipeline::Frame.
Definition typedefs.hxx:111
Multimedia module of the StormByte suite.
Pipeline Demux / decode / filter / encode / mux types.
Internal pipeline workers.
Definition decoder.hxx:82
Multimedia-owned pipeline stages and unit holders.
@ Packet
Packet filter (Filter::Packet and derived).
Definition telemetry.hxx:409
@ Encoder
Track encoder feeding the muxer.
Definition telemetry.hxx:396
@ Muxer
Container writer.
Definition telemetry.hxx:398
Type
Kind of media stream or codec.
Definition type.hxx:72
Root namespace of the StormByte C++ suite.
STL namespace.
#define STORMBYTE_MULTIMEDIA_PUBLIC
Definition visibility.h:61