How to Stream With Livepeer.com's RTMP API

Angie Ramirez

5 min read

The RTMP API is the newest API feature from Livepeer.com It allows a user to ingest RTMP streams into the Livepeer.com service, and receive a transcoded HLS output stream that enables adaptive bitrate streaming. RTMP, the Real-Time Messaging Protocol, and HLS, HTTP live streaming, are two of many standards for transporting video, audio, and data over the internet. In this tutorial, we'll go through the steps of creating and viewing transcoded streams with the RTMP feature of Livepeer.com.

Step 1: Create a free account at Livepeer.com, and generate an API key.

On Livepeer.com, hit the Sign Up button at the top right of the homepage, enter your email and a password, wait for a verification email from Livepeer, click on the verify email button, and once signed into Livepeer.com, navigate to the API keys section of the site. Click the Create button to generate an API key, which should look something like this: d210eded-46a9-4119-86f9-64c33e003f1b. Be sure to record the API key once you generate it, as you won't be able to view it again after closing the window.

Step 2: Get a location-specific “base” URL

Depending on where you are in the world, you’ll need access to a different “ingest” and “playback” urls. This is important, because where your video enters the Livepeer ecosystem should be as close to where you are broadcasting from as possible to reduce latency. You’ll use this base URL to populate the “ingest base URL” and “playback base url” in step 4.

To get the base URL, curl https://livepeer.com/api/ingest. You should see results similar to this:

[{"ingest":"rtmp://mdw-rtmp.livepeer.com/live","playback":"https://mdw-cdn.livepeer.com/hls"}]

Step 3: Create a stream

It’s time to create a stream, which will give us a couple of important fields: a "streamKey", a "playbackId", and an "id" (or a "streamId"). We’ll use all of these in steps 4 and 6.

To create a stream, send an HTTP POST request to https://livepeer.com/api/stream. In that request, include an Authorization header of Bearer YOUR_API_KEY, a JSON body with a stream name of your choosing, and details about which video profiles or renditions you’d like to transcode your stream into.

For example:

curl -X POST \-H 'content-type: application/json'\-H 'authorization: Bearer {api_key}'\-d '{ "name": "test_stream", "profiles": [ { "name": "720p", "bitrate": 2000000, "fps": 30, "width": 1280, "height": 720 }, { "name": "480p", "bitrate": 1000000, "fps": 30, "width": 854, "height": 480 }, { "name": "360p", "bitrate": 500000, "fps": 30, "width": 640, "height": 360 } ]}'\https://livepeer.com/api/stream

The result from that HTTP POST request should look something like this:

{
  "name": "test_stream",
  "profiles": [
    {
      "name": "720p",
      "bitrate": 2000000,
      "fps": 30,
      "width": 1280,
      "height": 720
    },
    {
      "name": "480p",
      "bitrate": 1000000,
      "fps": 30,
      "width": 854,
      "height": 480
    },
    {
      "name": "360p",
      "bitrate": 500000,
      "fps": 30,
      "width": 640,
      "height": 360
    }
  ],
  "id": "0bf161f3-95bd-4971-a7b1-4dcb5d39e78a",
  "createdAt": 1596081229373,
  "streamKey": "rlmn-uimq-jtgy-x98v",
  "playbackId": "emh3b2mxupongp5k"
}

Step 4: Broadcast a stream

To broadcast a stream, you may use whatever capture device or software you’d like. We’ll use OBS for this example, video software that is available for free. Download here.

Once you’ve got OBS downloaded and open, go to "Settings", then select "Stream", and click on the "Service" dropdown to select "Custom".

To fill in the empty fields on that page, copy and past the “ingest” base URL from step 2 and copy into the “Server” or “Url” field. In this case, it’s rtmp://mdw-rtmp.livepeer.com/live. For "Stream key", use "streamKey" from the newly created stream object in step 3. From our example, it’s rlmn-uimq-jtgy-x98v. Click "OK" to save the configuration.

Now go to "Settings" -> "Output", and hit “Output Mode” to “Advanced”. In the “Keyframe Interval” further down the page, type in "2". This will ensure a more consistent playback experience. Click "OK" to save the configuration. If you are building a live streaming application, you should help your users set their keyframe interval to 2 seconds as well.

When you click "Start Streaming", the RTMP stream will be pushed into the ingest point.

Step 5: Verify stream status

To verify a stream is running, you can fetch the stream status using the "id" of the stream object by sending a GET request to https://livepeer.com/api/stream/.

For example:

curl -H 'authorization: Bearer {api_key}'\"https://livepeer.com/api/stream/{streamId}"

Your results will look like this:

{
  "name": "test_stream",
  "profiles": [
    {
      "bitrate": 2000000,
      "fps": 30,
      "height": 720,
      "name": "720p",
      "width": 1280
    },
    {
      "bitrate": 1000000,
      "fps": 30,
      "height": 480,
      "name": "480p",
      "width": 854
    },
    {
      "bitrate": 500000,
      "fps": 30,
      "height": 360,
      "name": "360p",
      "width": 640
    }
  ],
  "id": "2d10f1fd-dbf7-495b-8aef-08916507fcce",
  "createdAt": 1596118509635,
  "lastSeen": 1596119750455
}

The "lastSeen" field represents when the stream was last observed by the monitoring system. It should contain an epoch that's close to the current time. To easily convert an epoch to a human-readable date, use this online calculator or take a look at this forum that might be helpful.

Step 6: Playback a live stream

Once the broadcast session is started, transcoding will automatically happen. Users can view the live stream with any HLS video player by using the playback URL:

{playback_base_url}/{playbackId}/index.m3u8

From our example, the playback url should look like this: https://mdw-cdn.livepeer.com/hls/emh3b2mxupongp5k/index.m3u8

Livepeer.com supports and has tested with video.js, hls.js, safari/ios native player, and Theoplayer. On safari, you can simply enter the playback URL into the address bar, and see your transcoded video come to life!

If you’d like to examine the playlist in more detail by using the playback URL, which should give you the full HLS playlist that includes all 4 different renditions, you may curl the URL for more information.

For example:

curl "https://mdw-cdn.livepeer.com/hls/emh3b2mxupongp5k/index.m3u8"

You should see a response like this:

#EXTM3U#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=2145120,RESOLUTION=1920x1080,FRAME-RATE=30,CODECS="avc1.4d4028,mp4a.40.2"1_0/index.m3u8?sessId=23351#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=2018712,RESOLUTION=1280x720,FRAME-RATE=29.97,CODECS="avc1.4d401f,mp4a.40.2"2_0/index.m3u8?sessId=23351#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=1111792,RESOLUTION=854x480,FRAME-RATE=29.97,CODECS="avc1.4d401f,mp4a.40.2"3_0/index.m3u8?sessId=23351#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=638672,RESOLUTION=640x360,FRAME-RATE=29.97,CODECS="avc1.4d401e,mp4a.40.2"4_0/index.m3u8?sessId=23351

If you don't see a response like this, it's likely because the stream is not live. What we’re seeing here is rendition manifests, with file type information, the EXTM3U header, and information on individual renditions being returned, the EXT-X-STREAM-INF header.

For more information on streaming with the livepeer API, please visit our documentation page here.