Membrane.ICE.Sink (Membrane ICE plugin v0.1.0) View Source

Element that sends buffers (over UDP or TCP) received on different pads to relevant receivers.

Architecture and pad semantic

Each sink instance owns exactly one stream which can have multiple components. There is no possibility to add more streams or remove the existing one. User specify number of components at Sink initialization by passing relevant option - see def_options macro for more information.

Multiple components are handled with dynamic pads. Other elements can be linked to the Sink using pad with id component_id. After successful linking sending data to the Sink on newly added pad will cause conveying this data through the net using component with id component_id.

For example if buffer was received on pad 1 the element will send it through component 1 to the receiver which then will convey this data through its pad 1 to some other element.

Other elements can be linked to the Sink in any moment but before playing pipeline. Playing your pipeline is possible only after linking all pads. E.g. if your stream has 2 components you have to link to the Sink using two dynamic pads with ids 1 and 2 and after this you can play your pipeline.

Handshakes

Membrane ICE Plugin provides mechanism for performing handshakes (e.g. DTLS-SRTP) after establishing ICE connection. This is done by passing handshake module as on option at Sink/Source initialization. Provided handshake module has to implement Membrane.ICE.Handshake behaviour. By default none handshake is performed. Please refer to Membrane.ICE.Handshake module for more information.

Interacting with Sink

Interacting with Sink is held by sending it proper messages. Some of them are synchronous i.e. the result is returned immediately while other are asynchronous i.e. Sink will notify us about result after completing some work. Below there are listed messages that can be send to Sink and by Sink. As these messages are analogous to those sent by ExLibnice library please refer to its documentation for more details.

Messages Sink is able to process

Each result that Sink produces is conveyed to the pipeline/bin as notification. Below there are listed messages Sink is able process:

  • :generate_local_sdp

    Result notifications:

    • {:local_sdp, sdp}
  • {:parse_remote_sdp, remote_sdp}

    Result notifications:

    • {:parse_remote_sdp_ok, added_cand_num}
  • {:set_remote_credentials, credentials}

    Result notifications:

    • none
  • :peer_candidate_gathering_done

    Result notifications:

    • none
  • {:set_remote_candidate, candidate, component_id}

    Result notifications:

    • none in case of success
    • {:error, :failed_to_parse_sdp_string}
    • {:error, :failed_to_set}

Messages Sink sends

Sending some messages to Sink can cause it will start performing some work. Below there are listed notifications that the sink sends after handling incoming messages:

  • {:new_candidate_full, candidate}

    Triggered by: starting pipeline i.e. YourPipeline.play(pid)

  • {:new_remote_candidate_full, candidate}

    Triggered by: {:set_remote_candidate, candidate, component_id}

  • :candidate_gathering_done

    Triggered by: starting pipeline i.e. YourPipeline.play(pid)

  • {:new_selected_pair, component_id, lfoundation, rfoundation}

    Triggered by: {:set_remote_candidate, candidate, component_id}

  • {:component_state_failed, stream_id, component_id}

    Triggered by: {:set_remote_candidate, candidate, component_id}

  • {:component_state_ready, component_id, handshake_data}

    Triggered by: {:set_remote_candidate, candidate, component_id}

Sending messages

Sending messages (over the net) was described in Architecture and pad semantic section. Here we only want to notice that Sink can fail to send message. In this case notification {:error, :failed_to_send} is fired to pipeline/bin.

Element options

Passed via struct Membrane.ICE.Sink.t/0

  • n_components

    Default value: 1 Number of components that will be created in the stream

  • stream_name

    Default value: "" Name of the stream

  • stun_servers

    Default value: [] List of stun servers in form of ip:port

  • controlling_mode

    Default value: false Refer to RFC 8445 section 4 - Controlling and Controlled Agent

  • port_range

    Default value: 0..0 The port range to use

  • handshake_module

    Default value: Membrane.ICE.Handshake.Default Module implementing Handshake behaviour

  • handshake_opts

    Default value: [] Options for handshake module. They will be passed to start_link

                function of handshake_module

Pads

:input

Availability:on_request
Bin?false
Caps:any
Demand unit:buffers
Direction:input
Mode:pull
Name:input

Link to this section Summary

Types

t()

Struct containing options for Membrane.ICE.Sink

Functions

Returns pads descriptions for Membrane.ICE.Sink

Returns description of options available for this module

Link to this section Types

Specs

t() :: %Membrane.ICE.Sink{
  controlling_mode: any(),
  handshake_module: any(),
  handshake_opts: any(),
  n_components: any(),
  port_range: any(),
  stream_name: String.t(),
  stun_servers: any()
}

Struct containing options for Membrane.ICE.Sink

Link to this section Functions

Specs

membrane_pads() :: [{Membrane.Pad.name_t(), Membrane.Pad.description_t()}]

Returns pads descriptions for Membrane.ICE.Sink

Specs

options() :: keyword()

Returns description of options available for this module