<?xml version="1.0"?>

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

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

<module name="Модуль ngx_http_mp4_module"
        link="/ru/docs/http/ngx_http_mp4_module.html"
        lang="ru"
        rev="9">

<section id="summary">

<para>
Модуль <literal>ngx_http_mp4_module</literal> обеспечивает серверную поддержку
псевдо-стриминга для файлов в формате MP4.
Такие файлы обычно имеют расширения
<path>.mp4</path>, <path>.m4v</path> и <path>.m4a</path>.
</para>

<para>
Псевдо-стриминг работает в паре с совместимым медиаплеером.
Плеер посылает серверу HTTP-запрос с указанием точки времени старта
в аргументе
<literal>start</literal>
строки запроса (время задаётся в секундах), а сервер в
ответ посылает поток, у которого начальная позиция соответствует
запрошенному времени, например:
<example>
http://example.com/elephants_dream.mp4?start=238.88
</example>
Это позволяет в любой момент времени выполнить произвольное
позиционирование, а также начать воспроизведение с середины
временной шкалы.
</para>

<para>
В форматах, основанных на H.264, метаданные, необходимые для поддержки
позиционирования, хранятся в так называемом “moov-атоме”.
Это часть файла, которая содержит индексную информацию для всего файла.
</para>

<para>
До начала воспроизведения плееру необходимо прочитать метаданные.
Для этого он отсылает специальный запрос с аргументом
<literal>start=0</literal>.
Многие кодирующие программы добавляют метаданные в конец файла.
Это неоптимально для псевдо-стриминга, поскольку плееру
потребуется загрузить файл целиком прежде чем начать воспроизведение.
Если метаданные находятся в начале файла,
nginx’у достаточно начать отправлять в ответ содержимое файла.
Если же метаданные находятся в конце файла,
потребуется прочитать весь
файл и подготовить новый поток, в котором метаданные предшествуют
медийным данным.
Это требует дополнительного процессорного
времени, памяти и дискового ввода/вывода, поэтому лучше
заранее <link
url="https://github.com/flowplayer/flowplayer/wiki/7.1.1-video-file-correction">
подготовить исходный файл для псевдо-стриминга</link>,
нежели делать это для каждого запроса.
</para>

<para>
Модуль также поддерживает аргумент <literal>end</literal> HTTP-запроса
(1.5.13), задающий время окончания воспроизведения потока.
Аргумент <literal>end</literal> задаётся совместно с
аргументом <literal>start</literal>
или самостоятельно:
<example>
http://example.com/elephants_dream.mp4?start=238.88&amp;end=555.55
</example>
</para>

<para>
Для запроса с ненулевыми аргументами
<literal>start</literal> или <literal>end</literal>
nginx считывает из файла метаданные, готовит поток с запрошенным
диапазоном и отправляет его клиенту.
Это тоже требует дополнительных ресурсов, как указано выше.
</para>

<para id="keyframe">
Если аргумент <literal>start</literal> указывает на
видеокадр, не являющийся ключевым,
то начало такого видео может воспроизводиться с ошибками.
В этом случае к запрашиваемому видео
<link id="mp4_start_key_frame">могут</link> быть добавлены
ближайший к точке <literal>start</literal> ключевой кадр
и все промежуточные кадры между ними.
При воспроизведении эти кадры будут скрыты
при помощи edit-листа (1.21.4).
</para>

<para>
Если запрос, обрабатываемый этим модулем, не содержит аргументов
<literal>start</literal> и <literal>end</literal>,
дополнительные ресурсы не тратятся, а файл отсылается непосредственно как
статический ресурс.
Некоторые плееры также поддерживают запросы с указанием диапазона
запрашиваемых байт (byte-range requests), для них этот модуль не требуется.
</para>

<para>
По умолчанию этот модуль не собирается, его сборку необходимо
разрешить с помощью конфигурационного параметра
<literal>--with-http_mp4_module</literal>.
<note>
Если ранее использовался сторонний модуль mp4, следует его отключить.
</note>
</para>

<para>
Схожая поддержка псевдо-стриминга для FLV-файлов обеспечивается модулем
<link doc="ngx_http_flv_module.xml">ngx_http_flv_module</link>.
</para>

</section>


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

<para>
<example>
location /video/ {
    mp4;
    mp4_buffer_size     1m;
    mp4_max_buffer_size 5m;
}
</example>
</para>

</section>


<section id="directives" name="Директивы">

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

<para>
Включает в содержащем location обработку этим модулем.
</para>

</directive>


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

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

</directive>


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

<para>
В ходе обработки метаданных может понадобиться буфер большего размера.
Его размер не может превышать указанного,
иначе 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 mp4_max_buffer_size
</example>
</para>

</directive>


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

<para>
Включает режим, в котором видео всегда начинается с ключевого видеокадра.
Если аргумент <literal>start</literal> не указывает на ключевой кадр,
то первоначальные кадры будут скрыты при помощи mp4 edit-листа.
Edit-листы поддерживаются большинством плееров и браузеров
включая Chrome, Safari, QuickTime и ffmpeg,
частично поддерживаются в Firefox.
</para>

</directive>

</section>

</module>