W3C home > Mailing lists > Public > public-webrtc@w3.org > March 2017

[webrtc-stats] Reuse of "inbound-rtp" and "outbound-rtp" for RTCP is confusing.

From: jan-ivar via GitHub <sysbot+gh@w3.org>
Date: Wed, 22 Mar 2017 20:01:02 +0000
To: public-webrtc@w3.org
Message-ID: <issues.opened-216190363-1490212859-sysbot+gh@w3.org>
jan-ivar has just created a new issue for https://github.com/w3c/webrtc-stats:

== Reuse of "inbound-rtp" and "outbound-rtp" for RTCP is confusing. ==
The `isRemote` overload of `"inbound-rtp"` and `"outbound-rtp"` is just confusing. It invites surprise and bugs to anyone trying to enumerate stats (scripts end up reading wrong data without knowing it!)

I can't think of a single use-case where enumerating by type alone is not wrong.

It's also false symmetry: both dictionaries have members which existence depend on `isRemote`:
 * [RTCOutboundRTPStreamStats](http://rawgit.com/w3c/webrtc-stats/master/webrtc-stats.html#outboundrtpstats-dict*) has `framesEncoded` (local-only), `remoteTimestamp` (remote-only),
 * [RTCInboundRTPStreamStats](http://rawgit.com/w3c/webrtc-stats/master/webrtc-stats.html#inboundrtpstats-dict*) has `framesDecoded` (local-only), `roundTripTime` (remote-only).

These absences break down easily by type, i.e. *never* appear in subsequent calls where missing.

## Proposal

Remove `isRemote`, and round out the two rtp types with two more for rtcp instead:
 * "outbound-rtp"
 * "inbound-rtp"
 *  **"outbound-rtcp"** (formerly "inbound-rtp" with `isRemote == true`)
 *  **"inbound-rtcp"** (formerly "outbound-rtp" with `isRemote == true`)

Define discrete dictionaries for the four types (in inheritance rather than corrresponding order):
```js
dictionary RTCSentRTPStreamStats : RTCRTPStreamStats {
    unsigned long       packetsSent;
    unsigned long long  bytesSent;
};

dictionary RTCOutboundRTPStreamStats : RTCSentRTPStreamStats {
    double              targetBitrate;
    unsigned long       framesEncoded;
};

dictionary RTCInboundRTCPStreamStats : RTCSentRTPStreamStats {
    DOMHighResTimeStamp remoteTimestamp;
};
```

```js
dictionary RTCReceivedRTPStreamStats : RTCRTPStreamStats {
    unsigned long      packetsReceived;
    unsigned long long bytesReceived;
    unsigned long      packetsLost;
    double             jitter;
    double             fractionLost;
    unsigned long      packetsDiscarded;
    unsigned long      packetsRepaired;
    unsigned long      burstPacketsLost;
    unsigned long      burstPacketsDiscarded;
    unsigned long      burstLossCount;
    unsigned long      burstDiscardCount;
    double             burstLossRate;
    double             burstDiscardRate;
    double             gapLossRate;
    double             gapDiscardRate;
};

dictionary RTCInboundRTPStreamStats : RTCReceivedRTPStreamStats {
    unsigned long      framesDecoded;
};

dictionary RTCOutboundRTCPStreamStats : RTCReceivedRTPStreamStats {
    double             roundTripTime;
};
```
## Benefit:

No need to read prose anymore to see what's where, and it simplifies [usage](https://blog.mozilla.org/webrtc/fiddle-of-the-week-await/) as well:
```js
  let html = "", stats = await pc.getStats();
  for (let stat of stats.values()) {
    // if (stat.isRemote) continue; <--- don't need this line anymore!
    switch (stat.type) {
      case "outbound-rtp": {
        html += dumpOutbound(stat) + "<br>";
        let rtcp = stats.get(stat.remoteId);
        if (rtcp) html += "RTCP " + dumpInbound(rtcp) + "<br>";
        break;
      }
```
Thoughts?

Please view or discuss this issue at https://github.com/w3c/webrtc-stats/issues/189 using your GitHub account
Received on Wednesday, 22 March 2017 20:01:08 UTC

This archive was generated by hypermail 2.3.1 : Monday, 23 October 2017 15:19:50 UTC