Contributing
View SourceThis page is for people changing erlang_webrtc_codecs itself. For using it, start with the README and docs/raw-media.md.
Write for the person who reads it
Every issue, pull request and comment is read by a person. Make it easy for them.
- Read what you send before you send it. You are responsible for every line, whether you wrote it or a tool did.
- Use plain English and short sentences. Say what happens, what you expected, and how to reproduce it. Explain any term a reader may not know.
- Don't inflate it. No buzzwords, no severity scores, no "critical" for a bug, no long generated write-ups. If it takes a page to explain, cut it down until it doesn't.
- A bug report gives: the erlang_webrtc_codecs, erlang_webrtc and OTP versions, the operating system, the codec and the version of its library, the options you set, a minimal reproduction, what you got and what you expected. A file with the frames that fail helps most.
- A pull request says what was wrong and why it matters, the fix in a few lines, and any breaking change. Link the issue. Don't walk through the diff file by file; the reviewer reads the code.
- A fix comes with a test that fails without it.
For a security problem, follow SECURITY.md instead of opening an issue.
AI tools are fine to use. Before you open anything, you must have read the change, run the tests, and be able to answer questions about it yourself.
Set up
You need Erlang/OTP 29 or later, rebar3, CMake, pkg-config and a C compiler,
plus the codec libraries: libopus, libvpx, OpenH264, dav1d and libaom.
docs/install.md has the packages for each system. A codec whose library is missing is left
out and its tests skip themselves. Install ffmpeg to run the tests that
compare with it; they skip themselves too.
git clone https://github.com/benoitc/erlang_webrtc_codecs.git
cd erlang_webrtc_codecs
rebar3 compile
Before you commit
Run what CI runs:
rebar3 fmt # format first, then check the rest
rebar3 compile
rebar3 eunit
rebar3 ct
rebar3 fmt --check
rebar3 lint
rebar3 xref
rebar3 dialyzer
rebar3 ex_doc
Tests
test/webrtc_codecs_*_tests.erlare EUnit tests of the modules on their own, run byrebar3 eunit.test/webrtc_codecs_*_SUITE.erlare Common Test suites that run the plugins inside two erlang_webrtc peer connections on loopback, run byrebar3 ct.
webrtc_codecs_browser_SUITE runs the video plugins against headless
Chromium, both ways. It uses the browser peer of erlang_webrtc's interop
suite, which this package does not carry:
cd ../erlang_webrtc/interop/browser && npm ci && npx playwright install chromium
export WEBRTC_CODECS_BROWSER_PEER=$PWD
Without it, or without node, the suite skips itself with the reason. It
looks in ../erlang_webrtc/interop/browser when the variable is not set.
Test on Linux and FreeBSD
The native code has to build and pass on the three systems. From macOS or Linux, run the same tests on the other two:
rebar3 compile # fetches the dependencies the copies carry
scripts/test-linux.sh # Debian in Docker
WEBRTC_CODECS_LINUX=alpine scripts/test-linux.sh # Alpine, for musl
scripts/test-freebsd.sh # FreeBSD in a QEMU virtual machine
Each builds a copy of the sources with every codec library required, so a
library that is missing there is a failure, not a skip. Give a command to
run something else, for example scripts/test-linux.sh rebar3 dialyzer.
The FreeBSD script downloads the official cloud image once (600 MB, checked
against its published checksum), keeps the machine's disk in
~/.cache/webrtc_codecs/freebsd, and leaves the machine running between
runs: scripts/test-freebsd.sh stop ends it, destroy also forgets its
disk. It needs qemu, and listens for SSH on 127.0.0.1:52222
(WEBRTC_CODECS_FREEBSD_PORT to change it).
For a change to native code, run the tests with the NIFs built with ASan, UBSan and fault injection, which makes each allocation of a constructor fail in turn:
scripts/test-sanitizers.sh
The browser suite only runs on the machine you work on.
CI runs the same on GitHub: Linux with every check, then macOS and FreeBSD with the tests.
A codec gets a round trip (encode, decode, compare with
webrtc_codecs_pattern:psnr/2 or snr/2), a comparison with another
implementation where one is at hand, and the error paths: raw media in the
wrong format, and a truncated or corrupt frame.
Add a codec
- Write
src/webrtc_codecs_<family>.erlwith thewebrtc_media_codecbehaviour andcodecs/0, which lists the codecs the module can run in this build. A video codec also implementswebrtc_codecs_videoand delegates to it, and its tests runwebrtc_codecs_video_checks:all/1. - Add the module to
?MODULESinsrc/webrtc_codecs.erl. For a native codec, add the NIF toc_src/CMakeLists.txtwithadd_codec_nifand its library toWEBRTC_CODECS_REQUIREin the CI workflow. - Follow docs/raw-media.md for what
decode/2gives andencode/2takes, and the rules in AGENTS.md for native code. - Add its guide under
docs/, a row in the README table and a CHANGELOG entry.
Documentation
Guides are task-oriented and in the second person: one paragraph saying what the page is and when you need it, then steps with code, then short notes.