Membrane Core v1.1.2

View Source Membrane.Element.Base behaviour (Membrane Core v1.1.2)

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.

Note: This module (Membrane.Element.Base) should not be used directly.

To implement an element, one of the following base modules (Membrane.Source, Membrane.Filter, Membrane.Endpoint or 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),
  • endpoint, producing and consuming 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.

Link to this section Summary

Callbacks

__struct__()

A callback for constructing struct. Will be defined by def_options/1 if used.

__struct__(kv)

A callback for constructing struct with values. Will be defined by def_options/1 if used.

handle_event(pad, event, context, state)

Callback that is called when event arrives.

handle_info(message, context, state)

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

handle_init(context, options)

Callback invoked on initialization of element.

handle_pad_added(pad, context, state)

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

handle_pad_removed(pad, context, state)

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

handle_parent_notification(notification, context, state)

Callback invoked when a message from the parent is received. By default, it ignores the received message.

handle_playing(context, state)

Callback invoked when bin switches the playback to :playing.

handle_setup(context, state)

Callback invoked on element startup, right after handle_init/2.

handle_terminate_request(context, state)

Callback invoked when element is removed by its parent.

handle_tick(timer_id, context, state)

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

Functions

__using__(options)

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

def_clock(doc \\ "")

Defines that element exports a clock to pipeline.

def_options(options)

Macro defining options that parametrize element.

Link to this section Callbacks

Link to this callback

__struct__()

View Source (optional) 
@callback __struct__() :: struct()

A callback for constructing struct. Will be defined by def_options/1 if used.

See defstruct/1 for a more in-depth description.

Link to this callback

__struct__(kv)

View Source (optional) 
@callback __struct__(kv :: [atom() | {atom(), any()}]) :: struct()

A callback for constructing struct with values. Will be defined by def_options/1 if used.

See defstruct/1 for a more in-depth description.

Link to this callback

handle_event(pad, event, context, state)

View Source (optional) 
@callback handle_event(
  pad :: Membrane.Pad.ref(),
  event :: Membrane.Event.t(),
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
   ], Membrane.Element.state()}

Callback that is called when event arrives.

Events may arrive from both input and output pads. In filters by default event is forwarded to all output and input pads, respectively. By default, it ignores received event.

Link to this callback

handle_info(message, context, state)

View Source (optional) 
@callback handle_info(
  message :: any(),
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
     | Membrane.Element.Action.setup()
   ], Membrane.Element.state()}

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. By default, it logs and ignores the received message.

Link to this callback

handle_init(context, options)

View Source (optional) 
@callback handle_init(
  context :: Membrane.Element.CallbackContext.t(),
  options :: Membrane.Element.options()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.latency()
   ], Membrane.Element.state()}

Callback invoked on initialization of element.

This callback is synchronous: the parent waits until it finishes. Also, any failures that happen in this callback crash the parent as well, regardless of crash groups. For these reasons, it's important to do any long-lasting or complex work in handle_setup/2, while handle_init should be used for things like parsing options or initializing state. By default, it converts the opts struct to a map and sets them as the element's state.

Link to this callback

handle_pad_added(pad, context, state)

View Source (optional) 
@callback handle_pad_added(
  pad :: Membrane.Pad.ref(),
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
     | Membrane.Element.Action.setup()
   ], Membrane.Element.state()}

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

Context passed to this callback contains additional field :pad_options. By default, it does nothing.

Link to this callback

handle_pad_removed(pad, context, state)

View Source (optional) 
@callback handle_pad_removed(
  pad :: Membrane.Pad.ref(),
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
     | Membrane.Element.Action.setup()
   ], Membrane.Element.state()}

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

Context passed to this callback contains additional field :pad_options. By default, it does nothing.

Link to this callback

handle_parent_notification(notification, context, state)

View Source (optional) 
@callback handle_parent_notification(
  notification :: Membrane.ParentNotification.t(),
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
     | Membrane.Element.Action.setup()
   ], Membrane.Element.state()}

Callback invoked when a message from the parent is received. By default, it ignores the received message.

Link to this callback

handle_playing(context, state)

View Source (optional) 
@callback handle_playing(
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
   ], Membrane.Element.state()}

Callback invoked when bin switches the playback to :playing.

From this point, element can send and receive buffers, events, stream formats and demands through its pads. By default, it does nothing.

Link to this callback

handle_setup(context, state)

View Source (optional) 
@callback handle_setup(
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[Membrane.Element.Action.common_actions() | Membrane.Element.Action.setup()],
   Membrane.Element.state()}

Callback invoked on element startup, right after handle_init/2.

Any long-lasting or complex initialization should happen here. By default, it does nothing.

Link to this callback

handle_terminate_request(context, state)

View Source 
@callback handle_terminate_request(
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
     | Membrane.Element.Action.setup()
   ], Membrane.Element.state()}

Callback invoked when element is removed by its parent.

By default, it returns Membrane.Element.Action.terminate/0 with reason :normal.

Link to this callback

handle_tick(timer_id, context, state)

View Source (optional) 
@callback handle_tick(
  timer_id :: any(),
  context :: Membrane.Element.CallbackContext.t(),
  state :: Membrane.Element.state()
) ::
  {[
     Membrane.Element.Action.common_actions()
     | Membrane.Element.Action.stream_actions()
     | Membrane.Element.Action.setup()
   ], Membrane.Element.state()}

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

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, Membrane.Endpoint.__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:

  • spec: typespec for value in struct
  • 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, eg. inspector: &Membrane.Time.inspect/1
  • description: string describing an option. It will be used for generating the docs