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
74 changes: 73 additions & 1 deletion docs/guide/client-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -860,10 +860,82 @@ peer.onStats(Duration.ofSeconds(1), stats -> System.out.printf(
| `packetLoss()` | The share of received packets lost so far, 0 to 1. After a long session it barely moves. |
| `recentPacketLoss()` | The share of packets lost of those expected since the previous sample, 0 to 1, and 0 if none were expected; -1 for the first sample and after the clock went back. A stream that came up or whose counters started again counts all it has. |
| `outboundVideo()`, `inboundVideo()` | Codec, resolution and frame rate of each video stream, and what limits a sent one. |
| `report()` | The whole `RTCStatsReport`. |
| `inboundAudio()`, `outboundAudio()` | Audio streams ordered by statistics id: codec, jitter, concealment counters, audio level and sample counters. Unavailable fields are null; received PCM callbacks are observed only while an `onAudio` sink is attached. |
| `diagnostics()` | The current state and confirmed `QualityCondition` causes. |
| `diagnosticReport()` | A JSON snapshot with allowlisted diagnostics, media measurements, codec names, OS/architecture, Java version, library version and processor count. |
| `report()` | The whole `RTCStatsReport`, including potentially sensitive connection information. |

A peer bundles its media on one transport by default. When the remote side refuses to bundle, each m-line has a transport of its own. `transport()` is then the one with a candidate pair in use that carried the most bytes, sent and received, and of transports that carried as many, the one with the lowest id. Read `transports()` to watch each connection by itself.

### Diagnosis and quality events

```java
Subscription diagnosis = peer.onDiagnostics(Duration.ofSeconds(1), status -> {
System.out.println(status.state());
status.conditions().forEach(cause -> System.out.println(cause.reason()));
});

// Export on demand, for example from a support button. File I/O belongs on
// an application worker, outside the peer's event executor.
peer.stats().thenAccept(stats -> supportExecutor.execute(() -> {
try {
Files.write(Paths.get("diagnostics.json"),
stats.diagnosticReport().getBytes(StandardCharsets.UTF_8));
}
catch (IOException error) {
error.printStackTrace();
}
}));
```

The export example uses `java.nio.file.Files`, `java.nio.file.Paths`,
`java.nio.charset.StandardCharsets` and `java.io.IOException`; `supportExecutor`
is an application-owned executor.

`onDiagnostics` emits the initial diagnosis and then only changes to its state or
causes, including recovery. Handlers run on the peer's event executor; closing the
subscription stops sampling. All `stats`, `onStats` and `onDiagnostics` calls share
one history per peer. A captured `PeerStats` and its diagnosis stay immutable.

There is no combined score. `OBSERVING` means there is no continuous measurement
interval yet (including after a clock rollback or a gap longer than five seconds).
`HEALTHY` means no supported problem has been confirmed; it is not a guarantee
that all media paths work. `DEGRADED` includes the following confirmed causes:

| Condition | Evidence |
|---|---|
| `VIDEO_CPU_LIMITED` | The same outgoing video RTP stream consistently reports `qualityLimitationReason=cpu`. |
| `HIGH_PACKET_LOSS` | Recent inbound packet loss is at least 5%; recovery needs at most 2%. Values between those thresholds retain the current state and restart the confirmation window. |
| `AUDIO_PACKETS_WITHOUT_PCM` | The same received audio RTP stream gains packets while no PCM callbacks reach its attached `onAudio` sinks. This observes sink ingress, before application queues and handlers; it does not diagnose speakers or slow application handlers. |

Each problem and its recovery need at least three distinct measurements spanning
at least three seconds. Polling once a second is recommended; cached reports do
not advance the window. A missing stream or required measurement, a changed sink
set, or a reset audio counter discards that stream's evidence instead of guessing.
Sampling gaps longer than five seconds and backwards timestamps discard temporal
evidence. Diagnostics do not add audio sinks: without an application subscription,
PCM availability is unknown. Silence (audio level zero) alone is not a fault.

`TURN_IN_USE` is immediate information when either selected candidate on any
transport is a relay. It does not make a peer degraded. `TransportStats.relayed()`
also exposes this fact, while `candidateType()` continues to describe the local
candidate.

`AudioStats.jitter()` is a `Duration`, `audioLevel()` is linear (0 to 1), and
`concealedSamples()`, `concealmentEvents()` and `totalSamplesReceived()` are
cumulative counters. Outbound level is read from the media source when available;
receive-only measurements on outbound audio remain null. `pcmCallbacks()` counts
sink callbacks across subscriptions, so multiple subscriptions can count the same
audio more than once.

The JSON export includes the confirmation policy and cause explanations. It uses
schema version 1 and an explicit allowlist, including a
bounded set of codec MIME names; unknown names become `other`. It excludes raw
statistics, track/stream/transport/candidate identifiers, addresses, ports, URLs,
ICE credentials, SDP, certificates and codec parameters. Missing measurements
become JSON null. The raw `report()` and its string representation are not
sanitized diagnostic exports.

## Closing

You close what you created, and closing an owner closes what it owns:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,10 @@ public static void main(String[] args) throws Exception {

receive(callee);
caller.onStateChange(state -> System.out.println("Caller is " + state));
caller.onDiagnostics(Duration.ofSeconds(1), diagnosis -> {
System.out.println("Caller diagnosis: " + diagnosis.state());
diagnosis.conditions().forEach(cause -> System.out.println(cause.reason()));
});

// Pushed media. The same tracks could be sent on any number of peers.
CustomVideo video = rtc.media().customVideo("pattern");
Expand Down
13 changes: 13 additions & 0 deletions webrtc/src/main/java/dev/onvoid/webrtc/client/AudioDispatcher.java
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@

import java.time.Duration;
import java.util.function.Consumer;
import java.util.concurrent.atomic.AtomicLong;

import dev.onvoid.webrtc.internal.Timeouts;
import dev.onvoid.webrtc.media.audio.AudioTrackSink;
Expand All @@ -29,6 +30,12 @@
*/
final class AudioDispatcher extends Dispatcher<AudioChunk> implements AudioTrackSink {

private final AtomicLong pcmCallbacks = new AtomicLong();

long pcmCallbacks() {
return pcmCallbacks.get();
}

/**
* @param buffer how much audio may wait for the handler.
*/
Expand All @@ -43,6 +50,12 @@ public void onData(byte[] data, int bitsPerSample, int sampleRate, int channels,
return;
}

if (frames > 0) {

pcmCallbacks.incrementAndGet();

}

// The track reuses the array for the next chunk.
offer(new AudioChunk(data.clone(), sampleRate, channels, frames));
}
Expand Down
104 changes: 104 additions & 0 deletions webrtc/src/main/java/dev/onvoid/webrtc/client/AudioStats.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
/*
* 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 java.time.Duration;

/** Immutable statistics of one audio RTP stream. Missing measurements are null. */
public final class AudioStats {
private final String id;
private final String trackId;
private final String codec;
private final Long packetsReceived;
private final Duration jitter;
private final Long concealedSamples;
private final Long concealmentEvents;
private final Double audioLevel;
private final Long totalSamplesReceived;
private final Long pcmCallbacks;
final long pcmGeneration;

AudioStats(String id, String trackId, String codec, Long packetsReceived,
Duration jitter, Long concealedSamples, Long concealmentEvents,
Double audioLevel, Long totalSamplesReceived, Long pcmCallbacks, long pcmGeneration) {
this.id = id;
this.trackId = trackId;
this.codec = codec;
this.packetsReceived = packetsReceived;
this.jitter = jitter;
this.concealedSamples = concealedSamples;
this.concealmentEvents = concealmentEvents;
this.audioLevel = audioLevel;
this.totalSamplesReceived = totalSamplesReceived;
this.pcmCallbacks = pcmCallbacks;
this.pcmGeneration = pcmGeneration;
}

/** @return the RTP statistics id, for correlating successive measurements. */
public String id() {
return id;
}

/** @return the track identifier, or null. */
public String trackId() {
return trackId;
}

/** @return the negotiated codec MIME type, or null. */
public String codec() {
return codec;
}

/** @return cumulative packets received, or null for outbound or unavailable data. */
public Long packetsReceived() {
return packetsReceived;
}

/** @return interarrival jitter, or null if unavailable. */
public Duration jitter() {
return jitter;
}

/** @return cumulative samples replaced by concealment, or null. */
public Long concealedSamples() {
return concealedSamples;
}

/** @return cumulative concealment events, or null. */
public Long concealmentEvents() {
return concealmentEvents;
}

/** @return linear audio level from 0 to 1, or null. Zero can be silence. */
public Double audioLevel() {
return audioLevel;
}

/** @return cumulative received samples reported by WebRTC, or null. */
public Long totalSamplesReceived() {
return totalSamplesReceived;
}

/**
* @return cumulative PCM callbacks across this track's onAudio subscriptions,
* or null when none is attached. Counts sink ingress, before application queues.
* Several subscriptions can count the same audio more than once.
*/
public Long pcmCallbacks() {
return pcmCallbacks;
}
}
156 changes: 156 additions & 0 deletions webrtc/src/main/java/dev/onvoid/webrtc/client/DiagnosticExport.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
/*
* 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 java.util.Arrays;
import java.util.Locale;

/** An explicit export schema: never serializes raw stats or arbitrary string attributes. */
final class DiagnosticExport {
private DiagnosticExport() { }

static String json(PeerStats stats) {
StringBuilder out = new StringBuilder("{\"schemaVersion\":1");
field(out, "timestamp", stats.timestamp().toString());
field(out, "state", stats.diagnostics().state().name());
field(out, "os", platform(System.getProperty("os.name", "")));
field(out, "architecture", allowed(System.getProperty("os.arch", ""),
"amd64", "x86_64", "aarch64", "arm", "x86", "i386"));
String javaVersion = System.getProperty("java.specification.version", "");
field(out, "javaVersion", javaVersion.matches("[0-9]{1,3}(\\.[0-9]{1,3})?") ? javaVersion : "other");
String version = PeerStats.class.getPackage().getImplementationVersion();
field(out, "libraryVersion", version != null && version.matches("[0-9]+\\.[0-9]+\\.[0-9]+(-SNAPSHOT)?")
? version : "unversioned");
number(out, "availableProcessors", Runtime.getRuntime().availableProcessors());
number(out, "bytesSent", stats.bytesSent());
number(out, "bytesReceived", stats.bytesReceived());
number(out, "outgoingBitrate", stats.outgoingBitrate());
number(out, "incomingBitrate", stats.incomingBitrate());
number(out, "packetLoss", stats.packetLoss());
number(out, "recentPacketLoss", stats.recentPacketLoss());
out.append(",\"policy\":{\"confirmationSeconds\":").append(DiagnosticsReader.WINDOW.getSeconds());
number(out, "minimumMeasurements", DiagnosticsReader.MIN_SAMPLES);
number(out, "lossEnter", DiagnosticsReader.LOSS_ENTER);
number(out, "lossExit", DiagnosticsReader.LOSS_EXIT);
number(out, "maximumGapSeconds", DiagnosticsReader.MAX_GAP.getSeconds());
out.append('}');
out.append(",\"conditions\":[");
boolean comma = false;
for (QualityCondition condition : stats.diagnostics().conditions()) {
if (comma) {
out.append(',');
}
out.append("{\"cause\":");
Json.writeString(out, condition.name());
field(out, "reason", condition.reason());
out.append(",\"problem\":").append(condition.isProblem()).append('}');
comma = true;
}
out.append("],\"transports\":[");
comma = false;
for (TransportStats transport : stats.transports()) {
if (comma) {
out.append(',');
}
out.append("{\"relayed\":").append(transport.relayed());
field(out, "candidateType", allowed(transport.candidateType(), "host", "srflx", "prflx", "relay"));
number(out, "rttSeconds", transport.roundTripTime() == null ? null
: transport.roundTripTime().toNanos() / 1e9);
out.append('}');
comma = true;
}
out.append("],\"video\":[");
comma = false;
for (boolean outbound : new boolean[] { false, true }) {
for (VideoStats video : outbound ? stats.outboundVideo() : stats.inboundVideo()) {
if (comma) {
out.append(',');
}
out.append("{\"outbound\":").append(outbound);
field(out, "codec", codec(video.codec()));
number(out, "width", video.width());
number(out, "height", video.height());
number(out, "framesPerSecond", video.framesPerSecond());
field(out, "qualityLimitation", allowed(video.qualityLimitation(), "none", "cpu", "bandwidth", "other"));
out.append('}');
comma = true;
}
}
out.append("],\"audio\":[");
comma = false;
for (boolean outbound : new boolean[] { false, true }) {
for (AudioStats audio : outbound ? stats.outboundAudio() : stats.inboundAudio()) {
if (comma) {
out.append(',');
}
out.append("{\"outbound\":").append(outbound);
field(out, "codec", codec(audio.codec()));
number(out, "packetsReceived", audio.packetsReceived());
number(out, "jitterSeconds", audio.jitter() == null ? null : audio.jitter().toNanos() / 1e9);
number(out, "concealedSamples", audio.concealedSamples());
number(out, "concealmentEvents", audio.concealmentEvents());
number(out, "audioLevel", audio.audioLevel());
number(out, "totalSamplesReceived", audio.totalSamplesReceived());
number(out, "pcmCallbacks", audio.pcmCallbacks());
out.append('}');
comma = true;
}
}
return out.append("]}").toString();
}

private static String codec(String value) {
if (value == null) {
return null;
}
return allowed(value.toLowerCase(Locale.ROOT), "audio/opus", "audio/pcmu", "audio/pcma",
"audio/g722", "audio/isac", "audio/cn", "audio/telephone-event", "audio/red",
"video/vp8", "video/vp9", "video/h264", "video/h265", "video/av1", "video/rtx",
"video/red", "video/ulpfec", "video/flexfec-03");
}

private static String allowed(String value, String... allowed) {
return value == null ? null : Arrays.asList(allowed).contains(value) ? value : "other";
}

private static String platform(String name) {
if (name.startsWith("Windows")) {
return "Windows";
}
if (name.equals("Mac OS X")) {
return "macOS";
}
return name.equals("Linux") ? "Linux" : "other";
}

private static void field(StringBuilder out, String name, String value) {
out.append(',');
Json.writeString(out, name);
out.append(':');
if (value == null) {
out.append("null");
}
else Json.writeString(out, value);
}

private static void number(StringBuilder out, String name, Number value) {
out.append(',');
Json.writeString(out, name);
out.append(':');
out.append(value == null || !Double.isFinite(value.doubleValue()) ? "null" : value.toString());
}
}
Loading
Loading