Create custom media playlists with the Wowza Streaming Cloud REST API

Learn how to control the size of an adaptive bitrate HLS stream's media playlists, sometimes known as chunklists, by using the Wowza Streaming Cloud™ service REST API.

About HLS media segments, media playlists, and master playlists


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

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

When a client, or viewer, requests the stream, Wowza Streaming Cloud sends the first media playlist. The client accesses the media segments in the media playlist at a certain bitrate and plays the files. Before the client reaches the end of the media playlist, it requests another media playlist, and the server sends the next media playlist down the pipe. With each request, the server can send media segments 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 media segments (chunks), as well as control the size of its master playlist. By coordinating the values of these two properties, you can effectively define the size of your stream's media playlists, thereby controlling the frequency of adaptive bitrate switching.

A media playlist is determined by the length of the stream's master playlist divided by the size of the media segments in the stream. In other words:

master playlist length / media segment size = number of media segments in the media playlist

By default, Wowza Streaming Cloud uses a media segment size of 10 seconds and a master playlist length of 100 seconds. As a result, the default media playlist 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 media playlist must contain a mimimum of three media segments. If you try to configure a media playlist and segment size that would result in fewer than three media segments in the media playlist, Wowza Streaming Cloud will adjust your settings to accommodate. For example, if you specify a 6-second media playlist with 10-second segments, Wowza Streaming Cloud creates a 6-second media playlist with 3 2-second segments.
  • If you configure a media playlist that doesn't work out to be a whole number, Wowza Streaming Cloud rounds down. For example, if you specify a 30-second master playlist with 8-second segments, Wowza Streaming Cloud creates a 28-second master playlist with 3 8-second segments, not a 32-second mater playlist with 4 8-second segments.

Stream target chunk size and playlist properties


To define a media playlist size by using the Wowza Streaming Cloud REST API, configure the chunkSize and playlistSeconds properties. These properties are available for Wowza CDN on Akamai stream targets and custom stream targets whose provider is akamai_cupertino and available for Wowza CDN on Fastly stream targets.

Section Key Value Description
hls chunkSize integer Specifies the duration of the time-based audio and video media segments 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 The number of seconds in the master playlist. The default is 100. Valid values are any integer between 6 and 200.

Example requests


Notes:

Create media playlists that consist of 3 6-second segments

First create the 6-second media segments:

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 6
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

Then create a 18-second master playlist:

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "property": {
    "key": "playlistSeconds",
    "section": "playlist",
    "value": 18
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

Create media playlists that consist of 15 2-second segments

First create the 2-second media segments:

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 2
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

Then create a 30-second master playlist:

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "property": {
    "key": "playlistSeconds",
    "section": "playlist",
    "value": 30
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

Create media playlists that consist of 50 4-second segments

First create the 4-second media segments:

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 4
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

The create a 200-second master playlist:

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "property": {
    "key": "playlistSeconds",
    "section": "playlist",
    "value": 200
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

Related requests


View all of the properties applied to a stream target:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_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 \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_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 \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties/[property_id]"

More resources