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

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

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

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

Selecting streams to be included in a live streaming broadcast

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.

Enabling DVR functionality in HLS broadcasts

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.

Using HLS timestamp metadata to synchronize events

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.

Low-latency HLS broadcasts

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.

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

Audio-only and video-only broadcasts

When you start a live-streaming broacast using the OpenTok REST API, you can specify whether it will include audio, video, or both. (See the hasAudio and hasVideo options.) The default is to broadcast both.

Note: Audio-only broadcasts will include video with black 160x120 frames in RTMP streams. Some endpoints, like YoutTube and Facebook, do not accept audio-only RTMP 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:

Monitoring live streaming broadcast status changes (beta)

You can register a callback URL (webhook) to receive notifications of status changes for a project's live streaming broadcasts. The status of an live streaming broadcast is set to ether "started" or "stopped".

Note: This is a beta feature.

To register a broadcast callback for a project:

  1. Log in to your Vonage Video API Account.

  2. In the left-hand menu, select the desired Account (if you have multiple accounts).

  3. In the left-hand menu, select the Project for which you want to register a secure callback.

  4. Scroll down to Project Settings. Click the Edit icon, turn on the Secured Callback slider button, and click the Save button.

Currently, you must enable secured callbacks to set a Broadcast Monitoring callback. If you disable secure callbacks, any broadcast callback you set will be disabled.

  1. Locate the Broacast Monitoring section and click the Configure button.

  2. Specify the callback URL and (optionally) a signature secret.

    For more information on secure callbacks, see this page.

When a broadcast's status changes, the server sends HTTP POST requests to the URL you supply. The Content-Type for the request is application/json. The data of the request is a JSON object of the following form:

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "event": "broadcast",
  "group": "status",
  "resolution": "640x480",
  "streamMode" : "auto",
  "streams" : [],
  "broadcastUrls": {
    "hls" : "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "live",
    "rtmp": {
      "foo": {
        "serverUrl": "rtmps://myfooserver:443/myfooapp",
        "streamName": "myfoostream",
        "status": "live"
      },
      "bar": {
        "serverUrl": "rtmp://mybarserver:443/mybarapp",
        "streamName": "mybarstream",
        "status": "live"
      }
    }
  },
  "settings": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    }
  },
  "status": "started"
}

The JSON object includes the following properties:

Known issues with the OpenTok live streaming broadcast feature

The live streaming broadcast feature has the following known issues: