Subscribe: Diagnostics

Use this guide to inspect stream details, detect when streams end, and resolve common subscriber issues. It also includes guidance for handling connectivity problems in the UI.

Stream information

Get diagnostic details for active streams to aid debugging and analysis.

To get audio and video statistics for subscribers, add event handlers for the audioNetworkStats and videoNetworkStats event dispatched by the OTSubscriber. These provide information about the subscriber's stream, including the following:

  • The total number of audio and video packets lost.
  • The total number of audio and video packets received.
  • The total number of audio and video bytes received.
  • The current average video frame rate.
<OTSubscriber
  eventHandlers={{
    audioNetworkStats: event => {
      console.log('subscriber audioNetworkStats event', event);
    },
    videoNetworkStats: event => {
      console.log('subscriber videoNetworkStats event', event);
    },
  }}
/>

To get more detailed stream statistics, use the Subscriber.getRtcStatsReport() method of the OTSubscriber object. It returns a promise that, on success, resolves with a JSON representation of an RtcStatsReport object for the subscribed stream:

<OTSubscriber
  eventHandlers={{
    connected: event => {
      setTimeout(() => {
        this.subscriber.getRtcStatsReport();
      }, 4000);
    },
    rtcStatsReport: event => {
      console.log('subscriber rtcStatsReport event', event);
    },
  }}
/>

Detect stream end and video disabled

Detect when a stream ends so you can perform cleanup and adjust the UI.

When a subscriber's video is disabled, the OTSubscriber object dispatches a videoDisabled event:

<OTSubscriber
  eventHandlers={{
    videoDisabled: (event) => {
      console.log('stream video disabled -- stream ID:', event.streamId);
      // Display a user interface notification.
    },
  }}/>

When the Media Router disables the video of a subscriber, you may want to adjust the user interface related to the subscriber.

The reason property of the videoDisabled event object defines the reason the video was disabled. This can be set to one of the following values:

  • "PublisherPropertyChanged" — The publisher stopped publishing video.

  • "QualityChanged" — The Media Router stopped sending video to the subscriber based on stream quality changes. This feature of the Media Router has a subscriber drop the video stream when connectivity degrades. (The subscriber continues to receive the audio stream, if there is one.)

Before sending this event, when the subscriber's stream quality deteriorates to a level that is low enough that the video stream is at risk of being disabled, the OTSubscriber objet dispatches a videoDisableWarning event.

If connectivity improves to support video again, the OTSubscriber object dispatches a videoEnabled event, and the subscriber resumes receiving video.

This feature is only available in sessions that use the Media Router (sessions with the media mode set to routed), not in sessions with the media mode set to relayed.

When you publish a stream, you can prevent it from having its video disabled due to stream quality. Set audioFallbackEnabled to false in the properties prop pass into the OTPublisher component.

  • "SubscriberPropertyChanged" — The subscriber started or stopped subscribing to video, by setting subscribeToVideo to false in the properties prop passed into the OTSubscriber component.

  • "CodecNotSupported" — The subscriber stopped subscribing to video due to an incompatible codec (see the Video codecs developer guide).

The OTSubscriber object dispatches videoEnabled event when video resumes:

The reason property of the videoEnabled event object defines the reason the video was enabled. This can be set to one of the following values:

  • "PublisherPropertyChanged" — The publisher resumed publishing video.

  • "QualityChanged" — The Media Router resumed sending video to the subscriber based on stream quality changes. This feature of the Media Router has a subscriber drop the video stream when connectivity degrades and then resume the video stream if the stream quality improves.

This feature is only available in sessions that use the Media Router (sessions with the media mode set to routed), not in sessions with the media mode set to relayed.

  • "SubscriberPropertyChanged" — The subscriber started or stopped subscribing to video, by setting subscribeToVideo to false in the properties prop passed into the OTSubscriber component.

  • "CodecNotSupported" — The subscriber video was enabled after a codec change from an incompatible codec (see the Video codecs developer guide).

Troubleshooting (JavaScript)

Tips for handling subscribe errors and connectivity issues.

For general information on troubleshooting, see Debugging.

Handling Errors

There is only one way to subscribe—with Session.subscribe()—and most errors are network related. If the Subscriber fails to connect it will display its own error message, but it’s better to surface a clear message yourself:

session.subscribe(event.stream, 'subscriber', {insertMode: 'append'}, function (err) {
  if (err) {
    showMessage('Streaming connection failed. This could be due to a restrictive firewall.');
  }
});

Losing Connectivity

A Subscriber can lose its connection after it has connected. Handle the streamDestroyed event on the Session when the reason is networkDisconnected and inform the user without removing the Subscriber immediately:

session.on({
  streamDestroyed: function (event) {
    if (event.reason === 'networkDisconnected') {
      event.preventDefault();
      var subscribers = session.getSubscribersForStream(event.stream);
      if (subscribers.length > 0) {
        var subscriber = document.getElementById(subscribers[0].id);
        subscriber.innerHTML = 'Lost connection. This could be due to your internet connection or because the other party lost their connection.';
        event.preventDefault();
      }
    }
  }
});

For subscriber event handling and runtime adjustments (audio blocked, video disabled, stats), see Subscribe: Management & Events.