Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Nexmo APIs

Visit Nexmo

OpenTok.Subscriber

Used to consume an audio-video stream in the OpenTok session. More...

Inherits IDisposable.

Classes

class  AudioLevelArgs
 Defines arguments for AudioLevel events. More...
class  AudioNetworkStatsEventArgs
 Defines arguments for AudioStatsUpdated events. More...
class  ErrorEventArgs
 Defines arguments for the Error event. More...
class  VideoEventArgs
 Defines arguments for the VideoEnabled and VideoDisabled events. More...
class  VideoNetworkStatsEventArgs
 Defines arguments for VideoStatsUpdated events. More...

Public Types

enum  VideoReason : int { VideoReason.PublishVideo = 1, VideoReason.SubscriberToVideo = 2, VideoReason.Quality = 3 }
 Defines values for the VideoEventArgs.Reason and VideoEventArgs.Reason properties. More...

Public Member Functions

 Subscriber (Context context, Stream stream, IVideoRenderer renderer=null)
 Creates a new subscriber for a given stream. More...
void Dispose ()
 Disposes of the Subscriber object's resources. More...

Protected Member Functions

virtual void Dispose (bool disposing)

Properties

Stream Stream [get]
 The Stream corresponding to this subscriber. More...
bool SubscribeToAudio [get, set]
 Whether the Subscriber is subscribing to audio (true) or not (false). More...
bool SubscribeToVideo [get, set]
 Whether the Subscriber is subscribing to video (true) or not (false). More...
IVideoRenderer VideoRenderer [get]
 The video renderer used by this subscriber. More...
string Id [get]
 The unique identifier for the Subscriber. More...
Size PreferredResolution [get, set]
 The preferred resolution for the subscriber’s stream. More...
float PreferredFramerate [get, set]
 The preferred framerate for the subscriber’s stream. More...

Events

EventHandler Connected
 Invoked when the instance has successfully connected to the stream and begins playing media. More...
EventHandler StreamDisconnected
 Called when the subscriber's stream has been interrupted. More...
EventHandler StreamReconnected
 Sent when the subscriber's stream resumes (after temporarily being disconnected). More...
EventHandler< VideoEventArgsVideoDisabled
 Called when the subscriber stops receiving video. More...
EventHandler< VideoEventArgsVideoEnabled
 Called when the subscriber's video stream starts (when there previously was no video) or resumes (after video was disabled). More...
EventHandler< ErrorEventArgsError
 Invoked when a subscriber has failed to connect to the OpenTok server. More...
EventHandler VideoDisableWarning
 Called when the OpenTok Media Router determines that the stream quality has degraded and the video will be disabled if the quality degrades further. More...
EventHandler VideoDisableWarningLifted
 Called when the OpenTok Media Router determines that the stream quality has improved to the point at which the video being disabled is not an immediate risk. More...
EventHandler< AudioNetworkStatsEventArgsAudioStatsUpdated
 Invoked when the subscriber has audio stats to share. More...
EventHandler< VideoNetworkStatsEventArgsVideoStatsUpdated
 Invoked when the subscriber has video stats to share. More...
EventHandler< AudioLevelArgsAudioLevel
 Sent periodically to report the audio level of the subscriber. More...

Detailed Description

Used to consume an audio-video stream in the OpenTok session.

Create a Subscribers by passing a valid Stream instance into the Subscriber(Context, Stream, IVideoRenderer) constructor. Subscribers can connect to receive media when you call the Session.Subscribe(Subscriber) method.

The 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).

Member Enumeration Documentation

◆ VideoReason

Defines values for the VideoEventArgs.Reason and VideoEventArgs.Reason properties.

Enumerator
PublishVideo 

The event occured because the publisher of the stream started or stopped publishing video.

SubscriberToVideo 

The event occured because the local client started or stopped subscribing to video.

Quality 

The video event was caused by a change to the video stream quality.

Stream quality may change due to network conditions or CPU usage on either the subscriber or pubisher.

This reason is only used in sessions that have the media mode set to "routed". (See The OpenTok Media Router and media modes. This feature of the OpenTok Media Router has a subscriber drop the video stream when the video stream quality degrades, and the Subscriber sends the VideoDisabled event. When conditions improve, the video stream resumes, and the Subscriber sends the VideoEnabled event.

When the video stream is dropped, the subscriber continues to receive the audio stream, if there is one.

Constructor & Destructor Documentation

◆ Subscriber()

OpenTok.Subscriber.Subscriber ( Context  context,
Stream  stream,
IVideoRenderer  renderer = null 
)

Creates a new subscriber for a given stream.

Parameters
contextThe Content object used to manage resources for the Subscriber.
streamThe Stream object corresponding to the stream you will subscribe to.
rendererThe video renderer for the subscriber. If you do not specify a renderer, the video isn't rendered (and only audio is played back).

Member Function Documentation

◆ Dispose()

void OpenTok.Subscriber.Dispose ( )

Disposes of the Subscriber object's resources.

Property Documentation

◆ Id

string OpenTok.Subscriber.Id

The unique identifier for the Subscriber.

◆ PreferredFramerate

float OpenTok.Subscriber.PreferredFramerate

The preferred framerate for the subscriber’s stream.

Limiting the frame rate and video resolution (PreferredResolution) reduces the network and CPU usage on the subscribing client. You may want to use lower resolution based on the dimensions of subscriber's video in the app. You may want to use a lower frame rate or resolution for subscribers to a stream that is less important (and smaller) than other streams.

This property only applies when subscribing to a stream that uses the scalable video feature. Scalable video is available:

  • Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed).
  • Only for streams published by clients that support scalable video: clients that use the OpenTok Windows SDK, the OpenTok iOS SDK (on certain devices), the OpenTok Android SDK (on certain devices), or OpenTok.js in Chrome.

