Suggestions

close search

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

Visit the Vonage API Developer Portal

Live streaming broadcasts

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 5,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.

Starting and stopping live streaming broadcasts

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 REST method. You can set the maximum duration to be 60 seconds to 10 hours (36,000 seconds).

Configuring video layout for OpenTok live streaming broadcasts

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), or 720x1280 (HD 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).

Specifying the initial layout type

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:

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).

See Predefined layout types.

Dynamically changing the layout type during a live streaming broadcast

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:

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).

Getting information about live streaming 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:

Known issues with the OpenTok live streaming broadcast feature

Currently, 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.