@type accepted_format() :: module() | (pattern :: term())

Describes pattern, that should be matched by stream format send by element on specific pad. Will not be evaluated during runtime, but used for matching struct passed in :stream_format action. Can be a module name, pattern describing struct, or call to any_of function, which arguments are such patterns or modules names. If a module name is passed to the :accepted_format option or is passed to any_of, it will be converted to the match on a struct defined in that module, eg. accepted_format: My.Format will have this same effect, as accepted_format: %My.Format{} and accepted_format: any_of(My.Format, %My.Another.Format{field: value} when value in [:some, :enumeration]) will have this same effect, as accepted_format: any_of(%My.Format{}, %My.Another.Format{field: value} when value in [:some, :enumeration])

@type availability() :: :always | :on_request

Values used when defining pad availability:

• :always - a static pad, which can remain unlinked in stopped state only.
• :on_request - a dynamic pad, instance of which is created every time it is linked to another pad. Thus linking the pad with k other pads, creates k instances of the pad, and links each with another pad.

@type availability_mode() :: :static | :dynamic

Type describing availability mode of a created pad:

• :static - there always exist exactly one instance of such pad.
• :dynamic - multiple instances of such pad may be created and removed (which entails executing handle_pad_added and handle_pad_removed callbacks, respectively).

@type bin_spec() ::
  {name(),
   availability: availability(),
   accepted_format: accepted_format(),
   options: Keyword.t()}

Describes how a pad should be declared inside a bin.

Demand unit is derived from the first element inside the bin linked to the given input.

@type description() :: %{
  :availability => availability(),
  optional(:flow_control) => flow_control(),
  :name => name(),
  :accepted_formats_str => [String.t()],
  optional(:demand_unit) => Membrane.Buffer.Metric.unit() | nil,
  direction: direction(),
  options: nil | Keyword.t()
}

Type describing a pad. Contains data parsed from spec/0

@type direction() :: :output | :input

Defines possible pad directions:

• :output - data can only be sent through such pad,
• :input - data can only be received through such pad.

One cannot link two pads with the same direction.

@type dynamic_id() :: any()

Possible id of dynamic pad

@type element_spec() ::
  {name(),
   availability: availability(),
   accepted_format: accepted_format(),
   flow_control: flow_control(),
   options: Keyword.t(),
   demand_unit: Membrane.Buffer.Metric.unit()}

Describes how a pad should be declared inside an element.

@type flow_control() :: :auto | :manual | :push

Describes how an element sends and receives data.

The available values for that field are:

• :manual - meaning that the pad works in a pull mode and the demand is manually handled and requested. An element with output :manual pad can send data through such a pad only if it has already received demand on that pad. And element with input :manual pad receives data through such a pad only if it has been previously demanded, so that no undemanded data can arrive For more info, see Membrane.Element.Action.demand, Membrane.Element.Action.redemand and Membrane.Element.WithOutputPads.handle_demand/5.
• :auto - meaning that the pad works in a pull mode and the demand is managed automatically: the core ensures that there's demand on each input pad (that has flow_control set to :auto) whenever there's demand on all output pads (that have flow_control set to :auto). Currently works for Membrane.Filters, Membrane.Endpoints and Membrane.Sinks.
• :push - meaning that the pad works in a push mode. An element with a :push output pad can send data through that pad whenever it wants. An element with a :push input pad has to deal with data whenever it comes through such a pad - note, that it needs to be done fast enough so that not to let data accumulate, what may lead to overflow of element process erlang queue, which is highly unwanted.

Linking pads with different flow control is possible, but only in case of an output pad working in a push mode, and an input pad in pull mode (that is - with :manual or :auto flow control). In such case, however, an error will be raised whenever too many buffers accumulate on the input pad, waiting to be processed.

@type name() :: atom()

Defines the name of pad or group of dynamic pads

@type ref() :: name() | {Membrane.Pad, name(), dynamic_id()}

Defines the term by which the pad instance is identified.

@type spec() :: element_spec() | bin_spec()

Describes how a pad should be declared in element or bin.