Subscribe: Management & Events

Managing Subscriber Streams (React Native)

Detecting When a Stream's Video Dimensions Change

A stream's video dimensions can change if a stream published from a mobile device resizes (for example, due to device orientation changes) or if a screen-sharing source window is resized. When a stream's video dimensions change, the Session object dispatches a event, with set to .

Setting the Preferred Frame Rate and Resolution

When subscribing to a stream that uses the scalable video feature, you can set to to automatically manage Subscriber video resolution and optimize CPU/network usage. For advanced control, set the preferred frame rate and resolution for the subscribed stream:

• — Valid values are 30, 15, 7, and 1. Leave undefined to use the highest available frame rate.
• — Valid values are , , and . Leave undefined to use the highest available resolution.

Detecting When Streams Leave a Session

When a remote stream leaves a session, the component dispatches a event:

The event includes details such as , , , , , and .

Custom Rendering of Subscribers

By default, renders child views for subscriber videos. You can also provide a render function to fully control rendering using :

Setting Stream Properties

Set global properties for all subscribers via the prop on , or set per‑stream properties via the prop.

Managing Subscriber Streams (iOS Swift)

Manage subscribers, handle events, and adjust preferences in iOS.

Detecting When a Subscriber's Video Is Disabled

func subscriberVideoDisabled(_ subscriber: OTSubscriberKit, reason: OTSubscriberVideoEventReason) {
    print("subscriber video disabled.")
}

Possible Reasons

• OTSubscriberVideoEventPublisherPropertyChanged
• OTSubscriberVideoEventQualityChanged
• OTSubscriberVideoEventSubscriberPropertyChanged

When video resumes:

func subscriberVideoEnabled(_ subscriber: OTSubscriberKit, reason: OTSubscriberVideoEventReason) {
    print("subscriber video enabled.")
}

Getting Information About a Stream

The OTStream object includes:

• connection — The publishing connection
• creationTime — Timestamp
• hasAudio — Bool
• hasVideo — Bool
• name — Optional stream name
• session — Associated session
• streamId — Unique ID
• videoDimensions — CGSize
• videoType — Camera, screen, or custom

You can monitor stats using OTSubscriberKitNetworkStatsDelegate.

See the client observability guide for more details.

Setting the Preferred Frame Rate and Resolution

For scalable video streams, you can set:

• SubscriberKit.preferredFrameRate
• SubscriberKit.preferredResolution

Managing Subscriber Streams (JavaScript Only)

Restricting the Frame Rate of a Subscribed Stream

You can also restrict the frame rate of a Subscriber's video stream. To restrict the frame rate of a subscriber, call the method of the Subscriber object, passing in :

Pass in and the frame rate of the video stream is not restricted:

When the frame rate is restricted, the Subscriber video frame will update once or less per second.

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. In relayed sessions, calling this method has no effect.

Restricting the subscriber frame rate has the following benefits:

• It reduces CPU usage.
• It reduces the network bandwidth consumed by the app.
• It lets you subscribe to more streams simultaneously.

Reducing a subscriber's frame rate has no effect on the frame rate of the video in other clients.

Detecting When a Subscriber's Audio Is Blocked or Unblocked

Some browsers automatically block audio playback, requiring a event before audio playback starts for subscribers. These browsers include Safari, Firefox 66+, and Chrome 71+.

The Subscriber object displays an audio playback button if audio playback is blocked. You can disable the Subscriber's default audio playback button and display your own UI element that the user will click to start audio playback.

See Displaying a custom UI element when Subscriber audio is blocked.

When the subscriber's audio is blocked, the Subscriber object dispatches a event, and it dispatches an event when the audio is unblocked:

Also, the Subscriber includes an which returns if the audio is blocked or if it is not.

Subscriber audio is unblocked when any of the following occurs:

• The user clicks the default Subscriber audio playback icon
• The OT.unblockAudio() method is called in response to an HTML element dispatching a event (if you have disabled the default audio playback icon)
• The local client gains access to the camera or microphone (for instance, in response to a successful call to ).

For more information, see this Mozilla article about autoplay in Firefox and this Google article about autoplay in Chrome.

Detecting When a Subscriber's Video Is Disabled

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

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

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

• — The publisher stopped publishing video by calling .
• — 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 Subscriber dispatches a event.

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

By default, the Subscriber displays a video disabled indicator when a event with this reason is dispatched and removes the indicator when the event occurs.

When you publish a stream, you can prevent it from having its video disabled due to stream quality. Set to in the options you pass into .

Getting Subscriber Stats (Web)

The method of a Subscriber object provides you with 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

The following code logs loss ratios and bit rates every second:

To get statistics for a stream published by the local client, you must use a routed session and set the option to when subscribing:

To get more detailed stream statistics, use .

