PeerConnectionStats.js 

  1. import EventEmitter from 'events'
  2. import Logger from './Logger'
  4. const logger = Logger.get('PeerConnectionStats')
  6. /**
  7.  * @typedef {Object} ConnectionStats
  8.  * @property {RTCStatsReport} raw - All RTCPeerConnection stats without parsing. Reference {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport}.
  9.  * @property {TrackReport} audio - Parsed audio information.
  10.  * @property {TrackReport} video - Parsed video information.
  11.  * @property {Number} availableOutgoingBitrate - The available outbound capacity of the network connection. The higher the value, the more bandwidth you can assume is available for outgoing data. The value is reported in bits per second.
  12.  *
  13.  * This value comes from the nominated candidate-pair.
  14.  * @property {Number} totalRoundTripTime - Total round trip time is the total time in seconds that has elapsed between sending STUN requests and receiving the responses.
  15.  *
  16.  * This value comes from the nominated candidate-pair.
  17.  * @property {Number} currentRoundTripTime - Current round trip time indicate the number of seconds it takes for data to be sent by this peer to the remote peer and back over the connection described by this pair of ICE candidates.
  18.  *
  19.  * This value comes from the nominated candidate-pair.
  20.  * @property {RTCIceCandidateType} candidateType - Local candidate type from the nominated candidate-pair which indicates the type of ICE candidate the object represents.
  21.  */
  23. /**
  24.  * @typedef {Object} TrackReport
  25.  * @property {Array<InboundStats>} inbounds - Parsed information of each inbound-rtp.
  26.  * @property {Array<OutboundStats>} outbounds - Parsed information of each outbound-rtp.
  27.  */
  29. /**
  30.  * @typedef {Object} InboundStats
  31.  * @property {String} id - inbound-rtp Id.
  32.  * @property {Number} jitter - Current Jitter measured in seconds.
  33.  * @property {String} [mimeType] - Mime type if related report had codec report associated.
  34.  * @property {Number} [framesPerSecond] - Current framerate if it's video report.
  35.  * @property {Number} [frameHeight] - Current frame height if it's video report.
  36.  * @property {Number} [frameWidth] - Current frame width if it's video report.
  37.  * @property {Number} timestamp - Timestamp of report.
  38.  * @property {Number} totalBytesReceived - Total bytes received is an integer value which indicates the total number of bytes received so far from this synchronization source.
  39.  * @property {Number} totalPacketsReceived - Total packets received indicates the total number of packets of any kind that have been received on the connection described by the pair of candidates.
  40.  * @property {Number} totalPacketsLost - Total packets lost.
  41.  * @property {Number} packetsLostRatioPerSecond - Total packet lost ratio per second.
  42.  * @property {Number} packetsLostDeltaPerSecond - Total packet lost delta per second.
  43.  * @property {Number} bitrate - Current bitrate in bits per second.
  44.  */
  46. /**
  47.  * @typedef {Object} OutboundStats
  48.  * @property {String} id - outbound-rtp Id.
  49.  * @property {String} [mimeType] - Mime type if related report had codec report associated.
  50.  * @property {Number} [framesPerSecond] - Current framerate if it's video report.
  51.  * @property {Number} [frameHeight] - Current frame height if it's video report.
  52.  * @property {Number} [frameWidth] - Current frame width if it's video report.
  53.  * @property {String} [qualityLimitationReason] - If it's video report, indicate the reason why the media quality in the stream is currently being reduced by the codec during encoding, or none if no quality reduction is being performed.
  54.  * @property {Number} timestamp - Timestamp of report.
  55.  * @property {Number} totalBytesSent - Total bytes sent indicates the total number of payload bytes that hve been sent so far on the connection described by the candidate pair.
  56.  * @property {Number} bitrate - Current bitrate in bits per second.
  57.  */
  59. export const peerConnectionStatsEvents = {
  60.   stats: 'stats'
  61. }
  63. export default class PeerConnectionStats extends EventEmitter {
  64.   constructor (peer) {
  65.     super()
  66.     this.peer = peer
  67.     this.stats = null
  68.     this.emitInterval = null
  69.     this.previousStats = null
  70.   }
  72.   /**
  73.    * Initialize the statistics monitoring of the RTCPeerConnection.
  74.    */
  75.   init () {
  76.     logger.info('Initializing peer connection stats')
  77.     this.emitInterval = setInterval(async () => {
  78.       const stats = await this.peer.getStats()
  79.       this.parseStats(stats)
  80.       /**
  81.        * Peer connection incoming stats.
  82.        *
  83.        * @event PeerConnection#stats
  84.        * @type {ConnectionStats}
  85.       */
  86.       this.emit(peerConnectionStatsEvents.stats, this.stats)
  87.     }, 1000)
  88.   }
  90.   /**
  91.    * Parse incoming RTCPeerConnection stats.
  92.    * @param {RTCStatsReport} rawStats - RTCPeerConnection stats.
  93.    * @returns {ConnectionStats} RTCPeerConnection stats parsed.
  94.    */
  95.   parseStats (rawStats) {
  96.     this.previousStats = this.stats
  97.     const statsObject = {
  98.       audio: {
  99.         inbounds: [],
  100.         outbounds: []
  101.       },
  102.       video: {
  103.         inbounds: [],
  104.         outbounds: []
  105.       },
  106.       raw: rawStats
  107.     }
  109.     for (const report of rawStats.values()) {
  110.       switch (report.type) {
  111.         case 'outbound-rtp': {
  112.           addOutboundRtpReport(report, this.previousStats, statsObject)
  113.           break
  114.         }
  115.         case 'inbound-rtp': {
  116.           addInboundRtpReport(report, this.previousStats, statsObject)
  117.           break
  118.         }
  119.         case 'candidate-pair': {
  120.           if (report.nominated) {
  121.             addCandidateReport(report, statsObject)
  122.           }
  123.           break
  124.         }
  125.         default:
  126.           break
  127.       }
  128.     }
  129.     this.stats = statsObject
  130.   }
  132.   /**
  133.    * Stops the monitoring of RTCPeerConnection statistics.
  134.    */
  135.   stop () {
  136.     logger.info('Stopping peer connection stats')
  137.     clearInterval(this.emitInterval)
  138.   }
  139. }
  141. /**
  142.  * Parse and add incoming outbound-rtp report from RTCPeerConnection to final report.
  143.  * @param {Object} report - JSON object which represents a report from RTCPeerConnection stats.
  144.  * @param {ConnectionStats} previousStats - Previous stats parsed.
  145.  * @param {Object} statsObject - Current stats object being parsed.
  146.  */
  147. const addOutboundRtpReport = (report, previousStats, statsObject) => {
  148.   const mediaType = getMediaType(report)
  149.   const codecInfo = getCodecData(report.codecId, statsObject.raw)
  150.   const additionalData = getBaseRtpReportData(report, mediaType)
  151.   additionalData.totalBytesSent = report.bytesSent
  152.   additionalData.id = report.id
  153.   additionalData.mid = report.mid
  155.   const previousBytesSent = previousStats ? previousStats[mediaType].outbounds.find(x => x.id === additionalData.id)?.totalBytesSent ?? 0 : null
  156.   additionalData.bitrate = previousBytesSent ? 8 * (report.bytesSent - previousBytesSent) : 0
  158.   if (mediaType === 'video') {
  159.     additionalData.qualityLimitationReason = report.qualityLimitationReason
  160.   }
  161.   statsObject[mediaType].outbounds.push({
  162.     ...codecInfo,
  163.     ...additionalData
  164.   })
  165. }
  167. /**
  168.  * Parse and add incoming inbound-rtp report from RTCPeerConnection to final report.
  169.  * @param {Object} report - JSON object which represents a report from RTCPeerConnection stats.
  170.  * @param {ConnectionStats} previousStats - Previous stats parsed.
  171.  * @param {Object} statsObject - Current stats object being parsed.
  172.  */
  173. const addInboundRtpReport = (report, previousStats, statsObject) => {
  174.   let mediaType = getMediaType(report)
  175.   const codecInfo = getCodecData(report.codecId, statsObject.raw)
  177.   // Safari is missing mediaType and kind for 'inbound-rtp'
  178.   if (!['audio', 'video'].includes(mediaType)) {
  179.     if (report.id.includes('Video')) mediaType = 'video'
  180.     else mediaType = 'audio'
  181.   }
  182.   const additionalData = getBaseRtpReportData(report, mediaType)
  183.   additionalData.totalBytesReceived = report.bytesReceived
  184.   additionalData.totalPacketsReceived = report.packetsReceived
  185.   additionalData.totalPacketsLost = report.packetsLost
  186.   additionalData.jitter = report.jitter
  187.   additionalData.id = report.id
  188.   additionalData.mid = report.mid
  189.   additionalData.trackIdentifier = report.trackIdentifier
  191.   additionalData.bitrate = 0
  192.   additionalData.packetsLostRatioPerSecond = 0
  193.   additionalData.packetsLostDeltaPerSecond = 0
  194.   if (previousStats) {
  195.     const previousReport = previousStats[mediaType].inbounds.find(x => x.id === additionalData.id)
  196.     if (previousReport) {
  197.       const previousBytesReceived = previousReport.totalBytesReceived
  198.       additionalData.bitrate = 8 * (report.bytesReceived - previousBytesReceived)
  199.       additionalData.packetsLostRatioPerSecond = calculatePacketsLostRatio(additionalData, previousReport)
  200.       additionalData.packetsLostDeltaPerSecond = calculatePacketsLostDelta(additionalData, previousReport)
  201.     }
  202.   }
  204.   statsObject[mediaType].inbounds.push({
  205.     ...codecInfo,
  206.     ...additionalData
  207.   })
  208. }
  210. /**
  211.  * Parse and add incoming candidate-pair report from RTCPeerConnection to final report.
  212.  * Also adds associated local-candidate data to report.
  213.  * @param {Object} report - JSON object which represents a report from RTCPeerConnection stats.
  214.  * @param {Object} statsObject - Current stats object being parsed.
  215.  */
  216. const addCandidateReport = (report, statsObject) => {
  217.   statsObject.totalRoundTripTime = report.totalRoundTripTime
  218.   statsObject.currentRoundTripTime = report.currentRoundTripTime
  219.   statsObject.availableOutgoingBitrate = report.availableOutgoingBitrate
  220.   statsObject.candidateType = statsObject.raw.get(report.localCandidateId).candidateType
  221. }
  223. /**
  224.  * Get media type.
  225.  * @param {Object} report - JSON object which represents a report from RTCPeerConnection stats.
  226.  * @returns {String} Media type.
  227.  */
  228. const getMediaType = (report) => {
  229.   return report.mediaType || report.kind
  230. }
  232. /**
  233.  * Get codec information from stats.
  234.  * @param {String} codecReportId - Codec report ID.
  235.  * @param {RTCStatsReport} rawStats - RTCPeerConnection stats.
  236.  * @returns {Object} Object containing codec information.
  237.  */
  238. const getCodecData = (codecReportId, rawStats) => {
  239.   const { mimeType } = codecReportId ? rawStats.get(codecReportId) ?? {} : {}
  240.   return { mimeType }
  241. }
  243. /**
  244.  * Get common information for RTP reports.
  245.  * @param {Object} report - JSON object which represents a report from RTCPeerConnection stats.
  246.  * @param {String} mediaType - Media type.
  247.  * @returns {Object} Object containing common information.
  248.  */
  249. const getBaseRtpReportData = (report, mediaType) => {
  250.   const additionalData = {}
  251.   if (mediaType === 'video') {
  252.     additionalData.framesPerSecond = report.framesPerSecond
  253.     additionalData.frameHeight = report.frameHeight
  254.     additionalData.frameWidth = report.frameWidth
  255.   }
  256.   additionalData.timestamp = report.timestamp
  257.   return additionalData
  258. }
  260. /**
  261.  * Calculate the ratio packets lost
  262.  * @param {Object} actualReport - JSON object which represents a parsed report.
  263.  * @param {Object} previousReport - JSON object which represents a parsed report.
  264.  * @returns {Number} Packets lost ratio
  265.  */
  266. const calculatePacketsLostRatio = (actualReport, previousReport) => {
  267.   const currentLostPackages = calculatePacketsLostDelta(actualReport, previousReport)
  268.   const currentReceivedPackages = actualReport.totalPacketsReceived - previousReport.totalPacketsReceived
  269.   return currentLostPackages / currentReceivedPackages
  270. }
  272. /**
  273.  * Calculate the delta packets lost
  274.  * @param {Object} actualReport - JSON object which represents a parsed report.
  275.  * @param {Object} previousReport - JSON object which represents a parsed report.
  276.  * @returns {Number} Packets lost ratio
  277.  */
  278. const calculatePacketsLostDelta = (actualReport, previousReport) => {
  279.   return actualReport.totalPacketsLost - previousReport.totalPacketsLost
  280. }
  281. JAVASCRIPT
    Copied!