logo

Deliver Low-Latency HLS live streams using Wowza Streaming Engine and THEOplayer

Wowza Streaming Engine™ media server software version 4.7.8 and later together with THEOplayer version 3.65 and later can deliver Low-Latency HLS (LL-HLS) live streams.

Low-Latency HLS streams conform to Apple’s preliminary protocol extension to the HLS spec.

Table of Contents

SDKs

Web SDK Android SDK iOS SDK tvOS SDK Android TV SDK Chromecast SDK
Yes In Beta In Beta In Beta In Beta N/A

How to set up THEOplayer with Wowza Streaming Engine For LL-HLS

Prerequisites

There are three prerequisites in order to continue with this guide:

  1. In order to generate LL-HLS streams, you must first get a SSL certificate to secure your port and configure the port for HTTPS playback. LL-HLS playback does not work without an SSL secured port. For information on how to do this, refer to How to Get an SSL Certificate from Wowza's Streamlock Service.
  2. This guide expects that you have a THEOplayer license. If you are not using THEOplayer yet, you can start your free trial here. In addition, you will need a specify the LL-HLS feature flag when generating your SDK. Be sure to have THEOplayer version 2.65 or higher.
  3. This guide expects that you are a Wowza Streaming Engine client and that you are integrated with their streaming infrastructure. Information on Wowza Streaming Engine can be found here. Be sure to have Wowza Streaming Engine media server software version 4.7.8 or higher.

Configure a Wowza live application to deliver LL-HLS streams

Please Note: Wowza occasionally updates their documentation, which is available here.

Wowza Streaming Engine generates Low-Latency HLS streams using the CMAF packetizer, cmafstreamingpacketizer. The packetizer creates the partial segments needed for LL-HLS. The LL-HLS streams use the fMP4 container format.

To deliver LL-HLS streams from Wowza Streaming Engine you have to manually enable low latency CMAF packetization for live streaming, in the application, by editing the application's configuration in XML.

Configure the live application's setup in XML

  1. Navigate to [install-dir]/conf/live or [install-dir]/conf/[custom live application] and open the Application.xml file in a text editor.
  2. In the <Streams> container element, make sure the StreamType property is live. The XML looks like this:
<Streams>
    ...
    <StreamType>live</StreamType>
    ...
</Streams>
  1. Add cmafstreamingpacketizer to the LiveStreamPacketizers property. You can add it to the prepopulated comma-separated list, or it can be the only packetizer specified. The XML looks like this:
<Streams>
    ...
    <LiveStreamPacketizers>cmafstreamingpacketizer</LiveStreamPacketizers>
    ...
</Streams>
  1. Add the cmafLLEnableLowLatency property to the LiveStreamPacketizer element and set it to true.
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>cmafLLEnableLowLatency</Name>
            <Value>true</Value>
            <Type>Boolean</Type>
        </Property>
    </Properties>
</LiveStreamPacketizer>
  1. For the HTTPStreamers property, make sure HLS (cupertinostreaming) is specified. The XML looks like this:
<HTTPStreamers>cupertinostreaming</HTTPStreamers>
  1. Save your changes.

Your live application is now configured to deliver LL-HLS streams.

If desired, you can edit optional CMAF packetization properties. For information, see Configure CMAF live streaming packetization in Wowza Streaming Engine. You can also edit optional packetization properties to customize the low latency chunks generated by the cmafstreamingpacketizer, or you can edit an optional property to customize the media playlist.

Configure optional low latency partial segment properties and media playlist property

Low latency CMAF property reference

You can configure any of these optional LiveStreamPacketizer properties for the low latency chunks. These chunks, generated by the cmafstreamingpacketizer, are used as partial segments in the LL-HLS streams.

Name Type Description
cmafLLChunkingScheme String A value that specifies the chunking scheme for low latency CMAF-packetized streams. Valid values are byFrame or byDuration. The default is byFrame. If the value is byFrame, packetization is configured using the cmafLLChunkFrameCountTargetAudio and cmafLLChunkFrameCountTargetVideo properties. If the value is byDuration, packetization is configured using the cmafLLChunkDurationTargetAudio and cmafLLChunkDurationTargetVideo properties.
cmafLLChunkFrameCountTargetAudio Integer Specifies the number of audio frames to include in each low latency CMAF audio chunk. The default is 1, but the value should be updated in production environments to reflect the expected audio sample rate of the source media and your desired CMAF audio chunk duration. This property is only enabled if cmafLLChunkingScheme is byFrame.
cmafLLChunkFrameCountTargetVideo Integer Specifies the number of video frames to include in each low latency CMAF video chunk. The default is 1, but the value should be updated in production environments to reflect the expected video frame rate of the source media and your desired CMAF video chunk duration. This property is only enabled if cmafLLChunkingScheme is byFrame.
cmafLLChunkDurationTargetAudio Integer Specifies, in milliseconds, the duration of each low latency CMAF audio chunk. The default is 43, but we recommend using a value between 300 - 500 in production workflows. The duration cannot exceed the cmafSegmentDurationTarget value. This property is only available if cmafLLChunkingScheme is byDuration.
cmafLLChunkDurationTargetVideo Integer Specifies, in milliseconds, the duration of each low latency CMAF video chunk. The default is 43, but we recommend using a value between 300 - 500 in production workflows. The duration cannot exceed the cmafSegmentDurationTarget value. This property is only available if cmafLLChunkingScheme is byDuration.
cmafSegmentDurationTarget Integer Specifies, in milliseconds, the duration of the fMP4 segments in the stream. The value must be greater than 0. The default is 10000 (10 seconds), but we recommend a value around 3000 for Low-Latency HLS streaming. This property is only available if cmafLLChunkingScheme is byDuration.

