Membrane Core v0.1.1 Membrane.Element.Action View Source

This module contains type specifications of actions that can be returned from element callbacks.

Returning actions is a way of element interaction with other elements and parts of framework. Each action may be returned by any callback (except for c:Membrane.Element.Base.Mixin.CommonBehaviour.handle_init and c:Membrane.Element.Base.Mixin.CommonBehaviour.handle_terminate, as they do not return any actions) unless explicitly stated otherwise.

Link to this section Summary

Types

Sends buffers through a pad (it must be source pad)

Sends caps through a pad (it must be source pad). Sended caps must fit constraints on the pad

Makes a demand on a pad (it must be sink pad in pull mode). It does NOT entail sending demand through the pad, but just requesting some amount of data from Membrane.PullBuffer, which sends demands automatically when it runs out of data. If there is any data available at the pad, the data is passed to Membrane.Element.Base.Filter.handle_process/4 or Membrane.Element.Base.Sink.handle_write/4 callback. Invoked callback is guaranteed not to receive more data than demanded

Sends an event through a pad (sink or source)

Sends buffers/caps/event to all source pads of element (or to sink pads when event occurs on the source pad). Used by default implementations of Membrane.Element.Base.Mixin.SinkBehaviour.handle_caps/4 and Membrane.Element.Base.Mixin.CommonBehaviour.handle_event/4 callbacks in filter

Sends a message to the pipeline

Suspends/resumes change of playback state

Executes Membrane.Element.Base.Mixin.SourceBehaviour.handle_demand/5 callback with given pad (which must be a source pad in pull mode) if this demand is greater than 0

Allows to split callback execution into multiple applications of another callback (called from now sub-callback)

t()

Type that defines a single action that may be returned from element callbacks. Depending on element type, callback, current playback state and other circumstances there may be different actions available

Link to this section Types

Link to this type buffer_t() View Source
buffer_t() :: {:buffer, {Pad.name_t(), Buffer.t() | [Buffer.t()]}}

Sends buffers through a pad (it must be source pad).

Allowed only when playback state is playing.

Link to this type caps_t() View Source
caps_t() :: {:caps, {Pad.name_t(), Caps.t()}}

Sends caps through a pad (it must be source pad). Sended caps must fit constraints on the pad.

Forbidden when playback state is stopped.

Link to this type demand_common_payload_t() View Source
demand_common_payload_t() ::
  Pad.name_t() | {Pad.name_t(), size :: non_neg_integer()}
Link to this type demand_filter_payload_t() View Source
demand_filter_payload_t() ::
  {Pad.name_t(), {:source, Pad.name_t()} | :self,
   size :: non_neg_integer() | {:set_to, size :: non_neg_integer()}}
Link to this type demand_sink_payload_t() View Source
demand_sink_payload_t() :: {Pad.name_t(), {:set_to, size :: non_neg_integer()}}

Makes a demand on a pad (it must be sink pad in pull mode). It does NOT entail sending demand through the pad, but just requesting some amount of data from Membrane.PullBuffer, which sends demands automatically when it runs out of data. If there is any data available at the pad, the data is passed to Membrane.Element.Base.Filter.handle_process/4 or Membrane.Element.Base.Sink.handle_write/4 callback. Invoked callback is guaranteed not to receive more data than demanded.

Depending on element type and callback, it may contain different payloads or behave differently:

In sinks:

  • Payload {pad, size} increases demand on given pad by given size.
  • Payload {pad, {:set_to, size}} erases current demand and sets it to given size.

In filters:

  • Payload {pad, size} is only allowed from Membrane.Element.Base.Mixin.SourceBehaviour.handle_demand/5 callback. It overrides current demand.
  • Payload {pad, {{:source, demanding_source_pad}, size}} can be returned from any callback. demanding_source_pad is a pad which is to receive demanded buffers after they are processed.
  • Payload {pad, :self, size} makes demand act as if element was a sink, that is extends demand on a given pad. Buffers received as a result of the demand should be consumed by element itself or sent through a pad in push mode.
  • Payload {pad, :self, {:set_to, size}} do almost the same as the previous one, but it sets a demand on a given pad (not extends the previous demand).

Allowed only when playback state is playing.

Link to this type event_t() View Source
event_t() :: {:event, {Pad.name_t(), Event.t()}}

Sends an event through a pad (sink or source).

Forbidden when playback state is stopped.

Link to this type forward_t() View Source
forward_t() :: {:forward, Buffer.t() | [Buffer.t()] | Caps.t() | Event.t()}

Sends buffers/caps/event to all source pads of element (or to sink pads when event occurs on the source pad). Used by default implementations of Membrane.Element.Base.Mixin.SinkBehaviour.handle_caps/4 and Membrane.Element.Base.Mixin.CommonBehaviour.handle_event/4 callbacks in filter.

Allowed only when all below conditions are met:

Keep in mind that Membrane.Element.Base.Filter.handle_process/4 can only forward buffers, Membrane.Element.Base.Mixin.SinkBehaviour.handle_caps/4 - caps and Membrane.Element.Base.Mixin.CommonBehaviour.handle_event/4 - events.

Link to this type message_t() View Source
message_t() :: {:message, Message.t()}

Sends a message to the pipeline.

Link to this type playback_change_t() View Source
playback_change_t() :: {:playback_change, :suspend | :resume}

Suspends/resumes change of playback state.

There is no straight limit how long playback change can take, but keep in mind that it may affect application quality if not done quick enough.

Link to this type redemand_t() View Source
redemand_t() :: {:redemand, Pad.name_t()}

Executes Membrane.Element.Base.Mixin.SourceBehaviour.handle_demand/5 callback with given pad (which must be a source pad in pull mode) if this demand is greater than 0.

Useful when demand could not have been supplied when previous call to Membrane.Element.Base.Mixin.SourceBehaviour.handle_demand/5 happened, but some element-specific circumstances changed and it might be possible to supply it (at least partially).

Allowed only when playback state is playing.

Link to this type split_t() View Source
split_t() :: {:split, {callback_name :: atom(), args_list :: [[any()]]}}

Allows to split callback execution into multiple applications of another callback (called from now sub-callback).

Executions are synchronous in the element process, and each of them passes subsequent arguments from the args_list, along with the element state (passed as the last argument each time).

Return value of each execution of sub-callback can be any valid return value of the original callback (this also means sub-callback can return any action valid for the original callback, unless expliciltly stated). Returned actions are executed immediately (their are NOT accumulated and executed after all sub-callback executions are finished).

Useful when a long action is to be undertaken, and partial results need to be returned before entire process finishes (e.g. default implementation of Membrane.Element.Base.Filter.handle_process/4 uses split action to invoke Membrane.Element.Base.Filter.handle_process1/4 with each buffer)

Type that defines a single action that may be returned from element callbacks. Depending on element type, callback, current playback state and other circumstances there may be different actions available.