Endpoint used for establishing ICE connection, sending and receiving messages.

Architecture and pad semantic

Both input and output pads are dynamic ones. One instance of ICE Endpoint is responsible for handling only one ICE stream with only one component.

Linking using output pad

To receive messages after establishing ICE connection you have to link ICE Endpoint to your element via Pad.ref(:output, 1). 1 is an id of component from which your element will receive messages - because there will be always at most one component, id of it will be equal 1.

Important: you can link to ICE Endpoint using its output pad in any moment you want but if you don't want to miss any messages do it before playing your pipeline.

Linking using input pad

To send messages after establishing ICE connection you have to link to ICE Endpoint via Pad.ref(:input, 1). 1 is an id of component which will be used to send messages via net. To send data from multiple elements via the same component you have to use membrane_funnel_plugin.

Notifications API

ICE Endpoint handles the following notifications:

• :gather_candidates

• {:set_remote_credentials, credentials} - credentials are string in form of "ufrag passwd"

• :peer_candidate_gathering_done

ICE Endpoint sends the following notifications:

• {:new_candidate_full, candidate} Triggered by: :gather_candidates

• {:udp_integrated_turn, udp_integrated_turn}

• {:handshake_init_data, component_id, handshake_init_data}

• {:connection_ready, stream_id, component_id}

• {:component_state_failed, stream_id, component_id}

Sending and receiving messages

To send or receive messages just link to ICE Endpoint using relevant pads.

Establishing a connection

Gathering ICE candidates

Data about integrated TURN servers set up by Membrane.ICE.Endpoint, passed to the parent via notification, should be forwarded to the second peer, that will try to establish ICE connection with Membrane.ICE.Endpoint. The second peer should have at least one allocation, in any of running integrated TURN servers (Firefox or Chrome will probably have one allocation per TURN Server)

Performing ICE connectivity checks, selecting candidates pair

All ICE candidates from the second peer, that are not relay candidates corresponded to allocations on integrated TURN servers, will be ignored. Every ICE connectivity check sent via integrated TURN server is captured, parsed, and forwarded to ICE Endpoint in message {:connectivity_check, attributes, allocation_pid}. ICE Endpoint sends to messages in form of {:send_connectivity_check, attributes} on allocation_pid, to send his connectivity checks to the second peer. Role of ICE Endpoint can be ice-controlled, but cannot be ice-controlling. It is suggested, to use ice-lite option in SDP message, but it is not necessary. ICE Endpoint supports both, aggressive and normal nomination. After starting ICE or after every ICE restart, ICE Endpoint will pass all traffic and connectivity checks via allocation, which corresponds to the last selected ICE candidates pair.

Element options

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

• dtls?

  boolean()

  Default value: true
true, if using DTLS Handshake, false otherwise

• ice_lite?

  boolean()

  Default value: true
true, when ice-lite option was send in SDP message, false otherwise

• handshake_opts

  keyword()

  Default value: []
  Options for ExDTLS module. They will be passed to ExDTLS.start_link/1

• integrated_turn_options

  [integrated_turn_options_t()]

  Required
  Integrated TURN Options

• telemetry_label

  TelemetryMetrics.label()

  Default value: []
  Label passed to Membrane.TelemetryMetrics functions

Pads

:input

Accepted formats:

_any

:output

Accepted formats:

%RemoteStream{content_format: nil, type: :packetized}