Suggestions

close search

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

Visit the Vonage API Developer Portal

Live interactive video broadcasts

Vonage Video API broadcast lets you share live video sessions with many viewers.

This page includes the following sections:


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 3,000 simultaneous viewers of streams (subscribers to streams) in the session. It is important to distinguish between the number of streams and the number of viewers of streams — since OpenTok sessions may have more than one published video stream, the stream limit is different from app to app. To obtain the the number of viewers supported, simply divide the stream limit — 3,000 — by the expected number of simultaneously published streams in the session at one time. For example, 2 publishers can broadcast to an audience of 1,500 people.

Number of publishers * Simultaneous live interactive viewers supported
1 3,000
2 1,500
3 1,000
4 750
5 600

If the number of viewer of streams times the number of streams is greater than 3,000, you should use the live streaming feature (see Live streaming broadcasts)

Similarly, OpenTok sessions support up to 3,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 OpenTok Media Router). For more information, see The OpenTok 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 OpenTok sessions. See the following sections:

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.

Important: To optimize your application for this large scale, be sure to use the connection event suppression APIs described here.

In version 2.10.0 and later, each of the OpenTok client SDKs (for Web, iOS, and Android) includes an API enhancement for disabling connection events in the client. These are described in the following sections:

Although you can use other supported OpenTok 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:

var props = {connectionEventsSuppressed: true};
var session = OT.initSession(API_KEY, SESSION_ID, props);
session.connect(token, function(error) {
  if (error) {
    console.log('Error connecting: ', error.code, error.message);
  } else {
    console.log('Connected 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 OpenTok server does not send these events to the web client.)

Suppressing connection events with the OpenTok 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:apiKey
                                        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:] and [SessionDelegate session:connectionCreated:] messages from being sent when other clients connect to or disconnect from the session. (Also, the OpenTok server does not send these events to the iOS client.)

Suppressing connection events with the OpenTok Android SDK

To connect to the session, instantiate a Session.Builder object, passing in your API key and OpenTok 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:

Session session = new Session.Builder(this, API_KEY, mySessionId)
                    .connectionEventsSuppressed(true)
                    .build();

session.connect(myToken);

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 OpenTok server does not send these events to the Android client.)

Suppressing connection events with the OpenTok Windows SDK

To connect to the session, instantiate a Session object using the Session.Builder class. Pass your API key and OpenTok 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:

Session = new Session.Builder(Context.Instance, API_KEY, SESSION_ID, true).Build();
// Set event handlers for the Session object. Then, connect:
Session.Connect(TOKEN);

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 OpenTok server does not send these events to the Windows client.)

Suppressing connection events with the OpenTok Linux SDK

To connect to the session, instantiate an otc_session_settings struct, passing in your API key and OpenTok 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(API_KEY, 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 OpenTok server does not send these events to the Linux client.)

Detecting when connection and stream limits are exceeded

The OpenTok client SDKs include errors that indicate when a client is attempting to connect to a session or subscribe to a stream when the connection (3,000) or stream limit (3,000) for the session has been exceeded. These are described in the following sections:

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 OpenTok.js (web)

If you attempt to connect to a session when the connection limit for a session (3,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 (3,000 simultaneous subscribers to streams) 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 the OpenTok Android SDK

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

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

Connection and stream limit errors the OpenTok iOS SDK

If you attempt to connect to a session when the connection limit for a session (3,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 (3,000 simultaneous connected clients) 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.

Video quality in live interactive video broadcasts

Large-scale sessions benefit from the OpenTok 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 OpenTok iOS SDK (on certain devices), the OpenTok Android SDK (on certain devices), the OpenTok Windows SDK, and OpenTok.js in Chrome and Safari.

When you are using the live interactive video broadcast feature, you may want to set a minimum video bitrate for streams that will be consumed by many subscribers. This will maintain video at the specified quality (or better) for all clients subscribing to this stream. However, you should ensure that the client publishing the stream can support the minimum video bitrate you assign. Contact us at broadcast@tokbox.com if you would like to set a minimum video bitrate for a live interactive video broadcast.

Pricing for live interactive broadcasts

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