Caracola.SDP.WebRTC (Caracola v0.1.0-rc.1)

Copy Markdown View Source

SDP utilities for WebRTC endpoints. Successor of NkSIP's nksip_sdp_util.

  • ICE (RFC 8839): credentials, and candidates as browsers give and take them (RTCIceCandidate: candidate, sdpMid and sdpMLineIndex), to add them to an SDP or extract them.
  • Trickle ICE over SIP (RFC 8840): the application/trickle-ice-sdpfrag bodies of the INFO requests of the trickle-ice Info Package.
  • DTLS-SRTP (RFC 5763, RFC 8842): fingerprint and setup role.
  • BUNDLE (RFC 8843), mid and rtcp-mux (RFC 5761).
  • Codecs: listing, keeping or removing them by name.

Values at media level take precedence over session level ones.

iex> {:ok, sdp} = Caracola.SDP.parse("""
...> v=0\r
...> o=- 1 1 IN IP4 127.0.0.1\r
...> s=-\r
...> t=0 0\r
...> a=group:BUNDLE 0\r
...> a=ice-ufrag:abcd\r
...> a=ice-pwd:0123456789012345678901\r
...> m=audio 9 UDP/TLS/RTP/SAVPF 111\r
...> c=IN IP4 0.0.0.0\r
...> a=mid:0\r
...> a=rtcp-mux\r
...> a=setup:actpass\r
...> a=fingerprint:sha-256 AB:CD\r
...> a=rtpmap:111 opus/48000/2\r
...> """)
iex> alias Caracola.SDP.WebRTC
iex> {WebRTC.bundle(sdp), WebRTC.ice(sdp).ufrag, WebRTC.setup(sdp), WebRTC.fingerprint(sdp)}
{["0"], "abcd", :actpass, {"sha-256", "AB:CD"}}

Summary

Types

An ICE candidate as a browser gives and takes it: the attribute value ("candidate:...", without a=), the mid of its media (nil if unknown) and its index.

A codec of a media: payload type, encoding name, clock rate and parameters.

A DTLS setup role (RFC 4145).

Functions

Adds ICE candidates to the medias they belong to: by mid if the media has one, or by index. Candidates for unknown medias are ignored.

The setup role of an answer for the role of the offer (RFC 5763 §5: the answerer is active if it can).

The mids of the BUNDLE group of an SDP (RFC 8843), [] if none.

The ICE candidates of an SDP, in the order of their medias.

The codecs of a media, in order of preference.

The DTLS fingerprint of a media (by index) or of the session: {hash_function, value}, or nil.

ICE credentials and options of a media (by index), or of the session: %{ufrag, pwd, options, lite}.

Keeps only the codecs with these names (case insensitive) in the medias of type media (as "audio"), and the retransmission (rtx) codecs of the kept ones.

The mid of a media (nil if it has none).

Parses a candidate (with or without the candidate: prefix).

Parses a trickle ICE body: %{ufrag, pwd, candidates, end_of_candidates}. Candidates get the mid and index of their m= line.

Removes the codecs with these names (case insensitive) from the medias of type media, and the retransmission (rtx) codecs of the removed ones.

true if the media multiplexes RTP and RTCP (RFC 5761).

The body of a trickle ICE INFO (application/trickle-ice-sdpfrag): the ICE credentials of sdp (the local one), an m= line (with port 9) and mid for each media, and the candidates, by mid or index. With end_of_candidates: true, the end-of-candidates attribute is added.

The Content-Type of trickle ICE bodies (RFC 8840).

true if the media uses a secure RTP profile (RTP/SAVP, UDP/TLS/RTP/SAVPF...).

The DTLS setup role of a media (by index) or of the session (RFC 4145).

Types

candidate()

@type candidate() :: %{
  candidate: String.t(),
  mid: String.t() | nil,
  index: non_neg_integer()
}

An ICE candidate as a browser gives and takes it: the attribute value ("candidate:...", without a=), the mid of its media (nil if unknown) and its index.

codec()

@type codec() :: %{
  pt: String.t(),
  name: String.t(),
  rate: pos_integer() | nil,
  channels: pos_integer() | nil,
  fmtp: [String.t()],
  rtcp_fb: [String.t()]
}

A codec of a media: payload type, encoding name, clock rate and parameters.

setup()

@type setup() :: :actpass | :active | :passive | :holdconn

A DTLS setup role (RFC 4145).

