Membrane.Transcoder (Membrane Transcoder plugin v0.3.4)

Copy Markdown View Source

Provides transcoding capabilities for audio and video streams in Membrane.

The bin takes an incoming stream on its input and converts it into the desired one as specified by the option. Transcoding is applied only if it is neccessary. The following video stream formats are supported:

The following audio stream formats are supported:

While Membrane.Transcoder can transcode between different stream formats, it can also be used to change some parameters of the stream format. Now, the only supported stream parameters are:

When the membrane_vk_video_plugin dependency is present and Vulkan hardware is available, H.264 encode/decode can be offloaded to the GPU by setting native_acceleration: :if_available.

Bin options

Passed via struct Membrane.Transcoder.t/0

  • output_stream_format 

    stream_format() | stream_format_module() | stream_format_tuple() | stream_format_resolver()

    Required
    An option specifying desired output format.

    Can be either:

    • a struct being a Membrane stream format,
    • a module in which Membrane stream format struct is defined,
    • a function which receives input stream format as an input argument and is supposed to return the desired output stream format or its module.

  • transcoding_policy 

    :always | :if_needed | :never | (stream_format() -> :always | :if_needed | :never)

    Default value: :if_needed
    Specifies, when transcoding should be applied.

    Can be either:

    • an atom: :always, :if_needed (default) or :never,
    • a function that receives the input stream format and returns either :always, :if_needed or :never.

    If set to :always, the input media stream will be decoded and encoded, even if the input stream format and the output stream format are the same type.

    If set to :if_needed, the input media stream will be transcoded only if the input stream format and the output stream format are different types. This is the default behavior.

    If set to :never, the input media stream won't be neither decoded nor encoded. Changing alignment, encapsulation or stream structure is still possible. This option is helpful when you want to ensure that Membrane.Transcoder will not use too much of resources, e.g. CPU or memory.

    If the transition from the input stream format to the output stream format is not possible without decoding or encoding the stream, an error will be raised.

  • assumed_input_stream_format 

    struct() | nil

    Default value: nil
    Allows to override stream format of the input stream.

    Overriding will fail, the stream format sent on the Membrane.Transcoder's input pad is not Membrane.RemoteStream

    If nil or not set, the input stream format won't be overriden.

  • native_acceleration 

    :never | :if_available

    Default value: :never
    Specifies whether to use Vulkan hardware acceleration for video transcoding.

    Can be:

    • :never - Always use software-based transcoding (default)
    • :if_available - Use Vulkan acceleration when available on the system

Pads

:input

Accepted formats:

format
when Audio.is_audio_format(format) or Video.is_video_format(format) or
       format.__struct__ == RemoteStream
Direction::input
Availability::always

:output

Accepted formats:

format when Audio.is_audio_format(format) or Video.is_video_format(format)
Direction::output
Availability::always

Summary

Types

stream_format()

Describes stream formats acceptable on the bin's input and output.

stream_format_module()

Describes stream format modules that can be used to define inputs and outputs of the bin.

stream_format_resolver()

Describes a function which can be used to provide output format based on the input format.

stream_format_tuple()

Describes a tuple consisting of a stream format module and its options.

t()

Struct containing options for Membrane.Transcoder

Functions

options()

Returns description of options available for this module

vulkan_available?()

Returns true if the optional membrane_vk_video_plugin dependency is installed and its modules can be loaded in the current runtime.

Types

stream_format()

@type stream_format() ::
  Membrane.H264.t()
  | Membrane.H265.t()
  | Membrane.VP8.t()
  | Membrane.VP9.t()
  | Membrane.RawVideo.t()
  | Membrane.AAC.t()
  | Membrane.Opus.t()
  | Membrane.MPEGAudio.t()
  | Membrane.RemoteStream.t()
  | Membrane.RawAudio.t()

Describes stream formats acceptable on the bin's input and output.

stream_format_module()

@type stream_format_module() ::
  Membrane.H264
  | Membrane.H265
  | Membrane.VP8
  | Membrane.VP9
  | Membrane.RawVideo
  | Membrane.AAC
  | Membrane.Opus
  | Membrane.MPEGAudio
  | Membrane.RawAudio

Describes stream format modules that can be used to define inputs and outputs of the bin.

stream_format_resolver()

@type stream_format_resolver() :: (stream_format() ->
                               stream_format() | stream_format_module())

Describes a function which can be used to provide output format based on the input format.

stream_format_tuple()

@type stream_format_tuple() :: {stream_format_module(), keyword()}

Describes a tuple consisting of a stream format module and its options.

An alternative to Membrane.Transcoder.stream_format/0.

Allows you to specify some fields of the output stream format, without the need to set all keys required by the struct.

t()

@type t() :: %Membrane.Transcoder{
  assumed_input_stream_format: struct() | nil,
  native_acceleration: :never | :if_available,
  output_stream_format:
    stream_format()
    | stream_format_module()
    | stream_format_tuple()
    | stream_format_resolver(),
  transcoding_policy:
    :always
    | :if_needed
    | :never
    | (stream_format() -> :always | :if_needed | :never)
}

Struct containing options for Membrane.Transcoder

Functions

options()

@spec options() :: keyword()

Returns description of options available for this module

vulkan_available?()

@spec vulkan_available?() :: boolean()

Returns true if the optional membrane_vk_video_plugin dependency is installed and its modules can be loaded in the current runtime.

Note: a true result only confirms the plugin is loadable - it does not guarantee that the host actually exposes Vulkan Video extensions with H.264 encode/decode capabilities. The underlying plugin may still fail at runtime if the GPU/driver does not support them.