<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_hls_module"
        link="/en/docs/http/ngx_http_hls_module.html"
        lang="en"
        rev="7">

<section id="summary">

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

<para>
For each media file, two URIs are supported:
<list type="bullet">

<listitem>
A playlist URI with the “<literal>.m3u8</literal>” filename extension.
The URI can accept optional arguments:
<list type="bullet">

<listitem>
“<literal>start</literal>” and “<literal>end</literal>”
define playlist boundaries in seconds (1.9.0).
</listitem>

<listitem>
“<literal>offset</literal>” 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.
</listitem>

<listitem>
“<literal>len</literal>” defines the fragment length in seconds.
</listitem>
</list>

</listitem>

<listitem>
A fragment URI with the “<literal>.ts</literal>” filename extension.
The URI can accept optional arguments:
<list type="bullet">

<listitem>
“<literal>start</literal>” and “<literal>end</literal>”
define fragment boundaries in seconds.
</listitem>

</list>
</listitem>

</list>
</para>

<para>
<note>
This module is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
location / {
    hls;
    hls_fragment            5s;
    hls_buffers             10 10m;
    hls_mp4_buffer_size     1m;
    hls_mp4_max_buffer_size 5m;
    root /var/video/;
}
</example>
With this configuration, the following URIs are supported for
the “<path>/var/video/test.mp4</path>” file:
<example>
http://hls.example.com/test.mp4.m3u8?offset=1.000&amp;start=1.000&amp;end=2.200
http://hls.example.com/test.mp4.m3u8?len=8.000
http://hls.example.com/test.mp4.ts?start=1.000&amp;end=2.200
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="hls">
<syntax/>
<default/>
<context>location</context>

<para>
Turns on HLS streaming in the surrounding location.
</para>

</directive>


<directive name="hls_buffers">
<syntax><value>number</value> <value>size</value></syntax>
<default>8 2m</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Sets the maximum <value>number</value> and <value>size</value> of buffers
that are used for reading and writing data frames.
</para>

</directive>


<directive name="hls_forward_args">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.5.12</appeared-in>

<para>
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
<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>
module.
</para>

<para>
For example, if a client requests a playlist
<literal>http://example.com/hls/test.mp4.m3u8?a=1&amp;b=2</literal>,
the arguments <literal>a=1</literal> and <literal>b=2</literal>
will be added to URIs of fragments after the arguments
<literal>start</literal> and <literal>end</literal>:
<example>
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:15
#EXT-X-PLAYLIST-TYPE:VOD

#EXTINF:9.333,
test.mp4.ts?start=0.000&amp;end=9.333&amp;a=1&amp;b=2
#EXTINF:7.167,
test.mp4.ts?start=9.333&amp;end=16.500&amp;a=1&amp;b=2
#EXTINF:5.416,
test.mp4.ts?start=16.500&amp;end=21.916&amp;a=1&amp;b=2
#EXTINF:5.500,
test.mp4.ts?start=21.916&amp;end=27.416&amp;a=1&amp;b=2
#EXTINF:15.167,
test.mp4.ts?start=27.416&amp;end=42.583&amp;a=1&amp;b=2
#EXTINF:9.626,
test.mp4.ts?start=42.583&amp;end=52.209&amp;a=1&amp;b=2

#EXT-X-ENDLIST
</example>
</para>

<para>
If an HLS stream is protected with the
<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>
module, <var>$uri</var> should not be used in the
<link doc="ngx_http_secure_link_module.xml" id="secure_link_md5"/>
expression because this will cause errors when requesting the fragments.
<link doc="ngx_http_map_module.xml" id="map">Base URI</link> should be used
instead of <var>$uri</var>
(<var>$hls_uri</var> in the example):
<example>
http {
    ...

    map $uri $hls_uri {
        ~^(?&lt;base_uri&gt;.*).m3u8$ $base_uri;
        ~^(?&lt;base_uri&gt;.*).ts$   $base_uri;
        default                 $uri;
    }

    server {
        ...

        location /hls/ {
            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;
            }
        }
    }
}
</example>
</para>

</directive>


<directive name="hls_fragment">
<syntax><value>time</value></syntax>
<default>5s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Defines the default fragment length for playlist URIs requested without the
“<literal>len</literal>” argument.
</para>

</directive>


<directive name="hls_mp4_buffer_size">
<syntax><value>size</value></syntax>
<default>512k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Sets the initial <value>size</value> of the buffer used for
processing MP4 and MOV files.
</para>

</directive>


<directive name="hls_mp4_max_buffer_size">
<syntax><value>size</value></syntax>
<default>10m</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
During metadata processing, a larger buffer may become necessary.
Its size cannot exceed the specified <value>size</value>,
or else nginx will return the server error
<http-status code="500" text="Internal Server Error"/>,
and log the following message:
<example>
"/some/movie/file.mp4" mp4 moov atom is too large:
12583268, you may want to increase hls_mp4_max_buffer_size
</example>
</para>

</directive>

</section>

</module>