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:
Membrane.Element.Base- this module, behaviour common to all elements,Membrane.Element.WithOutputPads- behaviour common to sources and filters,Membrane.Element.WithInputPads- behaviour common to sinks and filters,- Base modules (
Membrane.Source,Membrane.Filter,Membrane.Sink) - behaviours specific to each element type.
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
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 aliasesMembrane.Pad
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.
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 parsingspec: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 toany/0default:default value for option. If not present, value for this option will have to be provided each time options struct is createdinspector:function converting fields' value to a string. Used when creating documentation instead ofinspect/1description:string describing an option. It will be used for generating the docs
Link to this section Callbacks
Specs
handle_event( pad :: Membrane.Pad.ref_t(), event :: Membrane.Event.t(), context :: Membrane.Element.CallbackContext.Event.t(), state :: Membrane.Element.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.
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.
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.
Specs
handle_pad_added( pad :: Membrane.Pad.ref_t(), context :: Membrane.Element.CallbackContext.PadAdded.t(), state :: Membrane.Element.state_t() ) :: callback_return_t()
Callback that is called when new pad has beed added to element. Executed ONLY for dynamic pads.
Specs
handle_pad_removed( pad :: Membrane.Pad.ref_t(), context :: Membrane.Element.CallbackContext.PadRemoved.t(), state :: Membrane.Element.state_t() ) :: callback_return_t()
Callback that is called when some pad of the element has beed removed. Executed ONLY for dynamic pads.
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.
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.
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.
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.
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.
Specs
handle_stopped_to_terminating( context :: Membrane.Element.CallbackContext.PlaybackChange.t(), state :: Membrane.Element.state_t() ) :: callback_return_t()
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.
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.