StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Multimedia::Pipeline::Encoder Class Referencefinal

Encodes frames of one output track into packets. More...

#include <StormByte/multimedia/pipeline/encoder.hxx>

Inheritance diagram for StormByte::Multimedia::Pipeline::Encoder:
Collaboration diagram for StormByte::Multimedia::Pipeline::Encoder:

Public Member Functions

Lifecycle
 Encoder (StormByte::Safe::Shared< StormByte::Logger::Log > log, int output_index, const Codec &codec)
 Encoder for output track output_index and destination codec.
 Encoder (const Encoder &other)=delete
 Copy constructor.
 Encoder (Encoder &&other) noexcept=delete
 Move constructor.
 ~Encoder () noexcept override
 Destructor.
Encoder & operator= (const Encoder &other)=delete
 Copy assignment.
Encoder & operator= (Encoder &&other) noexcept=delete
 Move assignment.
State
 operator bool () const noexcept
 true if the encoder is open and has not failed.
int Index () const noexcept
 Mux destination order key.
StormByte::Size InputCeiling () const noexcept override
 Maximum number of queued input frames.
const Codec & Destination () const noexcept
 Destination codec.
bool Opened () const noexcept
 Whether encoder initialization has completed.
StormByte::Safe::Optional< int > AudioChannels () const
 Encoder channel count after Open(), audio only.
StormByte::Safe::Optional< int > AudioSampleRate () const
 Encoder sample rate after Open(), audio only.
StormByte::Safe::Optional< int > AudioFrameSize () const
 Encoder frame_size after Open(), audio only.
StormByte::Safe::Optional< int > AudioSampleFormat () const
 Encoder sample format after Open(), audio only.
Encoder tag
const StormByte::Safe::String & EncoderTag () const noexcept
 Writing-application tag stamped on every encoded stream.
Implementation
const StormByte::Safe::Optional< StormByte::Safe::String > & Implementation () const noexcept
 Pinned FFmpeg encoder name, if any.
void Implementation (StormByte::Safe::String name) noexcept
 Pins an FFmpeg encoder name.
const Features & Require () const noexcept
 Extra features the caller demands besides Frame HDR.
void Require (Features features) noexcept
 Replaces the extra feature mask (before open).
const Features & Capabilities () const noexcept
 Features of the row selected at open.
Rate and style
void CRF (double value) noexcept
 Constant quality (CRF/CQ).
const StormByte::Safe::Optional< double > & CRF () const noexcept
 CRF/CQ, if set.
void BitRate (std::int64_t bits_per_second) noexcept
 Target bitrate in bits per second.
const StormByte::Safe::Optional< std::int64_t > & BitRate () const noexcept
 Target bitrate, if set.
void MaxBitRate (std::int64_t bits_per_second) noexcept
 VBV ceiling in bits per second.
const StormByte::Safe::Optional< std::int64_t > & MaxBitRate () const noexcept
 VBV ceiling, if set.
void Preset (StormByte::Safe::String name) noexcept
 Encoder preset.
const StormByte::Safe::Optional< StormByte::Safe::String > & Preset () const noexcept
 Preset, if set.
void Tune (StormByte::Safe::String name) noexcept
 Content tune.
const StormByte::Safe::Optional< StormByte::Safe::String > & Tune () const noexcept
 Tune, if set.
FineTune
const StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > & FineTune () const noexcept
 Vendor leftovers.
void FineTune (StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > options) noexcept
 Replaces the vendor dict (before open).
Public Member Functions inherited from StormByte::Multimedia::Pipeline::Step
 Step (const Step &other)=delete
 Copy construction is disabled.
 Step (Step &&other) noexcept=delete
 Move construction is disabled.
virtual ~Step () noexcept
 Destructor.
Step & operator= (const Step &other)=delete
 Copy assignment is disabled.
Step & operator= (Step &&other) noexcept=delete
 Move assignment is disabled.
