Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions .github/workflows/platforms.yml
Original file line number Diff line number Diff line change
Expand Up @@ -197,3 +197,79 @@ jobs:
java-distribution: temurin
version: ${{ inputs.version }}
jni-check: 'true'

# The native image example, built with GraalVM against the natives the build
# job uploaded, which the image carries inside itself. It connects two peers
# and exits with an error unless video, audio, channel messages, statistics
# and log messages all arrived. --exact-reachability-metadata makes anything
# the metadata of webrtc-java lacks fail at once, which would otherwise only
# fail where a lookup happens to find nothing.
native-image:
name: native-image (linux_x86-64)
needs: build
timeout-minutes: 30
runs-on: ubuntu-22.04
steps:
- name: Checkout code
uses: actions/checkout@v7
with:
ref: ${{ github.sha }}

- name: Download natives
uses: actions/download-artifact@v8
with:
name: natives-linux_x86-64
path: natives

- name: Download media natives
uses: actions/download-artifact@v8
with:
name: natives-media-linux_x86-64
path: natives

- name: Install runtime libraries
run: |
sudo apt-get update
sudo apt-get install -y libx11-6 libxext6 libxfixes3 libxdamage1 libxtst6 libxrandr2 libxcomposite1 libglib2.0-0 libgbm1 libdrm2

- name: Set up GraalVM
uses: graalvm/setup-graalvm@v1
with:
java-version: '25'
distribution: 'graalvm-community'

- name: Set the release dry-run version
if: inputs.version != ''
env:
RELEASE_VERSION: ${{ inputs.version }}
run: mvn -B versions:set -DnewVersion="$RELEASE_VERSION" -DgenerateBackupPoms=false

# The example resolves the libraries from the local repository, natives
# included, as an application does. webrtc attaches its natives from
# webrtc-jni/target and needs them installed beforehand, since it depends
# on them itself; webrtc-media packages its own from target/natives.
- name: Install the libraries with the natives
run: |
VERSION=$(sed -n 's|.*<version>\([^<]*\)</version>.*|\1|p' pom.xml | head -n 1)
WEBRTC_JAR=$(find natives -name 'webrtc-java-*-linux-x86_64.jar' ! -name 'webrtc-java-media-*' | head -n 1)
MEDIA_JAR=$(find natives -name 'webrtc-java-media-*-linux-x86_64.jar' | head -n 1)

if [ -z "$VERSION" ] || [ -z "$WEBRTC_JAR" ] || [ -z "$MEDIA_JAR" ]; then
echo "Missing the version ($VERSION) or a native jar ($WEBRTC_JAR, $MEDIA_JAR)" >&2
exit 1
fi

mvn -B -q install:install-file -Dfile="$WEBRTC_JAR" -DgroupId=dev.onvoid.webrtc \
-DartifactId=webrtc-java -Dversion="$VERSION" -Dpackaging=jar -Dclassifier=linux-x86_64

mkdir -p webrtc-jni/target webrtc-media/target/natives
cp "$WEBRTC_JAR" "webrtc-jni/target/webrtc-java-$VERSION-linux-x86_64.jar"
(cd webrtc-media/target/natives && "$JAVA_HOME/bin/jar" xf "$GITHUB_WORKSPACE/$MEDIA_JAR" && rm -rf META-INF)

mvn -B -pl webrtc,webrtc-media,webrtc-swing,webrtc-javafx install -DskipNativeBuild -DskipTests

- name: Build the native image
run: mvn -B -pl webrtc-examples -Pnative package

- name: Run the native image
run: timeout 120 webrtc-examples/target/webrtc-native-image-example
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ The library provides a comprehensive set of Java classes that map to the WebRTC

**Platforms**

Prebuilt native libraries behind a thin JNI layer:
Prebuilt native libraries behind a thin JNI layer, also in a **[GraalVM native image](https://jrtc.dev/guide/advanced/native-image)**, a single executable without an installed Java runtime:

| OS | x64 | arm64 | arm32 |
|---------|:---:|:-----:|:-----:|
Expand Down
1 change: 1 addition & 0 deletions docs/.vitepress/sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
{ text: 'End-to-End Encryption', link: '/advanced/end-to-end-encryption' },
{ text: 'Video Codecs', link: '/advanced/video-codecs' },
{ text: 'Audio Codecs', link: '/advanced/audio-codecs' },
{ text: 'GraalVM Native Image', link: '/advanced/native-image' },
],
},
]
Expand Down
111 changes: 111 additions & 0 deletions docs/guide/advanced/native-image.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# GraalVM Native Image

