close search

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

Visit the Vonage API Developer Portal

Subscribing to streams — Windows

Once 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 Session object sends an StreamReceived event 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.)

session.StreamReceived += Session_StreamReceived;

private void Session_StreamReceived(object sender, Session.StreamEventArgs e)
    Console.WriteLine("Session stream received");

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 object by calling the Subscriber(context, stream, renderer) constructor. Pass in the Windows application context for the Subscriber, the Stream object, and a video renderer. The OpenTok.IVideoRenderer interface defines the video renderer. The OpenTok.VideoRenderer class, included in OpenTok Windows SDK, renders video to an Windows Presentation Framework control. The VideoRenderer object is a subclass of System.Windows.Controls.Control. You can add this element to your view hierarchy. Or you can create your own custom video renderer that implements the OpenTok.IVideoRenderer interface.

Call the subscribe() method of the Session object to start subscribing to the stream:

VideoRenderer videoRenderer = new VideoRenderer();
// Add the video renderer to the application's view hierarchy.

Subscriber subscriber = new Subscriber(Context.Instance, stream, renderer);
subscriber.Error += Subscriber_Error;

private void Session_Error(object sender, Subscriber.ErrorEventArgs e)
    Console.WriteLine("Subscriber error:" + e.ErrorCode);

The Subscriber object sends an Error event if there is an error in subscribing to the stream. Check the ErrorCode property of the arguments passed into the event to see details on why subscribing failed. (The OpenTok.ErrorCode enum defines ErrorCode values.)

The Subscriber object sends a Connected event when the app starts receiving the subscriber's stream.

Note: The OpenTok.Subscriber class implements the System.IDisposable interface. Be sure to call the Dispose() method of the Subscriber object to release its resources when you no longer need the object (for example, when the Subscriber stops streaming video or when the app or window is closing).

You can create a custom audio driver to be used by all publishers and subscribers.

Unsubscribing from a stream

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


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 Session object sends a StreamDisconnected event. When the connection is restored, the Subscriber object sends a StreamReconnected event. If the client cannot restore the stream, the Session object sends a StreamDropped event.

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

session.StreamDropped += Session_StreamDropped;

subscriber.StreamDisconnected += Subscriber_StreamDisconnected;
subscriber.StreamReconnected += Subscriber_StreamReconnected;

public void Subscriber_StreamDisconnected(object sender)
  // Display a user interface notification.

public void Subscriber_StreamReconnected(object sender)
  // Display a user interface notification.

public void Session_StreamDropped(object sender, EventArgs e)
  // Display a user interface notification.

Detecting when streams leave a session

When streams published by other clients leave a session, the the Session object sends a StreamDropped event:

session.StreamDropped += Session_StreamDropped;

public void Session_StreamDropped(object sender, EventArgs e)
  // Stream dropped

The event arguments object passed into this are defined by the OpenTok.Session.StreamEventArgs class. This class includes a Stream property. Compare this Stream object to the Stream property of each Subscriber object to identify the subscriber for the stream.

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. When the OpenTok Media Router stops sending video, the Subscriber object sends a VideoDisabled event:

subscriber.VideoDisabled += Subscriber_VideoDisabled;

public void Subscriber_VideoDisabled(object sender)
  // Display a user interface notification.

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

The Subscriber object sends a VideoDisabled event when video resumes:

subscriber.VideoEnabled += Subscriber_VideoEnabled;

public void Subscriber_VideoEnabled(object sender)
  // Video resumes for the subscriber.

Getting information about a stream

The Stream object has the following properties that define the stream:

You use the Subscriber.AudioStatsUpdated and Subscriber.VideoStatsUpdated events to monitor the following statistics for a subscriber's stream:

To get more detailed stream statics, use the Subscriber.GetRtcStatsReport() method. This provides an RTC stats report for the media stream. This is an asynchronous operation. When the stats are available, the RtcStatsReport event is sent. The RtcStatsReportArgs object includes a JsonArrayOfReports property. This is a JSON array of RTC stats reports, which are similar to the format 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 Subscriber.PreferredFramerate and Subscriber.PreferredResolution.