Membrane Core v0.1.1 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

Type of user-managed state of element

Describes how pads should be declared in element

Functions

Macro that defines options that parametrize element

Callbacks

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

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 is supposed to start playing

Callback invoked when element is prepared. It receives the previous playback state (:stopped or :playing)

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

Callback invoked when element is supposed to stop

Returns module that manages this element

Used to determine if a module is membrane element

Link to this section Types

Type that defines all valid return values from most callbacks.

Link to this type internal_state_t() View Source
internal_state_t() :: map() | struct()

Type of user-managed state of element.

Link to this section Functions

Link to this macro def_options(options) View Source (macro)

Macro that defines options that parametrize element.

It automatically generates appropriate struct.

def_options/1 should receive keyword list, where each key is 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] 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
  • description: string describing an option. It will be present in value returned by options/0 and in typedoc for the struct.

Link to this section Callbacks

Link to this callback handle_event(pad, event, context, state) View Source
handle_event(
  pad :: Membrane.Element.Pad.name_t(),
  event :: Event.type_t(),
  context :: Membrane.Element.Context.Event.t(),
  state :: internal_state_t()
) :: callback_return_t()

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.

Link to this callback handle_init(options) View Source
handle_init(options :: Membrane.Element.element_options_t()) ::
  {:ok, internal_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, state) View Source
handle_other(message :: any(), state :: internal_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
handle_pad_added(
  pad :: Membrane.Element.Pad.name_t(),
  context :: Membrane.Element.Context.PadAdded.t(),
  state :: internal_state_t()
) :: callback_return_t()

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
handle_pad_removed(
  pad :: Membrane.Element.Pad.name_t(),
  context :: Membrane.Element.Context.PadRemoved.t(),
  state :: internal_state_t()
) :: callback_return_t()

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

Link to this callback handle_play(state) View Source
handle_play(state :: internal_state_t()) :: callback_return_t()

Callback invoked when element is supposed to start 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_prepare(previous_playback_state, state) View Source
handle_prepare(
  previous_playback_state :: Membrane.Mixins.Playback.state_t(),
  state :: internal_state_t()
) :: callback_return_t()

Callback invoked when element is prepared. It receives the previous playback state (:stopped or :playing).

If the prevoius playback state is :stopped, then 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_stop/1.

If the previous playback state is :playing, then all resources allocated in handle_play/1 callback should be released here, and no more buffers or demands should be sent.

Link to this callback handle_shutdown(state) View Source
handle_shutdown(state :: internal_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_stop(state) View Source
handle_stop(state :: internal_state_t()) :: callback_return_t()

Callback invoked when element is supposed to stop.

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

Link to this callback manager_module() View Source
manager_module() :: module()

Returns module that manages this element.

Link to this callback membrane_element?() View Source
membrane_element?() :: true

Used to determine if a module is membrane element.