Membrane.Element.Base behaviour (Membrane Core v0.7.0) View Source

Module defining behaviour common to all elements.

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

Elements

Elements are units that produce, process or consume data. They can be linked with Membrane.Pipeline, and thus form a pipeline able to perform complex data processing. Each element defines a set of pads, through which it can be linked with other elements. During playback, pads can either send (output pads) or receive (input pads) data. For more information on pads, see Membrane.Pad.

To implement an element, one of base modules (Membrane.Source, Membrane.Filter, Membrane.Sink) has to be used, depending on the element type:

  • source, producing buffers (contain only output pads),
  • filter, processing buffers (contain both input and output pads),
  • sink, consuming buffers (contain only input pads). For more information on each element type, check documentation for appropriate base module.

Behaviours

Element-specific behaviours are specified in modules:

Callbacks

Modules listed above provide specifications of callbacks that define elements lifecycle. All of these callbacks have names with the handle_ prefix. They are used to define reaction to certain events that happen during runtime, and indicate what actions framework should undertake as a result, besides executing element-specific code.

For actions that can be returned by each callback, see Membrane.Element.Action module.

Link to this section Summary

Types

Type that defines all valid return values from most callbacks.

Functions

Brings common stuff needed to implement an element. Used by Membrane.Source.__using__/1, Membrane.Filter.__using__/1 and Membrane.Sink.__using__/1.

Defines that element exports a clock to pipeline.

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.terminate/2 callback.

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

Callback invoked upon each timer tick. A timer can be started with Membrane.Element.Action.start_timer_t action.

Automatically implemented callback used to determine whether element exports clock.

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

Specs

callback_return_t() ::
  {:ok | {:ok, [Membrane.Element.Action.t()]} | {:error, any()},
   Membrane.Element.state_t()}
  | {:error, any()}

Type that defines all valid return values from most callbacks.

In case of error, a callback is supposed to return {:error, any} if it is not passed state, and {{:error, any}, state} otherwise.

Link to this section Functions

Link to this macro

__using__(options)

View Source (macro)

Brings common stuff needed to implement an element. Used by Membrane.Source.__using__/1, Membrane.Filter.__using__/1 and Membrane.Sink.__using__/1.

Options:

  • :bring_pad? - if true (default) requires and aliases Membrane.Pad
Link to this macro

def_clock(doc \\ "")

View Source (macro)

Defines that element exports a clock to pipeline.

Exporting clock allows pipeline to choose it as the pipeline clock, enabling other elements to synchronize with it. Element's clock is accessible via clock field, while pipeline's one - via parent_clock field in callback contexts. Both of them can be used for starting timers.

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 (optional)

Specs

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 (optional)

Specs

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 (optional)

Specs

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 (optional)

Specs

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 (optional)

Specs

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 (optional)

Specs

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 (optional)

Specs

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 (optional)

Specs

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(reason, state)

View Source (optional)

Specs

handle_shutdown(reason, state :: Membrane.Element.state_t()) :: :ok
when reason: :normal | :shutdown | {:shutdown, any()} | term()

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

Link to this callback

handle_stopped_to_prepared(context, state)

View Source (optional)

Specs

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

handle_stopped_to_terminating(context, state)

View Source

Specs

handle_stopped_to_terminating(
  context :: Membrane.Element.CallbackContext.PlaybackChange.t(),
  state :: Membrane.Element.state_t()
) :: callback_return_t()
Link to this callback

handle_tick(timer_id, context, state)

View Source (optional)

Specs

handle_tick(
  timer_id :: any(),
  context :: Membrane.Element.CallbackContext.Tick.t(),
  state :: Membrane.Element.state_t()
) :: callback_return_t()

Callback invoked upon each timer tick. A timer can be started with Membrane.Element.Action.start_timer_t action.

Link to this callback

membrane_clock?()

View Source (optional)

Specs

membrane_clock?() :: true

Automatically implemented callback used to determine whether element exports clock.

Specs

membrane_element?() :: true

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

Specs

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

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

Specs

membrane_pads() :: [{Membrane.Pad.name_t(), Membrane.Pad.description_t()}]

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

Generated by Membrane.Element.WithInputPads.def_input_pad/2 and Membrane..WithOutputPads.def_output_pad/2 macros.