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 suitable for playback over Apple HLS-compatible clients.

Note: Wowza Streaming Engine 4.0.0 or later is required.

Configure Apple HLS packetization in Wowza Streaming Engine Manager


Configure for live streams

  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 (such as live).
     
  3. On the live 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. To enable a property, select the Enabled check box for the property. You can also change the value for an enabled property from its default setting. All time values are in milliseconds and the values are set on a per-application basis. Refer to the Cupertino segmenter property reference below for more information about the individual properties you can use to manage the Cupertino segmenter for live streams.


     
  5. Click Save, and then restart the application when prompted to apply the changes. 
Note: For more information about how to configure properties, see Configure properties.

Cupertino segmenter property reference

  • cupertinoChunkDurationTarget - Sets the duration of each chunk in milliseconds. If you're using Origin/Edge configuration this will need to be set on the origin and edge servers with matching values.
     
  • 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. A live edge application will have a StreamType of liverepeater-edge in the Application.xml file.

Property details

Audio and video packets from a live encoder enter Wowza Streaming Engine and are segmented 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 an iOS device requests the stream, a playlist is returned that contains the [n] most recently added chunks. The number of items returned in the playlist ([n]) is controlled by the cupertinoPlaylistChunkCount setting.

A live stream repeater is a system that's used to deliver a single live stream in an origin/edge configuration 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 an iOS device. The cupertinoRepeaterChunkCount setting controls the number of chunks that are immediately sent from the origin to the edge after initial connection. It's best if this setting is 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.
 
Notes:
  • Chunks must start on a keyframe, so use a keyframe interval that's a factor of the cupertinoChunkDurationTarget setting. For example, if cupertinoChunkDurationTarget is set to 10 seconds, use a keyframe interval of either 2, 2.5, 5, or 10 seconds.
     
  • To estimate how much memory is used to store the chunks for a single live stream, use the following 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 the following amount of memory, given the default settings above:
     
    (500/(1024*8)) * 10 * 10 = 6 MB of memory

Additional properties for live streams

cupertinoCalculateChunkIDBasedOnTimecode – Turns on chunk ID numbering based on incoming packet time. When enabled, the chunkID is equal to the quotient of the timecode divided by the cupertinoChunkDurationTarget value. To enable this, do the following:

  1. On the live application page Properties tab, click Custom in the Quick Links bar.
     
  2. In the Custom section, click Edit.
     
  3. Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:
     
    • Path - Select /Root/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 Save, and then restart the application when prompted to apply the changes.

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

  1. On the live application page Properties tab, click Custom in the Quick Links bar.
     
  2. In the Custom section, click Edit.
     
  3. Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:
     
    • 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 Save, and then restart the application when prompted to apply the changes.

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 cupertinoForceEndChunkWhenNoKeyframe 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 live application page Properties tab, click Custom in the Quick Links bar.
     
  2. In the Custom section, click Edit.
     
  3. Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:
     
    • 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 Save, and then restart the application when prompted to apply the changes.

Configure 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 (such as vod).
     
  3. On the VOD 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, specify the following custom property settings in the Add Custom Property dialog box, and then click Add.
     
    1. In Path, select /Root/Application/HTTPStreamer.
       
    2. In Name, enter cupertinoChunkDurationTarget.
       
    3. In Type, select Integer.
       
    4. In Value, enter a value (in milliseconds) to specify the default VOD chunk size.
  6. Click Save, and then restart the application when prompted to apply the custom property.

Configure Apple HLS packetization in XML


If you configured the properties in Wowza Streaming Engine Manager, you can skip this section. If you make changes to [install-dir]/conf/[application]/Application.xml, any supported settings are displayed in Wowza Streaming Engine Manager the next time it's started. You must edit Application.xml in a text editor if you're running Wowza Media Server software.

Configure for live streams

  1. Use a text editor to open the Application.xml file for your live application. Then add the properties described in the Cupertino segmenter property reference above to the <LiveStreamPacketizer>/<Properties> container. Be sure to add the properties to the correct <Properties> container in Application.xml as there are several in the file.
    <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>
    	<Value>-1</Value>
    	<Type>Integer</Type>
    </Property>
    <Property>
    	<Name>cupertinoCalculateChunkIDBasedOnTimecode</Name>
    	<Value>false</Value>
    	<Type>Boolean</Type>
    </Property>
  2. Restart Wowza Streaming Engine to apply the changes.

Configure for VOD streams

  1. Open the Application.xml file for your VOD application using a text editor and then add the cupertinoChunkDurationTarget property to the <HTTPStreamer>/<Properties> container. Be sure the to add the properties to the correct <Properties> container in Application.xml as there are several in the file.
    <Property>
    	<Name>cupertinoChunkDurationTarget</Name>
    	<Value>10000</Value>
    	<Type>Integer</Type>
    </Property>
  2. Restart Wowza Streaming Engine to apply the changes.

More resources