Suggestions

close search

Broadcasting RTMP streams (beta)

The OpenTok live streaming broadcast feature now lets you broadcast both HLS and RTMP streams of OpenTok sessions.

Important: RTMP streaming is currently available as a beta feature. The beta API is subject to change. To participate in this beta program, contact rtmp-broadcast-beta@tokbox.com.

Changes to the OpenTok REST API to support RTMP streams

To broadcast an OpenTok session to an RTMP stream, use the existing OpenTok REST method to start a live streaming broadcast. However, the POST data you include in the API call includes a new outputs property, which is an object that defines the types of broadcast streams you want to start (both HLS and RTMP). You can include HLS, RTMP, or both as broadcast streams. If you include RTMP streaming, you can specify multiple target RTMP stream URLs (or just one). For each RTMP stream URL, you may (optionally) specify a unique name for the stream. If you specify an name, it will be included in the REST call response and the REST method for getting information about a live streaming broadcast). TokBox streams the session to each RTMP URL you specify.

Here's an example of the POST data that supports HLS streaming and two RTMP stream URLs:

{
  "sessionId": "<session-id>",
  "layout": {
    "type": "custom",
    "stylesheet": "the layout stylesheet (only used with type == custom)"
  },
  "outputs": {
    "hls": {},
    "rtmp": [{
      "name": "foo",
      "url": "rtmp://your-first-rtmp-url"
    },
    {
      "name": "bar",
      "url": "rtmp://your-second-rtmp-url"
    }]
  }
}

Important: The current OpenTok RTMP URL supports Facebook Live and You Tube Live (the Server URL followed by stream key or stream name):

rtmp://destinationHost:destinationPort/applicationName/streamKeyORStreamName

For example, we support a YouTube Live URL such as
rtmp://a.rtmp.youtube.com/live2/47qh-jt4j-5hh1-8dmd. And we support a FaceBook Live URL such as
rtmp://rtmp-api.facebook.com:80/rtmp/10158311198165238?ds=1&s_l=1&a=BTgwUBCnYgSZK664.

Other CDN providers and RTMP servers have different URL requirements that we do not support. We are investigating how we can support these.

The response to this request includes the RTMP URLs you provide in the broadcastURLs property (an array):

{
  "id": "1748b7070a81464c9759c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "broadcastUrls": {
    "hls" : "http://an-hls-url/playlist.m3u8",
    "rtmp": {
      "foo": "rtmp://your-first-rtmp-url",
      "bar": "rtmp://your-second-rtmp-url"
    }
  }
}

The OpenTok REST API method to get information about a live streaming broadcast now includes information about any RTMP streams you specified (in the response):

{
  "id": "1748b7070a81464c9759c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "broadcastUrls": {
    "hls" : "hlsurl",
    "rtmp": {
      "foo": "rtmp://your-first-rtmp-url",
      "bar": "rtmp://your-second-rtmp-url"
    }
  }
}

If you need to support only one RTMP URL, you can pass in an object (instead of an array of objects) for the rtmp property value in the POST data you supply when calling the REST method. For example, the following POST data specifies one RTMP output URL (and does not include HLS output):

{
  "sessionId": "<session-id>",
  "layout": {
    "type": "custom",
    "stylesheet": "the layout stylesheet (only used with type == custom)"
  },
  "outputs": {
    "rtmp": {
      "name": "foo",
      "url": "rtmp://your-rtmp-url"
    }
  }
}

Upcoming API changes

Important: The REST API will change with the upcoming non-beta release, as described in this section.

Instead of specifying name and url properties in the JSON you send in the REST POST request, you will specify id, serverUrl, and streamName properties for each RTMP stream, as in the following:

{
  "sessionId": "<session-id>",
  "layout": {
    "type": "custom",
    "stylesheet": "the layout stylesheet (only used with type == custom)"
  },
  "outputs": {
    "hls": {},
    "rtmp": [{
      "id": "foo",
      "serverUrl": "rtmp://myfooserver/myfooapp",
      "streamName": "myfoostream"
    },
    {
      "id": "bar",
      "serverUrl": "rtmp://mybarserver/mybarapp",
      "streamName": "mybarstream"
    }]
  }
}

The id property in the upcoming API will replace the current name property. The serverUrl and streamName properties will replace the current url property.

In addition to the new format, we will support the existing schema for POST requests for some period of time after the upcoming release.

Also, in the upcoming non-beta release, the JSON returned when calling the OpenTok REST API method to get information about a live streaming broadcast will change to have an array of RTMP objects, with each object named after the id and with serverUrl and streamName properties for each RTMP object:

{
  "id": "1748b7070a81464c9759c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "projectId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "broadcastUrls": {
    "hls" : "hlsurl",
    "rtmp": {
      "foo": {
        "serverUrl": "rtmp://myfooserver/myfooapp",
        "streamName": "myfoostream"
      },
      "bar": {
        "serverUrl": "rtmp://mybarserver/mybarapp",
        "streamName": "mybarstream"
      }
    }
  }
}