webrtc-java can be compiled into a [GraalVM native image](https://www.graalvm.org/latest/reference-manual/native-image/): one executable that starts in milliseconds and runs without an installed Java runtime. The jars bring the metadata the image needs, so an application needs no configuration of its own for webrtc-java.

## What the Jars Bring

A native image knows only the classes, members and resources it was told about at build time. `webrtc-java` and `webrtc-java-media` carry that metadata under `META-INF/native-image/dev.onvoid.webrtc/`, where `native-image` finds it on its own:

- **JNI.** The native library calls into Java from WebRTC's own threads: observers, sinks, the log sink, the classes it builds results from. Every class it uses is registered with all its members, the JDK classes with the members it calls.
- **Reflection.** The native library finds its classes through a class loader, and the Java code asks a few questions by reflection, such as whether an audio sink takes RTP packets.
- **Resources.** The native libraries of the native JARs, so that the image carries them.

The metadata is in the format GraalVM 21 and later read. It is tested with GraalVM 25 on Linux x86_64, also with `--exact-reachability-metadata`, under which anything missing fails at once.

## Building an Image

Add the [Native Build Tools](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html) plugin, and run `mvn -Pnative package` with a GraalVM as `JAVA_HOME`:

```xml
<profile>
<id>native</id>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<version>1.1.17</version>
<extensions>true</extensions>
<executions>
<execution>
<id>build-native</id>
<goals>
<goal>compile-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
<configuration>
<mainClass>com.example.App</mainClass>
<buildArgs>
<buildArg>--enable-native-access=ALL-UNNAMED</buildArg>
</buildArgs>
</configuration>
</plugin>
</plugins>
</build>
</profile>
```

`System.load` is a restricted method from JDK 24 on. Without `--enable-native-access`, an image built with GraalVM 24 or later prints a warning each time it loads the library. The option is the application's to give, and GraalVM 21 does not know it.

With Gradle, the [Gradle plugin](https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html) of the Native Build Tools does the same.

## Where the Native Library Is Loaded From

The [loading order](/guide/get-started#where-the-native-library-is-loaded-from) is the same as on the JVM, which gives an image two ways to get the library:

**Inside the image.** With the native JAR on the class path at build time, as Maven puts it there, the image carries the library. It writes it to the temporary directory when it starts and loads it from there, as the JVM does from the JAR, so the executable is all there is to ship. Set `webrtc.java.extract.dir` when the temporary directory does not allow running code:

```shell
./app -Dwebrtc.java.extract.dir=/var/lib/app/natives
```

**Next to the image.** Leave the native JAR off the class path at build time, and put the library next to the executable under its name in the native JAR, `libwebrtc-java-linux-x86_64.so` for example. With Maven, exclude the native JAR that `webrtc-java` brings along:

```xml
<dependency>
<groupId>dev.onvoid.webrtc</groupId>
<artifactId>webrtc-java</artifactId>
<version>{{ VERSION }}</version>
<exclusions>
<!-- The native JAR, which has the same coordinates and a platform classifier. -->
<exclusion>
<groupId>dev.onvoid.webrtc</groupId>
<artifactId>webrtc-java</artifactId>
</exclusion>
</exclusions>
</dependency>
```

In a native image `System.loadLibrary` looks in the directory of the executable, so nothing has to be set. The executable gets smaller by the size of the library, and nothing is written to disk at start. A different directory is named with `webrtc.java.library.dir`, as on the JVM.

The media module works the same way: its library and the FFmpeg libraries are carried inside the image, or go next to it under their names in its native JAR, `libavcodec.so.62` and so on.

An image is built for one platform, so it carries the library of the platform it was built on. Build it on each platform it is meant for.

## Audio Sinks with RTP Packets

An `AudioTrackSink` may implement the `onData` method that also receives [the RTP packets](/guide/audio/headless-audio#who-sent-the-received-audio) the audio was assembled from. Whether a sink does is found out by reflection, which a native image answers only for registered classes. For any other sink, an anonymous class or a lambda among them, the packets are collected: a sink that implements the method gets them, one that does not gets its audio without them, as on the JVM. To spare the collecting, register the sink class for the query:

```json
[
{ "name": "com.example.LevelMeter", "queryAllPublicMethods": true }
]
```

in `src/main/resources/META-INF/native-image/<group>/<artifact>/reflect-config.json` of the application.

## Not Covered

- **Swing and JavaFX.** The video views of `webrtc-java-swing` and `webrtc-java-javafx` have no metadata of their own. AWT and Swing need GraalVM's own AWT support, JavaFX the [Gluon](https://gluonhq.com/products/substrate/) toolchain.
- **Classes of the application** that it hands to webrtc-java are covered as far as webrtc-java uses them: a callback is called through its interface, which is registered. What the application itself does by reflection is the application's to register, for example with the [tracing agent](https://www.graalvm.org/latest/reference-manual/native-image/metadata/AutomaticMetadataCollection/).

## Example

The [`NativeImageExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/NativeImageExample.java) connects two peers in one process and checks that video, audio, data channel messages, statistics and log messages arrive. It exits with status 0 only if they all did, and builds with `--exact-reachability-metadata`, which needs GraalVM 24 or later:

```shell
mvn -pl webrtc-examples -Pnative package
webrtc-examples/target/webrtc-native-image-example
```
17 changes: 17 additions & 0 deletions docs/guide/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,23 @@ This example is the shortest way to see a complete call working, and a starting
mvn exec:java -D"exec.mainClass=dev.onvoid.webrtc.examples.ClientApiExample" -D"exec.args=10"
```

## Native Image

The [`NativeImageExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/NativeImageExample.java) is made to be compiled into a [GraalVM native image](/guide/advanced/native-image), a single executable that needs no installed Java runtime. It connects two peers in one process and checks itself: it exits with status 0 only if everything arrived.

**Key features demonstrated:**
- Loading the native library that the image carries inside itself
- Callbacks from WebRTC's threads: negotiation, ICE candidates, tracks and channel messages
- Video frames, audio and statistics that the native code hands to Java
- A log sink, called by WebRTC's logging from any thread

Build it with GraalVM 24 or later as `JAVA_HOME`, then run it:

```bash
mvn -pl webrtc-examples -Pnative package
webrtc-examples/target/webrtc-native-image-example
```

## File Transfer

The [`FileTransferExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/FileTransferExample.java) connects two peers in one process with the [Client API](/guide/client-api), and sends a file from one to the other with [File Transfer](/guide/data/file-transfer). It needs no audio or video hardware and no server.
Expand Down
2 changes: 2 additions & 0 deletions docs/guide/get-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,8 @@ java -Dwebrtc.java.extract.dir=/var/lib/myapp/natives -jar myapp.jar

A library loaded from a directory keeps the file name it has in the native JAR, for example `libwebrtc-java-linux-x86_64.so`. The media module's library is found the same way; its FFmpeg libraries go next to it under their names in its native JAR (`libavcodec.so.62` and so on). If the library is found nowhere, the `UnsatisfiedLinkError` lists every place that was tried.

A [GraalVM native image](/guide/advanced/native-image) carries the library inside itself, or finds it next to the executable.

The Linux libraries are built against glibc. They do not load on a system with the musl C library, such as Alpine Linux; the error says so when it finds one.

## Your First Call
Expand Down
50 changes: 50 additions & 0 deletions webrtc-examples/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,56 @@
</resources>
</build>

<profiles>
<!--
Compiles NativeImageExample into a GraalVM native image,
target/webrtc-native-image-example, which carries the native
library inside itself. Needs GraalVM 24 or later as JAVA_HOME
(or GRAALVM_HOME): mvn -pl webrtc-examples -Pnative package
-->
<profile>
<id>native</id>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<version>1.1.17</version>
<extensions>true</extensions>
<executions>
<execution>
<id>build-native</id>
<goals>
<goal>compile-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
<configuration>
<imageName>webrtc-native-image-example</imageName>
<mainClass>dev.onvoid.webrtc.examples.NativeImageExample</mainClass>
<buildArgs>
<!-- System.load is a restricted method from JDK 24 on, and
the image would warn about it on every start. -->
<buildArg>--enable-native-access=ALL-UNNAMED</buildArg>
<!-- A class, member or resource the metadata lacks fails
at once, instead of only where a lookup happens to
find nothing, so that the example checks the
metadata of webrtc-java. -->
<buildArg>--exact-reachability-metadata</buildArg>
</buildArgs>
<!-- webrtc-java brings its own metadata; nothing else this
example runs needs any. -->
<metadataRepository>
<enabled>false</enabled>
</metadataRepository>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>

<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
Expand Down
Loading
Loading