Setting the Preferred Frame Rate and Resolution (Web)

When subscribing to a stream that uses the scalable video feature, you can set to to automatically manage Subscriber video resolution. For advanced control, set and in the options you pass to (or use and after subscribing).

Managing Subscriber Streams (Android)

Manage subscribers, handle events, and adjust preferences in Android.

Detecting When a Subscriber's Video Is Disabled

When video is disabled:

override fun onVideoDisabled(subscriber: SubscriberKit, reason: String) {
    // Video disabled
}

When video resumes:

override fun onVideoEnabled(subscriber: SubscriberKit, reason: String) {
    // Video resumed
}

The reason parameter explains why the change occurred.

Getting Information About a Stream

The Stream object provides:

• getConnection() — Connection object
• getCreationTime() — Creation timestamp
• hasAudio() — Boolean
• hasVideo() — Boolean
• getName() — Stream name
• getStreamId() — Unique ID
• getVideoHeight() — Height in pixels
• getVideoWidth() — Width in pixels
• getVideoType() — Camera, screen share, or custom

You can also monitor stats:

• setAudioStatsListener()
• setVideoStatsListener()
• setMediaLinkStatsListener()
• getRtcStatsReport()

Setting the Preferred Frame Rate and Resolution

For scalable video streams, you can set preferences:

• SubscriberKit.setPreferredFrameRate()
• SubscriberKit.setPreferredResolution()

Managing Subscriber Streams (Windows)

Manage subscribers, handle events, and adjust preferences in Windows.

Detecting When a Subscriber's Video Is Disabled

The OpenTok Media Router may stop sending video if network conditions degrade.

The subscriber continues receiving audio if available.

When video is disabled, the Subscriber object sends a VideoDisabled event:

subscriber.VideoDisabled += Subscriber_VideoDisabled;

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

When video resumes:

subscriber.VideoEnabled += Subscriber_VideoEnabled;

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

You may want to adjust the UI in response to these events.

Getting Information About a Stream

The Stream object exposes the following properties:

• Connection — The publishing connection
• CreationTime — Stream creation timestamp
• HasAudio — Whether the stream has audio
• HasVideo — Whether the stream has video
• Name — Stream name
• Id — Unique stream ID
• Height — Video height in pixels
• Width — Video width in pixels
• VideoSourceType — Camera, screen-sharing, or custom source type

Possible VideoSourceType values:

• VideoSourceType.StreamVideoTypeCamera
• VideoSourceType.StreamVideoTypeScreen
• VideoSourceType.StreamVideoTypeCustom

Monitoring Statistics

Use these events to monitor stream statistics:

• Subscriber.AudioStatsUpdated
• Subscriber.VideoStatsUpdated
• Subscriber.MediaLinkStatsUpdated

To retrieve low-level RTC statistics:

subscriber.GetRtcStatsReport();

Setting the Preferred Frame Rate and Resolution

For streams using the scalable video feature, configure:

• Subscriber.PreferredFramerate
• Subscriber.PreferredResolution

Managing Subscriber Streams (Linux)

Manage subscribers, handle events, and adjust preferences in Linux.

Detecting When a Stream's Video Is Disabled

The on_stream_has_video_changed callback function of the otc_session_callbacks struct is called when a stream’s video availability changes.

The stream parameter is a pointer to an otc_stream struct.

Use:

otc_stream_get_id(stream)

to retrieve the stream ID.

Getting Information About a Stream

Use the following functions to retrieve stream information:

• otc_stream_get_connection() — Returns the publishing connection
• otc_stream_get_creation_time() — Returns the stream creation timestamp
• otc_stream_has_audio() — Whether the stream is publishing audio
• otc_stream_has_video() — Whether the stream is publishing video
• otc_stream_has_audio_track() — Whether the stream has an audio track
• otc_stream_has_video_track() — Whether the stream has a video track
• otc_stream_get_name() — Returns the stream name
• otc_stream_get_id() — Returns the unique stream ID
• otc_stream_get_video_height() — Returns the video height in pixels
• otc_stream_get_video_width() — Returns the video width in pixels
• otc_stream_get_video_type() — Returns the stream video type

Possible video types:

• OTC_STREAM_VIDEO_TYPE_CAMERA
• OTC_STREAM_VIDEO_TYPE_SCREEN

Monitoring Statistics

Use these subscriber callback functions:

• on_audio_stats()
• on_video_stats()
• on_media_link_stats()

To retrieve low-level RTC statistics, use:

otc_subscriber_get_rtc_stats_report()

Setting the Preferred Frame Rate and Resolution

For streams using the scalable video feature, you can set preferred frame rate and resolution using:

• otc_subscriber_set_preferred_framerate()
• otc_subscriber_set_preferred_resolution()