In streams that do not use scalable video, setting this property has no effect.

Note: The frame rate for scalable video streams automatically adjusts for each subscriber, based on network conditions and CPU usage, even if you do not set this property. Set this property if you want to set a maximum frame rate for this subscriber.

The frame rates available are based on the value of the maximum frame rate available for the stream. When you set the preferred frame rate for the subscriber, the OpenTok Windows SDK picks the best frame rate available that is closest to the preferred frame rate, based on the client's bandwidth and CPU constraints.

The actual frame rates available depend, dynamically, on network and CPU resources available to the publisher.

◆ PreferredResolution

Size OpenTok.Subscriber.PreferredResolution

The preferred resolution for the subscriber’s stream.

The preferred resolution for the subscriber's stream.

Limiting the video resolution and frame rate (PreferredFramerate) reduces the network and CPU usage on the subscribing client. You may want to use lower resolution based on the dimensions of subscriber's video in the app. You may want to use a lower frame rate or resolution for subscribers to a stream that is less important (and smaller) than other streams.

This property only applies when subscribing to a stream that uses the scalable video feature. Scalable video is available:

  • Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed).
  • Only for streams published by clients that support scalable video: clients that use the OpenTok Windows SDK, the OpenTok iOS SDK (on certain devices), the OpenTok Android SDK (on certain devices), or OpenTok.js in Chrome.

In streams that do not use scalable video, setting this property has no effect.

Note: The resolution for scalable video streams automatically adjusts for each subscriber, based on network conditions and CPU usage, even if you do not set this property. Set this property if you want to set a maximum resolution for this subscriber.

Not every resolution is available to a subscriber. When you set the preferred resolution, the OpenTok Windows SDK picks the best resolution available that matches your constraints. The resolutions available depend on the maximum width and height the Publisher sets for the stream, which are returned by the Stream.Width and Stream.Height properties of the Stream object. Each of the resolutions available for a stream will use the same aspect ratio.

◆ Stream

Stream OpenTok.Subscriber.Stream

The Stream corresponding to this subscriber.

◆ SubscribeToAudio

bool OpenTok.Subscriber.SubscribeToAudio

Whether the Subscriber is subscribing to audio (true) or not (false).

◆ SubscribeToVideo

bool OpenTok.Subscriber.SubscribeToVideo

Whether the Subscriber is subscribing to video (true) or not (false).

◆ VideoRenderer

IVideoRenderer OpenTok.Subscriber.VideoRenderer

The video renderer used by this subscriber.

Set the video renderer by passing in the VideoRenderer when calling the Subscriber(Context, Stream, IVideoRenderer) constructor.

Event Documentation

◆ AudioLevel

EventHandler<AudioLevelArgs> OpenTok.Subscriber.AudioLevel

Sent periodically to report the audio level of the subscriber.

◆ AudioStatsUpdated

EventHandler<AudioNetworkStatsEventArgs> OpenTok.Subscriber.AudioStatsUpdated

Invoked when the subscriber has audio stats to share.

◆ Connected

EventHandler OpenTok.Subscriber.Connected

Invoked when the instance has successfully connected to the stream and begins playing media.

◆ Error

EventHandler<ErrorEventArgs> OpenTok.Subscriber.Error

Invoked when a subscriber has failed to connect to the OpenTok server.

◆ StreamDisconnected

EventHandler OpenTok.Subscriber.StreamDisconnected

Called when the subscriber's stream has been interrupted.

In response to this method being called, you may want to provide a user interface notification, to let the user know that the audio-video stream is temporarily disconnected and the app is trying to reconnect to the stream.

If the client reconnects to the stream, the Subscribers sends the StreamReconnected event. Otherwise, the Session object sends the Session.StreamDropped event.

◆ StreamReconnected

EventHandler OpenTok.Subscriber.StreamReconnected

Sent when the subscriber's stream resumes (after temporarily being disconnected).

The Subscriber sends this event after it sends the StreamDisconnected event.

◆ VideoDisabled

EventHandler<VideoEventArgs> OpenTok.Subscriber.VideoDisabled

Called when the subscriber stops receiving video.

Check the reason property of the event arguments for the reason why the video stopped.

◆ VideoDisableWarning

EventHandler OpenTok.Subscriber.VideoDisableWarning

Called when the OpenTok Media Router determines that the stream quality has degraded and the video will be disabled if the quality degrades further.

If the quality degrades further, the subscriber disables the video and the Subscriber sends the VideoDisabled message. If the stream quality improves, the Subscriber sends the VideoDisableWarningLifted event.

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

This method is mainly called when connection quality degrades.

◆ VideoDisableWarningLifted

EventHandler OpenTok.Subscriber.VideoDisableWarningLifted

Called when the OpenTok Media Router determines that the stream quality has improved to the point at which the video being disabled is not an immediate risk.

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

This method is mainly called when connection quality improves.

◆ VideoEnabled

EventHandler<VideoEventArgs> OpenTok.Subscriber.VideoEnabled

Called when the subscriber's video stream starts (when there previously was no video) or resumes (after video was disabled).

Check the reason property of the event arguments for the reason why the video was enabled.

◆ VideoStatsUpdated

EventHandler<VideoNetworkStatsEventArgs> OpenTok.Subscriber.VideoStatsUpdated

Invoked when the subscriber has video stats to share.