Skip to main content

Live Streaming

This guide outlines the basic steps to build a live streaming application using the Streamdiver API. It includes:

  • Creating a live stream
  • Starting the live broadcast
  • Playing back the live stream
  • Ending the live broadcast

Glossary​

Common terms and abbreviations used in live video streaming:

  • VOD: Video-on-Demand
  • RTMP: Real-Time Messaging Protocol, a protocol developed by Adobe, Inc. for streaming audio, video, and data over the Internet.
  • HLS: HTTP Live Streaming, an adaptive bitrate streaming protocol developed by Apple Inc. to facilitate live and on-demand video playback in a web browser.
  • Ingest: The input of a video stream to be published as a live stream, e.g., in HLS format.

Creating a Live Stream​

A Livestream in the Streamdiver API serves as a placeholder for a future live video stream that will be pushed to the streaming server infrastructure. Refer to the Authentication guide for basic API access information.

To create a new Livestream, use the Create API request. Provide a name and associate it with an existing Channel via channelIds, as shown below:

curl --request POST '{{baseUrl}}/livestreams' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJh...20yA' \
  --data '{
    "name": "Live1",
    "channelIds": [
        "e4742100-8750-4ee8-b788-f7366d07a737"
    ],
    "source": "rtmp",
    "withDvr": true
  }'

Set the source to "rtmp" to enable video inputs via the Real-Time Messaging Protocol (RTMP).

Creating the Livestream merely registers it on the server—no live playout occurs yet. You can use it as a placeholder until the actual live event is broadcasted. The id of the created live stream, as provided by the response, will be required for subsequent requests:

{
  "status": "success",
  "data": {
    "id": "01234567-89ab-cdef-0123-456789101112",
    ...
  }
}

Starting the Live Broadcast​

Use the Start API request to activate the Livestream ingest and prepare it for broadcasting. The response contains an RTMP url, listed under inputs:

{
  "status": "success",
  "data": {
    ...,
    "inputs": [{
      "source": "rtmp",
      "url": "rtmp://at-cdn01.streamdiver.com/live-tenantname/96cntmao-spgc7dql",
      "primary": true
    }],
    ...
  }
}

This URL will be used to configure the RTMP encoder for video ingest.

Configure the RTMP Encoder​

To push a live video stream to the Streamdiver platform, you need a video encoder to prepare the video signal for delivery over the Internet. The RTMP protocol, supported by various software applications, mobile apps, and hardware appliances, is used to transport the video.

The RTMP URL, returned by the Start request above, is structured as follows:

rtmp://{host_name}/{application_name}/{stream_key}
  • Server URL: rtmp://{host_name}/{application_name} identifies the RTMP server on the Streamdiver platform.
  • Stream Key: Used to authenticate your live video input on our server.
info

Keep the RTMP URL and stream key confidential.

Enter the RTMP URL and stream key into your RTMP encoder. Refer to the encoder's manual for details and check the recommended encoder settings. Some encoders also provide programming interfaces to automate the process of setting up an RTMP stream.

Once the encoder is configured, start broadcasting. The RTMP encoder will push the video signal (e.g., from a camera) to the streaming server.

Check the HLS Playout​

To verify the broadcast, use the Retrieve API request. The response will include an HLS playlist URL (.m3u8 extension) under playouts:

{
  "status": "success",
  "data": {
    ...,
    playouts: [{
      "mimeType": "application/x-mpegURL",
      "source": "https://at-cdn01.streamdiver.com/live-tenantname/.../playlist.m3u8",
      "type": "videostream",
      "primary": true
    }],
    ...
  }
}

Use an HLS-compatible video player to test playback, e.g., the free and open-source VLC Media Player on desktop or mobile, or Video.js for the web.

Publish the Live Broadcast​

After verifying the RTMP ingest and HLS playback, you can publish the Livestream using the Publish API request. This makes the live stream available to your audience via the associated Channel.

Finishing the Live Broadcast​

To end the live broadcast, use the Stop API request. This deactivates the ingest, invalidates the stream key, and removes the live stream from the associated channels.

Live Recording​

If the withDvr flag was set during the Create request, the live stream will be recorded. Upon finishing, the stream will be converted and published as a MediaAsset in the associated channels.

If recording was not enabled, all video data will be removed from the server upon completion. It is advisable to use the RTMP encoder’s recording functionality as a local backup.

Recommendations​

Use the following settings to configure your RTMP encoder:

General​

  • Protocol: RTMP
  • Video Codec: H.264 (Main Profile)
  • Audio Codec: AAC LC (Low Complexity)
  • Keyframe Interval: 2 seconds
  • Frame Rate: 25 fps
  • Rate Control Mode: CBR (Constant Bitrate)

Full HD (1080p)​

  • Resolution: 1920x1080
  • Bitrate: 4500 kbps

HD (720p)​

  • Resolution: 1280x720
  • Bitrate: 3000 kbps

Encoder Options​

Many software and hardware encoder products support the RTMP protocol and work with the Streamdiver platform, including the following examples:

Software Encoders​

  • Open Broadcaster Software - OBS (free, open-source)
  • FFmpeg command line tool (free, open-source)
  • vMix by StudioCoast Pty Ltd. (commercial)

Hardware Encoders​

  • AJA Helo by AJA Video Systems Inc. (commercial)
  • Epiphan Pearl-2 by Epiphan Systems Inc. (commercial)

Network and Bandwidth​

Ensure a stable internet connection. The video bitrate of the RTMP stream should not exceed 50% of your available upload bandwidth. Additionally, ensure that your firewall allows connecting to TCP port 1935, which is required for RTMP.