Live Interactive Video Broadcasts

In a live interactive video broadcast, a large number of clients can communicate live by publishing and subscribing to each others' streams in the session. A live interactive video broadcast session can support up to 15,000 total participants in the session, based on the number of active publishers in the session.

The table below details the number of live interactive broadcast participants that can subscribe to all the publishers of the session. The interactive broadcast participants are the low-latency, view-only subscribers of all the published streams and viewers of the live interactive broadcast. The publishers of the session can be considered the hosts of the broadcast, and as hosts they can also subscribe to the other published streams. As the number of publishers per session increases, the number of simultaneous viewers of all published streams is also reduced.

For example, based on the table below, when there are 1 or 2 published streams in the session, up to 15,000 participants can view both of these published streams with real-time latency as live broadcast participants. Similarly, when there are 3 published streams in the session, up to 13,000 participants can view all 3 published streams with real-time latency as live broadcast participants.

• Published streams include both camera and screen-sharing streams.

If the number of participants in the session is greater than the value in the table, you should use the live streaming feature (see Live streaming broadcasts).

Similarly, sessions support up to 15,000 clients simultaneously connecting to a session.

Application developers should manage the platform limits in the application. See the next section.

The live interactive video broadcast feature is only available for routed sessions (sessions that use the Vonage Media Router). For more information, see The Media Router and Media Modes.

Live interactive video broadcasts support HD video (as well as lower-resolution video) if the client's resources (bandwidth and CPU) support the resolution.

Building your app to support live interactive video broadcasts

There are a few API enhancements you should use to support large numbers of clients connecting to sessions. See the following sections:

• Suppressing connection events
• Detecting when connection and stream limits are exceeded

Suppressing connection events

If a large number of clients will connect to a session, it is important to disable connection events in the clients. These events include those dispatched when other clients connect and disconnect from the session. Most clients do not need to process these events, and disabling them prevents clients from incurring performance penalties (for example in publishing or subscribing to audio-video streams) caused by these high-volume events.

In version 2.10.0 and later, each of the client SDKs (for Web, iOS, and Android) includes an API enhancement for disabling connection events in the client.

Although you can use other supported client versions (2.9.0+) in large sessions, connection events will not be suppressed in clients using versions older than 2.10.0+. Clients using older versions of OpenTok.js may see degraded performance, due to the high-volume connection events.

Suppressing connection events with OpenTok.js (web)

When initializing the Session object, create an object with the connectionEventsSuppressed property set to true, and pass in that object as the options parameter when calling the OT.initSession() method. Then connect to the session:

This prevents the Session object from dispatching connectionCreated and connectionDestroyed events when other clients connect to or disconnect from the session. (Also, the Vonage server does not send these events to the web client.)

Suppressing connection events with the iOS SDK

When initializing an OTSessionSettings object, set its connectionEventsSuppressed property to YES. Then pass that object in as the settings parameter when calling the [OTSession initWithApiKey:sessionId:delegate:settings:] method to initialize the OTSession object:

OTSessionSettings *settings = [[OTSessionSettings alloc] init];
settings.connectionEventsSuppressed = YES;
OTSession *session = [[OTSession alloc] initWithApiKey:applicationId
                                        sessionId:sessionId
                                        delegate:self
                                        Settings:settings];

Then connect to the session:

OTError* error = nil;
[session connectWithToken:kToken error:&error];
if (error) {
  NSLog(@"connect failed with error: (%@)", error);
}

This prevents the [SessionDelegate session:connectionCreated:] messages from being sent when other clients connect to or disconnect from the session. (Also, the Vonage server does not send these events to the iOS client.)

Suppressing connection events with the Android SDK

To connect to the session, instantiate a Session.Builder object, passing in your App ID and session ID. Then call the connectionEventsSuppressed() method of the Builder object, passing in true. Call the build() method to create the Session object. Then call the connect() method of the Session object to connect to the session:

Do not call the Session.setConnectionListener(ConnectionListener listener) method (to set a ConnectionListener for the Session object); calling this method will have no effect. Suppressing connection events prevents the ConnectionListener methods from being called when other clients connect to or disconnect from the session. (Also, the Vonage server does not send these events to the Android client.)

Suppressing connection events with the Windows SDK

To connect to the session, instantiate a Session object using the Session.Builder class. Pass your App ID and session ID into the Session.Builder() constructor, and set the connectionEventsSuppressed parameter to true. Then call the Connect() method of the Session object to connect to the session:

Do not set the Session.StreamReceived or Session.StreamDropped event handlers, Suppressing connection events prevents these events from being raised when other clients connect to or disconnect from the session. (Also, the Vonage server does not send these events to the Windows client.)

