Configure Apple HLS packetization in Wowza Streaming Engine

This article describes how to configure properties in Wowza Streaming Engine™ media server software to control how the Apple HLS packetizer, cupertinostreaming, splits streams into segments for playback over Apple HLS clients.

Note: Wowza Streaming Engine 4.0.0 or later is required.

Configure Apple HLS packetization in Wowza Streaming Engine Manager

Configure HLS (Cupertino) packetization for live streams

HLS packetization properties are defined for individual streaming applications.

1. In Wowza Streaming Engine Manager, click the Applications tab at the top of the page.
    
2. In the Applications contents panel, click the name of your live application.
    
3. On the application page Properties tab, click Cupertino Streaming Packetizer in the Quick Links bar.
    
   
   

   Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
   
    
4. Click Edit in the Cupertino Streaming Packetizer properties area.
5. To enable a property, select the Enabled check box for it and, optionally, change the default value. See the HLS (Cupertino) live stream segmenter property reference, below, for information about the properties.
   
   
    
6. Click Save, and then restart the application. 

Note: For more information about how to configure properties, see Configure properties.

HLS (Cupertino) live stream segmenter property reference

• cupertinoChunkDurationTarget - Sets the duration of each chunk, in milliseconds. On an origin/edge configuration, the origin and edge servers must use the same value.
   
• cupertinoMaxChunkCount - Sets the maximum number of chunks stored in the available chunk list.
   
• cupertinoPlaylistChunkCount - Sets the number of items returned in the playlist.
   
• cupertinoRepeaterChunkCount - Sets the number of chunks that are immediately sent from the origin to the edge after initial connection and is configured on the origin. This property is only required for use with live edge applications, which have the stream type liverepeater-edge in the Application.xml file.

These four properties work together.

Wowza Streaming Engine ingests audio and video packets from a live encoder and segments them into time-based chunks. The duration of each chunk (in milliseconds) is controlled by the cupertinoChunkDurationTarget setting. As the chunks are created, they're added to the available chunk list. The maximum number of chunks stored in the available chunk list is controlled by the cupertinoMaxChunkCount setting. When a player or device requests the HLS stream, Wowza Streaming Engine sends a playlist that contains the n most recently added chunks. The number of items returned in the playlist (n) is controlled by the cupertinoPlaylistChunkCount setting.

In a repeater configuration—when Wowza Streaming Engine delivers a single live stream from an origin server to multiple edge servers—the first time an edge server requests the stream, it pulls the previously segmented chunks from the origin to the edge for delivery to the requesting player. The cupertinoRepeaterChunkCount setting controls the number of chunks that are immediately sent from the origin to the edge after initial connection. The cupertinoRepeaterChunkCount value should be equal to or greater than cupertinoPlaylistChunkCount but less then cupertinoMaxChunkCount. With Wowza Streaming Engine 4.5.0.02 and later, if you set the cupertinoRepeaterChunkCount to a value that is equal to or less than 0, the cupertinoPlaylistChunkCount value is used.

Note: Chunks must start on a keyframe, so use a keyframe interval that's a factor of the cupertinoChunkDurationTarget setting. For example, if cupertinoChunkDurationTarget is 10 seconds, use a keyframe interval of either 2, 2.5, 5, or 10 seconds. To calculate how much memory is needed to store the chunks for a single live stream, use the formula:

[total-memory-mb] = ([stream-bitrate-kbps]/([1024-kb-per-mb]*[8-bits-per-byte])) * [cupertinoChunkDurationTarget-seconds] * [cupertinoMaxChunkCount]

For example, a 500 kbps stream consumes 6 MB of memory, given the default settings above:

(500/(1024*8)) * 10 * 10 = 6 MB

Enable custom HLS (Cupertino) properties for live streams

cupertinoCalculateChunkIDBasedOnTimecode – Turns on chunk ID numbering based on incoming packet time. When enabled, the chunk ID equals the quotient of the timecode divided by the cupertinoChunkDurationTarget value.

Note: Only use cupertinoCalculateChunkIDBasedOnTimecode with encoders that send synchronized timecodes to Wowza Streaming Engine. Synchronized timecodes synchronize to UTC or some other time base so that they advance at a constant rate. If cupertinoCalculateChunkIDBasedOnTimecode is used with an encoder that doesn't send synchronized timecodes, when the stream restarts, the chunk IDs will restart at 0 or, in some cases, at a random value. This is particularly problematic with HTTP origin live streams that are ingested from primary and backup servers. In these cases, the proxy may return old chunks to players.

1. On the application page Properties tab, click Custom in the Quick Links bar.
    
2. In the Custom section, click Edit.
    
3. Click Add Custom Property and specify the following:
    
   • Path - Select /Root/Application/LiveStreamPacketizers.
      
   • Name - Enter cupertinoCalculateChunkIDBasedOnTimecode.
      
   • Type - Select Boolean.
      
   • Value - To start Apple HLS chunk IDs at 0, enter false. To calculate Apple HLS chunk IDs based on the incoming live stream timecodes, enter true. Use this mode to synchronize chunk IDs between two servers that packetize the same live stream.
