diff --git a/docs/guide/client-api-design.md b/docs/guide/client-api-design.md index b6e0b58f..82e87a61 100644 --- a/docs/guide/client-api-design.md +++ b/docs/guide/client-api-design.md @@ -340,6 +340,7 @@ public interface Peer extends AutoCloseable { // Sending. In AUTOMATIC mode each change renegotiates by itself. Sender addTrack(LocalTrack track, String... streamIds); + Sender addTrack(LocalTrack track, Simulcast simulcast, String... streamIds); // video, two or three layers with rids List senders(); // Receiving. Late subscribers get the tracks that already arrived. @@ -635,6 +636,8 @@ public interface Sender { LocalTrack track(); CompletableFuture replaceTrack(LocalTrack track); // no renegotiation, null sends nothing CompletableFuture configure(Encoding encoding); // max bitrate, max frame rate, scale down, active + CompletableFuture configure(String rid, Encoding encoding); // one simulcast layer + List rids(); // the simulcast layers, none without CompletableFuture transform(RTCEncodedFrameTransformer transform); // null sends frames unchanged CompletableFuture generateKeyFrame(); CompletableFuture remove(); // renegotiates in AUTOMATIC mode diff --git a/docs/guide/client/sending-media.md b/docs/guide/client/sending-media.md index 27f022d5..c14a8643 100644 --- a/docs/guide/client/sending-media.md +++ b/docs/guide/client/sending-media.md @@ -134,6 +134,29 @@ audioSender.sendTones("*99,1", Duration.ofMillis(200), Duration.ofMillis(100)); The characters 0 to 9, A to D, `#` and `*` are tones, and a comma is a pause of 2 seconds. What happens to queued and stopped tones is described under [Details](#dtmf-tones), and the [DTMF Sender](/guide/audio/dtmf-sender) guide has more. +## Simulcast + +With simulcast, a video track is sent in several layers at once, each at its own resolution and bitrate. A server that forwards the stream, such as an SFU, then gives each receiver the layer its connection takes. Each layer has an RTP stream id, its `rid`: + +```java +Sender sender = peer.addTrack(camera, Simulcast.builder() + .layer("q", Encoding.builder().scaleDownBy(4).maxBitrate(150_000).build()) + .layer("h", Encoding.builder().scaleDownBy(2).maxBitrate(500_000).build()) + .layer("f", Encoding.builder().maxBitrate(1_500_000).build()) + .build()); +``` + +`Simulcast.standard()` gives three layers in full, half and quarter resolution, with the rids `f`, `h` and `q`. + +`configure(rid, encoding)` changes one layer, and `configure(encoding)` every layer alike. A server may ask the sender to pause the layers no receiver wants: + +```java +sender.configure("f", Encoding.builder().active(false).build()); // stop sending full resolution +sender.configure("f", Encoding.builder().active(true).build()); // and start again +``` + +`rids()` lists the layers of a sender, in their order. + ## Switching Cameras A `LocalCamera` switches to another camera without renegotiating. Every peer that sends it keeps sending it, and preview handlers keep getting frames: @@ -184,6 +207,14 @@ If the thread stalls, as in a long garbage collection pause, it makes up for at - A video sender, or a sender whose remote peer accepts no telephone events, fails the future with an `IllegalStateException`. - So do tones that WebRTC stops sending midway, for example because the sender was paused with `configure`. The future then fails a few seconds after their planned end. +### Simulcast Layers + +- A simulcast takes two or three layers, the most WebRTC sends. +- A rid has 1 to 16 letters and digits, and is unique among the layers. It cannot change once the track is added. +- Only video tracks take simulcast. `addTrack` throws an `IllegalArgumentException` for an audio track. +- A remote peer without simulcast leaves it out of its answer and gets only the first layer. A plain WebRTC peer, such as another `Peer`, is one of them. +- `configure(rid, encoding)` throws an `IllegalArgumentException` for a rid the sender does not have. + ### When a Camera Switch Fails - If the new camera cannot be opened, the future fails with a `MediaException`, and the track keeps sending the camera it had. diff --git a/docs/guide/client/whip-whep.md b/docs/guide/client/whip-whep.md index fa8986f8..ec1cddff 100644 --- a/docs/guide/client/whip-whep.md +++ b/docs/guide/client/whip-whep.md @@ -95,7 +95,7 @@ Whip.Session live = Whip.to(URI.create("https://example.com/live/whip")) .get(15, TimeUnit.SECONDS); ``` -Simulcast needs a video track. `Sender.configure` on its sender changes every layer alike. +Simulcast needs a video track. `Sender.configure(Encoding)` on its sender changes every layer alike, and `configure(rid, Encoding)` one layer. Simulcast outside WHIP is described under [Simulcast](/guide/client/sending-media#simulcast). ## Errors diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/Peer.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/Peer.java index c8952ac0..852c8476 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/Peer.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/Peer.java @@ -75,6 +75,22 @@ public interface Peer extends AutoCloseable { */ Sender addTrack(LocalTrack track, String... streamIds); + /** + * Sends a video track in the layers of the given simulcast, each with + * its rid. Otherwise as {@link #addTrack(LocalTrack, String...)}. Should + * WebRTC refuse the layers, the error handlers of the peer hear of it, + * and every operation of the sender fails. + * + * @param track a video track of the same runtime. + * @param simulcast the layers to send the track in. + * @param streamIds the streams the remote peer sees the track in. + * + * @return the handle of the new sender, at once. + * + * @throws IllegalArgumentException if the track is not a video track. + */ + Sender addTrack(LocalTrack track, Simulcast simulcast, String... streamIds); + /** * @return the senders that were added and not removed. */ diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java index 34b85f92..98958587 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/PeerImpl.java @@ -290,6 +290,27 @@ public Sender addTrack(LocalTrack track, String... streamIds) { return addSender(local, ids, Collections.emptyList(), new CompletableFuture<>()); } + @Override + public Sender addTrack(LocalTrack track, Simulcast simulcast, String... streamIds) { + LocalTrackImpl local = checkTrack(track); + requireNonNull(simulcast, "simulcast"); + + if (local.kind() != MediaKind.VIDEO) { + throw new IllegalArgumentException("Simulcast takes a video track, got " + local.kind()); + } + + List ids = new ArrayList<>(); + + for (String id : streamIds) { + ids.add(requireNonNull(id, "streamId")); + } + if (ids.isEmpty()) { + ids.add(defaultStreamId); + } + + return addSender(local, ids, simulcast.encodings(), new CompletableFuture<>()); + } + /** * Adds a track to the stream of the tracks added without stream ids, sent * in the given encodings, as simulcast (RFC 8853) does with one for each @@ -308,7 +329,14 @@ CompletableFuture addTrack(LocalTrack track, List ids, List encodings, CompletableFuture added) { - SenderImpl sender = new SenderImpl(this, local); + List rids = new ArrayList<>(); + for (RTCRtpEncodingParameters encoding : encodings) { + if (encoding.rid != null) { + rids.add(encoding.rid); + } + } + + SenderImpl sender = new SenderImpl(this, local, rids); senders.add(sender); control.execute(() -> { diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/Sender.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/Sender.java index bef0e55d..054180e6 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/Sender.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/Sender.java @@ -17,6 +17,7 @@ package dev.onvoid.webrtc.client; import java.time.Duration; +import java.util.List; import java.util.concurrent.CompletableFuture; import java.util.function.Consumer; @@ -42,7 +43,8 @@ public interface Sender { CompletableFuture replaceTrack(LocalTrack track); /** - * Changes how the track is encoded. Values left unset stay as they are. + * Changes how the track is encoded, in every layer alike if it is sent + * as {@link Simulcast}. Values left unset stay as they are. * * @param encoding the values to change. * @@ -50,6 +52,27 @@ public interface Sender { */ CompletableFuture configure(Encoding encoding); + /** + * Changes how one layer of a {@link Simulcast} track is encoded, such as + * pausing it with {@code active(false)} while no receiver wants it. + * Values left unset stay as they are. + * + * @param rid the rid of the layer, one of {@link #rids()}. + * @param encoding the values to change. + * + * @return a future that completes once the values are applied. + * + * @throws IllegalArgumentException if the sender has no layer of that + * rid. + */ + CompletableFuture configure(String rid, Encoding encoding); + + /** + * @return the rids of the layers the track is sent in, in their order, + * or none if it is sent without simulcast. + */ + List rids(); + /** * Sets the transform that every encoded frame of this sender passes * through, after the encoder and before the packetizer, in place of the diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/SenderImpl.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/SenderImpl.java index 3ab922a8..71210c8b 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/SenderImpl.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/SenderImpl.java @@ -53,6 +53,8 @@ final class SenderImpl implements Sender { private final MediaKind kind; + private final List rids; + private volatile LocalTrackImpl track; /** @@ -85,10 +87,15 @@ final class SenderImpl implements Sender { private final Handlers toneHandlers; - SenderImpl(PeerImpl peer, LocalTrackImpl track) { + /** + * @param rids the rids of the simulcast layers the track is sent in, or + * none without simulcast. + */ + SenderImpl(PeerImpl peer, LocalTrackImpl track, List rids) { this.peer = peer; this.track = track; this.kind = track.kind(); + this.rids = List.copyOf(rids); this.toneHandlers = new Handlers<>(peer.rtc::reportError); } @@ -205,26 +212,68 @@ public CompletableFuture configure(Encoding encoding) { RTCRtpSendParameters parameters = sender.getParameters(); for (RTCRtpEncodingParameters values : parameters.encodings) { - if (encoding.active != null) { - values.active = encoding.active; - } - if (encoding.maxBitrate != null) { - values.maxBitrate = encoding.maxBitrate; - } - if (kind == MediaKind.VIDEO) { - if (encoding.maxFrameRate != null) { - values.maxFramerate = encoding.maxFrameRate; - } - if (encoding.scaleDownBy != null) { - values.scaleResolutionDownBy = encoding.scaleDownBy; - } + apply(encoding, values); + } + + sender.setParameters(parameters); + }); + } + + @Override + public CompletableFuture configure(String rid, Encoding encoding) { + if (rid == null) { + throw new NullPointerException("rid"); + } + if (encoding == null) { + throw new NullPointerException("encoding"); + } + if (!rids.contains(rid)) { + throw new IllegalArgumentException(rids.isEmpty() + ? "The track is sent without simulcast, so it has no layer " + rid + : "The track is sent in the layers " + rids + ", not in " + rid); + } + + return run(() -> { + RTCRtpSendParameters parameters = sender.getParameters(); + boolean found = false; + + for (RTCRtpEncodingParameters values : parameters.encodings) { + if (rid.equals(values.rid)) { + apply(encoding, values); + found = true; } } + if (!found) { + throw new WebRtcException("WebRTC reports no layer " + rid); + } + sender.setParameters(parameters); }); } + @Override + public List rids() { + return rids; + } + + private void apply(Encoding encoding, RTCRtpEncodingParameters values) { + if (encoding.active != null) { + values.active = encoding.active; + } + if (encoding.maxBitrate != null) { + values.maxBitrate = encoding.maxBitrate; + } + if (kind == MediaKind.VIDEO) { + if (encoding.maxFrameRate != null) { + values.maxFramerate = encoding.maxFrameRate; + } + if (encoding.scaleDownBy != null) { + values.scaleResolutionDownBy = encoding.scaleDownBy; + } + } + } + @Override public CompletableFuture transform(RTCEncodedFrameTransformer transform) { return run(() -> sender.setTransform(peer.guard(transform, "a sender of " + peer.name))); diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/Simulcast.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/Simulcast.java new file mode 100644 index 00000000..c186d848 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/Simulcast.java @@ -0,0 +1,187 @@ +/* + * 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.client; + +import static java.util.Objects.requireNonNull; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +import dev.onvoid.webrtc.RTCRtpEncodingParameters; + +/** + * The layers a video track is sent in, as simulcast (RFC 8853): the same video + * encoded several times, each layer with an RTP stream id (rid) and encoding + * values of its own, so that a server that forwards the stream can give each + * receiver the layer its connection takes. + *
{@code
+ * Sender sender = peer.addTrack(camera, Simulcast.builder()
+ *         .layer("q", Encoding.builder().scaleDownBy(4).maxBitrate(150_000).build())
+ *         .layer("h", Encoding.builder().scaleDownBy(2).maxBitrate(500_000).build())
+ *         .layer("f", Encoding.builder().maxBitrate(1_500_000).build())
+ *         .build());
+ *
+ * sender.configure("f", Encoding.builder().active(false).build());
+ * }
+ * The rids are fixed once the track is added. A remote peer that takes no + * simulcast gets the first layer only. + */ +public final class Simulcast { + + /** The most layers WebRTC sends (kMaxSimulcastStreams). */ + static final int MAX_LAYERS = 3; + + /** The longest rid WebRTC takes. */ + private static final int MAX_RID_LENGTH = 16; + + private final Map layers; + + + private Simulcast(Map layers) { + this.layers = Collections.unmodifiableMap(new LinkedHashMap<>(layers)); + } + + /** + * @return three layers in full, half and quarter resolution, with the rids + * {@code f}, {@code h} and {@code q}, the largest first. + */ + public static Simulcast standard() { + return builder() + .layer("f", Encoding.builder().scaleDownBy(1).build()) + .layer("h", Encoding.builder().scaleDownBy(2).build()) + .layer("q", Encoding.builder().scaleDownBy(4).build()) + .build(); + } + + /** + * @return a builder without layers. + */ + public static Builder builder() { + return new Builder(); + } + + /** + * @return the rids of the layers, in their order. + */ + public List rids() { + return List.copyOf(layers.keySet()); + } + + /** + * @return the encodings to create the transceiver with, one per layer. + */ + List encodings() { + List encodings = new ArrayList<>(); + + layers.forEach((rid, layer) -> { + RTCRtpEncodingParameters parameters = new RTCRtpEncodingParameters(); + parameters.rid = rid; + parameters.active = layer.active; + parameters.maxBitrate = layer.maxBitrate; + parameters.maxFramerate = layer.maxFrameRate; + parameters.scaleResolutionDownBy = layer.scaleDownBy; + + encodings.add(parameters); + }); + + return encodings; + } + + @Override + public String toString() { + return "Simulcast" + rids(); + } + + + + /** Builds a {@link Simulcast}. */ + public static final class Builder { + + private final Map layers = new LinkedHashMap<>(); + + + private Builder() { + } + + /** + * Adds a layer after those added before. + * + * @param rid the layer's RTP stream id: 1 to 16 letters and + * digits, unique among the layers. + * @param encoding the layer's values; without a {@link + * Encoding.Builder#scaleDownBy factor} it keeps the + * resolution of the track. + * + * @return this builder. + * + * @throws IllegalArgumentException if the rid is not one WebRTC + * takes, or is taken already. + */ + public Builder layer(String rid, Encoding encoding) { + requireNonNull(rid, "rid"); + requireNonNull(encoding, "encoding"); + + if (!isLegalRid(rid)) { + throw new IllegalArgumentException( + "A rid has 1 to " + MAX_RID_LENGTH + " letters and digits, got \"" + rid + "\""); + } + if (layers.containsKey(rid)) { + throw new IllegalArgumentException("The rid " + rid + " is taken already"); + } + + layers.put(rid, encoding); + return this; + } + + /** + * @return the layers. + * + * @throws IllegalArgumentException if there are fewer than two layers, + * or more than three, the most WebRTC + * sends. + */ + public Simulcast build() { + if (layers.size() < 2 || layers.size() > MAX_LAYERS) { + throw new IllegalArgumentException( + "Simulcast takes two or three layers, got " + layers.size()); + } + + return new Simulcast(layers); + } + + /** + * As WebRTC checks it (IsLegalRsidName): ASCII letters and digits. + */ + private static boolean isLegalRid(String rid) { + if (rid.isEmpty() || rid.length() > MAX_RID_LENGTH) { + return false; + } + for (int i = 0; i < rid.length(); i++) { + char c = rid.charAt(i); + + if (!(c >= '0' && c <= '9' || c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z')) { + return false; + } + } + return true; + } + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java index 4f19e006..9ee309d0 100644 --- a/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/Whip.java @@ -88,27 +88,6 @@ public static Builder to(URI endpoint) { return new Builder(HttpSession.checkEndpoint(endpoint)); } - /** - * @return the encodings of the simulcast layers, with their rids, or none - * without simulcast. - */ - private static List encodings(List layers) { - List encodings = new ArrayList<>(); - - for (int i = 0; i < layers.size(); i++) { - Encoding layer = layers.get(i); - RTCRtpEncodingParameters parameters = new RTCRtpEncodingParameters(); - parameters.rid = RIDS.get(i); - parameters.active = layer.active; - parameters.maxBitrate = layer.maxBitrate; - parameters.maxFramerate = layer.maxFrameRate; - parameters.scaleResolutionDownBy = layer.scaleDownBy; - - encodings.add(parameters); - } - - return encodings; - } @@ -140,7 +119,8 @@ public static final class Builder { private boolean alwaysOfferVideo; - private List simulcast = List.of(); + /** The layers of the video track, or null without simulcast. */ + private Simulcast simulcast; private Gathering gathering = Gathering.TRICKLE; @@ -253,8 +233,8 @@ public Builder alwaysOfferVideo() { * @return this builder. */ public Builder simulcast() { - return simulcast(Encoding.builder().scaleDownBy(1).build(), Encoding.builder().scaleDownBy(2).build(), - Encoding.builder().scaleDownBy(4).build()); + this.simulcast = Simulcast.standard(); + return this; } /** @@ -262,8 +242,8 @@ public Builder simulcast() { * simulcast (RFC 8853), with the rids {@code f}, {@code h} and * {@code q} in this order. An endpoint that takes no simulcast gets the * first layer only, so the largest comes first. {@link - * Sender#configure} on the sender of the track changes every layer - * alike. + * Sender#configure(Encoding)} on the sender of the track changes every + * layer alike, {@link Sender#configure(String, Encoding)} one layer. * * @param layers two or three encodings, the most WebRTC sends; those * without a {@link Encoding.Builder#scaleDownBy factor} @@ -279,7 +259,12 @@ public Builder simulcast(Encoding... layers) { throw new IllegalArgumentException("Simulcast takes two or three layers, got " + layers.length); } - this.simulcast = List.of(layers); + Simulcast.Builder builder = Simulcast.builder(); + for (int i = 0; i < layers.length; i++) { + builder.layer(RIDS.get(i), layers[i]); + } + + this.simulcast = builder.build(); return this; } @@ -412,7 +397,7 @@ public CompletableFuture publish(WebRtc rtc) { + track.kind().name().toLowerCase(Locale.ROOT) + " track, got another: " + track); } } - if (!simulcast.isEmpty() && !kinds.contains(MediaKind.VIDEO)) { + if (simulcast != null && !kinds.contains(MediaKind.VIDEO)) { throw new IllegalStateException("Simulcast needs a video track to publish"); } @@ -422,7 +407,7 @@ public CompletableFuture publish(WebRtc rtc) { Duration limit = timeout; Map> names = new EnumMap<>(codecs); boolean placeholder = alwaysOfferVideo && !kinds.contains(MediaKind.VIDEO); - List layers = encodings(simulcast); + List layers = simulcast == null ? List.of() : simulcast.encodings(); PeerImpl peer = (PeerImpl) rtc.createPeer(options.build()); try { diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/client/SimulcastTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/client/SimulcastTests.java new file mode 100644 index 00000000..9fec468a --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/client/SimulcastTests.java @@ -0,0 +1,169 @@ +/* + * 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.client; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +import org.junit.jupiter.api.Test; + +import dev.onvoid.webrtc.RTCRtpEncodingParameters; +import dev.onvoid.webrtc.RTCRtpSender; + +class SimulcastTests extends ClientTestBase { + + /** Smallest first, as LiveKit orders them. */ + private static Simulcast layers() { + return Simulcast.builder() + .layer("q", Encoding.builder().scaleDownBy(4).maxBitrate(150_000).build()) + .layer("h", Encoding.builder().scaleDownBy(2).maxBitrate(500_000).build()) + .layer("f", Encoding.builder().maxBitrate(1_500_000).build()) + .build(); + } + + @Test + void builderChecksRids() { + Encoding encoding = Encoding.builder().build(); + + for (String rid : new String[] { "", "a-b", "a b", "รค", "12345678901234567" }) { + assertThrows(IllegalArgumentException.class, () -> Simulcast.builder().layer(rid, encoding), rid); + } + + Simulcast.Builder builder = Simulcast.builder().layer("a1", encoding); + assertThrows(IllegalArgumentException.class, () -> builder.layer("a1", encoding)); + assertThrows(NullPointerException.class, () -> builder.layer(null, encoding)); + + // As long as WebRTC takes. + assertEquals(List.of("1234567890123456", "B"), Simulcast.builder() + .layer("1234567890123456", encoding).layer("B", encoding).build().rids()); + } + + @Test + void builderChecksCount() { + Encoding encoding = Encoding.builder().build(); + + assertThrows(IllegalArgumentException.class, () -> Simulcast.builder().layer("a", encoding).build()); + assertThrows(IllegalArgumentException.class, () -> Simulcast.builder().layer("a", encoding) + .layer("b", encoding).layer("c", encoding).layer("d", encoding).build()); + + assertEquals(List.of("f", "h", "q"), Simulcast.standard().rids()); + } + + @Test + void layersOffered() throws Exception { + Peer peer = manualPeer(); + Sender sender = peer.addTrack(rtc.media().customVideo("video"), layers()); + + assertEquals(List.of("q", "h", "f"), sender.rids()); + + String sdp = await(peer.negotiator().createOffer()).sdp; + + assertTrue(sdp.contains("a=rid:q send\r\n"), sdp); + assertTrue(sdp.contains("a=rid:h send\r\n"), sdp); + assertTrue(sdp.contains("a=rid:f send\r\n"), sdp); + assertTrue(sdp.contains("a=simulcast:send q;h;f\r\n"), sdp); + } + + @Test + void layerConfigured() throws Exception { + Peer peer = manualPeer(); + Sender sender = peer.addTrack(rtc.media().customVideo("video"), layers()); + + await(sender.configure("f", Encoding.builder().active(false).maxBitrate(1_000_000).build())); + + Map encodings = encodings(peer); + assertEquals(List.of("q", "h", "f"), List.copyOf(encodings.keySet())); + + assertFalse(encodings.get("f").active); + assertEquals(1_000_000, encodings.get("f").maxBitrate); + // The other layers keep their values. + assertTrue(encodings.get("q").active); + assertEquals(150_000, encodings.get("q").maxBitrate); + assertEquals(4.0, encodings.get("q").scaleResolutionDownBy); + assertTrue(encodings.get("h").active); + assertEquals(500_000, encodings.get("h").maxBitrate); + + // Every layer alike. + await(sender.configure(Encoding.builder().maxFrameRate(10).build())); + + encodings(peer).values().forEach(encoding -> assertEquals(10.0, encoding.maxFramerate)); + } + + @Test + void unknownLayerRefused() throws Exception { + Peer peer = manualPeer(); + Sender layered = peer.addTrack(rtc.media().customVideo("layered"), layers()); + Sender single = peer.addTrack(rtc.media().customVideo("single")); + Encoding encoding = Encoding.builder().active(false).build(); + + assertThrows(IllegalArgumentException.class, () -> layered.configure("x", encoding)); + assertThrows(IllegalArgumentException.class, () -> single.configure("f", encoding)); + assertThrows(NullPointerException.class, () -> layered.configure(null, encoding)); + assertTrue(single.rids().isEmpty()); + + // Nothing changed: the refusal comes before the peer is reached. + encodings(peer).values().forEach(values -> assertTrue(values.active, values.rid)); + } + + @Test + void audioRefused() { + Peer peer = manualPeer(); + + assertThrows(IllegalArgumentException.class, + () -> peer.addTrack(rtc.media().customAudio("audio"), layers())); + assertTrue(peer.senders().isEmpty()); + } + + private Peer manualPeer() { + return rtc.createPeer(PeerOptions.builder().negotiation(Negotiation.MANUAL).build()); + } + + /** + * @return the encodings of the peer's layered sender, by rid, in their + * order, as WebRTC has them. + */ + private static Map encodings(Peer peer) throws Exception { + return await(peer.withNative(connection -> { + Map byRid = new LinkedHashMap<>(); + RTCRtpSender[] senders = connection.getSenders(); + + try { + for (RTCRtpSender sender : senders) { + for (RTCRtpEncodingParameters encoding : sender.getParameters().encodings) { + if (encoding.rid != null) { + byRid.put(encoding.rid, encoding); + } + } + } + } + finally { + for (RTCRtpSender sender : senders) { + sender.dispose(); + } + } + + return byRid; + })); + } + +}