Membrane.AV1.Encoder (Membrane AV1 plugin v0.1.0)

View Source

AV1 Encoder based on SVT-AV1 library. It expects each buffer to contain a single raw frame.

The encoder supports stream formats changing resolution on the fly when the following conditions are met:

  • New resolution is not greater than the previous one.
  • Low-Delay mode is set (see option :prediction_structure).
  • New luma width and height are not smaller than 64.
  • :intra_refresh_type is set to :closed_gop.

Keyframes can be forced with Membrane.KeyframeRequestEvent.t/0 events when :intra_refresh_type option is set to :closed_gop and :rate_control is not VBR.

Element options

Passed via struct Membrane.AV1.Encoder.t/0

  • encoder_mode 

    0..13

    Default value: 8
    Encoder preset. Higher values increase encoding speed and decrease quality. For more details see https://gitlab.com/AOMediaCodec/SVT-AV1/-/blob/master/Docs/CommonQuestions.md#what-presets-do

  • real_time_coding 

    boolean()

    Default value: false
    Applies a set of speed and latency optimizations, so that the stream is more suitable for real-time applications. Forces :low_delay value for :prediction_structure option. It's intended to be used with CBR rate control (see :rate_control option).

  • rate_control 

    rate_control()

    Default value: {:crf, 35}
    Rate control mode used by the encoder:

    • CQP (Constant Quantization Parameter) - The same quantization parameter (which controls the compression level) is used for each frame. Higher values mean higher compression.
    • CRF (Constant Rate Factor) - Quantization parameter is adjusted for each frame to maintain a certain level of perceived quality. Higher values mean higher compression.
    • CBR (Constant Bit Rate) - Provided bitrate is maintained for each frame for the whole stream. Suitable for live-streaming. :prediction_structure option MUST be set to :low_delay.
    • VBR (Variable Bit Rate) - The encoder will aim to produce a stream with the average bitrate of the provided value, varying the size of the output depending on the complexity of the input. This mode prohibits forcing keyframes.

  • prediction_structure 

    prediction_structure()

    Default value: :random_access
    Prediction structure used when encoding the stream:

    • :all_intra - Every frame is an intra frame.
    • :low_delay - Frames can only reference previous frames. Additionally no frames are buffered, each input frame will result in an encoded output frame. Forced for real time coding.
    • :random_access - B-frames are allowed.

  • intra_refresh_type 

    intra_refresh_type()

    Default value: :closed_gop
    Determines whether the encoder produces open or closed GOPs and what type of intra-frame is inserted at their boundaries:

    • :closed_gop - the encoder produces IDR (Instantaneous Decoder Refresh) frames. Frames belonging to its GOP can only reference frames also belonging to the same GOP. An IDR also fully resets the decoder state, which allows a decoder to start decoding up from this point.
    • :open_gop - the encoder produces CRA (Clean Random Access) frames. Frames belonging to its GOP can reference frames from other GOPs, which can lead to better compression.

    To allow the encoder to force keyframes, this option has to be set to :closed_gop, so that it's guaranteed that the stream is fully decodable up from this point. Forcing keyframes is not allowed when :rate_control option is in VBR mode, even if this option is set to :closed_gop.

  • level 

    AV1.level() | :auto

    Default value: :auto
    Determines the level of the encoded stream. If not provided, it will be automatically detected from the input stream.

  • approx_framerate 

    AV1.framerate() | nil

    Default value: nil
    Used by the encoder for computations regarding bitrate and intra periods. If not provided here, value from stream format is assumed. If not present there too, a default fallback value of {30, 1} is assumed.

  • config_parameters 

    %{String.t() => String.t()}

    Default value: %{}
    Parameters accepted by SVT-AV1 encoder. They override parameters set by other options. For possible values refer to https://gitlab.com/AOMediaCodec/SVT-AV1/-/blob/master/Docs/Parameters.md ("Command line" column, without leading dashes).

Pads

:input

Accepted formats:

%Membrane.RawVideo{pixel_format: :I420, aligned: true}
Direction::input
Availability::always
Flow control::auto

:output

Accepted formats:

AV1
Direction::output
Availability::always
Flow control::auto

Summary

Types

intra_refresh_type()
prediction_structure()
rate_control()
t()

Struct containing options for Membrane.AV1.Encoder

Functions

options()

Returns description of options available for this module

Types

intra_refresh_type()

@type intra_refresh_type() :: :closed_gop | :open_gop

prediction_structure()

@type prediction_structure() :: :all_intra | :low_delay | :random_access

rate_control()

@type rate_control() ::
  {:cqp | :crf, quantization_parameter :: 0..63}
  | {:cbr | :vbr, target_bitrate :: non_neg_integer()}

t()

@type t() :: %Membrane.AV1.Encoder{
  approx_framerate: Membrane.AV1.framerate() | nil,
  config_parameters: %{required(String.t()) => String.t()},
  encoder_mode: 0..13,
  intra_refresh_type: intra_refresh_type(),
  level: Membrane.AV1.level() | :auto,
  prediction_structure: prediction_structure(),
  rate_control: rate_control(),
  real_time_coding: boolean()
}

Struct containing options for Membrane.AV1.Encoder

Functions

options()

@spec options() :: keyword()

Returns description of options available for this module