# WebRTC module

<a id="webrtcmodule"></a>

# WebRTC module

WebRTC media transport via libdatachannel; peer sessions, media bridge, codec negotiation.

## Classes

| Name | Description |
|------|-------------|
| [`SignallingInterface`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-SignallingInterface.md#signallinginterface) | Transport-agnostic signalling interface for WebRTC session setup. |
| [`MediaBridge`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-MediaBridge.md#mediabridge) | Convenience wrapper that creates WebRTC tracks on a PeerConnection and exposes per-track sender/receiver adapters for [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) integration. |
| [`PeerSession`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-PeerSession.md#peersession) | Manages a WebRTC peer connection lifecycle over any signalling transport that implements [SignallingInterface](https://auscaster.com/icey/docs/api-reference/icy-wrtc-SignallingInterface.md#signallinginterface). |
| [`WebRtcTrackSender`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-WebRtcTrackSender.md#webrtctracksender) | [PacketProcessor](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) that sends encoded media to a single libdatachannel Track via sendFrame(). |
| [`WebRtcTrackReceiver`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-WebRtcTrackReceiver.md#webrtctrackreceiver) | [PacketStreamAdapter](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) that receives depacketized frames from a single remote libdatachannel Track and emits them as VideoPacket or AudioPacket into a [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream). |
| [`CodecNegotiator`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-CodecNegotiator.md#codecnegotiator) | Maps RTP codec names to FFmpeg encoders and queries FFmpeg at runtime to determine what codecs are available. |
| [`TrackHandle`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-TrackHandle.md#trackhandle) | Result of creating a track: the track itself plus its RTP config. Keep the config around - you need it for [WebRtcTrackSender](https://auscaster.com/icey/docs/api-reference/icy-wrtc-WebRtcTrackSender.md#webrtctracksender). |
| [`JitterBufferConfig`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-JitterBufferConfig.md#jitterbufferconfig) | Receive-side jitter buffer behaviour for depacketized WebRTC media frames. |
| [`CodecSpec`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-CodecSpec.md#codecspec) | Canonical description of a codec supported by icey's WebRTC helpers. |
| [`NegotiatedCodec`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-NegotiatedCodec.md#negotiatedcodec) | Result of codec negotiation between a remote SDP offer and the local FFmpeg codec inventory. |

## Macros

| Name | Description |
|------|-------------|
| [`WEBRTC_API`](#webrtc_api)  |  |

---

<a id="webrtc_api"></a>

### WEBRTC_API

```cpp
#define WEBRTC_API ICY_IMPORT
```

[Defined in src/webrtc/include/icy/webrtc/webrtc.h:24](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/webrtc.h#L24)

## Enumerations

| Name | Description |
|------|-------------|
| [`CodecMediaType`](#codecmediatype)  | Whether a codec carries audio or video media. |
| [`CodecId`](#codecid)  | Stable codec identifiers used across negotiation and track setup. |

---

<a id="codecmediatype"></a>

### CodecMediaType

```cpp
enum CodecMediaType
```

[Defined in src/webrtc/include/icy/webrtc/codecnegotiator.h:40](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/codecnegotiator.h#L40)

Whether a codec carries audio or video media.

| Value | Description |
|-------|-------------|
| `Video` | Video RTP payload. |
| `Audio` | Audio RTP payload. |

---

<a id="codecid"></a>

### CodecId

```cpp
enum CodecId
```

[Defined in src/webrtc/include/icy/webrtc/codecnegotiator.h:48](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/codecnegotiator.h#L48)

Stable codec identifiers used across negotiation and track setup.

| Value | Description |
|-------|-------------|
| `Unknown` | Unrecognized or unsupported codec. |
| `H264` | H.264 / AVC. |
| `H265` | H.265 / HEVC. |
| `VP8` | Google VP8. |
| `VP9` | Google VP9. |
| `AV1` | AOMedia AV1. |
| `Opus` | Opus audio. |
| `PCMU` | G.711 mu-law audio. |
| `PCMA` | G.711 A-law audio. |
| `G722` | G.722 wideband audio. |
| `AAC` | AAC audio. |
## Functions

| Return | Name | Description |
|--------|------|-------------|
| [`TrackHandle`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-TrackHandle.md#trackhandle) | [`createVideoTrack`](#createvideotrack)  | Create a video send track on a PeerConnection. |
| [`TrackHandle`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-TrackHandle.md#trackhandle) | [`createAudioTrack`](#createaudiotrack)  | Create an audio send track on a PeerConnection. |
| `std::shared_ptr< rtc::Track >` | [`createVideoReceiveTrack`](#createvideoreceivetrack)  | Create a pure receive-side video track on a PeerConnection. |
| `std::shared_ptr< rtc::Track >` | [`createAudioReceiveTrack`](#createaudioreceivetrack)  | Create a pure receive-side audio track on a PeerConnection. |
| `bool` | [`setupReceiveTrack`](#setupreceivetrack)  | Set up the receive-side media handler chain on a remote track. |
| `uint32_t` | [`generateSsrc`](#generatessrc)  | Generate a random SSRC. |
| `const char *` | [`stateToString`](#statetostring)  | Convert a [PeerSession::State](https://auscaster.com/icey/docs/api-reference/icy-wrtc-PeerSession.md#state-9) to a lowercase C string for logging. |

---

<a id="createvideotrack"></a>

### createVideoTrack

```cpp
TrackHandle createVideoTrack(std::shared_ptr< rtc::PeerConnection > pc, const av::VideoCodec & codec, uint32_t ssrc = 0, const std::string & cname = {}, const std::string & mid = {}, rtc::Description::Direction direction = rtc::Description::Direction::SendRecv, unsigned nackBuffer = 512, std::function< void()> onPli = nullptr, std::function< void(unsigned int)> onRemb = nullptr, int payloadType = -1)
```

[Defined in src/webrtc/include/icy/webrtc/track.h:63](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/track.h#L63)

Create a video send track on a PeerConnection.

Sets up the full outgoing media handler chain: Packetizer → SrReporter → NackResponder → PliHandler → RembHandler

The packetizer is selected based on the codec: H264 → H264RtpPacketizer (Annex-B long start sequence) H265 → H265RtpPacketizer (Annex-B long start sequence) VP8/VP9/other → generic RtpPacketizer

#### Returns
[TrackHandle](https://auscaster.com/icey/docs/api-reference/icy-wrtc-TrackHandle.md#trackhandle) with the track and its RTP config.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pc` | `std::shared_ptr< rtc::PeerConnection >` | PeerConnection to add the track to. |
| `codec` | const [`av::VideoCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-VideoCodec.md#videocodec) & | Video codec. Must name a supported RTP codec or FFmpeg encoder (e.g. "H264" or "libx264"). |
| `ssrc` | `uint32_t` | RTP SSRC. 0 = auto-generate. |
| `cname` | `const std::string &` | RTCP CNAME. Empty = "icey". |
| `mid` | `const std::string &` | MID to use for the track when answering an existing offer. |
| `direction` | `rtc::Description::Direction` | Direction to advertise for the negotiated m-line. |
| `nackBuffer` | `unsigned` | Max packets stored for NACK retransmission. |
| `onPli` | `std::function< void()>` | Callback when remote peer requests a keyframe. Connect to your encoder to force IDR. |
| `onRemb` | `std::function< void(unsigned int)>` | Callback when remote peer reports bandwidth estimate. Bitrate in bits/sec. |
| `payloadType` | `int` | Explicit RTP payload type to reuse when answering an offer. -1 = use the codec's default/preferred type. |

---

<a id="createaudiotrack"></a>

### createAudioTrack

```cpp
TrackHandle createAudioTrack(std::shared_ptr< rtc::PeerConnection > pc, const av::AudioCodec & codec, uint32_t ssrc = 0, const std::string & cname = {}, const std::string & mid = {}, rtc::Description::Direction direction = rtc::Description::Direction::SendRecv, int payloadType = -1)
```

[Defined in src/webrtc/include/icy/webrtc/track.h:94](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/track.h#L94)

Create an audio send track on a PeerConnection.

Sets up the outgoing media handler chain: AudioRtpPacketizer → SrReporter

The packetizer clock rate is selected based on codec: opus → 48kHz, PCMU/PCMA → 8kHz, etc.

#### Returns
[TrackHandle](https://auscaster.com/icey/docs/api-reference/icy-wrtc-TrackHandle.md#trackhandle) with the track and its RTP config.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pc` | `std::shared_ptr< rtc::PeerConnection >` | PeerConnection to add the track to. |
| `codec` | const [`av::AudioCodec`](https://auscaster.com/icey/docs/api-reference/icy-av-AudioCodec.md#audiocodec) & | Audio codec. Must name a supported RTP codec or FFmpeg encoder (e.g. "opus" or "libopus"). |
| `ssrc` | `uint32_t` | RTP SSRC. 0 = auto-generate. |
| `cname` | `const std::string &` | RTCP CNAME. Empty = "icey". |
| `mid` | `const std::string &` | MID to use for the track when answering an existing offer. |
| `direction` | `rtc::Description::Direction` | Direction to advertise for the negotiated m-line. |
| `payloadType` | `int` | Explicit RTP payload type to reuse when answering an offer. -1 = use the codec's default/preferred type. |

---

<a id="createvideoreceivetrack"></a>

### createVideoReceiveTrack

```cpp
std::shared_ptr< rtc::Track > createVideoReceiveTrack(std::shared_ptr< rtc::PeerConnection > pc, const av::VideoCodec & codec, const std::string & mid = {}, rtc::Description::Direction direction = rtc::Description::Direction::RecvOnly, int payloadType = -1)
```

[Defined in src/webrtc/include/icy/webrtc/track.h:108](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/track.h#L108)

Create a pure receive-side video track on a PeerConnection.

Unlike [createVideoTrack()](#createvideotrack), this does not add a local SSRC or sender packetizer chain. It is for answers that only receive remote media.

---

<a id="createaudioreceivetrack"></a>

### createAudioReceiveTrack

```cpp
std::shared_ptr< rtc::Track > createAudioReceiveTrack(std::shared_ptr< rtc::PeerConnection > pc, const av::AudioCodec & codec, const std::string & mid = {}, rtc::Description::Direction direction = rtc::Description::Direction::RecvOnly, int payloadType = -1)
```

[Defined in src/webrtc/include/icy/webrtc/track.h:120](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/track.h#L120)

Create a pure receive-side audio track on a PeerConnection.

Unlike [createAudioTrack()](#createaudiotrack), this does not add a local SSRC or sender packetizer chain. It is for answers that only receive remote media.

---

<a id="setupreceivetrack"></a>

### setupReceiveTrack

```cpp
bool setupReceiveTrack(std::shared_ptr< rtc::Track > track)
```

[Defined in src/webrtc/include/icy/webrtc/track.h:141](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/track.h#L141)

Set up the receive-side media handler chain on a remote track.

Selects the correct depacketizer based on the track's SDP codec: Video: H264RtpDepacketizer, H265RtpDepacketizer, or generic Audio: OpusRtpDepacketizer, PCMURtpDepacketizer, etc.

Also chains an RtcpReceivingSession for receiver reports.

Call this from PeerConnection::onTrack() before binding a [WebRtcTrackReceiver](https://auscaster.com/icey/docs/api-reference/icy-wrtc-WebRtcTrackReceiver.md#webrtctrackreceiver).

#### Returns
True when a supported depacketizer was installed.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `track` | `std::shared_ptr< rtc::Track >` | The remote track from onTrack callback. |

---

<a id="generatessrc"></a>

### generateSsrc

```cpp
uint32_t generateSsrc()
```

[Defined in src/webrtc/include/icy/webrtc/track.h:145](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/track.h#L145)

Generate a random SSRC.

---

<a id="statetostring"></a>

### stateToString

```cpp
const char * stateToString(PeerSession::State state)
```

[Defined in src/webrtc/include/icy/webrtc/peersession.h:206](https://github.com/auscaster/icey/blob/main/src/webrtc/include/icy/webrtc/peersession.h#L206)

Convert a [PeerSession::State](https://auscaster.com/icey/docs/api-reference/icy-wrtc-PeerSession.md#state-9) to a lowercase C string for logging. 
#### Returns
One of: "idle", "outgoing-init", "incoming-init", "negotiating", "active", "ending", "ended".

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `state` | [`PeerSession::State`](https://auscaster.com/icey/docs/api-reference/icy-wrtc-PeerSession.md#state-9) | [State](https://auscaster.com/icey/docs/api-reference/icy-State.md#state) value to convert. |