Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalVonage 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 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.
| Number of publishers * | Simultaneous live interactive participants per session (participants subscribe to all publishers) |
|---|---|
| 1 | 15,000 |
| 2 | 15,000 |
| 3 | 13,000 |
| 4 | 11,000 |
| 5 | 8,000 |
| 6 | 6,800 |
| 7 | 5,700 |
| 8 | 5,000 |
| 9 | 4,300 |
| 10 | 4,000 |
| 12 | 3,400 |
| 15 | 2,900 |
| 16 | 2,800 |
| 20 | 2,000 |
| 25 | 1,600 |
| 50 | 800 |
| 55 | 700 |
* 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, OpenTok 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 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.
There are a few API enhancements you should use to support large numbers of clients connecting to OpenTok sessions. See the following sections:
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.
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.)
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.)
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.)
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.)
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.)
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 (15,000) or stream limit (15,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).
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'.
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 OpenTokError 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 OpenTokError object with the code property
set to SubscriberStreamLimitExceeded.
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.
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.
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 .
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 if you would like to set a minimum video bitrate for a live interactive video broadcast.
Live interactive video uses the same subscribed minute pricing as is used by other OpenTok sessions. For details, see Pricing.