Skip to main content

Livestreaming

This guide will present basic steps to build your live streaming application on the Streamdiver API. It involves:

  • Create a live stream
  • Start the live broadcast
  • Playback of the live stream
  • Finish the live broadcast

Glossary​

Common terms and appreviations used in live video streaming:

VOD: video-on-demand

RTMP: Real-Time Messaging Protocol. A protocoll developed by

HLS: HTTP Live Streaming is an adaptive bitrate streaming protocol developed by Apple Inc. to facilitate live and on-deman video playback in a web browser.

Ingest: A video stream input to be published as a live stream, e.g. as HLS.

Creating a live stream​

The Livestream in the Streamdiver API is a record for the future live video stream, that will be pushed to our streaming server infrastructure. See Authentication for the basic API access topics.

Use the Create API request to add a new Livestream. Provide a name and associate it with an existing Channel via channelIds like:

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
}'

Keep the source with "rtmp" to enable the video inputs using the Real-Time Messaging Protocol (RTMP) (for details see recommended encoder settings).

This will just register the new live stream. There is no live playout yet. It is possible to use it as placeholder until the real live event is broadcasted. The id of the newly created live stream is relevant for the following actions.

Starting the live broadcast​

Use the Start request to actually start up the Livestream and get ready for broadcasting.

The response contains an RTMP URL like "rtmp://at-cdn01.streamdiver.com/live-tenantname/96cntmao-spgc7dql listed in inputs.

{
    "source": "rtmp",
    "url": "rtmp://at-cdn01.streamdiver.com/live-tenantname/96cntmao-spgc7dql",
    "primary": true
}

Continue to set up the video ingest via RTMP using this URL.

Configure RTMP encoder​

Pushing a live video stream to the Streamdiver platform requires a video encoder to perpare the video signal for the delivery over the Internet. In this case the video is transported via RTMP protocol, which is supported by a wide range of broadcasting solutions. So various software applications, mobile apps or hardware appliances can be used to ingest a video stream via RTMP.

After starting the Livestream before, the RTMP URL is available now. This URL already contains all information needed to configure the RTMP ingest. It is structured like:

rtmp://{host_name}/{application_name}/{stream_key}

The server URL part rtmp://{host_name}/{application_name} identifies the targeted RTMP server on the Streamdiver platform. The stream_key is used to authenticate your live video input on our server infrastructure.

info

Keep the RTMP URL with the stream key secret!

Enter the RTMP URL with the stream key on your RTMP encoder. Check the basic guideline for details regarding encoder settings and consult the encoder's manual. Many encoder also provide programming interfaces to automate the process to set up an RTMP stream. Regarding credentials, some encoder have split inputs for the server URL and the stream key, so the use the URL parts accordingly.

If the encoder setup is ready, you can start broadcast. The RTMP encoder will push the video signal from e.g. a local camera via RTMP to the streaming server.

Check the HLS playout​

Use the Retrieve API request to check the status of the live stream. You will notice, that since the live stream start the playouts are available. It holds the video source URL, which is an HLS playlist URL with the extension *.m3u8.

{
    "mimeType": "application/x-mpegURL",
    "source": "https://at-cdn01.streamdiver.com/live-tenantname/_definst_/amlst:2024/04/d2f3f6a0-a186-4156-b784-248de16e9e2a/playlist.m3u8",
    "type": "videostream",
    "primary": true
}

Use an HLS-capable video player to check the playback. For a quick test on desktop e.g. the free and open-source the VideoLAN VLC media player can handle HLS playback. In web- or mobile applications, any HLS-capable player library should work.

Publish the live broadcast​

After starting and validating the RTMP ingest the Livestream can be published. Use the Publish API request to share our live stream in the given Channel with the audience.

Finish the live broadcast​

Use the Stop API request to finish the the Livestream.

Live recording​

Depending on the withDvr flag in the inital Create API request the live stream is recorded.

A recorded live stream will be converted to a MediaAsset after finishing it. It is converted in the background and then published as asset in the given channel.

Without recording all video data on our server infrastructure is removed after Livestream has been finished. A local backup using the RTMP encoder recording functionality is recommended in any case.

Recommendations​

Following settings are a guideline to set up the RTMP encoder. In any case it is recommended to validate the encoder compatiblity, performance and setup in advance. Due to the wide range of solutions with RTMP support on the market, we don't endorse a particular product or manufacturer.

Common​

  • Protocol: RTMP
  • Video codec: H.264 (Main profile)
  • Audio codec: AAC (LC, low complexity)
  • Keyframe interval: 2 seconds
  • Framerate: 25 fps
  • Rate control mode: CBR, constant bitrate

Streaming in Full HD (1080p):​

  • Resolution: 1920x1080
  • Bitrate: 4500 kbps

Streaming in Full HD (720p):​

  • Resolution: 1280x720
  • Bitrate: 3000 kbps

Software encoders​

Many software encoder products support the RTMP protocol and should work with the Streamdiver platform. Some examples:

  • Open Broadcaster Software - OBS (free, available as open-source)
  • FFmpeg (cli application, free, available as open-source)
  • vMix (by StudioCoast Pty Ltd., commercial)

Hardware encoders​

Many hardware encoder appliances include support for the RTMP protocol and should work with the Streamdiver platform. Some examples:

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

Network & bandwidth​

The RTMP video stream will require a stable internet connection to assure a smooth playout for the audience. The desired video bitrate of the RTMP stream should not use more than 50% of your available upload bandwidth.

Certain firewall policies might block relevant ports. Validate, that the RTMP encoder can use TCP port number 1935 to connect to our streaming infrastructure.