devopvoid · Oct 23, 2026 · Oct 22, 2026
diff --git a/docs/guide/build.md b/docs/guide/build.md
@@ -1,22 +1,97 @@
 # Build Notes
 
-To build the native code, be sure to install the prerequisite software (follow the links):
+Building from source compiles three native libraries: Google's WebRTC, the JNI library around it, and FFmpeg with dav1d for the `webrtc-java-media` module. The tools below are what the build expects to find. The CI setup in `.github/actions/prepare-<os>/action.yml` installs the same set and is the reference when in doubt.
 
-**Note**: You don't have to install the Depot Tools, the build script will do that for you.
+You don't have to install Chromium's `depot_tools`, Siso or GN: the build clones `depot_tools` into the WebRTC checkout and uses the tools it brings.
 
-| OS        | Build Instructions                                                |
-| --------- | ----------------------------------------------------------------- |
-| Linux     | [Ubuntu][build-linux-ubuntu], [other distros][build-linux-other]  |
-| macOS     | Xcode 9 or higher                                                 |
-| Windows   | [Visual Studio][build-windows]                                    |
+## Prerequisites
 
-Assuming you have all the prerequisites installed for your OS, run:
+### All platforms
+
+| Tool                  | Notes                                                                                     |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| JDK 17 or newer       | The libraries target Java 8, but the JavaFX module needs 11 and the examples need 17.     |
+| Maven 3.6.3 or newer  |                                                                                           |
+| Git                   | Clones `depot_tools`, the WebRTC sources and the submodules.                              |
+| CMake 3.13 or newer   | Must be on the `PATH`. The Maven build does not download it.                              |
+| Python 3              | Runs `depot_tools` and the Linux sysroot script. On macOS it also needs `setuptools`.     |
+| Meson and Ninja       | Build dav1d, the AV1 software decoder linked into FFmpeg (`pip install meson`).           |
+| Disk space            | About 15 GB for the WebRTC checkout and its toolchains, kept in `~/webrtc` by default.   |
+
+FFmpeg and dav1d come from Git submodules, which a plain clone leaves empty. Fetch them before the first build:
+
+```shell
+git submodule update --init --depth 1 webrtc-java-media/third-party/ffmpeg webrtc-java-media/third-party/dav1d
+```
+
+### Linux
+
+Linux builds run on an x86-64 host and cross-compile for ARM. Install the build tools (Debian/Ubuntu package names):
+
+```shell
+sudo apt-get install binutils cmake git make meson nasm ninja-build pkg-config python3 python3-setuptools rsync unzip wget xz-utils
+```
+
+The JNI library compiles against the libc++ headers of the WebRTC build. Those headers only support the Clang that the WebRTC branch pins, so the toolchain files expect that exact Clang in `/opt/clang`. Install it this way (the package name is in `.github/actions/prepare-linux/action.yml` and changes with the WebRTC branch):
+
+```shell
+CLANG_PACKAGE=clang-llvmorg-24-init-7747-g62397f8b-27.tar.xz
+wget https://commondatastorage.googleapis.com/chromium-browser-clang/Linux_x64/$CLANG_PACKAGE
+sudo mkdir -p /opt/clang
+sudo tar -xf $CLANG_PACKAGE -C /opt/clang
+```
+
+Headers and libraries (X11, D-Bus, GIO, GBM, libdrm) come from a Debian sysroot in `/opt/sysroot` rather than from the host, so no `-dev` packages are needed. Install the sysroot for each target architecture you build for (`amd64`, `arm64` or `armhf`):
+
+```shell
+python3 webrtc-jni/src/main/cpp/dependencies/webrtc/linux/sysroot/install-sysroot.py --arch=amd64
+sudo mkdir -p /opt/sysroot
+sudo mv webrtc-jni/src/main/cpp/dependencies/webrtc/linux/debian* /opt/sysroot/
+```
+
+To cross-compile for ARM, CI also installs `gcc-aarch64-linux-gnu g++-aarch64-linux-gnu` (`-Plinux-aarch64`) or `gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf` (`-Plinux-aarch32`).
+
+Running the tests requires the runtime libraries the native library links against. A desktop system already has them. On a headless one, install them with:
+
+```shell
+sudo apt-get install libx11-6 libxext6 libxfixes3 libxdamage1 libxtst6 libxrandr2 libxcomposite1 libglib2.0-0 libgbm1 libdrm2
+```
+
+### macOS
+
+- Xcode 16 (CI uses 16.1), selected with `xcode-select`. The library targets macOS 11 and later.
+- The remaining tools from [Homebrew](https://brew.sh):
+
+```shell
+brew install cmake nasm meson ninja pkgconf python-setuptools
+```
+
+`nasm` is needed for the x86-64 build (`-Pmacos-cross-x86_64`), including when you cross-compile from Apple Silicon.
+
+### Windows
+
+- **Visual Studio 2022** with the *Desktop development with C++* workload. The build uses this local installation, not Google's internal toolchain. Add *MSVC ARM64 build tools* to build for `windows-aarch64`, and *C++ Clang tools for Windows* to build with `-Pwindows-clang`.
+- **Windows SDK 10.0.28000.0**, this exact version. The WebRTC branch pins it, and `gn gen` fails without it. Install it with the *Debugging Tools for Windows* feature, because the toolchain setup needs `dbghelp.dll`. A different WebRTC branch may pin a different SDK (`SDK_VERSION` in `build/vs_toolchain.py`).
+- **MSYS2**, installed in `C:\msys64` (set `MSYS2_ROOT` for another location). FFmpeg's configure scripts and makefiles need a POSIX shell with `make` and `nasm`. Git for Windows' bash has neither.
+
+  ```shell
+  winget install MSYS2.MSYS2
+  C:\msys64\usr\bin\bash -lc "pacman -S --needed make nasm diffutils pkgconf"
+  ```
+
+- **Ninja and Meson** on the `PATH`, e.g. `choco install ninja` and `pip install meson`.
+
+Run Maven from an ordinary command prompt or PowerShell. The build sets up the MSYS2 shell and the Visual Studio environment itself.
+
+## Building
+
+With the prerequisites installed, run:
 
 ```shell
 mvn install
 ```
 
-On the first run, the WebRTC source tree will be loaded into the `/<user home>/webrtc` directory. This will take a while and require about 20 GB of disk space.
+On the first run, the WebRTC source tree is loaded into the `/<user home>/webrtc` directory, and FFmpeg and dav1d are built into `/<user home>/ffmpeg`. This takes a long time. Later builds reuse both as long as their configuration is unchanged. To build the native libraries without running the tests, use `mvn package -DskipTests`, as CI does.
 
 ## Build Parameters
 
@@ -37,10 +112,6 @@ A compiled WebRTC build records its GN arguments, extra targets, and patch
 fingerprint. Changes to patch content invalidate both build-tree and installed
 caches, so a native rebuild also includes the updated patches.
 
-[build-linux-ubuntu]: https://chromium.googlesource.com/chromium/src/+/master/docs/linux/build_instructions.md#system-requirements
-[build-linux-other]: https://chromium.googlesource.com/chromium/src/+/master/docs/linux/build_instructions.md#Notes-for-other-distros
-[build-windows]: https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md#visual-studio
-
 ## Release workflow
 
 Maintainers start **Prepare release** (`release.yml`) from `main`, providing the