Change the code

View Source

This 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

  1. CONCEPTS.md: the vocabulary (peer connection, transport, mid, SSRC, engine).
  2. ARCHITECTURE.md: the layers, the processes and the packet paths.
  3. This page: where things live and how to change them.
  4. 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.

AreaStart withAlsoTestsRequirements
Public API, option validationsrc/webrtc.erltest/e2e/webrtc_pc_SUITE.erlREFERENCE.md
Peer connection process, supervisionsrc/pc/webrtc_pc.erlwebrtc_peer_sup, webrtc_pc_sup, src/webrtc_registry.erlwebrtc_pc_SUITE, webrtc_lifecycle_SUITEARCHITECTURE.md
Offer and answer (JSEP)src/sdp/webrtc_jsep.erlwebrtc_jsep_build (offers, answers), _params (what each side negotiated), _caps (codecs, extensions, feedback), _simulcast, _transport (BUNDLE groups)webrtc_jsep_tests, prop_webrtc_sdpsdp
SDP textsrc/sdp/webrtc_sdp.erlwebrtc_sdp_attr, _media, _rtp, _rid, _candidate, _lexwebrtc_sdp_testssdp
Transport processsrc/transport/webrtc_transport.erl_net (sockets, datagrams, ICE actions), _secure (DTLS, SRTP keys, media and SCTP actions), webrtc_demuxwebrtc_pc_SUITE, webrtc_security_SUITEtransport
DSCP markingsrc/transport/webrtc_dscp.erlsrc/ice/webrtc_ice_marks.erlwebrtc_dscp_teststransport, TR-20 and on
Candidate names, mDNSsrc/mdns/webrtc_mdns.erl_resolver, _responder (engines), _client, _msg, _publicwebrtc_mdns_SUITEice
ICEsrc/ice/webrtc_ice_agent.erl_checklist, _conncheck, _responder, _session (nomination), _consent, _gather, _relay, _tcp, _resolve, _uriwebrtc_ice_*_tests, webrtc_ice_net_testsice
STUN and TURNsrc/stun/webrtc_stun.erlwebrtc_stun_tx, webrtc_turn_client, _auth, _channel, _streamwebrtc_stun_tests, webrtc_turn_*_tests, webrtc_turn_interop_SUITEstun, turn
DTLSsrc/dtls/webrtc_dtls.erlwebrtc_dtls12, webrtc_dtls13*, webrtc_dtls_hs, _record, _msg, _crypto, _cert, _ticketswebrtc_dtls*_tests, webrtc_dtls_interop_SUITE, webrtc_bogo_SUITEdtls, ADR 0001
SRTPsrc/srtp/webrtc_srtp.erl_cipher, _kdf, _profile, _replaywebrtc_srtp_tests, prop_webrtc_srtpsrtp
Media sessionsrc/media/webrtc_media.erlwebrtc_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_*_testsrtp
RTP and RTCP codecssrc/rtp/webrtc_rtp.erl, webrtc_rtcp.erlwebrtc_rtcp_fb, _xr, _twcc, _ccfb, webrtc_rtp_ext, webrtc_rtcp_sched, _interval, webrtc_rtp_statswebrtc_rtp*_tests, webrtc_rtcp*_tests, prop_webrtc_rtp, webrtc_corpus_testsrtp
Retransmission, FEC, REDsrc/rtp/webrtc_nack.erl, webrtc_nack_buffer.erlwebrtc_rtx, webrtc_red, webrtc_ulpfec, webrtc_flexfecwebrtc_nack_tests, webrtc_ulpfec_tests, webrtc_flexfec_tests, the GStreamer suitesrtp
Payload formatssrc/rtp/webrtc_rtp_<codec>.erlwebrtc_rtp_vp8, _vp9, _h264, _av1, _opuswebrtc_rtp_<codec>_testsrtp
Framessrc/rtp/webrtc_frame_buffer.erlwebrtc_frame_codecwebrtc_frame_buffer_tests, prop_webrtc_frames, webrtc_frames_gst_SUITErtp
Bandwidth limits from the peersrc/rtp/webrtc_tmmbr.erlsrc/media/webrtc_media_limit.erl, src/cc/webrtc_rate_limit.erlwebrtc_tmmbr_tests, webrtc_media_tmmbr_testsrtp, CCM rows
Congestion controlsrc/cc/webrtc_cc.erlwebrtc_gcc, _delay, _aimd, webrtc_pacer, webrtc_cc_probe, webrtc_twcc_*, webrtc_ccfb_receiver, webrtc_circuit_breakerwebrtc_cc_*_tests, webrtc_gcc_tests, webrtc_rmcat_tests, webrtc_cc_SUITErtp, RMCAT rows
SCTP and data channelssrc/sctp/webrtc_sctp_assoc.erl, webrtc_dcep.erlwebrtc_sctp_send, _recv, _ack, _pr, _reconfig, _pmtu, _handshake, _chunkwebrtc_sctp_*_tests, the ETSI corpus, webrtc_examples_SUITEsctp, guide
Statisticssrc/pc/webrtc_stats.erlsrc/media/webrtc_media_report.erl, src/rtp/webrtc_rtp_stats.erlwebrtc_stats_SUITEstats
Safety: redaction, bounds, lifecyclesrc/webrtc_redact.erlsrc/webrtc_registry.erl, the bounds in src/media/webrtc_media.hrlwebrtc_security_SUITE, webrtc_lifecycle_SUITE, bench/webrtc_soak.erlsecurity

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_, -spec on 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

  1. Find the normative text. Add every MUST and SHOULD to the matching docs/compliance/<area>.md page with status "Not implemented".
  2. Write the failing test next to the module (test/<module>_tests.erl), with the RFC's test vectors when it has some.
  3. Implement it in the engine or codec.
  4. Add malformed input coverage for any new parser path.
  5. If it is visible end to end, add a case to test/e2e/webrtc_pc_SUITE.erl, then to an interop suite.
  6. Update the rows to the status the tests justify, and INTEROP.md for interop results.