void Wake () noexcept
 Notifies all waiters of this step.
StormByte::Safe::Shared< class Plan > Plan () const noexcept
 Bound job intention, if any.
const Kinds & Receives () const noexcept
 Kinds this step consumes.
const Kinds & Produces () const noexcept
 Kinds this step emits.
State Status () const noexcept
 Current lifecycle value.
StormByte::Safe::Shared< const StageTelemetry > Telemetry () const
 Shared stage counters, retained independently of this Step.
StormByte::Buffer::QueueSnapshot QueueSnapshot (int track) const noexcept
 Reads effective queue limits and logical-byte accounting.
virtual bool Ready () const noexcept
 Whether this step can take work.
void Stop () noexcept
 Requests shutdown and notifies connected stages.
bool Failed () const noexcept
 Whether this step has failed.
StormByte::Safe::Optional< StormByte::Safe::String > Error () const
 Failure text.
void Fail (StormByte::Safe::String reason) noexcept
 Marks the stage as failed and notifies connected stages.
void Fail () noexcept
 Marks failure without storing a message or allocating.
STORMBYTE_FORCE_INLINE void Fail (const char *reason) noexcept
 Copies a null-terminated failure literal into Safe storage.
void Fail (std::string_view reason) noexcept
 Copies borrowed failure text before calling the DLL-safe overload.

Friends

class Backend::Pipeline::Encoder
 Allows the encode backend to wrap and emit encoded packets.
class Backend::Pipeline::Detail::Worker::Encode
 Allows the encode worker to access encoder internals.
class Muxer
 Allows the muxer to bind the encoded stream.

Additional Inherited Members

Protected Member Functions inherited from StormByte::Multimedia::Pipeline::Step
bool Connect (Step &downstream) noexcept
 Registers a borrowed downstream stage and shares any bound plan.
bool WaitPlan () noexcept
 Waits interruptibly for the shared plan to enter Running.
Backend::Pipeline::Pipe & pipe () noexcept
const Backend::Pipeline::Pipe & pipe () const noexcept
 Step (StormByte::Safe::Shared< StormByte::Logger::Log > log, enum Producer name, Kinds receives, Kinds produces)
 Constructs a stage in State::Created.
void Emit (Item::PointerType item) noexcept
 Sends item to connected consumers.
Item::PointerType CloneItem (const Item &item) const
 Creates a distinct item through Item::Clone.
virtual void Wait () noexcept
 Waits until input is available, the stage fails or stops, or WakeNow.
virtual bool WakeNow () const noexcept
 Extra reason to leave Wait.
virtual void AfterWait () noexcept
 Work on the waiting worker after Wait unblocks.
void Launch () noexcept
 Starts stage initialization and processing.
void Halt () noexcept
 Stops the stage and waits for execution to finish.
bool Stopping () const noexcept
 Worker must return (Stop, Halt or Fail).
void RecordWork (std::int64_t microseconds) noexcept
 Adds one Process duration to the step summary.
std::int64_t LastWork () const noexcept
 Duration of the last timed Process, or 0.
void DumpWork () noexcept
 Writes min/max Process time at Debug.
Backend::Pipeline::Host & Face () noexcept
void Mount (StormByte::Safe::Unique< Backend::Pipeline::Pumper > pumper, StormByte::Safe::Unique< Backend::Pipeline::Worker > worker)
Protected Attributes inherited from StormByte::Multimedia::Pipeline::Step
StormByte::Safe::Shared< StormByte::Logger::Log > m_log
 Scoped logger retained through Base-heap shared ownership.
enum Producer m_name
 UseLog leaf / default Label.
Kinds m_receives
 Receives.
Kinds m_produces
 Produces.

Detailed Description

Encodes frames of one output track into packets.

Encoder stage used to record settled track settings.

The bound Plan selects the destination codec. Logging identifies the selected encoder, and the supplied logger controls throttling.

