<?xml version="1.0"?>

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

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

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

<section id="summary">

<para>
Модуль <literal>ngx_http_hls_module</literal> обеспечивает серверную поддержку
протокола HTTP Live Streaming (HLS) для медиафайлов в формате MP4 и MOV.
Такие файлы обычно имеют расширения <path>.mp4</path>, <path>.m4v</path>,
<path>.m4a</path>, <path>.mov</path> или <path>.qt</path>.
Модуль поддерживает видеокодек H.264, а также аудиокодеки AAC и MP3.
</para>

<para>
Для каждого медиафайла поддерживается два URI:
<list type="bullet">

<listitem>
URI плейлиста, имеющий расширение “<literal>.m3u8</literal>”.
URI может принимать необязательные аргументы:
<list type="bullet">

<listitem>
“<literal>start</literal>” и “<literal>end</literal>”
задают границы плейлиста в секундах (1.9.0).
</listitem>

<listitem>
“<literal>offset</literal>” сдвигает первоначальную позицию воспроизведения
на указанное время в секундах (1.9.0).
Положительное значение задаёт временной сдвиг с начала плейлиста.
Отрицательное значение задаёт временной сдвиг с конца последнего фрагмента
в плейлисте.
</listitem>

<listitem>
“<literal>len</literal>” задаёт длину фрагмента в секундах.
</listitem>
</list>

</listitem>

<listitem>
URI фрагмента, имеющий расширение “<literal>.ts</literal>”.
URI может принимать необязательные аргументы:
<list type="bullet">

<listitem>
“<literal>start</literal>” и “<literal>end</literal>”
задают границы фрагмента в секундах.
</listitem>

</list>
</listitem>

</list>
</para>

<para>
<note>
Модуль доступен как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Пример конфигурации">

<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>
В такой конфигурации для файла “<path>/var/video/test.mp4</path>”
будут поддерживаться следующие URI:
<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="Директивы">

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

<para>
Включает HLS-поток во вложенном location.
</para>

</directive>


<directive name="hls_buffers">
<syntax><value>число</value> <value>размер</value></syntax>
<default>8 2m</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт максимальное <value>число</value> и <value>размер</value> буферов,
которые используются для чтения и записи блоков данных.
</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>
Добавляет аргументы из запроса плейлиста в URI фрагментов.
Это может быть необходимо для авторизации клиента
во время запроса фрагментов, а также для защиты HLS-потока с помощью
модуля
<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>.
</para>

<para>
Например, если клиент запрашивает плейлист
<literal>http://example.com/hls/test.mp4.m3u8?a=1&amp;b=2</literal>,
то аргументы <literal>a=1</literal> и <literal>b=2</literal>
будут добавлены в URI фрагментов после аргументов
<literal>start</literal> и <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>
Если HLS-поток защищён с помощью модуля
<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>,
переменную <var>$uri</var> не следует использовать в выражении
<link doc="ngx_http_secure_link_module.xml" id="secure_link_md5"/>,
так как это приведёт к ошибкам при запросах к фрагментам.
Вместо <var>$uri</var> следует использовать
<link doc="ngx_http_map_module.xml" id="map">базовую часть URI</link>
(<var>$hls_uri</var> в примере):
<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>время</value></syntax>
<default>5s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт длину фрагмента по умолчанию для всех URI в плейлисте,
запрошенных без аргумента “<literal>len</literal>”.
</para>

</directive>


<directive name="hls_mp4_buffer_size">
<syntax><value>размер</value></syntax>
<default>512k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт начальный <value>размер</value> буфера, используемого для
обработки MP4- и MOV-файлов.
</para>

</directive>


<directive name="hls_mp4_max_buffer_size">
<syntax><value>размер</value></syntax>
<default>10m</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
В ходе обработки метаданных может понадобиться буфер большего размера.
Его <value>размер</value> не может превышать указанного,
иначе nginx вернёт серверную ошибку
<http-status code="500" text="Internal Server Error"/>
и запишет в лог следующее сообщение:
<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>