@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(),
   max_instances: max_instances()}

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.

Pad options are defined by a keyword list, where each key is an option name and is described by another keyword list with following fields:

• spec: Typespec of the values this option can assume. Will be used in the type definition of pad options for a given pad.
• default: Default value for option. If not present, value for this option will have to be provided each time options the pad is created.
• inspector: Function converting fields' value to a string. Used when creating documentation instead of inspect/1, eg. inspector: &Membrane.Time.inspect/1.
• description: String describing the option. It will be used for generating the docs.

@type demand_unit() :: non_timestamp_demand_unit() | timestamp_demand_unit()

Specifies the unit in which a pad's demand is expressed.

Output pads only support non_timestamp_demand_unit/0 (:buffers or :bytes). Input pads support both non_timestamp_demand_unit/0 and timestamp_demand_unit/0.

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

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() :: output_element_spec() | input_element_spec()

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 input_element_spec() ::
  {name(),
   availability: availability(),
   accepted_format: accepted_format(),
   flow_control: flow_control(),
   options: Keyword.t(),
   demand_unit: demand_unit(),
   max_instances: max_instances()}

Describes how an input pad should be declared inside an element.

Pad options are defined by a keyword list, where each key is an option name and is described by another keyword list with following fields:

• spec: Typespec of the values this option can assume. Will be used in the type definition of pad options for a given pad.
• default: Default value for option. If not present, value for this option will have to be provided each time options the pad is created.
• inspector: Function converting fields' value to a string. Used when creating documentation instead of inspect/1, eg. inspector: &Membrane.Time.inspect/1.
• description: String describing the option. It will be used for generating the docs.

@type max_instances() :: non_neg_integer() | :infinity

Describes maximal number of instances of dynamic pad (availability: :on_request) that can occur simultaneously within a single component.

Defaults to :infinity.

@type name() :: atom()

Defines the name of pad or group of dynamic pads

@type non_timestamp_demand_unit() :: :buffers | :bytes

Demand unit that does not involve timestamps — applicable to both input and output pads.

• :buffers — demand expressed in number of buffers
• :bytes — demand expressed in bytes of payload

@type output_element_spec() ::
  {name(),
   availability: availability(),
   accepted_format: accepted_format(),
   flow_control: flow_control(),
   options: Keyword.t(),
   demand_unit: non_timestamp_demand_unit(),
   max_instances: max_instances()}

Describes how an output pad should be declared inside an element.

Output pads only support non_timestamp_demand_unit/0 for demand_unit.

Pad options are defined by a keyword list, where each key is an option name and is described by another keyword list with following fields:

• spec: Typespec of the values this option can assume. Will be used in the type definition of pad options for a given pad.
• default: Default value for option. If not present, value for this option will have to be provided each time options the pad is created.
• inspector: Function converting fields' value to a string. Used when creating documentation instead of inspect/1, eg. inspector: &Membrane.Time.inspect/1.
• description: String describing the option. It will be used for generating the docs.

@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.

@type timestamp_demand_unit() :: :timestamp | {:timestamp, :pts | :dts | :dts_or_pts}

Demand unit based on timestamps — applicable to input pads only.

• :timestamp / {:timestamp, :dts_or_pts} — demand expressed as a DTS-or-PTS duration
• {:timestamp, :pts} — demand expressed as a PTS duration
• {:timestamp, :dts} — demand expressed as a DTS duration