Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Subscribing to streams — Android

Once you have connected to a session, you can subscribe to streams in the session. When you subscribe to a stream, you can put its video view in the app.

This topic includes the following sections:

Detecting streams in a session

The onStreamReceived(Session session, Stream stream) method of the Session.SessionListener object is called when a stream published by another client is created in a session. (A stream is created when a client publishes a stream to the session or if the stream exists when you connect to the session.) 

@Override
public void onStreamReceived(Session session, Stream stream) {
   // There is a new stream.
   // You may want to subscribe to it.
}

Add a listener object for this event by calling the setSessionListener(Session.SessionListener listener) method of the Session object: 

mSession.setSessionListener(this);

You can subscribe to a stream to display it in your app. See the next section.

Subscribing to a stream

To subscribe to a stream, first instantiate a Subscriber.Builder object by calling the Subscriber.Builder(Context context, Stream stream) constructor. Pass in the Android application context for the Subscriber and the Stream object. Call the build() method to create the Subscriber object. Then call the subscribe() method of the Session object to start subscribing to the stream: 

mSubscriber = new Subscriber.Builder(context, stream)
  .build();
mSession.subscribe(mSubscriber);

The SubscriberKit.SubscriberListener.onConnected(SubscriberKit subscriber) method is called when the app starts receiving the subscriber's stream. At this point, you can add the subscriber's view (returned by the getView() method of the Subscriber object) as a subview of an android.view.ViewGroup object to display it in the app: 

@Override
public void onConnected(subscriber) {
   // mViewContainer is an Android View
   RelativeLayout.LayoutParams layoutParams = new RelativeLayout.LayoutParams(
           getResources().getDisplayMetrics().widthPixels, getResources()
                   .getDisplayMetrics().heightPixels);
   mViewContainer.addView(mSubscriber.getView(), layoutParams);
}

Unsubscribing from a stream

To stop playing a stream you are subscribed to, call the Session.unsubscribe(Subscriber subscriber) method: 

mSession.unsubscribe(mSubscriber);

The Subscriber is disconnected, and its view is removed from its superview.

Automatic reconnection

If a client drops a connection to a subscribed stream (for example, due to a drop in network connectivity in either client), it will attempt to automatically reconnect to the stream. When the stream is dropped and the client tries to reconnect, the SubscriberKit.StreamListener.onDisconnected(SubscriberKit subscriber) method is called. When the connection is restored, the SubscriberKit.StreamListener.onReconnected(SubscriberKit subscriber) method is called. If the client cannot restore the stream, the Session.SessionListener.onStreamDropped(Session session, Stream stream) method is called.

In response to these events, your application can (optionally) display user interface notifications indicating the temporary disconnection, reconnection, and destroyed states: 

// In the implementation of the SubscriberKit.StreamListener interface:
@Override
public void onDisconnected(SubscriberKit subscriber) {
  // Display a user interface notification.
}

@Override
public void onReconnected(SubscriberKit subscriber) {
  // Adjust user interface.
}

// In the implementation of the Session.SessionListener interface:
@Override
public void onStreamDropped(Session session, Stream stream) {
  // Adjust user interface.
}

Detecting when streams leave a session

When streams published by other clients leave a session, the onStreamDropped(Session session, Stream stream) method of the Session.SessionListener object is called. When a stream is dropped, the view for any Subscriber object for the stream is removed from its superview.

Detecting when a subscriber's video is disabled

The OpenTok Media Router stops sending video to the subscriber when it detects that connectivity degrades. The subscriber continues to receive the audio stream, if there is one. The onVideoDisabled(subscriber, subscriber) method of the SubscriberKit.VideoListener object is called when the OpenTok OpenTok Media Router stops sending video: 

@Override
public void onVideoDisabled(subscriber, reason) {
	// Video is disabled for the subscriber
}

The reason parameter identifies the reason the subscriber stopped streaming video.

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

The onVideoEnabled(subscriber, reason) method of the SubscriberKit.VideoListener object is called when the video resumes: 

@Override
public void onVideoEnabled(subscriber, reason) {
// Video is resumes for the subscriber
}

The reason parameter identifies the reason the subscriber's video resumed.

When you publish a stream, you enable or disable publisher and subscriber audio fallback. The audio fallback feature disables video (in publishers and subscribers) when network or CPU conditions do not support video. See Audio fallback (iOS).

Getting information about a stream

The Stream object has the following methods that return values that define the stream:

You can set listeners to monitor the following statistics for a subscriber's stream:

See the SubscriberKit.setAudioStatsListener(AudioStatsListener listener) and SubscriberKit.setVideoStatsListener(VideoStatsListener listener) methods.

To get statistics for a stream published by the local client, you must use a session that uses the OpenTok Media Router (sessions with the media mode set to routed).

To get more detailed stream statics, use the SubscriberKit.getRtcStatsReport() method. This provides an RTC stats report for the media stream. This is an asynchronous operation. Call the SubscriberKit.setRtcStatsReportListener(SubscriberKit.SubscriberRtcStatsReportListener listener) method, and then implement the SubscriberKit.SubscriberRtcStatsReportListener.onRtcStatsReport(SubscriberKit subscriber, java.lang.String jsonArrayOfReports) method prior to calling SubscriberKit.getRtcStatsReport(). When the stats are available, the implementation of the SubscriberKit.SubscriberRtcStatsReportListener.onRtcStatsReport(SubscriberKit subscriber, java.lang.String jsonArrayOfReports) method is called. The jsonArrayOfReports parameter is a JSON array of RTC stats reports, which are similar to the format of the RtcStatsReport object implemented in web browsers (see these Mozilla docs). Also see this W3C documentation.

Setting the preferred frame rate and resolution

When subscribing to a stream that uses the scalable video feature, you can set the preferred frame rate and resolution for the stream the subscribing client receives from the OpenTok Media Router. For details, see SubscriberKit.setPreferredFrameRate() and SubscriberKit.setPreferredResolution().