@type audio_codec_name() :: :opus

Allowed audio codec names which will get expanded to the relevant default ExWebRTC.RTPCodecParameters.t/0

@type feature() :: :twcc | :inbound_rtx | :outbound_rtx | :rtcp_reports

Features provided by the ExWebRTC's PeerConnection:

• :twcc - ExWebRTC's PeerConnection will generate TWCC RTCP feedbacks based on incoming packets and send them to the remote peer (implicitly adds the http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01 to negotiated RTP header extensions and :twcc RTCP feedback to all of the negotiated codecs, both audio and video).
• :inbound_rtx - ExWebRTC's PeerConnection will generate NACK RTCP feedbacks in response to missing incoming video packets and properly handle incoming retransmissions (implicitly adds the :nack RTCP feedback and a matching a=rtpmap:[id] rtx/... attribute for every negotiated video codec).
• :outbound_rtx - ExWebRTC's PeerConnection will respond to incoming NACK RTCP feedbacks and retransmit packets accordingly (implicitly adds the same attributes as :inbound_rtx).
• :rtcp_reports - ExWebRTC's PeerConnection will generate and send RTCP Sender/Receiver Reports based on incoming/send RTP packets.

Use default_features/0 to get the list of features enabled by default. When passing a list of features to options/0, it will override the default features.

@type ice_server() :: %{
  optional(:credential) => String.t(),
  optional(:username) => String.t(),
  urls: [String.t()] | String.t()
}

ICE (STUN and/or TURN) server used to create the ICE connection.

@type options() :: [
  controlling_process: Process.dest(),
  ice_servers: [ice_server()],
  ice_transport_policy: :relay | :all,
  ice_ip_filter: ExICE.ICEAgent.ip_filter(),
  ice_port_range: Enumerable.t(non_neg_integer()),
  ice_aggressive_nomination: boolean(),
  audio_codecs: [ExWebRTC.RTPCodecParameters.t()] | [audio_codec_name()],
  video_codecs: [ExWebRTC.RTPCodecParameters.t()] | [video_codec_name()],
  features: [feature()],
  rtp_header_extensions: [rtp_header_extension()],
  rtcp_feedbacks: [rtcp_feedback()]
]

Options that can be passed to ExWebRTC.PeerConnection.start_link/1.

• controlling_process - a pid of a process where all messages will be sent. self() by default,
• ice_servers - list of STUN/TURN servers to use. By default, no servers are provided.
• ice_transport_policy - which type of ICE candidates should be used. Defaults to :all.
• ice_ip_filter - filter applied when gathering local candidates. By default, all IP addresses are accepted.
• ice_port_range - range of ports that ICE will use for gathering host candidates. Defaults to ephemeral ports.
• ice_aggressive_nomination - whether ICE agent should use aggressive nomination. By default, ICE agent relies on the regular nomination defined in RFC 8445. However, some WebRTC implementations require the controlling side to nominate a pair before they can start sending data (e.g. Pion, Firefox). This can result in longer, connection establishment time as regular nomination nominates only one pair, at the very end of the whole connection establishment process. To mitigate this issue, you can eitehr add an empty ICE candidate (this will indicate that there won't be further remote candidates and once all connectivity checks pass, ICE will nominate the pair), or use aggressive nomination. Defaults to false.
• audio_codecs and video_codecs - lists of audio and video codecs to negotiate. By default these are equal to default_audio_codecs/0 and default_video_codecs/0. To extend the list with your own codecs, do audio_codecs: Configuration.default_audio_codecs() ++ my_codecs. To use a subset of the default codecs, you can pass the atoms defined in audio_codec_name/0 and video_codec_name/0.
• features - feature flags for some of the ExWebRTC functinalities. Refer to feature/0 for more information.
• rtp_header_extensions - list of RTP header extensions to negotiate. Refer to rtp_header_extension/0 for more information.
• rtcp_feedbacks - list of RTCP feedbacks to negotiate. Refer to rtcp_feedback/0 for more information.

Instead of manually enabling an RTP header extension or an RTCP feedback, you may want to use a feature/0, which will enable necessary header extensions under the hood. If you enable RTCP feedback/RTP header extension corresponding to some feature (but not the feature itself), the functionality might not work (e.g. even if you enable TWCC RTP header extension and TWCC feedbacks, without enabling the :twcc features, TWCC feedbacks won't be sent).

ExWebRTC does not allow for configuration of some of the W3C options, but behaves as if these values were used:

• bundle_policy - max_bundle
• ice_candidate_pool_size - 0
• rtcp_mux_policy - require

@type rtcp_feedback() :: %{
  type: :audio | :video | :all,
  feedback: :nack | :fir | :pli | :twcc
}

RTCP feedbacks that are going to be added by default to all of the codecs.

Use default_rtcp_feedbacks/0 to check the RTCP feedbacks included by default. When passing a list of RTPC feedbacks to options/0, it will override the default feedbacks.

Be aware that some of the features (see feature/0) can implicitly add RTCP feedbacks.

@type rtp_header_extension() :: %{type: :audio | :video | :all, uri: String.t()}

RTP header extension that are going to be included in the SDP offer/answer.

Keep in mind that you are free to pass any RTP header extension URI, but the underlying RTP parsing library (ex_rtp) might not support it. In such case, you have to parse the header extension yourself.

This header extension will be included in all of the m-lines of provided type (or for both audio and video if :all is used).

Use default_rtp_header_extensions/0 to check the RTP header extensions included by default. When passing a list of RTP header extensions to options/0, it will override the default RTP header extensions.

Be aware that some of the features (see feature/0) can implicitly add RTP header extensions).

@type t() :: %ExWebRTC.PeerConnection.Configuration{
  audio_codecs: [ExWebRTC.RTPCodecParameters.t()],
  audio_extensions: [ExSDP.Attribute.Extmap.t()],
  controlling_process: Process.dest(),
  features: [feature()],
  ice_aggressive_nomination: boolean(),
  ice_ip_filter: (:inet.ip_address() -> boolean()) | nil,
  ice_port_range: Enumerable.t(non_neg_integer()),
  ice_servers: [ice_server()],
  ice_transport_policy: :relay | :all,
  video_codecs: [ExWebRTC.RTPCodecParameters.t()],
  video_extensions: [ExSDP.Attribute.Extmap.t()]
}

ExWebRTC.PeerConnection configuration.

It is created from options passed to ExWebRTC.PeerConnection.start_link/1. See options/0 for more.

@type video_codec_name() :: :vp8 | :h264 | :av1

Allowed video codec names which will get expanded to the relevant default ExWebRTC.RTPCodecParameters.t/0