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
70 changes: 70 additions & 0 deletions docs/guide/client-api-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,7 @@ public final class WebRtc implements AutoCloseable {
public List<Peer> peers(); // snapshot of the open peers
public AudioMode audioMode();
public LoadStats loadStats(); // how much work waits and runs, cheap enough to read every second
public CompletableFuture<CallCheckResult> checkCall(CallCheck check); // camera, microphone and network before a call

public CompletableFuture<Void> closeAsync();
@Override
Expand Down Expand Up @@ -858,6 +859,75 @@ public enum QualityCondition {
- `diagnosticReport()` can go into a support ticket as it is. It leaves out raw stats, ids,
addresses, ports, URLs, credentials, SDP, certificates and codec parameters.

### `CallCheck`, before a call

A self-test for "am I ready for the call?": the camera delivers frames, the microphone audio that is
neither silent nor clipped, and a connection to a test peer comes up.

```java
public final class CallCheck {

public static Builder builder();

public static final class Builder {
public Builder video(LocalVideo track); // frames arrive, not all black
public Builder audio(LocalAudio track); // audio arrives, not silent, not clipped
public Builder network(PeerOptions options); // a connection to a test peer comes up
public Builder duration(Duration duration); // how long to measure, default 3 s
public Builder timeout(Duration timeout); // how long to wait for the first sample, default 10 s
public CallCheck build();
}
}

public final class CallCheckResult {

public enum Problem { NO_VIDEO, DARK_VIDEO, NO_AUDIO, SILENT_AUDIO, CLIPPED_AUDIO, NO_CONNECTION;
public String reason();
}

public boolean isReady(); // no problem found, not a guarantee
public Set<Problem> problems();
public Video video(); // null for a part not checked
public Audio audio();
public Network network();

public static final class Video {
public int frames();
public double framesPerSecond();
public int width();
public int height();
public double brightness(); // average luma of the brightest frame, 0 to 1
}

public static final class Audio {
public Duration received();
public double peakLevel(); // linear, 0 to 1
public double rmsLevel();
public double clipping(); // share of samples at full scale
}

public static final class Network {
public boolean isConnected();
public Duration connectTime();
public Duration roundTripTime();
public String candidateType();
public boolean isRelayed();
public Throwable failure(); // TimeoutException, or why the peer failed
}
}
```

- The parts run at the same time, so a check takes as long as its slowest part. Each waits on the
runtime's timer for its first sample, then measures for the duration, which tests fire by hand
with a `ManualTimer`.
- Problems with reasons, as for `PeerDiagnostics`, rather than a score.
- Reachability is told by a connection to a real test peer, never derived from the configuration.
`relayOnly(true)` makes a connection prove the TURN servers.
- WebRTC records a microphone only while a send stream runs, and the client API does not start the
recording itself. So the check sends a microphone to a pair of peers of its own, whose sender drops
every encoded frame, so that the user does not hear themselves. The audio reaches the check
through a sink on the track, after processing.

### `Whip` and `Whep`

Sessions with a media server, over a peer with `Negotiation.MANUAL`. Their requests follow RFC 9725
Expand Down
63 changes: 63 additions & 0 deletions docs/guide/client-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -1019,6 +1019,69 @@ ICE credentials, SDP, certificates and codec parameters. Missing measurements
become JSON null. The raw `report()` and its string representation are not
sanitized diagnostic exports.

## Checking Before a Call

Diagnostics watch a call that is under way. `checkCall` answers the question before it: am I ready
for the call? It checks that the camera delivers frames, that the microphone delivers audio that is
neither silent nor clipped, and that a connection to a test peer comes up, all at the same time:

```java
LocalCamera camera = rtc.media().camera();
LocalAudio microphone = rtc.media().microphone();

CallCheck check = CallCheck.builder()
.video(camera)
.audio(microphone) // ask the user to say something meanwhile
.network(PeerOptions.builder()
.iceServer("turn:turn.example.com", "user", "secret")
.relayOnly(true) // only a relayed connection counts
.signaling(testPeerSignaling)
.build())
.build();

rtc.checkCall(check).thenAccept(result -> {
if (result.isReady()) {
System.out.println("Ready: " + result);
}
result.problems().forEach(problem -> System.out.println(problem.reason()));
});
```

Every part is optional, but a check needs at least one. Each waits up to the check's `timeout`
(10 seconds by default) for the first frame, the first audio or the connection, then measures for
its `duration` (3 seconds by default). The future completes on an event thread of the runtime's
local media, so the rule against `join()` holds there. The tracks stay the application's: the check
neither closes nor mutes them, and the same tracks can go into the call once it is done.

| Problem | Found when |
|---|---|
| `NO_VIDEO` | The video track delivered no frame within the timeout. |
| `DARK_VIDEO` | No frame had an average luma above 8% of white: a covered lens, a closed privacy shutter or no light. The brightest frame counts, since a camera's first frames are often dark while its exposure settles. A muted track sends black frames, so it is dark too. |
| `NO_AUDIO` | The audio track delivered no audio within the timeout. |
| `SILENT_AUDIO` | The audio never rose above -50 dBFS: a muted microphone, or nobody spoke. |
| `CLIPPED_AUDIO` | More than 0.1% of the samples were at full scale (99% of it or above): the input is too loud and distorts. |
| `NO_CONNECTION` | No connection to the test peer came up within the timeout. `network().failure()` tells why: a `TimeoutException`, or the failure of the peer. |

Besides the problems, the result has the measurements behind them: frames, frame rate, resolution and
brightness of the video; how much audio arrived, with its peak and RMS level and the share of
clipped samples; and for the network the time it took to connect, the round trip time, the local
candidate type and whether the connection is relayed. `isReady()` means that no part found a
problem, not that the call is sure to work.

Audio is measured as the track sends it, after audio processing. WebRTC records a microphone only
while it sends it, so for a microphone the check sends the track to a peer of its own, in the same
runtime, which drops every encoded frame before it goes out: nothing is played back, and the user
does not hear themselves. That peer, and the one of the network check, show among `rtc.peers()`
while the check runs and are closed before the result goes out.

Whether the network lets a call through cannot be told from the local configuration, only from a
connection that is made. The network part therefore connects to a real test peer: one the
application runs for this, such as an echo bot behind its own signaling, or any other peer that
answers the offer. The check creates a peer with the given options, opens a data channel so that it
offers, reads the connection's statistics once it is up and closes the peer. With `relayOnly(true)`
the connection can only go through the TURN servers of the options, so a connection proves that they
work; without it, a direct connection may come up instead.

## Closing

You close what you created, and closing an owner closes what it owns:
Expand Down
191 changes: 191 additions & 0 deletions webrtc/src/main/java/dev/onvoid/webrtc/client/CallCheck.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
/*
* 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.time.Duration;

import dev.onvoid.webrtc.internal.Timeouts;

/**
* What {@link WebRtc#checkCall(CallCheck)} checks before a call: whether a
* video track delivers frames, whether an audio track delivers audio that is
* neither silent nor clipped, and whether a connection to a test peer comes
* up. Any of the three may be left out, but not all of them.
* <pre>{@code
* LocalCamera camera = rtc.media().camera();
* LocalAudio microphone = rtc.media().microphone();
*
* CallCheck check = CallCheck.builder()
* .video(camera)
* .audio(microphone)
* .network(PeerOptions.builder()
* .iceServer("turn:turn.example.com", "user", "secret")
* .relayOnly(true)
* .signaling(testPeerSignaling)
* .build())
* .build();
*
* rtc.checkCall(check).thenAccept(result -> {
* result.problems().forEach(problem -> System.out.println(problem.reason()));
* });
* }</pre>
* The tracks stay the application's: the check neither closes nor mutes them,
* so the same tracks can go into the call afterwards.
*/
public final class CallCheck {

final LocalVideo video;

final LocalAudio audio;

final PeerOptions network;

final Duration duration;

final Duration timeout;


private CallCheck(Builder builder) {
this.video = builder.video;
this.audio = builder.audio;
this.network = builder.network;
this.duration = builder.duration;
this.timeout = builder.timeout;
}

/**
* @return a builder of a check.
*/
public static Builder builder() {
return new Builder();
}



/** Builds a {@link CallCheck}. */
public static final class Builder {

private LocalVideo video;

private LocalAudio audio;

private PeerOptions network;

private Duration duration = Duration.ofSeconds(3);

private Duration timeout = Duration.ofSeconds(10);


private Builder() {
}

/**
* Checks that the track delivers frames that are not all black, as
* from a covered lens or a closed privacy shutter. The frames are
* those a local preview of the track gets.
*
* @param track a camera, a screen or any other local video track.
*
* @return this builder.
*/
public Builder video(LocalVideo track) {
this.video = requireNonNull(track, "track");
return this;
}

/**
* Checks that the track delivers audio that is neither silent nor
* clipped, so the user should speak during the check. The audio is
* measured as the track sends it, after audio processing.
* <p>
* WebRTC records a microphone only while it sends it, so for a
* {@link LocalMedia#microphone() microphone} the check sends the track
* to a peer of its own, in this runtime, which it closes again. That
* peer drops every encoded frame before it goes out, so nothing is
* played back and the user does not hear themselves.
*
* @param track a microphone or any other local audio track.
*
* @return this builder.
*/
public Builder audio(LocalAudio track) {
this.audio = requireNonNull(track, "track");
return this;
}

/**
* Checks that a connection to a test peer comes up: a peer the
* application runs for this, or any other that answers over the
* signaling of the options, such as an echo bot. Only a connection
* that is made tells that the network lets one through; the local
* configuration alone cannot. With {@link
* PeerOptions.Builder#relayOnly(boolean) relayOnly} set, a connection
* proves that the TURN servers of the options work.
* <p>
* The check creates a peer with the options, opens a data channel, so
* that the peer offers, reads the statistics of the connection and
* closes the peer again.
*
* @param options the ICE servers and the signaling to the test peer.
*
* @return this builder.
*/
public Builder network(PeerOptions options) {
this.network = requireNonNull(options, "options");
return this;
}

/**
* @param duration how long frames and audio are measured, from the
* first frame or the first audio on; 3 seconds by
* default.
*
* @return this builder.
*/
public Builder duration(Duration duration) {
this.duration = Timeouts.requirePositive(duration, "duration");
return this;
}

/**
* @param timeout how long the check waits for the first frame, the
* first audio and the connection before it reports
* that there is none; 10 seconds by default.
*
* @return this builder.
*/
public Builder timeout(Duration timeout) {
this.timeout = Timeouts.requirePositive(timeout, "timeout");
return this;
}

/**
* @return the check.
*
* @throws IllegalStateException if nothing was given to check.
*/
public CallCheck build() {
if (video == null && audio == null && network == null) {
throw new IllegalStateException("A call check needs video, audio or a network to check");
}

return new CallCheck(this);
}
}
}
Loading
Loading