You can configure the following optional HTTPStreamer property to address how the media playlist is constructed for an LL-HLS stream.

Name Type Description
cupertinoPartHoldBack Double (Available from version 4.8.0) Specifies, in seconds, the server-recommended minimum distance from the live edge at which clients should begin to play or seek in a LL-HLS stream. If the cmafLLChunkingScheme is byDuration, the cupertinoPartHoldBack value must be greater than or equal to the value for cmafLLChunkDurationTargetAudio or cmafLLChunkDurationTargetVideo. If the cmafLLChunkingScheme is byFrame, the cupertinoPartHoldBack value must be greater than or equal to the calculated partial segment (chunk) duration. The default and recommended value is three times the partial segment (chunk) duration target.
Configure properties

Configure the optional low latency CMAF chunk properties and media playlist property by editing the Application.xml file for your LL-HLS live stream application.

  1. Navigate to the Application.xml file for your LL-HLS live stream. If you're using the default live application that installs with Wowza Streaming Engine, navigate to [install-dir]/conf/live.
  2. Open Application.xml in a text editor.
  3. In the <LiveStreamPacketizer> container element, add the desired property or properties, making sure to specify a name, value, and type for each one. The XML looks like this:
<LiveStreamPacketizer>
    <Properties>
        <Property>
            <Name>...</Name>
            <Value>...</Value>
            <Type>...</Type>
        </Property>
        <Property>
            <Name>...</Name>
            <Value>...</Value>
            <Type>...</Type>
        </Property>
    </Properties>
</LiveStreamPacketizer>
  1. In the <HTTPStreamer> container element, optionally add cupertinoPartHoldBack, making sure to specify a name, value, and type. The XML looks like this:
<HTTPStreamer>
    <Properties>
        <Property>
            <Name>...</Name>
            <Value>...</Value>
            <Type>...</Type>
        </Property>
    </Properties>
</HTTPStreamer>
  1. Save your changes and restart Wowza Streaming Engine.

After your live application is configured to deliver an LL-HLS stream, complete the stream setup by connecting a source encoder or IP camera to Wowza Streaming Engine and publishing the live source stream to the server. Although you enabled CMAF packetization in the Application.xml configuration file, your live application is available in Wowza Streaming Engine Manager, where you can establish a connection to a live source.

  • In Wowza Streaming Engine Manager, click Applications in the menu bar and select your live application in the contents panel.
  • Click Sources (Live) in the contents panel.
  • Select the encoder or camera you want to use as your source. Click Learn more under any tile for detailed instructions on how to connect that encoder or camera, including how to configure source authentication.

If your encoder or camera isn't listed, click Other Encoders or use the Application Connection Settings in the Help panel to publish the stream to Wowza Streaming Engine. For more information about how to enter the connection settings in your source encoder or camera, consult that device or software's documentation. These articles may also help:

Connect a live source to Wowza Streaming Engine Connect the Wowza GoCoder encoding app to Wowza Streaming Engine

When the camera or encoder is connected and the live stream is active, preview LL-HLS playback using THEOplayer.

Test stream playback

To test LL-HLS live streams when only cmafstreamingpacketizer is enabled, specify the stream playback URL using the format:

https://[wowza-address]/[application]/[application-instance]/[stream-name]/playlist.m3u8

If cmafstreamingpacketizer and cupertinostreamingpacketizer are enabled, use the format:

https://[wowza-address]/[application]/[application-instance]/[stream-name]/playlist_sfm4s.m3u8

Where:

[wowza-address] is the IP address or domain and port of Wowza Streaming Engine (default port 443) [application] is the application name [application-instance] is the name of the application instance (if omitted, defaults to definst) [stream-name] is the stream name

So, for example, if only cmafstreamingpacketizer is enabled, the playlist URL for a LL-HLS stream that uses the address mycompany.com, the default live application, and the default stream name myStream is: https://mycompany.com/live/myStream/playlist.m3u8

If cmafstreamingpacketizer and cupertinostreamingpacketizer are both enabled, the LL-HLS playlist URL for the same example is: https://mycompany.com/live/myStream/playlist_sfm4s.m3u8

and the playback URL for the Cupertino HLS stream is either:

https://mycompany.com/live/myStream/playlist.m3u8 or

https://mycompany.com/live/myStream/playlist_sfts.m3u8 where _sfts indicates that the media playlist contains .ts segments.

Configure THEOplayer to play your LL-HLS stream

Web SDK
  1. Setup a basic HTML file and include the THEOplayer library. You can check: How to get started with THEOplayer Web SDK and How to configure THEOplayer for LL-HLS
  2. Specify the LL-HLS stream generated above, as the src parameter in your source configuration
  3. Set the flag lowLatency parameter to TRUE, in your source configuration
<script>
  // LL-HLS
  player.source = {
    sources: [
      {
        src:
          "https://5d6e17f1ca731.streamlock.net/LowLatencyBBB/myStream/playlist.m3u8", // set the LL-HLS source
        type: "application/x-mpegurl", // set the type to HLS
        lowLatency: true,
      },
    ],
  };
</script>

Conclusion

THEOplayer is partnered with Wowza Streaming Engine to fully implement low-latency HLS (LL-HLS) streaming playback.

Resources

github
Make sure to follow us on GitHub!
THEO-logo-white
twitter
facebook
linkedin
Copyright © 2020. All Rights Reserved.
Leuven
New York
San Francisco
Singapore
Barcelona