Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_hls_module.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
parents | 5cacd6fffade |
children |
line wrap: on
line source
<?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&start=1.000&end=2.200 http://hls.example.com/test.mp4.m3u8?len=8.000 http://hls.example.com/test.mp4.ts?start=1.000&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&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&end=9.333&a=1&b=2 #EXTINF:7.167, test.mp4.ts?start=9.333&end=16.500&a=1&b=2 #EXTINF:5.416, test.mp4.ts?start=16.500&end=21.916&a=1&b=2 #EXTINF:5.500, test.mp4.ts?start=21.916&end=27.416&a=1&b=2 #EXTINF:15.167, test.mp4.ts?start=27.416&end=42.583&a=1&b=2 #EXTINF:9.626, test.mp4.ts?start=42.583&end=52.209&a=1&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 { ~^(?<base_uri>.*).m3u8$ $base_uri; ~^(?<base_uri>.*).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>