Create custom chunklists with the Wowza Streaming Cloud REST API

Learn how to control the size of an adaptive-bitrate HLS stream's chunklists by using the Wowza Streaming Cloud™ service REST API.

Contents


About HLS chunks, chunklists, and playlists
Stream target chunk size and playlist properties
Example requests
Related requests
More resources

About HLS chunks, chunklists, and playlists


HLS adaptive-bitrate streaming from Wowza Streaming Cloud involves three interrelated concepts: media segments (also called chunks), chunklists, and playlists.

A chunk is segment of the stream that's somewhere between 2 and 10 seconds long. A playlist is a manifest (index) file, encoded in UTF-8 with the extension .m3u8, that includes the URLs to the chunks, complete with their bitrates and sequence numbers. A playlist comprises multiple chunklists, which are subsets of URLs in the playlist.

When a client, or viewer, requests the stream, Wowza Streaming Cloud sends the first chunklist. The client accesses the chunks in the chunklist at a certain bitrate and plays the files. Before the client reaches the end of the chunklist, it requests another chunklist, and the server sends the next chunklist down the pipe. With each request, the server can send chunks at a different bitrate, resulting in dynamic, adaptive switching between different bitrates as required by network bandwidth.

The Wowza Streaming Cloud REST API allows you to directly control the size of an HLS stream's chunks, as well as control the size of the its playlist. By coordinating the values of these two properties, you can effectively define the size of your stream's chunklists, thereby controlling the frequency of adaptive bitrate switching.

A chunklist is determined by the length of the stream's playlist divided by the size of the chunks in the stream. In other words:

playlist length / chunk size = number of media segments in the chunklist

By default, Wowza Streaming Cloud uses a chunk size of 10 seconds and a playlist length of 100 seconds. As a result, the default chunklist contains 10 media segments.

To change these advanced properties, use the REST API to specify the section of the stream target configuration table that contains the property. Then, specify a new key-value pair for the chunk size and playlist length properties.

Notes:

  • A chunklist must contain a mimimum of three media segments. If you try to configure a playlist and chunk size that would result in fewer than three media segments in the chunklist, Wowza Streaming Cloud will adjust your settings to accommodate. For example, if you specify a 6-second playlist with 10-second chunks, Wowza Streaming Cloud creates a 6-second playlist with 3 2-second chunks.
  • If you configure a chunklist that doesn't work out to be a whole number, Wowza Streaming Cloud rounds down. For example, if you specify a 30-second playlist with 8-second chunks, Wowza Streaming Cloud creates a 28-second playlist with 3 8-second chunks, not a 32-second playlist with 4 8-second chunks.

Stream target chunk size and playlist properties


To define a chunklist size by using the Wowza Streaming Cloud REST API, configure the chunkSize and playlistSeconds properties. These properties are available only for Wowza stream targets and custom stream targets whose provider is akamai_cupertino.

Section Key Value Description
hls chunkSize integer Specifies the duration of the time-based audio and video chunks that Wowza Streaming Cloud delivers to the target. A lower (shorter) duration can reduce latency but may affect playback on some older devices. Valid values are 2, 4, 6, 8, and 10 (the default).
playlist playlistSeconds integer Available from API version 1.1.

The number of seconds in the playlist. The default is 100. Valid values are any integer between 6 and 200.

Example requests


Notes:

  • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
  • For [version], substitute the version number of the API that you're using. For the current version, use v1.2.

Create chunklists that consist of 3 6-second chunks

First create the 6-second chunks:

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 6
  }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/"

Then create a 18-second playlist:

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
  "property": {
    "key": "playlistSeconds",
    "section": "playlist",
    "value": 18
  }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/"

Create chunklists that consist of 15 2-second chunks

First create the 2-second chunks:

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 2
  }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/"

Then create a 30-second playlist:

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
  "property": {
    "key": "playlistSeconds",
    "section": "playlist",
    "value": 30
  }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/"

Create chunklists that consist of 50 4-second chunks

First create the 4-second chunks:

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 4
  }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/"

The create a 200-second playlist:

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{
  "property": {
    "key": "playlistSeconds",
    "section": "playlist",
    "value": 200
  }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/"

Related requests


View all of the properties applied to a stream target:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties"

The details of all of the target's properties—including chunkSize and playlistSeconds—are listed in the response, which should look something like this:

{
    "properties": [{
            "section": "hls",
            "key": "chunkSize",
            "value": 6
        },
        {
            "section": "playlist",
            "key": "playlistSeconds",
            "value": 12
        }
    ]
}

View the details of a specific property applied to a stream target:

Note: This call requires the property_id, which is a string that contains the property's section and key, connected by a dash. For example, hls-chunkSize.

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/[property_id]"

Delete a property applied to a stream target:

Note: This call requires the property_id, which is a string that contains the property's section and key, connected by a dash. For example, hls-chunkSize.

curl -X DELETE --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/[property_id]"

More resources