Membrane Core v0.3.2 Membrane.Element.Base.Mixin.CommonBehaviour behaviour View Source

Module defining behaviour common to all elements.

When used declares behaviour implementation, provides default callback definitions and imports macros.

For more information on implementing elements, see Membrane.Element.Base.

Link to this section Summary

Types

Type that defines all valid return values from most callbacks.

Functions

Macro defining options that parametrize element.

Callbacks

Callback that is called when event arrives.

Callback invoked on initialization of element process. It should parse options and initialize element internal state. Internally it is invoked inside GenServer.init/1 callback.

Callback invoked when element receives a message that is not recognized as an internal membrane message.

Callback that is called when new pad has beed added to element. Executed ONLY for dynamic pads.

Callback that is called when some pad of the element has beed removed. Executed ONLY for dynamic pads.

Callback invoked when element goes to :prepared state from state :playing and should get ready to enter :stopped state.

Callback invoked when element is supposed to start playing (goes from state :prepared to :playing).

Callback invoked when element is supposed to stop (goes from state :prepared to :stopped).

Callback invoked when element is shutting down just before process is exiting. Internally called in GenServer.termintate/2 callback.

Callback invoked when element goes to :prepared state from state :stopped and should get ready to enter :playing state.

Automatically implemented callback used to determine if module is a membrane element.

Automatically implemented callback determining whether element is a source, a filter or a sink.

Automatically implemented callback returning specification of pads exported by the element.

Link to this section Types

Link to this type

callback_return_t()

View Source
callback_return_t() ::
  Membrane.Core.CallbackHandler.callback_return_t(
    Membrane.Element.Action.t(),
    Membrane.Element.state_t()
  )

Type that defines all valid return values from most callbacks.

Link to this section Functions

Link to this macro

def_options(options)

View Source (macro)

Macro defining options that parametrize element.

It automatically generates appropriate struct and documentation.

Options are defined by a keyword list, where each key is an option name and is described by another keyword list with following fields:

  • type: atom, used for parsing
  • spec: typespec for value in struct. If ommitted, for types: [:atom, :boolean, :caps, :keyword, :string, :struct, :time] the default typespec is provided, for others typespec is set to any/0
  • default: default value for option. If not present, value for this option will have to be provided each time options struct is created
  • inspector: function converting fields' value to a string. Used when creating documentation instead of inspect/1
  • description: string describing an option. It will be used for generating the docs

Link to this section Callbacks

Link to this callback

handle_event(pad, event, context, state)

View Source

Callback that is called when event arrives.

Events may arrive from both sinks and sources. In filters by default event is forwarded to all sources or sinks, respectively. If event is either Membrane.Event.StartOfStream or Membrane.Event.EndOfStream, notification is sent, to notify the pipeline that data processing is started or finished. This behaviour can be overriden, e.g. by sending end of stream notification after elements internal buffers become empty.

Link to this callback

handle_init(options)

View Source
handle_init(options :: Membrane.Element.options_t()) ::
  {:ok, Membrane.Element.state_t()} | {:error, any()}

Callback invoked on initialization of element process. It should parse options and initialize element internal state. Internally it is invoked inside GenServer.init/1 callback.

Link to this callback

handle_other(message, context, state)

View Source
handle_other(
  message :: any(),
  context :: Membrane.Element.CallbackContext.Other.t(),
  state :: Membrane.Element.state_t()
) :: callback_return_t()

Callback invoked when element receives a message that is not recognized as an internal membrane message.

Useful for receiving ticks from timer, data sent from NIFs or other stuff.

Link to this callback

handle_pad_added(pad, context, state)

View Source

Callback that is called when new pad has beed added to element. Executed ONLY for dynamic pads.

Link to this callback

handle_pad_removed(pad, context, state)

View Source

Callback that is called when some pad of the element has beed removed. Executed ONLY for dynamic pads.

Link to this callback

handle_playing_to_prepared(context, state)

View Source
handle_playing_to_prepared(
  context :: Membrane.Element.CallbackContext.PlaybackChange.t(),
  state :: Membrane.Element.state_t()
) :: callback_return_t()

Callback invoked when element goes to :prepared state from state :playing and should get ready to enter :stopped state.

All resources allocated in handle_prepared_to_playing/2 callback should be released here, and no more buffers or demands should be sent.

Link to this callback

handle_prepared_to_playing(context, state)

View Source
handle_prepared_to_playing(
  context :: Membrane.Element.CallbackContext.PlaybackChange.t(),
  state :: Membrane.Element.state_t()
) :: callback_return_t()

Callback invoked when element is supposed to start playing (goes from state :prepared to :playing).

This is moment when initial demands are sent and first buffers are generated if there are any pads in the push mode.

Link to this callback

handle_prepared_to_stopped(context, state)

View Source
handle_prepared_to_stopped(
  context :: Membrane.Element.CallbackContext.PlaybackChange.t(),
  state :: Membrane.Element.state_t()
) :: callback_return_t()

Callback invoked when element is supposed to stop (goes from state :prepared to :stopped).

Usually this is the place for releasing all remaining resources used by the element. For example, if element opens a file in handle_stopped_to_prepared/2, this is the place to close it.

Link to this callback

handle_shutdown(state)

View Source
handle_shutdown(state :: Membrane.Element.state_t()) :: :ok

Callback invoked when element is shutting down just before process is exiting. Internally called in GenServer.termintate/2 callback.

Link to this callback

handle_stopped_to_prepared(context, state)

View Source
handle_stopped_to_prepared(
  context :: Membrane.Element.CallbackContext.PlaybackChange.t(),
  state :: Membrane.Element.state_t()
) :: callback_return_t()

Callback invoked when element goes to :prepared state from state :stopped and should get ready to enter :playing state.

Usually most resources used by the element are allocated here. For example, if element opens a file, this is the place to try to actually open it and return error if that has failed. Such resources should be released in handle_prepared_to_stopped/2.

Link to this callback

membrane_element?()

View Source
membrane_element?() :: true

Automatically implemented callback used to determine if module is a membrane element.

Link to this callback

membrane_element_type()

View Source
membrane_element_type() :: Membrane.Element.type_t()

Automatically implemented callback determining whether element is a source, a filter or a sink.

Automatically implemented callback returning specification of pads exported by the element.

Generated by Membrane.Element.Base.Mixin.SinkBehaviour.def_input_pad/2 and Membrane.Element.Base.Mixin.SourceBehaviour.def_output_pad/2 macros.