View Source Lifecycle of Membrane Components

The lifecycle of Membrane Components is closely related to the execution of Membrane callbacks within these components. While some differences exist among the lifecycles of Membrane Pipelines, Bins, and Elements, they share many similarities. Let's explore the component lifecycle and identify differences depending on the type of component being addressed.

Initialization

The first callback executed in every Membrane Component is handle_init/2. This function is executed synchronously and blocks the parent process (the process that spawns a pipeline or the parent component) until it is done and actions returned from it are handled. It is advisable to avoid heavy computations within this function. handle_init/2 is ideally used for spawning children in a Pipeline or Bin through the :spec action or parsing some options.

Setup

Following handle_init/2 is handle_setup/2, which is executed asynchronously (the parent process does not wait for its completion). This is an optimal time to set up resources or perform other intensive operations required for the component to function properly.

Note: By default, after handle_setup/2, a component's setup is considered complete. This behavior can be modified by returning setup: :incomplete from handle_setup/2. The component must then mark its setup as completed by returning setup: :complete from another callback, like handle_info/3, to enter :playing playback and go further in lifecycle.

Linking pads

For components with pads having availability: :on_request, the corresponding handle_pad_added/3 callbacks are called just after setup is completed, but only if they are linked in the same spec where the component was spawned. Linking a pad in a different spec from the one spawning the component may lead to handle_pad_added/3 being invoked after handle_playing/2.

Playing

Once the setup is completed and appropriate handle_pad_added/3 are invoked, a component can enter the :playing state by invoking the handle_playing/2 callback. Note that:

  • Components spawned within the same :spec always enter the :playing state simultaneously. If the setup of the one component lasts longer, the others will wait.
  • Elements and Bins wait for their parent to enter the playing state before executing handle_playing/2.

Processing the data (applies only to Elements)

After handle_playing/2, Elements are prepared to process the data flowing through their pads.

Events

Events are one type of data that can be sent via an Element's pads and are managed in handle_event/4. Events are the only items that can travel both upstream and downstream - all other types of data sent through pads have to follow the direction of the link.

Stream Formats

The stream format, which defines the type of data carried by Membrane.Buffers, must be declared before the first data buffer and is managed in handle_stream_format/4.

Start of Stream

Callback handle_start_of_stream/3 is invoked just before processing the first Membrane.Buffer from a specific input pad.

Buffers

The core of multimedia processing is handling Membrane.Buffers, which contain multimedia payload and may also include metadata or timestamps. Buffers are managed within the handle_buffer/4 callback.

Demands

If the Element has pads with flow_control: :manual, entering :playing playback allows it to send demand on input pads using :demand action or to receive the demand via output pads in handle_demand/5 callback.

After processing the data

When an Element determines that it will no longer send buffers from a specific pad, it can return :end_of_stream action to that pad. The linked element receives it in handle_end_of_stream/3. The parent component (either a Bin or Pipeline) is notified via handle_element_end_of_stream/4.

Terminating

Typically, the last callback executed within a Membrane Component is handle_terminate_request. By default, it returns a terminate: :normal action, terminating the component process with the reason :normal. This behavior can be modified by overriding the default implementation, but ensure to return a terminate: reason elsewhere to avoid termination issues in your Pipeline.

Some callbacks are not confined to specific stages of the Membrane Component lifecycle.

Handling parent or child notification

handle_parent_notification/3 and handle_child_notification/4 can occur at any point during the component's lifecycle and are tasked with managing notifications from a parent or child component, respectively.

Handling messages from non-Membrane Erlang Processes

The handle_info/3 callback is present in all Membrane Components and handle_call/3 in Membrane Pipelines. These can be triggered at any time while the component is alive, functioning similarly to their counterparts in GenServer.

Default implementations

If you are new to Membrane and you just read about some new callbacks that are not implemented in your Element or Pipeline, that was supposed to work fine - don't worry! We decided to provide default implementations for the majority of the callbacks (some of the exceptions are handle_buffer/4 or handle_demand/5), which in general is to do nothing or to do the most expected operation. For more details, visit the documentation of Membrane.Pipeline, Membrane.Bin and Membrane.Element.