Module ngx_http_hls_module

The ngx_http_hls_module module provides HTTP Live Streaming (HLS) server-side support for MP4 and MOV media files. Such files typically have the .mp4 , .m4v , .m4a , .mov , or .qt filename extensions. The module supports H.264 video codec, AAC and MP3 audio codecs.

For each media file, two URIs are supported:

  • A playlist URI with the “ .m3u8 ” filename extension. The URI can accept optional arguments:

  • start ” and “ end ” define playlist boundaries in seconds (1.9.0).

    • offset ” shifts an initial playback position to the time offset in seconds (1.9.0). A positive value sets a time offset from the beginning of the playlist. A negative value sets a time offset from the end of the last fragment in the playlist.

    • len ” defines the fragment length in seconds.

  • A fragment URI with the “ .ts ” filename extension. The URI can accept optional arguments:

  • start ” and “ end ” define fragment boundaries in seconds.


This module is available as part of our commercial subscription.

Example Configuration

location / {
    hls_fragment            5s;
    hls_buffers             10 10m;
    hls_mp4_buffer_size     1m;
    hls_mp4_max_buffer_size 5m;
    root /var/video/;

With this configuration, the following URIs are supported for the “ /var/video/test.mp4 ” file:



Turns on HLS streaming in the surrounding location.

Syntax:hls_buffers number size;
Default:hls_buffers 8 2m;
Context:http , server , location

Sets the maximum number and size of buffers that are used for reading and writing data frames.

Syntax:hls_forward_args on | off;
Default:hls_forward_args off;
Context:http , server , location

This directive appeared in version 1.5.12.

Adds arguments from a playlist request to URIs of fragments. This may be useful for performing client authorization at the moment of requesting a fragment, or when protecting an HLS stream with the ngx_http_secure_link_module module.

For example, if a client requests a playlist , the arguments a=1 and b=2 will be added to URIs of fragments after the arguments start and end :




If an HLS stream is protected with the ngx_http_secure_link_module module, $uri should not be used in the secure_link_md5 expression because this will cause errors when requesting the fragments. Base URI should be used instead of $uri ( $hls_uri in the example):

http {

    map $uri $hls_uri {
        ~^(?<base_uri>.*).m3u8$ $base_uri;
        ~^(?<base_uri>.*).ts$   $base_uri;
        default                 $uri;

    server {

        location /hls/ {
            hls_forward_args on;

            alias /var/videos/;

            secure_link $arg_md5,$arg_expires;
            secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret";

            if ($secure_link = "") {
                return 403;

            if ($secure_link = "0") {
                return 410;

Syntax:hls_fragment time;
Default:hls_fragment 5s;
Context:http , server , location

Defines the default fragment length for playlist URIs requested without the “ len ” argument.

Syntax:hls_mp4_buffer_size size;
Default:hls_mp4_buffer_size 512k;
Context:http , server , location

Sets the initial size of the buffer used for processing MP4 and MOV files.

Syntax:hls_mp4_max_buffer_size size;
Default:hls_mp4_max_buffer_size 10m;
Context:http , server , location

During metadata processing, a larger buffer may become necessary. Its size cannot exceed the specified size , or else nginx will return the server error 500 (Internal Server Error), and log the following message:

"/some/movie/file.mp4" mp4 moov atom is too large:
12583268, you may want to increase hls_mp4_max_buffer_size