Add an RTCP feedback message

  1. The codec: a record in include/webrtc_rtp_rtcp.hrl, parse and build in src/rtp/webrtc_rtcp_fb.erl, tests in webrtc_rtcp_fb_tests.
  2. 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 in webrtc_corpus_tests.
  3. The receive side: a clause in webrtc_media_in:rtcp_packet2/3.
  4. The negotiation: the rtcp-fb value in src/sdp/webrtc_jsep_caps.erl; the message is used only when both sides negotiated it.
  5. Rows in rtp. The SLI and RPSI work (webrtc_media_fb) is a complete example.

Add an RTP header extension

  1. The value codec in src/rtp/webrtc_rtp_ext.erl, with tests in webrtc_rtp_ext_tests.
  2. Offer it: webrtc_jsep_caps:default_extensions/1.
  3. Send it: webrtc_media_out:header_ext/2. Read it: webrtc_media_in.
  4. The rapid synchronisation work (webrtc_media_sync, ntp-64) is a complete example.

Add a payload format or a frame codec

  1. src/rtp/webrtc_rtp_<codec>.erl: packetize and depacketize, key frame detection, with tests built on the format's examples.
  2. webrtc_frame_codec: map the codec name to the format; webrtc_frame_buffer then assembles its frames.
  3. Tests: prop_webrtc_frames for assembly under loss and reordering, and webrtc_frames_gst_SUITE against GStreamer's payloader.

Add a peer connection option

  1. Validate it in webrtc:new_pc/1; a bad value returns {error, {badarg, ...}}.
  2. Pass it on: to JSEP through webrtc_jsep:new/1, or to the transport through the options webrtc_pc builds for it.
  3. Document it in REFERENCE.md; webrtc_docs_tests fails until you do.
  4. Add an e2e case in webrtc_pc_SUITE that shows its effect.

Add a transceiver option

  1. Accept it in webrtc_jsep:add_transceiver/3 and keep it in the #tr{} record.
  2. Put it in the negotiated section: webrtc_jsep_params:media_params/4.
  3. Use it in the media session. The priority option is a complete example.
  4. Document it in REFERENCE.md.

Add an interop peer

  1. An adapter in interop/<peer>/ that speaks the protocol in interop/PROTOCOL.md.
  2. Its start in test/interop/webrtc_interop_peer.erl, a group in webrtc_pc_interop_SUITE.
  3. Its install step in CI, and a section in INTEROP.md.

Fix an interoperability failure

  1. Reproduce it with one interop case (see TESTING.md).
  2. Find which side breaks which requirement. Do not change our behaviour because one peer accepts it.
  3. Add a regression test at the lowest layer that shows the bug (codec or engine), then fix.
  4. 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:

  1. webrtc_transport_net:datagram/5: the socket message.
  2. webrtc_demux:classify/1: STUN, DTLS, TURN channel data or RTP, by the first byte.
  3. webrtc_transport_secure: DTLS records, then SRTP for RTP and RTCP.
  4. webrtc_media_in:rtp_in/3: the stream, RTX and FEC repair, NACK, the frame buffer.
  5. 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

  1. The bounds of the media session are in src/media/webrtc_media.hrl (MAX_STREAMS, MAX_ENDED); each engine documents its own.
  2. Tests: webrtc_media_bounds_tests, webrtc_security_SUITE, and the hostile parsers in prop_webrtc_parsers (make test-security).
  3. For growth over time, make soak DURATION=10 churns connections with a hostile peer for 10 minutes and fails on growth (see PERFORMANCE.md).
  4. Never raise a bound or drop a check to make a test pass. Record each bound in security.