+ * The container follows the file name: {@code .mkv} (Matroska) holds every
+ * codec WebRTC sends and is the safe choice; {@code .webm} holds VP8, VP9,
+ * AV1 and Opus; {@code .mp4} holds H.264, H.265, AV1, VP9 and Opus, and is
+ * written fragmented, so that it plays up to where a recording was cut short.
+ * A track whose codec the file cannot hold is left out and reported to the
+ * {@link MediaRecorderListener#onWarning(String) listener}.
+ *
keyFrameRequests = new CopyOnWriteArrayList<>();
+
+ /** Read on the event thread, so never a stale value. */
+ private volatile MediaRecorderListener listener;
+
+ /** Where listener calls and key frame requests run. */
+ private ExecutorService events;
+
+ /** The native recorder, or 0 once this recorder has been closed. */
+ private long handle;
+
+ private MediaRecorderState state = MediaRecorderState.IDLE;
+
+
+ /**
+ * Creates a recorder writing to the given file, which is created, or
+ * emptied if it exists.
+ *
+ * @param file Where to record to; its extension picks the container.
+ *
+ * @throws IOException If the file cannot be written.
+ */
+ public MediaRecorder(Path file) throws IOException {
+ Objects.requireNonNull(file, "File is null");
+
+ this.file = file.toAbsolutePath();
+ this.handle = create(this.file.toString(), NativeApi.tableAddress());
+ }
+
+ /**
+ * Sets what to report to, replacing whatever was set before. A listener of
+ * {@code null} stops reporting.
+ *
+ * @param listener The listener, or {@code null}.
+ */
+ public void setListener(MediaRecorderListener listener) {
+ this.listener = listener;
+ }
+
+ /**
+ * Records what the given sender sends, as it comes out of the encoder.
+ *
+ * @param sender The sender to record.
+ *
+ * @throws IllegalStateException If the recorder was started or closed.
+ * @throws IllegalArgumentException If the sender was disposed.
+ */
+ public void addTrack(RTCRtpSender sender) {
+ Objects.requireNonNull(sender, "Sender is null");
+
+ synchronized (lock) {
+ checkState(MediaRecorderState.IDLE);
+
+ addTrack(NativeApi.encodedFramesOf(sender), sender::generateKeyFrame);
+ }
+ }
+
+ /**
+ * Records what the given receiver receives, as it goes into the decoder.
+ *
+ * @param receiver The receiver to record.
+ *
+ * @throws IllegalStateException If the recorder was started or closed.
+ * @throws IllegalArgumentException If the receiver was disposed.
+ */
+ public void addTrack(RTCRtpReceiver receiver) {
+ Objects.requireNonNull(receiver, "Receiver is null");
+
+ synchronized (lock) {
+ checkState(MediaRecorderState.IDLE);
+
+ addTrack(NativeApi.encodedFramesOf(receiver), receiver::requestKeyFrame);
+ }
+ }
+
+ /**
+ * Starts recording the tracks added so far.
+ *
+ * @throws IllegalStateException If the recorder has no tracks, or was
+ * started or closed before.
+ */
+ public void start() {
+ synchronized (lock) {
+ checkState(MediaRecorderState.IDLE);
+
+ if (keyFrameRequests.isEmpty()) {
+ throw new IllegalStateException("A recorder needs at least one track");
+ }
+
+ events = Executors.newSingleThreadExecutor(runnable -> {
+ Thread thread = new Thread(runnable, "MediaRecorder-events");
+ thread.setDaemon(true);
+ return thread;
+ });
+
+ state = MediaRecorderState.RECORDING;
+
+ start(handle);
+ }
+ }
+
+ /**
+ * Stops recording and finishes the file, waiting for everything received
+ * so far to be written. A recorder that never got any media to write
+ * deletes its file rather than leave an unplayable one behind.
+ *
+ * Stopping a recorder that is stopped does nothing. Stopping one that was
+ * never started deletes its file.
+ *
+ * @return True if the file holds a recording, false if it was deleted.
+ */
+ public boolean stop() {
+ boolean recorded;
+
+ synchronized (lock) {
+ if (handle == 0) {
+ return false;
+ }
+ if (state == MediaRecorderState.STOPPED) {
+ return Files.exists(file);
+ }
+
+ recorded = stop(handle);
+ state = MediaRecorderState.STOPPED;
+
+ if (events != null) {
+ // Lets the reports already queued run, then ends the thread.
+ events.shutdown();
+ }
+ }
+
+ if (!recorded) {
+ try {
+ Files.deleteIfExists(file);
+ }
+ catch (IOException e) {
+ // The file stays behind, empty; there is nothing else to do.
+ }
+ }
+
+ return recorded;
+ }
+
+ /**
+ * Returns what the recorder is currently doing.
+ *
+ * @return The recorder state.
+ */
+ public MediaRecorderState getState() {
+ synchronized (lock) {
+ return state;
+ }
+ }
+
+ /**
+ * @return The file this recorder writes to.
+ */
+ public Path getFile() {
+ return file;
+ }
+
+ /**
+ * Stops the recording if it still runs and releases the native recorder.
+ * Closing a recorder that is closed does nothing.
+ */
+ @Override
+ public void close() {
+ stop();
+
+ synchronized (lock) {
+ if (handle != 0) {
+ dispose(handle);
+ handle = 0;
+ }
+ }
+ }
+
+ /** Called with the lock held, in the idle state. */
+ private void addTrack(long frames, Runnable keyFrameRequest) {
+ if (frames == 0) {
+ throw new IllegalArgumentException("The sender or receiver was disposed");
+ }
+
+ // The native recorder takes over the reference the handle carries.
+ addTrack(handle, frames);
+
+ keyFrameRequests.add(keyFrameRequest);
+ }
+
+ private void checkState(MediaRecorderState expected) {
+ if (handle == 0) {
+ throw new IllegalStateException("The recorder is closed");
+ }
+ if (state != expected) {
+ throw new IllegalStateException("The recorder is " + state.name().toLowerCase()
+ + ", not " + expected.name().toLowerCase());
+ }
+ }
+
+ private void post(Runnable event) {
+ ExecutorService executor = events;
+
+ if (executor == null) {
+ return;
+ }
+
+ try {
+ executor.execute(() -> {
+ try {
+ event.run();
+ }
+ catch (Throwable e) {
+ Thread thread = Thread.currentThread();
+ thread.getUncaughtExceptionHandler().uncaughtException(thread, e);
+ }
+ });
+ }
+ catch (RejectedExecutionException e) {
+ // Stopped in the meantime; nobody is waiting for this any more.
+ }
+ }
+
+ /** Called by native code on the writer thread. */
+ private void onNativeStarted() {
+ post(() -> {
+ MediaRecorderListener current = listener;
+
+ if (current != null) {
+ current.onStarted();
+ }
+ });
+ }
+
+ /** Called by native code on the writer thread. */
+ private void onNativeWarning(String message) {
+ post(() -> {
+ MediaRecorderListener current = listener;
+
+ if (current != null) {
+ current.onWarning(message);
+ }
+ });
+ }
+
+ /** Called by native code on the writer thread. */
+ private void onNativeError(String message) {
+ post(() -> {
+ MediaRecorderListener current = listener;
+
+ if (current != null) {
+ current.onError(message);
+ }
+ });
+ }
+
+ /** Called by native code on the writer thread. */
+ private void onNativeKeyFrameNeeded(int track) {
+ if (track < 0 || track >= keyFrameRequests.size()) {
+ return;
+ }
+
+ Runnable request = keyFrameRequests.get(track);
+
+ // Run away from the writer thread: asking WebRTC waits for its
+ // signaling thread, which may be busy stopping this very recorder.
+ post(() -> {
+ try {
+ request.run();
+ }
+ catch (RuntimeException e) {
+ // Not negotiated yet, or disposed of by the application. The
+ // recording waits for the next key frame instead.
+ }
+ });
+ }
+
+ private native long create(String path, long tableAddress) throws IOException;
+
+ private static native int addTrack(long handle, long frames);
+
+ private static native void start(long handle);
+
+ private static native boolean stop(long handle);
+
+ private static native void dispose(long handle);
+
+}
diff --git a/webrtc-java-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderListener.java b/webrtc-java-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderListener.java
new file mode 100644
index 00000000..56ebaba6
--- /dev/null
+++ b/webrtc-java-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderListener.java
@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026 Alex Andres
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package dev.onvoid.webrtc.media.recorder;
+
+/**
+ * What a {@link MediaRecorder} reports while it records.
+ *
+ * Calls arrive in order on a thread the recorder keeps for them, never on a
+ * thread that carries media, so an implementation may take its time and may
+ * call back into the recorder, including to stop it.
+ *
+ * @author Alex Andres
+ */
+public interface MediaRecorderListener {
+
+ /**
+ * The file header was written and media now goes into the file. This
+ * happens once every track has sent enough to describe its stream (for
+ * video, its first key frame), or once the tracks that have waited a few
+ * seconds for the others.
+ */
+ default void onStarted() {
+ }
+
+ /**
+ * Something went wrong that the recording carries on without, e.g. a
+ * track whose codec the file cannot hold, which is then left out.
+ *
+ * @param message What went wrong.
+ */
+ default void onWarning(String message) {
+ }
+
+ /**
+ * Writing the file failed, e.g. because the disk is full. Nothing more
+ * goes into the file; what is in it stays, and {@link MediaRecorder#stop()}
+ * still finishes it as far as it can.
+ *
+ * @param message What went wrong.
+ */
+ default void onError(String message) {
+ }
+
+}
diff --git a/webrtc-java-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderState.java b/webrtc-java-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderState.java
new file mode 100644
index 00000000..5d00663c
--- /dev/null
+++ b/webrtc-java-media/src/main/java/dev/onvoid/webrtc/media/recorder/MediaRecorderState.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2026 Alex Andres
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package dev.onvoid.webrtc.media.recorder;
+
+/**
+ * The states a {@link MediaRecorder} goes through, in this order.
+ *
+ * @author Alex Andres
+ */
+public enum MediaRecorderState {
+
+ /** Created, taking tracks, not recording yet. */
+ IDLE,
+
+ /** Started; frames go into the file. */
+ RECORDING,
+
+ /** Stopped, with the file finished. A recorder cannot start again. */
+ STOPPED
+
+}
diff --git a/webrtc-java-media/src/main/java/module-info.java b/webrtc-java-media/src/main/java/module-info.java
index 7ea0e974..b55c7029 100644
--- a/webrtc-java-media/src/main/java/module-info.java
+++ b/webrtc-java-media/src/main/java/module-info.java
@@ -1,11 +1,13 @@
/**
* Media extension for webrtc-java: reads media files and network streams with
- * FFmpeg and feeds them into a peer connection.
+ * FFmpeg and feeds them into a peer connection, and records what a peer
+ * connection sends or receives into media files.
*/
module webrtc.java.media {
requires webrtc.java;
exports dev.onvoid.webrtc.media.player;
+ exports dev.onvoid.webrtc.media.recorder;
}
diff --git a/webrtc-java-media/src/test/java/dev/onvoid/webrtc/media/recorder/MediaRecorderTest.java b/webrtc-java-media/src/test/java/dev/onvoid/webrtc/media/recorder/MediaRecorderTest.java
new file mode 100644
index 00000000..36fab892
--- /dev/null
+++ b/webrtc-java-media/src/test/java/dev/onvoid/webrtc/media/recorder/MediaRecorderTest.java
@@ -0,0 +1,294 @@
+/*
+ * Copyright 2026 Alex Andres
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package dev.onvoid.webrtc.media.recorder;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicReference;
+
+import dev.onvoid.webrtc.PeerConnectionFactory;
+import dev.onvoid.webrtc.RTCRtpReceiver;
+import dev.onvoid.webrtc.media.audio.AudioDeviceModule;
+import dev.onvoid.webrtc.media.audio.AudioLayer;
+import dev.onvoid.webrtc.media.player.MediaInfo;
+import dev.onvoid.webrtc.media.player.MediaReader;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestInstance;
+import org.junit.jupiter.api.io.TempDir;
+import org.junit.jupiter.api.parallel.Execution;
+import org.junit.jupiter.api.parallel.ExecutionMode;
+
+/**
+ * Tests recording a call between two local peer connections, checked by
+ * reading the recorded file back.
+ */
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+@Execution(ExecutionMode.SAME_THREAD)
+class MediaRecorderTest {
+
+ private static final long RECORD_MS = 3000;
+
+ private AudioDeviceModule audioModule;
+ private PeerConnectionFactory factory;
+
+ @TempDir
+ Path tempDir;
+
+
+ @BeforeAll
+ void initFactory() {
+ // A dummy audio layer, because this factory sends pushed audio.
+ audioModule = new AudioDeviceModule(AudioLayer.kDummyAudio);
+ factory = new PeerConnectionFactory(audioModule);
+ }
+
+ @AfterAll
+ void disposeFactory() {
+ factory.dispose();
+ audioModule.dispose();
+ }
+
+ @Test
+ void recordsReceivedCallIntoMatroska() throws Exception {
+ Path file = tempDir.resolve("received.mkv");
+ Listener listener = new Listener();
+
+ try (TestCall call = new TestCall(factory)) {
+ // Well into the call, so that the receiver has had its key frame
+ // long ago and the recorder has to ask for one.
+ Thread.sleep(1500);
+
+ RTCRtpReceiver video = call.getReceiver(0);
+ RTCRtpReceiver audio = call.getReceiver(1);
+
+ try (MediaRecorder recorder = new MediaRecorder(file)) {
+ recorder.setListener(listener);
+ recorder.addTrack(video);
+ recorder.addTrack(audio);
+ recorder.start();
+
+ assertEquals(MediaRecorderState.RECORDING, recorder.getState());
+ assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started");
+
+ Thread.sleep(RECORD_MS);
+
+ assertTrue(recorder.stop());
+ assertEquals(MediaRecorderState.STOPPED, recorder.getState());
+ }
+ finally {
+ video.dispose();
+ audio.dispose();
+ }
+ }
+
+ assertNull(listener.error.get());
+ assertTrue(listener.warnings.isEmpty(), listener.warnings.toString());
+
+ MediaInfo info = readInfo(file);
+
+ assertTrue(info.hasVideo());
+ assertTrue(info.hasAudio());
+ assertEquals("vp8", info.getVideoCodec());
+ assertEquals(TestCall.WIDTH, info.getVideoWidth());
+ assertEquals(TestCall.HEIGHT, info.getVideoHeight());
+ assertEquals("opus", info.getAudioCodec());
+ assertEquals(48000, info.getSampleRate());
+ assertDuration(info);
+ }
+
+ @Test
+ void recordsSentCallIntoWebm() throws Exception {
+ Path file = tempDir.resolve("sent.webm");
+ Listener listener = new Listener();
+
+ try (TestCall call = new TestCall(factory);
+ MediaRecorder recorder = new MediaRecorder(file)) {
+ recorder.setListener(listener);
+ recorder.addTrack(call.getVideoSender());
+ recorder.addTrack(call.getAudioSender());
+ recorder.start();
+
+ assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started");
+
+ Thread.sleep(RECORD_MS);
+
+ assertTrue(recorder.stop());
+ }
+
+ assertNull(listener.error.get());
+
+ MediaInfo info = readInfo(file);
+
+ assertEquals("vp8", info.getVideoCodec());
+ assertEquals("opus", info.getAudioCodec());
+ assertDuration(info);
+ }
+
+ @Test
+ void leavesOutCodecFileCannotHold() throws Exception {
+ // MP4 has no place for VP8, which the call sends.
+ Path file = tempDir.resolve("audio-only.mp4");
+ Listener listener = new Listener();
+
+ try (TestCall call = new TestCall(factory);
+ MediaRecorder recorder = new MediaRecorder(file)) {
+ recorder.setListener(listener);
+ recorder.addTrack(call.getVideoSender());
+ recorder.addTrack(call.getAudioSender());
+ recorder.start();
+
+ assertTrue(listener.started.await(10, TimeUnit.SECONDS), "not started");
+
+ Thread.sleep(RECORD_MS);
+
+ assertTrue(recorder.stop());
+ }
+
+ assertFalse(listener.warnings.isEmpty());
+ assertTrue(listener.warnings.get(0).contains("video/VP8"), listener.warnings.get(0));
+
+ MediaInfo info = readInfo(file);
+
+ assertFalse(info.hasVideo());
+ assertEquals("opus", info.getAudioCodec());
+ }
+
+ @Test
+ void deletesFileWithoutMedia() throws Exception {
+ Path file = tempDir.resolve("nothing.mkv");
+
+ try (TestCall call = new TestCall(factory);
+ MediaRecorder recorder = new MediaRecorder(file)) {
+ assertTrue(Files.exists(file));
+
+ recorder.addTrack(call.getVideoSender());
+ recorder.start();
+
+ // Too soon for any frame to have made it into the file.
+ assertFalse(recorder.stop());
+ }
+
+ assertFalse(Files.exists(file));
+ }
+
+ @Test
+ void unstartedRecorderDeletesFile() throws Exception {
+ Path file = tempDir.resolve("unstarted.mkv");
+
+ try (MediaRecorder recorder = new MediaRecorder(file)) {
+ assertEquals(MediaRecorderState.IDLE, recorder.getState());
+ assertThrows(IllegalStateException.class, recorder::start);
+ }
+
+ assertFalse(Files.exists(file));
+ }
+
+ @Test
+ void rejectsTracksOnceStarted() throws Exception {
+ Path file = tempDir.resolve("rejects.mkv");
+
+ try (TestCall call = new TestCall(factory);
+ MediaRecorder recorder = new MediaRecorder(file)) {
+ recorder.addTrack(call.getVideoSender());
+ recorder.start();
+
+ assertThrows(IllegalStateException.class, () -> recorder.addTrack(call.getAudioSender()));
+ assertThrows(IllegalStateException.class, recorder::start);
+ }
+ }
+
+ @Test
+ void stopFromListener() throws Exception {
+ Path file = tempDir.resolve("listener-stop.mkv");
+ AtomicReference stopped = new AtomicReference<>();
+ CountDownLatch done = new CountDownLatch(1);
+
+ try (TestCall call = new TestCall(factory);
+ MediaRecorder recorder = new MediaRecorder(file)) {
+ recorder.setListener(new MediaRecorderListener() {
+
+ @Override
+ public void onStarted() {
+ stopped.set(recorder.stop());
+ done.countDown();
+ }
+ });
+ recorder.addTrack(call.getVideoSender());
+ recorder.start();
+
+ assertTrue(done.await(10, TimeUnit.SECONDS), "stopping from the listener hung");
+ }
+
+ assertTrue(stopped.get());
+ assertTrue(readInfo(file).hasVideo());
+ }
+
+ private static MediaInfo readInfo(Path file) throws Exception {
+ try (MediaReader reader = new MediaReader(file)) {
+ return reader.getInfo();
+ }
+ }
+
+ private static void assertDuration(MediaInfo info) {
+ long durationMs = info.getDurationUs() / 1000;
+
+ // The file begins when the first key frame arrives, somewhat after
+ // the start, and ends with what was queued at the stop.
+ assertTrue(durationMs > RECORD_MS - 1000 && durationMs < RECORD_MS + 2000,
+ "duration: " + durationMs + " ms");
+ }
+
+
+ private static class Listener implements MediaRecorderListener {
+
+ final CountDownLatch started = new CountDownLatch(1);
+
+ final List warnings = new CopyOnWriteArrayList<>();
+
+ final AtomicReference error = new AtomicReference<>();
+
+
+ @Override
+ public void onStarted() {
+ started.countDown();
+ }
+
+ @Override
+ public void onWarning(String message) {
+ warnings.add(message);
+ }
+
+ @Override
+ public void onError(String message) {
+ error.set(message);
+ }
+ }
+
+}
diff --git a/webrtc-java-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java b/webrtc-java-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java
new file mode 100644
index 00000000..e282e797
--- /dev/null
+++ b/webrtc-java-media/src/test/java/dev/onvoid/webrtc/media/recorder/TestCall.java
@@ -0,0 +1,304 @@
+/*
+ * Copyright 2026 Alex Andres
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package dev.onvoid.webrtc.media.recorder;
+
+import java.nio.ByteBuffer;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+import dev.onvoid.webrtc.CreateSessionDescriptionObserver;
+import dev.onvoid.webrtc.PeerConnectionFactory;
+import dev.onvoid.webrtc.PeerConnectionObserver;
+import dev.onvoid.webrtc.RTCAnswerOptions;
+import dev.onvoid.webrtc.RTCConfiguration;
+import dev.onvoid.webrtc.RTCIceCandidate;
+import dev.onvoid.webrtc.RTCOfferOptions;
+import dev.onvoid.webrtc.RTCPeerConnection;
+import dev.onvoid.webrtc.RTCPeerConnectionState;
+import dev.onvoid.webrtc.RTCRtpCodecCapability;
+import dev.onvoid.webrtc.RTCRtpReceiver;
+import dev.onvoid.webrtc.RTCRtpSender;
+import dev.onvoid.webrtc.RTCRtpTransceiver;
+import dev.onvoid.webrtc.RTCSessionDescription;
+import dev.onvoid.webrtc.SetSessionDescriptionObserver;
+import dev.onvoid.webrtc.media.MediaType;
+import dev.onvoid.webrtc.media.audio.AudioTrack;
+import dev.onvoid.webrtc.media.audio.CustomAudioSource;
+import dev.onvoid.webrtc.media.video.CustomVideoSource;
+import dev.onvoid.webrtc.media.video.NativeI420Buffer;
+import dev.onvoid.webrtc.media.video.VideoFrame;
+import dev.onvoid.webrtc.media.video.VideoTrack;
+
+/**
+ * A call between two local peer connections that sends generated video
+ * (320x240 at 30 frames a second) and audio (a tone) from the caller to the
+ * callee, for recording.
+ */
+class TestCall implements AutoCloseable {
+
+ static final int WIDTH = 320;
+ static final int HEIGHT = 240;
+
+ private final CustomVideoSource videoSource = new CustomVideoSource();
+ private final CustomAudioSource audioSource = new CustomAudioSource();
+ private final VideoTrack videoTrack;
+ private final AudioTrack audioTrack;
+
+ private final Peer caller;
+ private final Peer callee;
+
+ private final RTCRtpSender videoSender;
+ private final RTCRtpSender audioSender;
+
+ private volatile boolean feeding;
+ private Thread feeder;
+
+
+ TestCall(PeerConnectionFactory factory) throws Exception {
+ caller = new Peer(factory);
+ callee = new Peer(factory);
+
+ caller.remote = callee;
+ callee.remote = caller;
+
+ videoTrack = factory.createVideoTrack("video", videoSource);
+ audioTrack = factory.createAudioTrack("audio", audioSource);
+
+ videoSender = caller.connection.addTrack(videoTrack, Collections.singletonList("stream"));
+ audioSender = caller.connection.addTrack(audioTrack, Collections.singletonList("stream"));
+
+ preferVp8(factory, caller.connection, videoSender);
+
+ RTCSessionDescription offer = caller.createOffer();
+ callee.setRemoteDescription(offer);
+ RTCSessionDescription answer = callee.createAnswer();
+ caller.setRemoteDescription(answer);
+
+ if (!caller.connected.await(10, TimeUnit.SECONDS) || !callee.connected.await(10, TimeUnit.SECONDS)) {
+ throw new IllegalStateException("The call did not connect");
+ }
+
+ feeding = true;
+ feeder = new Thread(this::feed, "TestCall-feeder");
+ feeder.setDaemon(true);
+ feeder.start();
+ }
+
+ RTCRtpSender getVideoSender() {
+ return videoSender;
+ }
+
+ RTCRtpSender getAudioSender() {
+ return audioSender;
+ }
+
+ /**
+ * Returns the callee's receiver of the video (0) or audio (1) transceiver,
+ * which follow the order of the offer. The instance is the caller's to
+ * dispose.
+ */
+ RTCRtpReceiver getReceiver(int index) {
+ RTCRtpTransceiver[] transceivers = callee.connection.getTransceivers();
+ RTCRtpReceiver receiver = transceivers[index].getReceiver();
+
+ for (RTCRtpTransceiver transceiver : transceivers) {
+ transceiver.dispose();
+ }
+
+ return receiver;
+ }
+
+ @Override
+ public void close() throws InterruptedException {
+ feeding = false;
+ feeder.join();
+
+ videoSender.dispose();
+ audioSender.dispose();
+
+ caller.connection.close();
+ callee.connection.close();
+
+ videoTrack.dispose();
+ audioTrack.dispose();
+ videoSource.dispose();
+ audioSource.dispose();
+ }
+
+ /**
+ * Makes VP8 the preferred video codec. Platforms prefer different codecs by
+ * default, macOS H.264 through VideoToolbox, and the tests should not
+ * depend on which: VP8 is available everywhere, and it is what the
+ * recordings are checked for.
+ */
+ private static void preferVp8(PeerConnectionFactory factory, RTCPeerConnection connection,
+ RTCRtpSender sender) {
+ List codecs = new ArrayList<>(
+ factory.getRtpSenderCapabilities(MediaType.VIDEO).getCodecs());
+
+ codecs.sort(Comparator.comparing(codec -> !"VP8".equalsIgnoreCase(codec.getName())));
+
+ for (RTCRtpTransceiver transceiver : connection.getTransceivers()) {
+ RTCRtpSender transceiverSender = transceiver.getSender();
+
+ if (transceiverSender.equals(sender)) {
+ transceiver.setCodecPreferences(codecs);
+ }
+
+ transceiverSender.dispose();
+ transceiver.dispose();
+ }
+ }
+
+ private void feed() {
+ byte[] audio = new byte[480 * 2];
+ long startNs = System.nanoTime();
+ long chunks = 0;
+ long frames = 0;
+ int shade = 0;
+
+ while (feeding) {
+ long elapsedMs = (System.nanoTime() - startNs) / 1_000_000;
+
+ while (chunks * 10 <= elapsedMs) {
+ for (int i = 0; i < 480; i++) {
+ short sample = (short) (Math.sin(2 * Math.PI * 440 * (chunks * 480 + i) / 48000) * 8000);
+ audio[2 * i] = (byte) sample;
+ audio[2 * i + 1] = (byte) (sample >> 8);
+ }
+
+ audioSource.pushAudio(audio, 16, 48000, 1, 480);
+ chunks++;
+ }
+
+ if (frames * 1000 / 30 <= elapsedMs) {
+ NativeI420Buffer buffer = NativeI420Buffer.allocate(WIDTH, HEIGHT);
+ ByteBuffer y = buffer.getDataY();
+
+ for (int i = 0; i < y.capacity(); i++) {
+ y.put(i, (byte) (i + shade));
+ }
+ shade += 3;
+
+ VideoFrame frame = new VideoFrame(buffer, 0);
+ videoSource.pushFrame(frame);
+ frame.release();
+ frames++;
+ }
+
+ try {
+ Thread.sleep(2);
+ }
+ catch (InterruptedException e) {
+ return;
+ }
+ }
+ }
+
+
+ private static class Peer implements PeerConnectionObserver {
+
+ final RTCPeerConnection connection;
+
+ final CountDownLatch connected = new CountDownLatch(1);
+
+ volatile Peer remote;
+
+
+ Peer(PeerConnectionFactory factory) {
+ connection = factory.createPeerConnection(new RTCConfiguration(), this);
+ }
+
+ @Override
+ public void onIceCandidate(RTCIceCandidate candidate) {
+ remote.connection.addIceCandidate(candidate);
+ }
+
+ @Override
+ public void onConnectionChange(RTCPeerConnectionState state) {
+ if (state == RTCPeerConnectionState.CONNECTED) {
+ connected.countDown();
+ }
+ }
+
+ RTCSessionDescription createOffer() throws Exception {
+ CompletableFuture created = new CompletableFuture<>();
+ connection.createOffer(new RTCOfferOptions(), created(created));
+
+ return setLocalDescription(created.get(10, TimeUnit.SECONDS));
+ }
+
+ RTCSessionDescription createAnswer() throws Exception {
+ CompletableFuture created = new CompletableFuture<>();
+ connection.createAnswer(new RTCAnswerOptions(), created(created));
+
+ return setLocalDescription(created.get(10, TimeUnit.SECONDS));
+ }
+
+ void setRemoteDescription(RTCSessionDescription description) throws Exception {
+ CompletableFuture set = new CompletableFuture<>();
+ connection.setRemoteDescription(description, set(set));
+ set.get(10, TimeUnit.SECONDS);
+ }
+
+ private RTCSessionDescription setLocalDescription(RTCSessionDescription description)
+ throws Exception {
+ CompletableFuture set = new CompletableFuture<>();
+ connection.setLocalDescription(description, set(set));
+ set.get(10, TimeUnit.SECONDS);
+
+ return description;
+ }
+
+ private static CreateSessionDescriptionObserver created(
+ CompletableFuture future) {
+ return new CreateSessionDescriptionObserver() {
+
+ @Override
+ public void onSuccess(RTCSessionDescription description) {
+ future.complete(description);
+ }
+
+ @Override
+ public void onFailure(String error) {
+ future.completeExceptionally(new IllegalStateException(error));
+ }
+ };
+ }
+
+ private static SetSessionDescriptionObserver set(CompletableFuture future) {
+ return new SetSessionDescriptionObserver() {
+
+ @Override
+ public void onSuccess() {
+ future.complete(null);
+ }
+
+ @Override
+ public void onFailure(String error) {
+ future.completeExceptionally(new IllegalStateException(error));
+ }
+ };
+ }
+ }
+
+}
diff --git a/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h b/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h
index 320b8851..3014d693 100644
--- a/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h
+++ b/webrtc-jni/src/main/cpp/include/JNI_NativeApi.h
@@ -38,6 +38,22 @@ extern "C" {
JNIEXPORT jint JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_version
(JNIEnv *, jclass);
+ /*
+ * Class: dev_onvoid_webrtc_internal_NativeApi
+ * Method: senderFrames
+ * Signature: (J)J
+ */
+ JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_senderFrames
+ (JNIEnv *, jclass, jlong);
+
+ /*
+ * Class: dev_onvoid_webrtc_internal_NativeApi
+ * Method: receiverFrames
+ * Signature: (J)J
+ */
+ JNIEXPORT jlong JNICALL Java_dev_onvoid_webrtc_internal_NativeApi_receiverFrames
+ (JNIEnv *, jclass, jlong);
+
#ifdef __cplusplus
}
#endif
diff --git a/webrtc-jni/src/main/cpp/include/JNI_RTCEncodedFrame.h b/webrtc-jni/src/main/cpp/include/JNI_RTCEncodedFrame.h
new file mode 100644
index 00000000..45f193b3
--- /dev/null
+++ b/webrtc-jni/src/main/cpp/include/JNI_RTCEncodedFrame.h
@@ -0,0 +1,52 @@
+/*
+ * Copyright 2026 Alex Andres
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include
+/* Header for class dev_onvoid_webrtc_RTCEncodedFrame */
+
+#ifndef _Included_dev_onvoid_webrtc_RTCEncodedFrame
+#define _Included_dev_onvoid_webrtc_RTCEncodedFrame
+#ifdef __cplusplus
+extern "C" {
+#endif
+ /*
+ * Class: dev_onvoid_webrtc_RTCEncodedFrame
+ * Method: copyData
+ * Signature: (JLjava/nio/ByteBuffer;)V
+ */
+ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCEncodedFrame_copyData
+ (JNIEnv *, jclass, jlong, jobject);
+
+ /*
+ * Class: dev_onvoid_webrtc_RTCEncodedFrame
+ * Method: setDataBuffer
+ * Signature: (JLjava/nio/ByteBuffer;II)V
+ */
+ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCEncodedFrame_setDataBuffer
+ (JNIEnv *, jclass, jlong, jobject, jint, jint);
+
+ /*
+ * Class: dev_onvoid_webrtc_RTCEncodedFrame
+ * Method: setDataArray
+ * Signature: (J[BII)V
+ */
+ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCEncodedFrame_setDataArray
+ (JNIEnv *, jclass, jlong, jbyteArray, jint, jint);
+
+#ifdef __cplusplus
+}
+#endif
+#endif
diff --git a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h
index 2a16ba70..8a9c8b2e 100644
--- a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h
+++ b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpReceiver.h
@@ -47,6 +47,22 @@ extern "C" {
JNIEXPORT jobject JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_getSynchronizationSources
(JNIEnv *, jobject);
+ /*
+ * Class: dev_onvoid_webrtc_RTCRtpReceiver
+ * Method: setTransform
+ * Signature: (Ldev/onvoid/webrtc/RTCEncodedFrameTransformer;)V
+ */
+ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_setTransform
+ (JNIEnv *, jobject, jobject);
+
+ /*
+ * Class: dev_onvoid_webrtc_RTCRtpReceiver
+ * Method: requestKeyFrame
+ * Signature: ()V
+ */
+ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpReceiver_requestKeyFrame
+ (JNIEnv *, jobject);
+
/*
* Class: dev_onvoid_webrtc_RTCRtpReceiver
* Method: dispose
diff --git a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h
index eec94f3f..eced0d4d 100644
--- a/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h
+++ b/webrtc-jni/src/main/cpp/include/JNI_RTCRtpSender.h
@@ -63,6 +63,22 @@ extern "C" {
JNIEXPORT jobject JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_getDtmfSender
(JNIEnv *, jobject);
+ /*
+ * Class: dev_onvoid_webrtc_RTCRtpSender
+ * Method: setTransform
+ * Signature: (Ldev/onvoid/webrtc/RTCEncodedFrameTransformer;)V
+ */
+ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_setTransform
+ (JNIEnv *, jobject, jobject);
+
+ /*
+ * Class: dev_onvoid_webrtc_RTCRtpSender
+ * Method: generateKeyFrame
+ * Signature: ()V
+ */
+ JNIEXPORT void JNICALL Java_dev_onvoid_webrtc_RTCRtpSender_generateKeyFrame
+ (JNIEnv *, jobject);
+
/*
* Class: dev_onvoid_webrtc_RTCRtpSender
* Method: dispose
diff --git a/webrtc-jni/src/main/cpp/include/api/EncodedFrameRouter.h b/webrtc-jni/src/main/cpp/include/api/EncodedFrameRouter.h
new file mode 100644
index 00000000..f7529dc4
--- /dev/null
+++ b/webrtc-jni/src/main/cpp/include/api/EncodedFrameRouter.h
@@ -0,0 +1,113 @@
+/*
+ * Copyright 2026 Alex Andres
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef JNI_WEBRTC_API_ENCODED_FRAME_ROUTER_H_
+#define JNI_WEBRTC_API_ENCODED_FRAME_ROUTER_H_
+
+#include "webrtc_java_api.h"
+
+#include "api/frame_transformer_interface.h"
+#include "api/media_types.h"
+#include "api/scoped_refptr.h"
+
+#include
+#include
+#include