Learn how to control the size of an adaptive bitrate HLS stream's media playlists, sometimes known as chunklists, by using the Wowza Video™ service REST API.
To define a media playlist size, you'll configure the chunkSize and playlistSeconds properties.
Before you start
You should have completed the following tasks:
- Create a live stream or an adaptive bitrate transcoder. You'll need the stream target IDs resulting from that process. View our Connect a source topics to learn how to create a live stream or transcoder for RTMP, RTSP, IP camera, SRT encoder, UDP encoder, WebRTC, and Wowza Streaming Engine.
About HLS media segments, media playlists, and master playlists
HLS adaptive bitrate streaming from Wowza Video 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 Video 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 Video 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 Video 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 minimum 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 Video will adjust your settings to accommodate. For example, if you specify a 6-second media playlist with 10-second segments, Wowza Video 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 Video rounds down. For example, if you specify a 30-second master playlist with 8-second segments, Wowza Video creates a 28-second master playlist with 3 8-second segments, not a 32-second mater playlist with 4 8-second segments.
1. Set the chunk size
Set the chunk size of the stream by sending a POST request to the /stream_targets/[stream_target_id]/properties endpoint. The example illustrated in steps 1 and 2 creates 3 6-second segments with an 18-second master playlist.
You can use the following sample request, making sure to:
- Set value to the duration of the time-based audio and video media segments you want Wowza Video to deliver 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).
- Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.
Sample request
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
"property": {
"key": "chunkSize",
"section": "hls",
"value": 6
}
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/[stream_target_id]/properties"
2. Set the master playlist duration
Set the master playlist duration of the stream by sending a POST request to the /stream_targets/[stream_target_id]/properties endpoint.
You can use the following sample request, making sure to:
- Set value to the number of seconds in the master playlist. The default is 100. Valid values are any integer between 6 and 28800 (8 hours).
- Change any values unique to your broadcast, using the API reference documentation as a resource. See the Endpoint Reference button below.
Sample request
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
"property": {
"key": "playlistSeconds",
"section": "playlist",
"value": 18
}
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/[stream_target_id]/properties"
The sample in this step creates an 18-second master playlist. With the 6-second chunk size set in step 1, there will be 3 chunklists (media segments) in the stream.
Other examples
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 "Authorization: Bearer ${WV_JWT}" \
-d '{
"property": {
"key": "chunkSize",
"section": "hls",
"value": 2
}
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/[stream_target_id]/properties"
Then create a 30-second master playlist:
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
"property": {
"key": "playlistSeconds",
"section": "playlist",
"value": 30
}
}' "${WV_HOST}/api/${WV_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 "Authorization: Bearer ${WV_JWT}" \
-d '{
"property": {
"key": "chunkSize",
"section": "hls",
"value": 4
}
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/[stream_target_id]/properties"
The create a 200-second master playlist:
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${WV_JWT}" \
-d '{
"property": {
"key": "playlistSeconds",
"section": "playlist",
"value": 200
}
}' "${WV_HOST}/api/${WV_VERSION}/stream_targets/[stream_target_id]/properties"
Related API requests
- GET /stream_targets/[stream_target_id]/properties — View all the properties applied to a stream target.
- GET /stream_targets/[stream_target_id]/properties/[property_id] — View the details of a specific property applied to a stream target.
- DELETE /stream_targets/[stream_target_id]/properties/[property_id] — Delete a specific property applied to a stream target.
