Cache an on-demand HLS library by file extension

Give the segments and the playlists of an on-demand HLS library their own cache settings, and apply each one with a rule on its file extension.

Last updated

View as Markdown Agent setup

You give the segments and the playlists of an on-demand HLS library their own cache settings, and apply each one with a rule on its file extension, from Azion Console, the Azion API, or the Azion CLI. For a live stream, refer to Enforce HLS cache for live streaming when your own origin produces it, or to Deliver a live stream from Live Ingest when Live Ingest does.

An HLS title is a set of playlists, .m3u8, and the segments they list, .ts. A segment of an encoded title does not change, so it can stay cached for a long time and use Tiered Cache. A playlist can be rewritten when a title is re-published, so it takes a shorter cache time, and it stays out of the Tiered Cache layer so that a URL purge removes it.

  1. A path that ends in .ts takes the vod-hls-segments cache setting.
  2. A path that ends in .m3u8 takes the vod-hls-playlists cache setting.
  3. Any other path is left to the other rules of the application.
  4. A miss reaches the origin through the connector, and the response is cached under the setting its path took.

Prerequisites

The examples cache segments for 86400 seconds and playlists for 300 seconds, on an application served at www.example.com. Replace them with the values your library needs.

Create the cache settings

Each file type takes its own cache setting. Max Age accepts 0 to 31,536,000 seconds. A value below 60 requires Application Accelerator on the application, or the API rejects the setting with 21021, so the examples stay at 60 or more. Tiered Cache requires Override cache behavior, or the API rejects the setting with 21001, and a Max Age of at least 3 seconds, or it fails with 21020.

Both settings override the browser cache to 0 seconds. Real-Time Purge removes a copy from Azion’s cache layers, and a copy the viewer’s browser keeps stays there until its own TTL ends.

To create the cache setting for the segments:

Open the Cache Settings tab

Access Azion Console > Applications, select the application that serves the library, and select the Cache Settings tab.

Select + Cache
Name the cache setting

In Name, enter vod-hls-segments.

Set the browser cache

Under Browser Cache, select Override cache settings and set the TTL to 0.

Set Max Age

Under Cache, keep Override cache behavior selected and set Max Age to 86400.

Turn on Tiered Cache

In the same section, turn on Tiered Cache and select the nearest region in Tiered Cache Region.

Select Save

Create the cache setting for the playlists with the same steps: name it vod-hls-playlists, set Max Age to 300, and leave Tiered Cache off.

Both settings appear in the Cache Settings tab of the application, and neither applies to a request until a rule names it.

Apply each setting with a rule on its extension

The matches operator compares the path with a regular expression. \.ts$ escapes the dot and anchors the pattern at the end of the path, so only a path that ends in .ts takes the segments setting. ${uri} holds the path without the query string, so a segment requested with a query string still matches. The rule uses the Set Cache Policy behavior, which needs no other Product on the application.

To create the rule for the segments:

Select the Rules Engine tab of the application
Select + Rule
Name the rule

In General, enter cache-vod-segments as the Name.

Select the request phase

In Phase, select Request Phase.

Set the criterion

Under Criteria, select the variable ${uri} and the operator matches, and enter \.ts$ as the argument.

Select the Set Cache Policy behavior

Under Behaviors, select Set Cache Policy, then select vod-hls-segments.

Select Save

Create the rule for the playlists with the same steps: name it cache-vod-playlists, enter \.m3u8$ as the argument, and select vod-hls-playlists.

Segments are cached for 86,400 seconds in Cache and in the Tiered Cache layer, and playlists for 300 seconds in Cache. A new rule can take a few minutes to propagate.

Confirm each file type answers from cache

The request header Pragma: azion-debug-cache makes the response carry the x-cache header. To confirm the segments setting:

Request a segment with the debug header
curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/<title>/<segment>.ts
Run the same command again

The x-cache header of the second response starts with HIT, because Azion answered from the stored copy. The header also carries the IP address of the server that answered and the protocol.

Repeat the two requests for a playlist, https://www.example.com/<title>/<playlist>.m3u8. The first response of each file can carry MISS, while Azion fetches it from the origin. For every status the header can carry, refer to Check the cache status of a response.

Next steps

Cache settingsEvery field of a cache setting, with its type, its default, its bounds, and its errors.Tiered CacheThe second cache layer, its topologies, its TTL floor, and how it is purged.Rules Engine for ApplicationsEvery criterion variable and operator a rule can use.Deliver an on-demand video libraryAn HLS library stored in Object Storage and served with these two cache settings.