Functions

add_candidates(sdp, candidates)

@spec add_candidates(Caracola.SDP.t(), [candidate()]) :: Caracola.SDP.t()

Adds ICE candidates to the medias they belong to: by mid if the media has one, or by index. Candidates for unknown medias are ignored.

answer_setup(arg1)

@spec answer_setup(setup() | nil) :: setup()

The setup role of an answer for the role of the offer (RFC 5763 §5: the answerer is active if it can).

iex> Caracola.SDP.WebRTC.answer_setup(:actpass)
:active
iex> Caracola.SDP.WebRTC.answer_setup(:active)
:passive

bundle(sdp)

@spec bundle(Caracola.SDP.t()) :: [String.t()]

The mids of the BUNDLE group of an SDP (RFC 8843), [] if none.

candidates(sdp)

@spec candidates(Caracola.SDP.t()) :: [candidate()]

The ICE candidates of an SDP, in the order of their medias.

codecs(media)

@spec codecs(Caracola.SDP.Media.t()) :: [codec()]

The codecs of a media, in order of preference.

fingerprint(sdp, index \\ 0)

@spec fingerprint(Caracola.SDP.t(), non_neg_integer()) ::
  {String.t(), String.t()} | nil

The DTLS fingerprint of a media (by index) or of the session: {hash_function, value}, or nil.

ice(sdp, index \\ 0)

@spec ice(Caracola.SDP.t(), non_neg_integer()) :: %{
  ufrag: String.t() | nil,
  pwd: String.t() | nil,
  options: [String.t()],
  lite: boolean()
}

ICE credentials and options of a media (by index), or of the session: %{ufrag, pwd, options, lite}.

keep_codecs(sdp, media, names)

@spec keep_codecs(Caracola.SDP.t(), String.t(), [String.t()]) :: Caracola.SDP.t()

Keeps only the codecs with these names (case insensitive) in the medias of type media (as "audio"), and the retransmission (rtx) codecs of the kept ones.

mid(media)

@spec mid(Caracola.SDP.Media.t()) :: String.t() | nil

The mid of a media (nil if it has none).

parse_candidate(line)

@spec parse_candidate(String.t()) :: {:ok, map()} | :error

Parses a candidate (with or without the candidate: prefix).

iex> Caracola.SDP.WebRTC.parse_candidate("candidate:1 1 udp 2122260223 192.0.2.1 54400 typ srflx raddr 10.0.0.1 rport 54400 generation 0")
{:ok,
 %{foundation: "1", component: 1, transport: "udp", priority: 2122260223,
   address: "192.0.2.1", port: 54400, type: "srflx", raddr: "10.0.0.1",
   rport: 54400, extensions: [{"generation", "0"}]}}

parse_sdpfrag(body)

@spec parse_sdpfrag(String.t()) :: {:ok, map()} | :error

Parses a trickle ICE body: %{ufrag, pwd, candidates, end_of_candidates}. Candidates get the mid and index of their m= line.

remove_codecs(sdp, media, names)

@spec remove_codecs(Caracola.SDP.t(), String.t(), [String.t()]) :: Caracola.SDP.t()

Removes the codecs with these names (case insensitive) from the medias of type media, and the retransmission (rtx) codecs of the removed ones.

rtcp_mux?(media)

@spec rtcp_mux?(Caracola.SDP.Media.t()) :: boolean()

true if the media multiplexes RTP and RTCP (RFC 5761).

sdpfrag(sdp, candidates, opts \\ [])

@spec sdpfrag(Caracola.SDP.t(), [candidate()], keyword()) :: String.t()

The body of a trickle ICE INFO (application/trickle-ice-sdpfrag): the ICE credentials of sdp (the local one), an m= line (with port 9) and mid for each media, and the candidates, by mid or index. With end_of_candidates: true, the end-of-candidates attribute is added.

sdpfrag_content_type()

@spec sdpfrag_content_type() :: String.t()

The Content-Type of trickle ICE bodies (RFC 8840).

secure?(media)

@spec secure?(Caracola.SDP.Media.t()) :: boolean()

true if the media uses a secure RTP profile (RTP/SAVP, UDP/TLS/RTP/SAVPF...).

setup(sdp, index \\ 0)

@spec setup(Caracola.SDP.t(), non_neg_integer()) :: setup() | nil

The DTLS setup role of a media (by index) or of the session (RFC 4145).