The Vonage Video API live streaming feature lets you broadcast a video session to a large audience using HTTP live streaming (HLS) or an RTMP stream.
This page includes the following sections:
More clients can simultaneously view an HLS stream than can view an OpenTok live interactive video session. For example, you may provide an HLS stream to a client if the OpenTok session has reached the 15,000-connection limit for OpenTok live interactive broadcasts. HLS streams support an unlimited number of viewers. RTMP streams are limited by the number of viewers supported by the RTMP provider.
You can use the RTMP streaming feature to provide a video stream to a platform that supports RTMP streams, such as YouTube Live or Facebook.
Also, clients that do not support WebRTC can view the HLS or RTMP stream.
A broadcast can include up to 16 video streams from the session (and up to 50 audio streams). If the session includes more than 16 video streams concurrently, the extra streams will not be included in the broadcast.
An HLS is delayed 15 to 20 seconds behind the live streams in the OpenTok session. During the initial delay, the broadcast stream is not available. Do not provide the broadcast URL to clients until the HLS or RTMP stream is available.
For an RTMP stream, the OpenTok platform introduces a latency of approximately 5 seconds. However, each the RTMP delivery platform (such as YouTube Live or Facebook) will add additional latency based on their processing of the video before publishing it.
The HLS and RTMP streaming 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.
HLS playback is not supported in all browsers. However, there are a number of plugins, such as Flowplayer, that provide cross-browser support (using Flash Player in browsers that do not provide direct HLS support).
OpenTok RTMP streams have the following specifications:
Streams published from Safari show up as audio-only in live streaming broadcasts.
See the OpenTok pricing page for details on HLS and RTMP streaming pricing.
Use the OpenTok REST API to start and stop live streaming of a session, and to check the status of a live streaming broadcast.
The HLS and RTMP streams stop automatically 60 seconds after the last client disconnects from
the session. Also there is a default maximum duration of 4 hours (14,400 seconds) for each HLS and RTMP stream
(the live stream broadcast automatically stops when this duration is reached). You can change the
maximum duration for the broadcast by setting the maxDuration
property when calling the
start broadcast REST method. You can set the maximum duration to be
60 seconds to 10 hours (36,000 seconds).
You can limit the maximum bitrate to be used for the broadcast by setting the
maxBitrate
property when calling the start broadcast
REST method. You can set the maximum bitrate to be a value from 100,000 to
6,000,000 bits per second.
When using the OpenTok live streaming feature, you can customize the layout of videos in the HLS or RTMP stream.
By default, the OpenTok live streaming feature arranges videos from the OpenTok session in a tiled layout in the composed HLS or RTMP video. The layout is based on the number of videos in the session. For example, the following illustrates the layout when there are 1, 2, 4, or 5 streams in a session:
This is known as the "best fit" layout. Alternately, you can select from a number of other predefined layouts. For the other layouts, you assign a class name to each OpenTok video streams to determine how it will appear in the layout. (See Predefined layout types.)
You can also define your own custom layouts using CSS. See Defining custom layouts.
By default, the broadcast video is 640x480 pixels (SD landscape, 4:3 aspect ratio). Individual
OpenTok videos are arranged in container rectangles within the composite video. By default,
the video is drawn with the CSS object-fit
property set to contain
. For example, the following
illustration shows a best-fit layout with two SD landscape (4:3) videos (1 and 4) and two
HD landscape (16:9) videos (2 and 3):
You can modify this behavior using custom layouts.
You can also set a broadcast stream to use an 480x640 (SD portrait, 3:4 aspect ratio), 1280x720 (HD landscape, 16:9 aspect ratio), 720x1280 (HD portrait, 9:16 aspect ratio), 1920x1080 (FHD landscape, 16:9 aspect ratio), 1080x1920 (FHD portrait, 9:16 aspect ratio) resolution when you call the start broadcast method of the OpenTok REST API. You may want to use a portrait aspect ratio for broadcasts that include video streams from mobile devices (which often use the portrait aspect ratio).
When you start the live streaming broadcast for a session, using the OpenTok REST API, you can, optionally, specify the initial layout type.
Set the Content-Type
to "application/json"
and set the in the layout type as a property of the JSON
data sent in the POST request.
{
"sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
"layout": {
"type": "pip"
}
}
If you are using a custom layout (see Defining
custom layouts), set the
type
property to "custom"
and pass in the stylesheet as an additional property —
stylesheet
:
{
"sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
"layout": {
"type": "custom",
"stylesheet": "stream.instructor {position: absolute; width: 100%; height:50%;}"
}
}
You can also specify a layout type to use when there is a screen-sharing stream
in the session by setting the screenshareType
property of the layout
property (see
screen-sharing layouts):
{
"sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
"layout": {
"type": "bestFit",
"screenshareType": "pip"
},
"name" : "archive_name",
"outputMode" : "composed"
}
The request returns a 400 error response code if you specify an invalid type.
You can also you can also specify the initial layout type when starting an broadcast using the OpenTok server SDKs:
OpenTok.startBroadcast(sessionId, properties)
(call the
layout()
method of the BroadcastProperties.Builder
object)OpenTok.startBroadcast()
(set the layout
property of the options
parameter)OpenTok->startBroadcast()
(set the layout
property of the options
parameter)opentok.start_broadcast()
(set the layout
property of the options
parameter)Broadcasts.create()
(set the layout
property of the options
hash)OpenTok.StartBroadcast()
(set the layout
parameter)If you do not specify an initial layout type, the HLS or RTMP stream uses the best fit layout type. If you specify any other layout type, be sure to apply appropriate layout classes for streams in the OpenTok session (see Assigning layout classes to OpenTok streams).
You can dynamically change the layout type by calling the OpenTok /broadcast/layout REST API.
Set the Content-Type
to "application/json"
and include the layout type as a property of
the JSON data in the PUT request:
{
"type": "pip"
}
If you are using a custom layout (see Defining
custom layouts) set the type
property to "custom"
and pass in the stylesheet as an additional property — stylesheet
:
{
"type": "custom",
"stylesheet": "stream.instructor {position: absolute; width: 100%; height:50%;}"
}
You can also specify a layout type to use when there is a screen-sharing
stream in the session by setting the screenshareType
property (see
screen-sharing layouts):
{
"type": "bestFit",
"screenshareType": "pip"
}
The request returns a 400 error response code if you specify an invalid type.
You can also you can also change the layout type using the OpenTok server SDKs:
OpenTok.setBroadcastLayout()
OpenTok.setBroadcastLayout()
OpenTok->setBroadcastLayout()
opentok.set_broadcast_layout()
Broadcasts.layout()
OpenTok.SetBroadcastLayout()
When specifying a layout type other than the default Best Fit layout type, be sure to apply appropriate layout classes for streams in the OpenTok session (see Assigning layout classes to OpenTok streams).
When you start a live streaming broadcast, if you set the streamMode
to "manual"
, you can choose
the streams to include in the broadcast. You can add and remove streams during the broadcast.
And you can specify whether the broadcast will include a stream's audio or video (or both). See
Starting a live streaming broadcast and
Selecting streams to be included in a live streaming broadcast.
HLS broadcasts support DVR functionality, which lets users rewind, pause, and resume the broadcasts
(in players that support DVR). You can set the dvr
option to true
when
starting a live streaming broadcast.
With DVR enabled, the HLS URL will include a ?DVR
query string appended
to the end.
The DVR feature provides a two-hour window for playing back broadcast content. While the broadcast is in progress, you can play back (and rewind to) any point in the broadcast up to two hours prior to the current time. The DVR recording is unavailable two hours after the broadcast is stopped.
The manifest of the HTTP live stream includes an EXT-X-PROGRAM-DATE-TIME
header, which is set to
the timestamp of the real-time start of the capture of the streaming segment. This is defined
in the HTTP live streaming specification.
This is set to a ISO 8601:2004
date/time value, in UTC.
For example, the header will look like:
#EXT-X-PROGRAM-DATE-TIME:2021-09-02T11:45:00.810+00:00
These timestamps let you synchronize events in client applications to account for the delay in the HLS stream. For example, if you want to send a client an event to display an emoji at a specific time in the video stream, the client can use the timestamp to delay the display of the emoji based on the delay of the received stream.
To set an HLS broadcast to support low-latency mode, set the low-latency
option to true
when
starting a live streaming broadcast.
Some HLS players do not support low-latency mode.
This feature is incompatible with DVR HLS broadcasts.
To start multiple live streaming broadcasts for the same session
simultaneously, set the multiBroadcastTag
option when
starting each live streaming broadcast.
You must set this to a unique string for each simultaneous broadcast of an ongoing session.
Although you can specify multiple RTMP streams when starting a live streaming broadcast,
they will each use the same options (such as the assigned streams and layout). However,
when you start simultaneous broadcasts (by calling the REST method multiple times, with
the multiBroadcastTag
option set), you can use different layouts and assign different
streams to each simultaneous broadcasts.
Use the OpenTok REST API to get information about a live streaming broadcast or to list live streaming broadcasts. Or use the OpenTok server SDKs:
OpenTok.getBroadcast()
OpenTok.getBroadcast()
and OpenTok.listBroadcasts()
OpenTok->getBroadcast()
opentok.get_broadcast()
Broadcasts.find()
and Broadcasts.all()
OpenTok.GetBroadcast()
The live streaming broadcast feature has the following known issues:
When you stop a live streaming broadcast, the last 5 seconds (prior to stopping the broadcast) of content from the OpenTok session are omitted from the broadcast stream.
Live streaming broadcasts do not support the #EXT-X-ENDLIST
tag for HLS streams.
Your application will need to stop the HLS player when the HLS stream ends.