Membrane Core v0.5.0 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 Membrane.Element.Base.handle_init/1
and Membrane.Element.Base.handle_shutdown/2
, as they
do not return any actions) unless explicitly stated otherwise.
Link to this section Summary
Types
Sends buffers through a pad.
Sends caps through a pad.
Makes a demand on a pad.
Sends EndOfStream event through a pad (output) that triggers
callback end_of_stream/3
at the receiver element.
Sends an event through a pad (input or output).
Sends buffers/caps/event to all output pads of element (or to input pads when event occurs on the output pad).
This action sets the latency for the element.
Sends a message to the watcher.
Suspends/resumes change of playback state.
Executes Membrane.Element.WithOutputPads.handle_demand/5
callback
for the given pad if its demand is greater than 0.
Allows to split callback execution into multiple applications of another callback (called from now sub-callback).
Starts a timer that will invoke Membrane.Element.Base.handle_tick/3
callback
every interval
according to the given clock
.
Stops a timer started with start_timer_t/0
action.
Type that defines a single action that may be returned from element callbacks.
Link to this section Types
buffer_t()
View Sourcebuffer_t() :: {:buffer, {Membrane.Pad.ref_t(), Membrane.Buffer.t() | [Membrane.Buffer.t()]}}
Sends buffers through a pad.
The pad must have output direction.
Allowed only when playback state is playing.
caps_t()
View Sourcecaps_t() :: {:caps, {Membrane.Pad.ref_t(), Membrane.Caps.t()}}
Sends caps through a pad.
The pad must have output direction. Sent caps must fit constraints on the pad.
Forbidden when playback state is stopped.
demand_size_t()
View Sourcedemand_size_t() :: pos_integer() | (pos_integer() -> non_neg_integer())
demand_t()
View Sourcedemand_t() :: {:demand, {Membrane.Pad.ref_t(), demand_size_t()}}
Makes a demand on a pad.
The pad must have input direction and work in pull mode. This action does NOT
entail sending demand through the pad, but just requesting some amount
of data from Membrane.Core.InputBuffer
, 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.Filter.handle_process_list/4
or Membrane.Sink.handle_write_list/4
callback. Invoked callback is
guaranteed not to receive more data than demanded.
Demand size can be either a non-negative integer, that overrides existing demand, or a function that is passed current demand, and is to return the new demand.
Allowed only when playback state is playing.
end_of_stream_t()
View Sourceend_of_stream_t() :: {:end_of_stream, Membrane.Pad.ref_t()}
Sends EndOfStream event through a pad (output) that triggers
callback end_of_stream/3
at the receiver element.
Allowed only when playback is in playing state.
event_t()
View Sourceevent_t() :: {:event, {Membrane.Pad.ref_t(), Membrane.Event.t()}}
Sends an event through a pad (input or output).
Forbidden when playback state is stopped.
forward_t()
View Sourceforward_t() :: {:forward, Membrane.Buffer.t() | [Membrane.Buffer.t()] | Membrane.Caps.t() | Membrane.Event.t() | :end_of_stream}
Sends buffers/caps/event to all output pads of element (or to input pads when event occurs on the output pad).
Used by default implementations of
Membrane.Element.WithInputPads.handle_caps/4
and
Membrane.Element.Base.handle_event/4
callbacks in filter.
Allowed only when all below conditions are met:
- element is filter,
- callback is
Membrane.Filter.handle_process_list/4
,Membrane.Element.WithInputPads.handle_caps/4
orMembrane.Element.Base.handle_event/4
, - playback state is valid for sending buffer, caps or event action respectively.
Keep in mind that Membrane.Filter.handle_process_list/4
can only
forward buffers, Membrane.Element.WithInputPads.handle_caps/4
- caps
and Membrane.Element.Base.handle_event/4
- events.
This action sets the latency for the element.
This action is not premitted in callback Membrane.Element.Base.handle_init/1
.
Sends a message to the watcher.
playback_change_t()
View Sourceplayback_change_t() :: {:playback_change, :suspend | :resume}
Suspends/resumes change of playback state.
playback_change: :suspend
may be returned only fromMembrane.Element.Base.handle_stopped_to_prepared/2
,Membrane.Element.Base.handle_playing_to_prepared/2
,Membrane.Element.Base.handle_prepared_to_playing/2
andMembrane.Element.Base.handle_prepared_to_stopped/2
callbacks, and defers playback state change untilplayback_change: :resume
is returned.playback_change: :resume
may be returned from any callback, only when playback state change is suspended, and causes it to finish.
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.
Executes Membrane.Element.WithOutputPads.handle_demand/5
callback
for the given pad if its demand is greater than 0.
The pad must have output direction and work in pull mode.
Redemand in Sources
In case of Sources, :redemand
is just a helper that simplifies element's code.
The element doesn't need to generate the whole demand synchronously at handle_demand
or store current demand size in its state, but it can just generate one buffer
and return :redemand
action.
If there is still one or more buffers to produce, returning :redemand
triggers
the next invocation of handle_demand
. In such case, the element is to produce
next buffer and call :redemand
again.
If there are no more buffers demanded, handle_demand
is not invoked and
the loop ends.
One more advantage of the approach with :redemand
action is that produced buffers
are sent one after another in separate messages and this can possibly improve
the latency.
Redemand in Filters
Redemand in Filters is useful in a situation where not the entire demand of output pad has been satisfied and there is a need to send a demand for additional buffers through the input pad. A typical example of this situation is a parser that has not demanded enough bytes to parse the whole frame.
Usage limitations
Allowed only when playback state is playing.
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 (they 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.Filter.handle_process_list/4
uses split action to invoke
Membrane.Filter.handle_process/4
with each buffer)
start_timer_t()
View Sourcestart_timer_t() :: {:start_timer, {id :: any(), interval :: Membrane.Time.t(), clock :: Membrane.Clock.t()} | {id :: any(), interval :: Membrane.Time.t()}}
Starts a timer that will invoke Membrane.Element.Base.handle_tick/3
callback
every interval
according to the given clock
.
If no clock is passed, pipeline clock is chosen. The timer's id
is passed
to the Membrane.Element.Base.handle_tick/3
callback and can be used for
stopping it (stop_timer_t/0
).
Timers use Process.send_after/3
under the hood.
Stops a timer started with start_timer_t/0
action.
This action is atomic: stopping timer guarantees that no ticks will arrive from it.
t()
View Sourcet() :: event_t() | notify_t() | split_t() | caps_t() | buffer_t() | demand_t() | redemand_t() | forward_t() | playback_change_t() | start_timer_t() | stop_timer_t() | latency_t() | end_of_stream_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.