@/webrtc

🚧 Beta
This library is in a beta state. It is not yet ready for production use.

📺 Part of the Astronaut Labs Broadcast Suite

Originally published as wrtc, forked primarily for use in Astronaut Labs Broadcast Stack. Feel free to use for your own purposes as well.

Node.js implementation of WebRTC API using Chromium WebRTC M150. This project aims for spec-compliance and is tested using the W3C's web-platform-tests project. A number of nonstandard APIs for testing are also included.

Install

npm install @astronautlabs/webrtc

Installing from NPM downloads a prebuilt binary for your operating system × architecture. Set the TARGET_ARCH environment variable to "arm" or "arm64" to download for armv7l or arm64, respectively. Linux and macOS users can also set the DEBUG environment variable to download debug builds.

You can also build from source.

Supported Platforms

Supports Node API v9 (Node.js 18+)

For the following platforms:

• Linux
• macOS
• Windows

On the following architectures:

• x64
• arm64

Build validation is not yet in place for all of these platforms.

Troubleshooting

Node.js >= 26.0.0 && < 26.3.0 on Windows

Node.js has started building with ClangCL, which triggers the bundled node-gyp to try to build normal .gyp addons like libyuv (which is a dependency of @/webrtc) using ClangCL, but simultaneously passes MSVC specific arguments such as /ltcg:incremental which causes the libyuv build to fail on npm install.

Solution: Either upgrade Node.js to 26.3 or later, or install a node-gyp@10.3 or later.

It is not in our interest to produce a workaround on our end for this short series of Node.js builds which are not in the LTS branch, especially when there are easy workarounds by upgrading Node.js or node-gyp.

Developers

This section has notes about how to be productive working with this codebase including building it from source.

Build Tools & Prerequisites

Linux:

• python 3.10.12+
• llvm/clang 22+
  If you use LLVM's Apt repository, ensure you have unprefixed versions of at least clang, clang++ and llvm-ar:

  sudo ln -s `which clang-22` /usr/local/bin/clang
  sudo ln -s `which clang++-22` /usr/local/bin/clang++
  sudo ln -s `which llvm-ar-22` /usr/local/bin/llvm-ar

• cmake 3.22.1+
• ninja 1.10.1+
• libnspr4/libnss3 (if you want to run the browser tests)

Windows:

• Python3
• Make sure long path support is enabled
  • Set HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnable to 1
  • git config --global core.longpaths true
  • git config core.longpaths true
• Install VS 2026 [Community edition is fine]
• Install Windows 10 or 11 SDK
• Install LLVM 22 or newer (from https://llvm.org/)
• Install cmake 4.4 or later

Build Commands

• npm run build - Compile everything
• npm run build:native - Compile libwebrtc and the Node.js addon in release mode
• npm run build:native:debug - Compile libwebrtc and Node.js addon in debug mode
• npm run build:native:webrtc - Compile libwebrtc in release mode. Note this can take a long time without a strong system, and the results are aggressively cached. If you make changes to the libwebrtc revision (see scripts/build-webrtc.ts) or anything else, you should delete build/external/webrtc to start fresh.
• npm run build:tsc - Compiles the Typescript sources into Javascript

IDEs

Visual Studio Code + clangd

This project will generate build/compile_commands.json when you use a developer build (npm run build:dev). The clangd VS Code extension will pick this up out of the box, providing excellent intellisense for the project.

CLion

This should work out of the box, except you need to make sure your node binary is available to CLion, which might not be the case if you are using NVM and have added its shell integration in .bashrc or .bash_profile instead of .profile. Also CLion has an option (default enabled in newer versions) to use the shell when executing commands, you would need that turned on. None of this applies if your Node is installed at the system level.

While CLion should more or less work, you are likely to have a better dev experience with VSC and clangd.

Debugging CI Core Dumps

In the event of test failure, the test job will collect any core dumps and deposit them as CircleCI Artifacts. You can then download the core dumps and debug them using gdb.

You can download the Debug binary from the build job that spawned the corresponding test job. Place it in your workspace as build/Debug/wrtc.node.

You'll also need to be running the exact same version of Node.js in order for the symbols to line up.

nvm install <node-version-that-crashed>
nvm use <node-version-that-crashed>

To load a dump and get its backtrace:

$ gdb $(which node) core-dump-filename
(gdb) set solib-search-path build/Debug/
(gdb) bt

If you have the wrong Node.js version (or if the build of that version is incompatible with the one from CI), or if you forget to set the solib-search-path to look in build/Debug, all but the Node.js symbols will be unknown (?? in GDB).

Required Reading

References

• RTP: A Transport Protocol for Real-Time Applications (IETF RFC 3550)
• Unified Plan
• Plan B
• RTCRtpTransceiver (MDN)
• Negotiating Media Multiplexing Using the Session Description Protocol ("BUNDLE" IETF I-D)

Editorial

• The evolution of WebRTC 1.0. (Mozilla)
• Exploring RTCRtpTransceiver. (Mozilla)
• Webrtc with transceivers (nterreri)