# `Caracola.SDP.WebRTC`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/sdp/webrtc.ex#L1)

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"}}

# `candidate`

```elixir
@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`

```elixir
@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`

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

A DTLS setup role (RFC 4145).

# `add_candidates`

```elixir
@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`

```elixir
@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`

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

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

# `candidates`

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

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

# `codecs`

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

The codecs of a media, in order of preference.

# `fingerprint`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

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

# `parse_candidate`

```elixir
@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`

```elixir
@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`

```elixir
@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?`

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

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

# `sdpfrag`

```elixir
@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`

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

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

# `secure?`

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

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

# `setup`

```elixir
@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).

---

*Consult [api-reference.md](api-reference.md) for complete listing*
