xmedialib

# XMediaLib

XMediaLib is a media and signaling toolkit for VoIP and WebRTC on Erlang/Elixir.
It provides wire-format helpers and optional native codecs for RTP/RTCP, SRTP,
STUN/TURN, SDP, SIP, and ZRTP. Parts of the API descend from
[Peter Lemenkov's](https://github.com/lemenkov)
[RTPLib](https://github.com/lemenkov/rtplib).

Published home: [https://github.com/Lazarus404/xmedialib](https://github.com/Lazarus404/xmedialib)

## What problem this solves

Building a phone or conference app means more than HTTP. Peers must agree on
codecs and network paths (SDP, ICE), authenticate and encrypt media (DTLS-SRTP
in WebRTC, or ZRTP as an in-band alternative), and move packets through NAT
(STUN/TURN). XMediaLib packages those building blocks as Elixir modules plus
optional NIF- or port-backed drivers where performance matters.

## Main modules

- `XMediaLib.Codec` -- audio encode/decode via native port drivers (G.711,
  G.722, Opus, and others). Opus in-band FEC/PLC via `set_inband_fec/2`,
  `decode_fec/2`, `decode_plc/1`; fmtp parse in `XMediaLib.Codec.OpusFmtp`.
- `XMediaLib.Rtp` / `XMediaLib.Rtcp` -- RFC 3550 RTP and RTCP framing;
  header extensions and Dependency Descriptor helpers under `XMediaLib.Rtp.*`.
- `XMediaLib.Srtp` -- SRTP protect/unprotect after key agreement.
- `XMediaLib.Stun` -- STUN/TURN message encode and decode.
- `XMediaLib.SDP` -- session description parse and encode.
- `XMediaLib.SIP` -- SIP message helpers (pure Elixir; optional PJSIP NIF).
- `XMediaLib.Zrtp` / `XMediaLib.ZrtpFsm` / `XMediaLib.ZrtpCrypto` -- ZRTP
  packet codec, key derivation, and handshake state machine.
- `XMediaLib.SAS` -- Short Authentication String rendering for ZRTP.
- `XMediaLib.CRC32C` -- Castagnoli CRC-32C (ZRTP packet trailer).
- `XMediaLib.TestUtils` -- lab helpers for codec golden-file checks (not for
  production wire paths).

## RFCs

Codecs and media:

- RFC 3551 (RTP profile, static payload types including PCMU/PCMA)
- RFC 3550 (RTP and RTCP)
- RFC 3711 (SRTP)
- ITU-T G.711 (PCMU/PCMA), ITU-T G.722, ITU-T G.729
- RFC 6716 (Opus)
- RFC 4867 (Speex over RTP), RFC 3951 (iLBC)
- RFC 8285 (RTP header extensions); AV1 RTP Dependency Descriptor

Signaling and connectivity:

- RFC 8866 / RFC 4566 (SDP)
- RFC 3261 (SIP)
- RFC 8489 (STUN), RFC 8656 (TURN)

ZRTP and related:

- RFC 6189 (ZRTP)
- RFC 3526 / RFC 5114 (DH groups referenced by ZRTP)
- RFC 8265 (SAS rendering / Base32)
- CRC-32C (Castagnoli); see RFC 3385 / RFC 4960 / RFC 3720 B.4

## Prerequisites

To run all tests and use all codec features, install the native libraries the
port drivers link against:

- [libilbc](https://github.com/TimothyGu/libilbc)
- [bcg729](https://github.com/BelledonneCommunications/bcg729)
- [SampleRate](https://launchpad.net/ubuntu/+source/libsamplerate)
- [SpanDSP](https://github.com/jart/spandsp)
- [libOpus](http://opus-codec.org/downloads/)
- [libSpeex](https://www.speex.org/)

Example on Ubuntu:

```
# install libilbc
wget https://github.com/TimothyGu/libilbc/releases/download/v2.0.2/libilbc-2.0.2.tar.gz
tar -xzvf libilbc-2.0.2.tar.gz
cd libilbc-2.0.2
./configure
make && sudo make install

# install bcg729
git clone git@github.com:BelledonneCommunications/bcg729.git
cd bcg729/
cmake . -DENABLE_STATIC=YES
make && sudo make install

# install remaining libs
sudo add-apt-repository ppa:jonathonf/ffmpeg-3
sudo apt-get update
sudo apt-get install libsamplerate-dev libspandsp-dev libopus-dev libopus0 opus-tools libspeex-dev
```

Without these libraries, codec drivers that need them will not load; other
modules (RTP, SDP, STUN, and so on) still work.

### SIP (optional NIF)

`XMediaLib.SIP.parse/1` and `encode/1` always work: they use the PJSIP NIF when
`priv/sip_nif.so` is built, otherwise the pure-Elixir fallback
(`XMediaLib.SIP.Elixir`).

Building the NIF requires PJSIP (`libpjproject`). If PJSIP is not installed,
`make` prints `skip sip_nif: PJSIP not found` and continues. NIF-specific tests
skip automatically; Elixir-path tests always run.

Install PJSIP (example on macOS with Homebrew):

```
brew install pjproject
```

Then from `xmedialib/`:

```
make
mix test test/sip/
```

### SDP

`XMediaLib.SDP.parse/1` and `encode/1` parse and serialize Session Description
Protocol for WebRTC-oriented offers and answers. Media attributes such as ICE
candidates, fingerprints, rtpmap/fmtp, and SCTP data-channel fields are
promoted onto `%XMediaLib.SDP.Media{}`.

```
mix test test/sdp/
```

### Codec (Opus FEC / PLC)

`XMediaLib.Codec` loads Erlang port drivers under `priv/`. Opus supports:

- `set_bitrate/2` -- `OPUS_SET_BITRATE`
- `set_inband_fec/2` -- `OPUS_SET_INBAND_FEC`
- `set_packet_loss_perc/2` -- `OPUS_SET_PACKET_LOSS_PERC` (0..100)
- `decode/2` -- normal decode (`fec=0`)
- `decode_fec/2` -- recover the previous lost frame from in-band FEC in this packet (`fec=1`)
- `decode_plc/1` -- concealment from decoder state (`NULL` packet)

Non-Opus codecs return `{:error, :unsupported}` for FEC/PLC setters and
decoders (no silent no-op). Parse SDP fmtp with `XMediaLib.Codec.OpusFmtp.parse/1`,
then call `set_inband_fec/2` after `start_link/1` when `useinbandfec` is true.

```
mix test test/codecs/codec_opus_test.exs
```

## Installation

Add `xmedialib` to your `mix.exs` dependencies:

```elixir
def deps do
  [{:xmedialib, "~> 0.3.0"}]
end
```

## Contact

For questions or suggestions, email experts@xirsys.com

## Copyright

Copyright (c) 2013 - 2026 Jahred Love & Xirsys LLC

All rights reserved.

XMediaLib is licensed by Xirsys, with permission, under the Apache License
Version 2.0. See LICENSE for the full license text.