Suppressing connection events with the Linux SDK

To connect to the session, instantiate an otc_session_settings struct, passing in your App ID and Vonage session ID. Then call the otc_session_settings_set_connection_events_suppressed() function, passing in the otc_session_settings instance as the first parameter, and OTC_TRUE as the second, suppress, parameter. Then call the otc_session_new_with_settings() function to create the otc_session struct. Then function to connect to the session:

otc_session_settings *session_settings = otc_session_settings_new();
otc_session_settings_set_connection_events_suppressed(session_settings, OTC_TRUE);

otc_session_callbacks session_callbacks = {0};
// Set the callback functions of the otc_session_callbacks instance.

otc_session *session = otc_session_new_with_settings(APPLICATION_ID, SESSION_ID,
                                                     &session_callbacks,
                                                     session_settings);
otc_session_connect(session, TOKEN);

Do not set the otc_session_callbacks.on_connection_created or otc_session_callbacks.on_connection_dropped callback functions. Suppressing connection events prevents these callback functions from being called when other clients connect to or disconnect from the session. (Also, the Vonage server does not send these events to the Linux client.)

Detecting when connection and stream limits are exceeded

The client SDKs include errors that indicate when a client is attempting to connect to a session or subscribe to a stream when the connection (15,000) or stream limit (15,000) for the session has been exceeded.

If the client cannot connect to a session or subscribe to a stream because the connection or stream limit has been reached, you can have the client view a live streaming broadcast of the session (if you have implemented one).

Connection and stream limit errors in the OpenTok.js (web)

If you attempt to connect to a session when the connection limit for a session (15,000 simultaneous connected clients) has been reached, the completion handler for the Session.connect() method is called with the error parameter set to an Error object with the name property set to 'OT_CONNECTION_LIMIT_EXCEEDED'.

If you attempt to subscribe to a stream when the stream limit for a session has been exceeded, the completion handler for the Session.subscribe() method is called with the error parameter set to an Error object with the name property set to 'OT_STREAM_LIMIT_EXCEEDED'.

Connection and stream limit errors in the Android SDK

If you attempt to connect to a session when the connection limit for a session (15,000 simultaneous connected clients) has been reached, the Session.SessionListener.onError(session, error) method is called with the error parameter set to an Error object with the code property set to SessionConnectionLimitExceeded.

If you attempt to subscribe to a stream when the stream limit for a session has been reached, the Session.SubscriberListener.onError(subscriber, error) method is called with the error parameter set to an Error object with the code property set to SubscriberStreamLimitExceeded.

Video quality in live interactive video broadcasts

Large-scale sessions benefit from the scalable video feature. With this feature, subscribing endpoints to consume different video resolutions and frame rates based on their network and CPU conditions. This feature is available in the Vonage iOS SDK (on certain devices), the Android SDK (on certain devices), the Windows SDK, and OpenTok.js in Chrome and Safari.

Connection and stream limit errors in the iOS SDK

If you attempt to connect to a session when the connection limit for a session (15,000 simultaneous connected clients) has been reached, the [SessionDelegate session:didFailWithError:] message is sent with the error set to an OTError object with the code property set to OTSessionConnectionLimitExceeded.

If you attempt to subscribe to a stream when the stream limit for a session has been reached, the [OTSubscriberKitDelegate subscriber:didFailWithError:] message is sent with the error set to an OTError object with the code property set to OTSubscriberStreamLimitExceeded.

Connection and stream limit errors in the Windows SDK

If you attempt to connect to a session when the connection limit for a session (15,000 simultaneous connected clients) has been reached, the Session object sends an Error event sent with the ErrorCode set to ErrorCode.SessionConnectionLimitExceeded.

If you attempt to subscribe to a stream when the stream limit for a session has been reached, the Subscriber object sends an Error event with the ErrorCode set to an OTError object with the code property set to ErrorCode.SubscriberStreamLimitExceeded.

Connection and stream limit errors in the Linux SDK

If you attempt to connect to a session when the connection limit for a session (15,000 simultaneous connected clients) has been reached, the otc_session_callbacks.on_error() function is called with the error parameter set to OTC_SESSION_CONNECTION_LIMIT_EXCEEDED.

If you attempt to subscribe to a stream when the stream limit for a session has been reached, the otc_subscriber_callbacks.on_error() function is called with the error parameter set to OTC_SUBSCRIBER_STREAM_LIMIT_EXCEEDED.

Pricing for live interactive broadcasts

Live interactive video uses the same subscribed minute pricing as is used by other sessions. For details, see Pricing.