Filters can analyze decoded pictures from the encoded output without changing the packets delivered to the muxer.

Constructor & Destructor Documentation

◆ Encoder() [1/3]

Encoder for output track output_index and destination codec.

Parameters
logShared logger. Empty pointer means no log.
output_indexMux destination order key.
codecRegistry codec. Must HasAccess(Write) at open.

◆ Encoder() [2/3]

Copy constructor.

Parameters
otherSource encoder.

◆ Encoder() [3/3]

Move constructor.

Parameters
otherEncoder to take.

◆ ~Encoder()

StormByte::Multimedia::Pipeline::Encoder::~Encoder ( )
overridenoexcept

Destructor.

Step::Join halts workers before backends die.

Member Function Documentation

◆ AudioChannels()

StormByte::Safe::Optional< int > StormByte::Multimedia::Pipeline::Encoder::AudioChannels ( ) const

Encoder channel count after Open(), audio only.

Returns
Channels, or empty if unavailable or result allocation fails.

◆ AudioFrameSize()

StormByte::Safe::Optional< int > StormByte::Multimedia::Pipeline::Encoder::AudioFrameSize ( ) const

Encoder frame_size after Open(), audio only.

Returns
Samples per packet, or empty if unavailable or result allocation fails.

◆ AudioSampleFormat()

StormByte::Safe::Optional< int > StormByte::Multimedia::Pipeline::Encoder::AudioSampleFormat ( ) const

Encoder sample format after Open(), audio only.

Returns
AVSampleFormat as int, or empty if unavailable or result allocation fails.

◆ AudioSampleRate()

StormByte::Safe::Optional< int > StormByte::Multimedia::Pipeline::Encoder::AudioSampleRate ( ) const

Encoder sample rate after Open(), audio only.

Returns
Hz, or empty if unavailable or result allocation fails.

◆ BitRate() [1/2]

const StormByte::Safe::Optional< std::int64_t > & StormByte::Multimedia::Pipeline::Encoder::BitRate ( ) const
inlinenoexcept

Target bitrate, if set.

Returns
Bits per second, or empty.

◆ BitRate() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::BitRate ( std::int64_t bits_per_second)
inlinenoexcept

Target bitrate in bits per second.

Incompatible with CRF.

Parameters
bits_per_secondBitrate.

◆ Capabilities()

const Features & StormByte::Multimedia::Pipeline::Encoder::Capabilities ( ) const
inlinenoexcept

Features of the row selected at open.

Empty if fallback.

Returns
Mask.

◆ CRF() [1/2]

const StormByte::Safe::Optional< double > & StormByte::Multimedia::Pipeline::Encoder::CRF ( ) const
inlinenoexcept

CRF/CQ, if set.

Returns
Value, or empty.

◆ CRF() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::CRF ( double value)
inlinenoexcept

Constant quality (CRF/CQ).

Incompatible with BitRate.

Parameters
valueEncoder quality value.

◆ Destination()

const Codec & StormByte::Multimedia::Pipeline::Encoder::Destination ( ) const
inlinenoexcept

Destination codec.

Returns
Registry codec bound at construction.

◆ EncoderTag()

const StormByte::Safe::String & StormByte::Multimedia::Pipeline::Encoder::EncoderTag ( ) const
inlinenoexcept

Writing-application tag stamped on every encoded stream.

Returns
StormByte-Multimedia version. Never empty after construction.

◆ FineTune() [1/2]

const StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > & StormByte::Multimedia::Pipeline::Encoder::FineTune ( ) const
inlinenoexcept

Vendor leftovers.

Not CRF/preset/tune/bufsize.

Returns
Key/value map.

◆ FineTune() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::FineTune ( StormByte::Safe::Map< StormByte::Safe::String, StormByte::Safe::String > options)
inlinenoexcept

Replaces the vendor dict (before open).

Parameters
optionsKey/value pairs.

◆ Implementation() [1/2]

