Suggestions

close search

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

Visit the Vonage API Developer Portal

OpenTok.Subscriber

Used to consume an audio-video stream in the Vonage Video API session. More...

Inherits IDisposable.

Classes

class  AudioDataEventArgs
 Defines parameters for OpenTok.AudioData events. More...
class  AudioLevelArgs
 Defines arguments for AudioLevel events. More...
class  AudioNetworkStatsEventArgs
 Defines arguments for AudioStatsUpdated events. More...
class  Builder
 Used to create a Subscriber instance. More...
class  CaptionTextArgs
 Defines arguments for CaptionText events. More...
class  ErrorEventArgs
 Defines arguments for the Error event. More...
class  RtcStatsReportArgs
 Defines arguments for RtcStatsReport events. 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...
void GetRtcStatsReport ()
 Gets the RTC stats report for the subscriber. This is an asynchronous operation. When the stats are available, the RtcStatsReport message is sent. More...

Protected Member Functions

virtual void Dispose (bool disposing)

Properties

StreamStream [get]
 The stream for this subscriber. The properties of the Stream object are a snapshot of the stream state at the time this property is accessed, and will not be updated as the state of the stream changes. More...
EventHandler< AudioLevelArgsAudioLevel
 Sent periodically to report the audio level of the subscriber. More...
EventHandler< AudioDataEventArgsAudioData
 Called periodically to report the PCM audio data of the subscriber. More...
EventHandler< RtcStatsReportArgsRtcStatsReport
 Sent in response to a call to GetRtcStatsReport(). More...
bool SubscribeToCaptions [get, set]
 Whether the Subscriber is subscribing to captions (true) or not (false). The default value is the captions value of the stream's publisher.Publisher.PublishCaptions 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...
double AudioVolume [get, set]
 The audio volume of the subscriber. 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< CaptionTextArgsCaptionText
 Sent when the subscriber's stream receives caption text. 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 Vonage Video API server. More...
EventHandler VideoDisableWarning
 Called when the Vonage Video API 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 Vonage Video API 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...

Detailed Description

Used to consume an audio-video stream in the Vonage Video API session.

Use the Subscriber.Builder class to create a Subscriber instance. 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 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 publisher.

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 Vonage Video API 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.

◆ GetRtcStatsReport()

void OpenTok.Subscriber.GetRtcStatsReport ( )

Gets the RTC stats report for the subscriber. This is an asynchronous operation. When the stats are available, the RtcStatsReport message is sent.

Also see AudioStatsUpdated, VideoStatsUpdated, and Publisher.GetRtcStatsReport().

Property Documentation

◆ AudioData

EventHandler<AudioDataEventArgs> OpenTok.Subscriber.AudioData

Called periodically to report the PCM audio data of the subscriber.

◆ AudioLevel

EventHandler<AudioLevelArgs> OpenTok.Subscriber.AudioLevel

Sent periodically to report the audio level of the subscriber.

◆ AudioVolume

double OpenTok.Subscriber.AudioVolume

The audio volume of the subscriber.

The audio volume, between 0 and 100, of the subscriber. When setting the value, if it is not in this range, it will be clamped to it.

The default value is 100.

◆ 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 Vonage Video API Media Router (sessions with the media mode set to routed).
  • Only for streams published by clients that support scalable video (see the documentation for the scalable video feature).

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 Vonage Video API 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 Vonage Video API Media Router (sessions with the media mode set to routed).
  • Only for streams published by clients that support scalable video (see the documentation for the scalable video feature).

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 Vonage Video API 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.

◆ RtcStatsReport

EventHandler<RtcStatsReportArgs> OpenTok.Subscriber.RtcStatsReport

Sent in response to a call to GetRtcStatsReport().

◆ Stream

Stream? OpenTok.Subscriber.Stream

The stream for this subscriber. The properties of the Stream object are a snapshot of the stream state at the time this property is accessed, and will not be updated as the state of the stream changes.

◆ SubscribeToAudio

bool OpenTok.Subscriber.SubscribeToAudio

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

◆ SubscribeToCaptions

bool OpenTok.Subscriber.SubscribeToCaptions

Whether the Subscriber is subscribing to captions (true) or not (false). The default value is the captions value of the stream's publisher.Publisher.PublishCaptions

◆ 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

◆ AudioStatsUpdated

EventHandler<AudioNetworkStatsEventArgs> OpenTok.Subscriber.AudioStatsUpdated

Invoked when the subscriber has audio stats to share.

◆ CaptionText

EventHandler<CaptionTextArgs> OpenTok.Subscriber.CaptionText

Sent when the subscriber's stream receives caption text.

◆ 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 Vonage Video API 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 Vonage Video API 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 Vonage Video API 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 Vonage Video API 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 Vonage Video API 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.