4. Click Add, click Save, and then restart the application.

cupertinoForceEndChunkWhenNoKeyframes – (Wowza Streaming Engine version 4.7.5 and later) Ends chunks when keyframes aren't received.

1. On the application page Properties tab, click Custom in the Quick Links bar.
    
2. In the Custom section, click Edit.
    
3. Click Add Custom Property and specify the following settings:
    
   • Path - Select /Root/LiveStreamPacketizers.
      
   • Name - Enter cupertinoForceEndChunkWhenNoKeyframes.
      
   • Type - Select Boolean.
      
   • Value - Set to true to end chunks when no keyframes are received, and then use the cupertinoChunkDurationOverflowThreshold property to configure the threshold at which chunks are ended. The default value is false. 
4. Click Add, click Save, and then restart the application.

cupertinoChunkDurationOverflowThreshold – Helps the packetizer recover if the video drops out or keyframes aren't present. If the threshold is exceeded, the live stream packetizer restarts.

Notes:

• With Wowza Streaming Engine 4.7.5 or later, to use the cupertinoChunkDurationOverflowThreshold property, you must set cupertinoForceEndChunkWhenNoKeyframes to true.
• You only need to add this property if you want to modify the default chunk duration overflow threshold, which is five times the cupertinoChunkDurationTarget value.

1. On the application page Properties tab, click Custom in the Quick Links bar.
    
2. In the Custom section, click Edit.
    
3. Click Add Custom Property and specify the following:
    
   • Path - Select /Root/LiveStreamPacketizers.
      
   • Name - Enter cupertinoChunkDurationOverflowThreshold.
      
   • Type - Select Integer.
      
   • Value - Enter a value, in milliseconds. The default value is five times the cupertinoChunkDurationTarget value.
4. Click Add, click Save, and then restart the application.

Configure HLS (Cupertino) properties for VOD streams

You can control the video-on-demand (VOD) chunk size by adding the cupertinoChunkDurationTarget property to your VOD application configuration.

1. In Wowza Streaming Engine Manager, click the Applications tab at the top of the page.
    
2. In the Applications contents panel, click the name of your VOD application.
    
3. On the application page Properties tab, click Custom in the Quick Links bar.
    
   
   

   Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
4. In the Custom area, click Edit.
    
5. Click Add Custom Property and specify the following:
    
   • Path - Select /Root/Application/HTTPStreamer.
   • Name - Enter cupertinoChunkDurationTarget.
   • Type - Select Integer.
   • Value - Enter a value (in milliseconds) to specify the default VOD chunk size.
6. Click Add, click Save, and then restart the application.

Configure Apple HLS packetization in XML

If you configured the properties in Wowza Streaming Engine Manager, skip this section. If you make changes to Application.xml, any supported settings are displayed in Wowza Streaming Engine Manager the next time it's started.

Configure HLS (Cupertino) packetization for live streams

1. Open the Application.xml file for your live application in a text editor.
2. Add any of the supported properties for HLS (Cupertino) live streams to the <LiveStreamPacketizer> properties container element. For details on them, see HLS (Cupertino) live stream segmenter property reference and Enable custom HLS (Cupertino) properties for live streams, above. The XML looks like this:

   <LiveStreamPacketizer>
       <Properties>
           <Property>
               <Name>cupertinoChunkDurationTarget</Name>
               <Value>10000</Value>
               <Type>Integer</Type>
           </Property>
           <Property>
               <Name>cupertinoMaxChunkCount</Name>
               <Value>10</Value>
               <Type>Integer</Type>
           </Property>
           <Property>
             <Name>cupertinoPlaylistChunkCount</Name>
             <Value>3</Value>
             <Type>Integer</Type>
           </Property>
           <Property>
               <Name>cupertinoRepeaterChunkCount</Name>
               <Type>Integer</Type>
               <Value>-1</Value>
           </Property>
           <Property>
               <Name>cupertinoCalculateChunkIDBasedOnTimecode</Name>
               <Value>false</Value>
               <Type>Boolean</Type>
           </Property>
       </Properties>
   </LiveStreamPacketizer>

3. Save and restart Wowza Streaming Engine.

Configure HLS (Cupertino) packetization for VOD streams

1. Open the Application.xml file for your VOD application in a text editor.
2. Add the cupertinoChunkDurationTarget property to the <HTTPStreamer> properties element. The XML looks like this:

   <HTTPStreamer>
       <Properties>
           <Property>
               <Name>cupertinoChunkDurationTarget</Name>
               <Value>10000</Value>
               <Type>Integer</Type>
           </Property>
       </Properties>
   </HTTPStreamer>

3. Save and restart Wowza Streaming Engine.

More resources

• Debug AAC or MP3 timecode issues with Apple HLS packetization in Wowza Streaming Engine
• Turn off data event processing for HLS streams in Wowza Streaming Engine
• Configure Wowza Streaming Engine to packetize HLS audio using TS chunks
• Improve playback of lower-latency Apple HLS streams from Wowza Streaming Engine