const StormByte::Safe::Optional< StormByte::Safe::String > & StormByte::Multimedia::Pipeline::Encoder::Implementation ( ) const
inlinenoexcept

Pinned FFmpeg encoder name, if any.

Returns
Name, or empty.

◆ Implementation() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::Implementation ( StormByte::Safe::String name)
noexcept

Pins an FFmpeg encoder name.

Empty clears the pin.

Parameters
nameavcodec_find_encoder_by_name key.

◆ Index()

int StormByte::Multimedia::Pipeline::Encoder::Index ( ) const
inlinenoexcept

Mux destination order key.

Returns
Index set at construction.

◆ InputCeiling()

StormByte::Size StormByte::Multimedia::Pipeline::Encoder::InputCeiling ( ) const
overridevirtualnoexcept

Maximum number of queued input frames.

Returns
Frame limit, or 0 if no input queue exists.

Reimplemented from StormByte::Multimedia::Pipeline::Step.

◆ MaxBitRate() [1/2]

const StormByte::Safe::Optional< std::int64_t > & StormByte::Multimedia::Pipeline::Encoder::MaxBitRate ( ) const
inlinenoexcept

VBV ceiling, if set.

Returns
Bits per second, or empty.

◆ MaxBitRate() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::MaxBitRate ( std::int64_t bits_per_second)
inlinenoexcept

VBV ceiling in bits per second.

Parameters
bits_per_secondMax bitrate.

◆ Opened()

bool StormByte::Multimedia::Pipeline::Encoder::Opened ( ) const
noexcept

Whether encoder initialization has completed.

Returns
false before the first frame or after Fail().

◆ operator bool()

StormByte::Multimedia::Pipeline::Encoder::operator bool ( ) const
explicitnoexcept

true if the encoder is open and has not failed.

Returns
Open and not Failed.

◆ operator=() [1/2]

Encoder & StormByte::Multimedia::Pipeline::Encoder::operator= ( const Encoder & other)
delete

Copy assignment.

Parameters
otherSource encoder.
Returns
*this.

◆ operator=() [2/2]

Encoder & StormByte::Multimedia::Pipeline::Encoder::operator= ( Encoder && other)
deletenoexcept

Move assignment.

Parameters
otherEncoder to take.
Returns
*this.

◆ Preset() [1/2]

const StormByte::Safe::Optional< StormByte::Safe::String > & StormByte::Multimedia::Pipeline::Encoder::Preset ( ) const
inlinenoexcept

Preset, if set.

Returns
Name, or empty.

◆ Preset() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::Preset ( StormByte::Safe::String name)
noexcept

Encoder preset.

Parameters
namePreset name.

◆ Require() [1/2]

const Features & StormByte::Multimedia::Pipeline::Encoder::Require ( ) const
inlinenoexcept

Extra features the caller demands besides Frame HDR.

Returns
Mask.

◆ Require() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::Require ( Features features)
inlinenoexcept

Replaces the extra feature mask (before open).

Parameters
featuresRequired bits.

◆ Tune() [1/2]

const StormByte::Safe::Optional< StormByte::Safe::String > & StormByte::Multimedia::Pipeline::Encoder::Tune ( ) const
inlinenoexcept

Tune, if set.

Returns
Name, or empty.

◆ Tune() [2/2]

void StormByte::Multimedia::Pipeline::Encoder::Tune ( StormByte::Safe::String name)
noexcept

Content tune.

Parameters
nameTune name.

◆ Backend::Pipeline::Detail::Worker::Encode

friend class Backend::Pipeline::Detail::Worker::Encode
friend

Allows the encode worker to access encoder internals.

◆ Backend::Pipeline::Encoder

friend class Backend::Pipeline::Encoder
friend

Allows the encode backend to wrap and emit encoded packets.

◆ Muxer

friend class Muxer
friend

Allows the muxer to bind the encoded stream.


The documentation for this class was generated from the following file: