Change the code
View SourceThis page is for you if you want to change erlang_webrtc: fix a bug, add a protocol feature, or follow a packet through the stack. It maps each part of WebRTC to the directory, modules and tests that implement it, states the rules every module follows, and gives step by step recipes for the common changes. Read CONCEPTS.md and ARCHITECTURE.md first; CONTRIBUTING.md says how to send your change.
Start here
- CONCEPTS.md: the vocabulary (peer connection, transport, mid, SSRC, engine).
- ARCHITECTURE.md: the layers, the processes and the packet paths.
- This page: where things live and how to change them.
- TESTING.md: which test layer to use and how to run it.
Public API and internal modules
The public API is the webrtc module and the webrtc_media_codec behaviour. Everything else is internal: you can change it freely, and it may change between releases. A change to webrtc or to the plugin behaviour is a change to the API: it needs a line in CHANGELOG.md, and a breaking one is called out in the pull request.
Options and events are listed in REFERENCE.md; webrtc_docs_tests checks that the list matches what webrtc:new_pc/1 accepts.
Where things live
Each row names where to start reading, the tests that cover the area, and the page that tracks its requirements.
| Area | Start with | Also | Tests | Requirements |
|---|---|---|---|---|
| Public API, option validation | src/webrtc.erl | test/e2e/webrtc_pc_SUITE.erl | REFERENCE.md | |
| Peer connection process, supervision | src/pc/webrtc_pc.erl | webrtc_peer_sup, webrtc_pc_sup, src/webrtc_registry.erl | webrtc_pc_SUITE, webrtc_lifecycle_SUITE | ARCHITECTURE.md |
| Offer and answer (JSEP) | src/sdp/webrtc_jsep.erl | webrtc_jsep_build (offers, answers), _params (what each side negotiated), _caps (codecs, extensions, feedback), _simulcast, _transport (BUNDLE groups) | webrtc_jsep_tests, prop_webrtc_sdp | sdp |
| SDP text | src/sdp/webrtc_sdp.erl | webrtc_sdp_attr, _media, _rtp, _rid, _candidate, _lex | webrtc_sdp_tests | sdp |
| Transport process | src/transport/webrtc_transport.erl | _net (sockets, datagrams, ICE actions), _secure (DTLS, SRTP keys, media and SCTP actions), webrtc_demux | webrtc_pc_SUITE, webrtc_security_SUITE | transport |
| DSCP marking | src/transport/webrtc_dscp.erl | src/ice/webrtc_ice_marks.erl | webrtc_dscp_tests | transport, TR-20 and on |
| Candidate names, mDNS | src/mdns/webrtc_mdns.erl | _resolver, _responder (engines), _client, _msg, _public | webrtc_mdns_SUITE | ice |
| ICE | src/ice/webrtc_ice_agent.erl | _checklist, _conncheck, _responder, _session (nomination), _consent, _gather, _relay, _tcp, _resolve, _uri | webrtc_ice_*_tests, webrtc_ice_net_tests | ice |
| STUN and TURN | src/stun/webrtc_stun.erl | webrtc_stun_tx, webrtc_turn_client, _auth, _channel, _stream | webrtc_stun_tests, webrtc_turn_*_tests, webrtc_turn_interop_SUITE | stun, turn |
| DTLS | src/dtls/webrtc_dtls.erl | webrtc_dtls12, webrtc_dtls13*, webrtc_dtls_hs, _record, _msg, _crypto, _cert, _tickets | webrtc_dtls*_tests, webrtc_dtls_interop_SUITE, webrtc_bogo_SUITE | dtls, ADR 0001 |
| SRTP | src/srtp/webrtc_srtp.erl | _cipher, _kdf, _profile, _replay | webrtc_srtp_tests, prop_webrtc_srtp | srtp |
| Media session | src/media/webrtc_media.erl | webrtc_media_in (receive), webrtc_media_out (send), _fb (SLI, RPSI), _limit (TMMBR), _sync (RFC 6051), _rid (simulcast receive), _pause, _report, _codec (plugin behaviour) | webrtc_media_*_tests | rtp |
| RTP and RTCP codecs | src/rtp/webrtc_rtp.erl, webrtc_rtcp.erl | webrtc_rtcp_fb, _xr, _twcc, _ccfb, webrtc_rtp_ext, webrtc_rtcp_sched, _interval, webrtc_rtp_stats | webrtc_rtp*_tests, webrtc_rtcp*_tests, prop_webrtc_rtp, webrtc_corpus_tests | rtp |
| Retransmission, FEC, RED | src/rtp/webrtc_nack.erl, webrtc_nack_buffer.erl | webrtc_rtx, webrtc_red, webrtc_ulpfec, webrtc_flexfec | webrtc_nack_tests, webrtc_ulpfec_tests, webrtc_flexfec_tests, the GStreamer suites | rtp |
| Payload formats | src/rtp/webrtc_rtp_<codec>.erl | webrtc_rtp_vp8, _vp9, _h264, _av1, _opus | webrtc_rtp_<codec>_tests | rtp |
| Frames | src/rtp/webrtc_frame_buffer.erl | webrtc_frame_codec | webrtc_frame_buffer_tests, prop_webrtc_frames, webrtc_frames_gst_SUITE | rtp |
| Bandwidth limits from the peer | src/rtp/webrtc_tmmbr.erl | src/media/webrtc_media_limit.erl, src/cc/webrtc_rate_limit.erl | webrtc_tmmbr_tests, webrtc_media_tmmbr_tests | rtp, CCM rows |
| Congestion control | src/cc/webrtc_cc.erl | webrtc_gcc, _delay, _aimd, webrtc_pacer, webrtc_cc_probe, webrtc_twcc_*, webrtc_ccfb_receiver, webrtc_circuit_breaker | webrtc_cc_*_tests, webrtc_gcc_tests, webrtc_rmcat_tests, webrtc_cc_SUITE | rtp, RMCAT rows |
| SCTP and data channels | src/sctp/webrtc_sctp_assoc.erl, webrtc_dcep.erl | webrtc_sctp_send, _recv, _ack, _pr, _reconfig, _pmtu, _handshake, _chunk | webrtc_sctp_*_tests, the ETSI corpus, webrtc_examples_SUITE | sctp, guide |
| Statistics | src/pc/webrtc_stats.erl | src/media/webrtc_media_report.erl, src/rtp/webrtc_rtp_stats.erl | webrtc_stats_SUITE | stats |
| Safety: redaction, bounds, lifecycle | src/webrtc_redact.erl | src/webrtc_registry.erl, the bounds in src/media/webrtc_media.hrl | webrtc_security_SUITE, webrtc_lifecycle_SUITE, bench/webrtc_soak.erl | security |
Test helpers live in test/support: webrtc_impair (loss, reordering and outages between peers), webrtc_test_signal (signaling between two peer connections in a test), webrtc_test_codec (a codec plugin), webrtc_test_turn_udp (a TURN server) and webrtc_dtls_sim.
The rules
One responsibility per module
A module does one job that you can say in a sentence: "SCTP send side", "TURN ChannelData framing". Size is a signal to check that, not a limit: when a module grows well past its neighbours, ask whether it now does two jobs, and split it along that line if it does. Codecs (parse and build) stay separate from state machines.
The engine contract
Every protocol engine is a pure module with new/1, handle_packet, handle_timeout/2 and next_timeout/1, returning {State, Actions}:
{St1, Actions} = webrtc_dtls:handle_packet(Datagram, Now, St0),
Deadline = webrtc_dtls:next_timeout(St1).- No sockets, no timers, no clock: the caller passes
Now. - No process messages: output is a list of actions.
- Bounded state: every queue, buffer and table has a limit and a documented behaviour when it is reached.
- Malformed input returns
{State, []}or{error, _}, never an exception.
webrtc_transport (with webrtc_transport_net and webrtc_transport_secure, which share its state) is the only place that turns actions into I/O. ADR 0002 says why.
How the layers talk
webrtc_pc --configure(Negotiated)--> webrtc_transport
^ |
| {webrtc_transport, T, Event} | ICE valid pair -> DTLS start
| | DTLS connected -> export SRTP keys -> webrtc_media
| | DTLS connected + data m= line -> webrtc_dcep connect
application <-- {webrtc, Pc, Event} -----+ (RTP and channel messages go straight here)webrtc_jsep:negotiated/1 is the contract between negotiation and transport: ICE credentials and candidates, DTLS role and fingerprints, per-mid codecs, extension ids, SSRCs and simulcast layers, SCTP ports and message size. When you add something the transport must know, add it there.
Compliance rows
Every requirement you implement or change has a row in docs/compliance/<area>.md, with the module, the test, and the status the tests justify. A row never claims more than its tests show.
Conventions
- Module prefix
webrtc_,-specon every export. - RFC references name the section (
RFC 8445 ยง7.2.5) of the current document; a superseded RFC is named by its replacement. - Formatting:
rebar3 fmt. - OTP 29 and later.
If you want to...
Add a protocol feature
- Find the normative text. Add every MUST and SHOULD to the matching
docs/compliance/<area>.mdpage with status "Not implemented". - Write the failing test next to the module (
test/<module>_tests.erl), with the RFC's test vectors when it has some. - Implement it in the engine or codec.
- Add malformed input coverage for any new parser path.
- If it is visible end to end, add a case to
test/e2e/webrtc_pc_SUITE.erl, then to an interop suite. - Update the rows to the status the tests justify, and INTEROP.md for interop results.
Add an RTCP feedback message
- The codec: a record in
include/webrtc_rtp_rtcp.hrl, parse and build insrc/rtp/webrtc_rtcp_fb.erl, tests inwebrtc_rtcp_fb_tests. - The fuzz properties: if the format was kept raw so far, remove its exclusion from
prop_webrtc_rtp, and give its corpus file a verdict inwebrtc_corpus_tests. - The receive side: a clause in
webrtc_media_in:rtcp_packet2/3. - The negotiation: the
rtcp-fbvalue insrc/sdp/webrtc_jsep_caps.erl; the message is used only when both sides negotiated it. - Rows in rtp. The SLI and RPSI work (
webrtc_media_fb) is a complete example.
Add an RTP header extension
- The value codec in
src/rtp/webrtc_rtp_ext.erl, with tests inwebrtc_rtp_ext_tests. - Offer it:
webrtc_jsep_caps:default_extensions/1. - Send it:
webrtc_media_out:header_ext/2. Read it:webrtc_media_in. - The rapid synchronisation work (
webrtc_media_sync,ntp-64) is a complete example.
Add a payload format or a frame codec
src/rtp/webrtc_rtp_<codec>.erl: packetize and depacketize, key frame detection, with tests built on the format's examples.webrtc_frame_codec: map the codec name to the format;webrtc_frame_bufferthen assembles its frames.- Tests:
prop_webrtc_framesfor assembly under loss and reordering, andwebrtc_frames_gst_SUITEagainst GStreamer's payloader.
Add a peer connection option
- Validate it in
webrtc:new_pc/1; a bad value returns{error, {badarg, ...}}. - Pass it on: to JSEP through
webrtc_jsep:new/1, or to the transport through the optionswebrtc_pcbuilds for it. - Document it in REFERENCE.md;
webrtc_docs_testsfails until you do. - Add an e2e case in
webrtc_pc_SUITEthat shows its effect.
Add a transceiver option
- Accept it in
webrtc_jsep:add_transceiver/3and keep it in the#tr{}record. - Put it in the negotiated section:
webrtc_jsep_params:media_params/4. - Use it in the media session. The
priorityoption is a complete example. - Document it in REFERENCE.md.
Add an interop peer
- An adapter in
interop/<peer>/that speaks the protocol in interop/PROTOCOL.md. - Its start in
test/interop/webrtc_interop_peer.erl, a group inwebrtc_pc_interop_SUITE. - Its install step in CI, and a section in INTEROP.md.
Fix an interoperability failure
- Reproduce it with one interop case (see TESTING.md).
- Find which side breaks which requirement. Do not change our behaviour because one peer accepts it.
- Add a regression test at the lowest layer that shows the bug (codec or engine), then fix.
- If the other implementation is wrong, keep our behaviour and record the deviation in INTEROP.md, with a workaround only if it does not weaken compliance or security.
Debug a packet through the stack
A received datagram goes through, in order:
webrtc_transport_net:datagram/5: the socket message.webrtc_demux:classify/1: STUN, DTLS, TURN channel data or RTP, by the first byte.webrtc_transport_secure: DTLS records, then SRTP for RTP and RTCP.webrtc_media_in:rtp_in/3: the stream, RTX and FEC repair, NACK, the frame buffer.- The owner:
{webrtc, Pc, {rtp, Mid, Packet}}or{webrtc, Pc, {frame, Mid, Frame}}.
webrtc:get_stats(Pc) without options returns the internal counters, which say where packets were dropped. In a test, webrtc_impair puts loss, reordering or an outage between two peers.
Change how the stack behaves under a hostile peer
- The bounds of the media session are in
src/media/webrtc_media.hrl(MAX_STREAMS,MAX_ENDED); each engine documents its own. - Tests:
webrtc_media_bounds_tests,webrtc_security_SUITE, and the hostile parsers inprop_webrtc_parsers(make test-security). - For growth over time,
make soak DURATION=10churns connections with a hostile peer for 10 minutes and fails on growth (see PERFORMANCE.md). - Never raise a bound or drop a check to make a test pass. Record each bound in security.