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,sdpMidandsdpMLineIndex), to add them to an SDP or extract them. - Trickle ICE over SIP (RFC 8840): the
application/trickle-ice-sdpfragbodies of the INFO requests of thetrickle-iceInfo Package. - DTLS-SRTP (RFC 5763, RFC 8842): fingerprint and setup role.
- BUNDLE (RFC 8843),
midand 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
@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.
@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.
@type setup() :: :actpass | :active | :passive | :holdconn
A DTLS setup role (RFC 4145).
Functions
@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.
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
@spec bundle(Caracola.SDP.t()) :: [String.t()]
The mids of the BUNDLE group of an SDP (RFC 8843), [] if none.
@spec candidates(Caracola.SDP.t()) :: [candidate()]
The ICE candidates of an SDP, in the order of their medias.
@spec codecs(Caracola.SDP.Media.t()) :: [codec()]
The codecs of a media, in order of preference.
@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.
@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}.
@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.
@spec mid(Caracola.SDP.Media.t()) :: String.t() | nil
The mid of a media (nil if it has none).
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"}]}}
Parses a trickle ICE body: %{ufrag, pwd, candidates, end_of_candidates}.
Candidates get the mid and index of their m= line.
@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.
@spec rtcp_mux?(Caracola.SDP.Media.t()) :: boolean()
true if the media multiplexes RTP and RTCP (RFC 5761).
@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.
@spec sdpfrag_content_type() :: String.t()
The Content-Type of trickle ICE bodies (RFC 8840).
@spec secure?(Caracola.SDP.Media.t()) :: boolean()
true if the media uses a secure RTP profile (RTP/SAVP, UDP/TLS/RTP/SAVPF...).
@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).